Semantic Router 集成 llm-d:让语义路由选模型池,llm-d 在池内调度副本
Semantic Router 集成 llm-d:让语义路由选模型池,llm-d 在池内调度副本
在 Kubernetes 推理网关栈中,一个请求往往需要做出两个不同层面的决策:先根据请求意图、策略和 recipe 状态选出逻辑模型(或模型池),再在该模型池内部按负载、前缀缓存等端点信息选出具体副本。本文基于仓库文档 Integrate with llm-d 展开,结合 e2e/profiles/llm-d 测试 profile、deploy/kubernetes/llmd-base 清单与 Semantic Router 的 extproc 源码,完整讲解这套“两级路由”拓扑的集成契约、部署步骤、逐层验证方法与常见故障排查,读完你可以独立完成 Semantic Router 与 llm-d 的共存部署并验证端到端行为。
拓扑与职责边界:两级决策,各司其职
llm-d 是 Semantic Router 支持的 Inference Router 集成之一,与 vLLM Router 和 AIBrix 网关集成 并列。当请求需要同时做出“选哪个池”和“选池内哪个副本”两个决策时,采用如下拓扑:
- Semantic Router 从请求意图、策略与 recipe 状态中选择逻辑模型或模型池;
- llm-d 利用负载、前缀缓存或其他端点信息,在该池内选择一个健康的副本。
请求的完整链路如下:
client
-> inference gateway
-> Semantic Router ExtProc
-> HTTPRoute selected by x-selected-model
-> InferencePool
-> llm-d endpoint picker
-> model replica
这条链路中最关键的约束是决策不能重叠:
- Semantic Router 不应该选择 Pod(副本);
- llm-d 不应该决定哪个业务策略或模型族适用于该请求。
两个系统若配置成做同一个决策,会导致路由行为难以预测。这也是文档反复强调的边界:Router 负责“逻辑模型”语义层,llm-d 的 endpoint picker 负责池内副本调度。
前提条件:先独立部署并验证 llm-d
在叠加 Semantic Router 之前,必须先把 llm-d 独立部署并验证通过。llm-d 的发布制品、CRD、Helm chart 与插件配置是配套演进的,因此应使用一个受支持的 llm-d 版本,而不是从不同版本混合拷贝清单。
准备阶段的三个要点(可参考 llm-d 官方文档中对应的 quickstart、gateway 集成与 artifacts 章节):
- 按 llm-d 当前 quickstart 或一条成熟的 well-lit path 完成基础部署;
- 选择一个受支持的网关集成方式(Gateway 与 Gateway API Inference Extension 的组合);
- 使用与所选 llm-d 版本匹配的 Gateway API Inference Extension 资源(如
InferencePool、EndpointPickerConfig)和 chart。
在此边界上,你应当已经能够不经过 Semantic Router,直接通过网关向每个 InferencePool 发送请求并拿到响应。这一步是后续集成排障的基线:一旦叠加 Router 后出问题,可以先区分是 llm-d 层还是 Router 层引入的。
仓库中 e2e/profiles/llm-d 就是这个前提条件的自动化体现。profile.go 定义的 Setup 流程依次为:
- 安装 Gateway API CRD(
gateway.networking.k8s.io/v1,期望资源gateways、httproutes)与 Inference Extension CRD(inference.networking.k8s.io/v1,期望资源inferencepools),EndpointPickerConfig(inference.networking.x-k8s.io/v1alpha1)按最佳努力处理; - 安装 Istio(测试中版本 1.28.0),并通过
ENABLE_GATEWAY_API_INFERENCE_EXTENSION=true启用 Inference Extension 支持; - 部署模型仿真器(
inference-sim.yaml)、llm-d 调度器与两个InferencePool(llama3-8b与phi4-mini); - 部署
Gateway、HTTPRoute、DestinationRule与 EnvoyFilter,并等待每条HTTPRoute的Accepted与ResolvedRefs条件为True(见 profile.go 的waitForGatewayRoutes)。
对应的池与路由清单可直接参考 deploy/kubernetes/llmd-base 下的 inferencepool-llama.yaml、inferencepool-phi4.yaml、dest-rule-epp-*.yaml 与 httproute-*-pool.yaml。
集成契约:五个名称必须对齐
两套系统之间通过一组名称衔接,文档要求在两个系统中保持以下五项一致:
| 名称 | 归属 | 要求 |
|---|---|---|
| Provider model | Semantic Router | providers.models[].name 是 recipe 选中的逻辑池名。 |
| Request header | Semantic Router | Router 把选中的 provider model 写入 x-selected-model。 |
| Route match | Gateway API | 一条 HTTPRoute 精确匹配该 header 值。 |
| Backend reference | Gateway API / llm-d | 该路由指向目标 InferencePool。 |
| Served model | 模型服务 | 池内副本接受网关转发的模型身份。 |
x-selected-model 不是约定俗成的名字,而是 Router 的固定输出:headers.go 中定义了 SelectedModel = "x-selected-model",注释明确它是“路由决策阶段设置”的请求头。extproc 处理路径中,processor_req_body_routing.go 的 appendRoutingHeaders 在请求体处理完成后,把 ctx.VSRSelectedModel 以覆盖方式(OVERWRITE_IF_EXISTS_OR_ADD)写进发往后端的路由头——这也解释了文档中“对比 x-selected-model 与 HTTPRoute 值时要连大小写一起看”的排障建议:header 是精确匹配(type: Exact)。
以仓库 e2e 环境为例,httproute-services.yaml 展示了两条把 Router 选择映射到 llm-d 池的路由:
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: vsr-llama8b-svc
namespace: default
spec:
parentRefs:
- group: gateway.networking.k8s.io
kind: Gateway
name: inference-gateway
rules:
- backendRefs:
- group: inference.networking.k8s.io
kind: InferencePool
name: vllm-llama3-8b-instruct
matches:
- path:
type: PathPrefix
value: /
headers:
- type: Exact
name: x-selected-model
value: llama3-8b
timeouts:
request: 300s
# 另一条 vsr-phi4-mini-svc 以相同结构匹配
# x-selected-model: phi4-mini -> InferencePool vllm-phi4-mini
文档中的通用示例(映射 Router 的 local/code 选择到既有 llm-d 池)等价于此结构,落地时只需按自己的部署调整名称与命名空间:
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: code-pool
namespace: inference
spec:
parentRefs:
- name: llm-d-inference-gateway
rules:
- matches:
- headers:
- type: Exact
name: x-selected-model
value: local/code
backendRefs:
- group: inference.networking.k8s.io
kind: InferencePool
name: code-pool
port: 8000
注意:HTTPRoute 本身不配置池或 endpoint picker,池选择器仍是 llm-d 部署的一部分,且必须使用对应 llm-d 版本支持的 API 版本。
添加 Semantic Router
在 llm-d 基线就绪后,按以下四步接入 Semantic Router:
1. 编写并校验 canonical Router 配置。 Provider model 名称必须与路由中的 x-selected-model 值一致:
vllm-sr config validate --config config.yaml
仓库提供了一份面向 llm-d 场景的 values 参考 deploy/kubernetes/llm-d/semantic-router-values/values.yaml,其结构要点:
gateway:
mode: extproc # 网关通过 ext_proc 调用 Router
config:
version: v0.3
providers:
defaults:
model: llama3-8b
models:
- name: llama3-8b
backend_refs:
- name: llama-8b-service
provider: vllm
endpoint: llama-8b:80
weight: 1
- name: phi4-mini
backend_refs:
- name: phi4-mini-service
provider: vllm
endpoint: phi4-mini:80
weight: 1
routing:
decisions:
- name: business # 按 domain 信号匹配业务类问题
priority: 10
rules:
operator: OR
conditions:
- type: domain
name: business
modelRefs:
- model: llama3-8b
use_reasoning: false
plugins:
- type: system_prompt
configuration: { enabled: false, system_prompt: "...", mode: replace }
global:
router:
clear_route_cache: true # 该拓扑的必需项,见下文第 4 步
e2e profile 使用的 values.yaml 则给出了更贴近真实服务地址的写法:endpoint 使用集群内 DNS(vllm-llama3-8b-instruct.default.svc.cluster.local:8000),并把决策按领域优先级编排——math_decision 映射到 phi4-mini(priority 100),computer_science_decision 等映射到 llama3-8b,other_decision 作为最低优先级兜底(priority 1)。注意该文件中注释说明:“Decision names match E2E test expectations(*_decision 格式)”,即决策名会出现在响应头中,供测试与调试比对。
2. 用 Helm 或 Operator 部署 Semantic Router。 部署方式详见 Configuration workflows。直接使用 Helm 时,建议用 configOverride 让 chart 示例配置被原子性地整体替换。从 chart 模板看(templates/_helpers.tpl),configOverride 必须是非空 mapping,会被 deepCopy 后作为完整 canonical 配置使用;README 中对其定义是“Unlike config, this map atomically replaces chart defaults before Kubernetes integration rewrites”。这避免了“chart 默认配置 + 片段覆盖”产生的半新半旧状态。
3. 把 Semantic Router 挂到网关的 ExtProc 服务上。 具体资源形态因网关而异(例如 Istio 用 EnvoyFilter),受支持的挂载模式见 Gateway API Inference Extension 文档。e2e profile 在 Istio 场景下挂载 EnvoyFilter 后,还会为 Gateway listener 上下文补齐匹配条件(match.context=GATEWAY、listener.portNumber=80,见 profile.go),保证 ext-proc 调用发生在网关监听器路径上。
4. 在 canonical 配置中保持 global.router.clear_route_cache: true。 这是该拓扑的关键开关:网关必须在下游请求路径上调用 ExtProc,保留其“清除路由缓存”的响应,然后在 Semantic Router 写入 x-selected-model 之后重新评估 HTTPRoute。从源码看,clear_route_cache 是 global.router 下的布尔字段,定义于配置 schema router-config-v0.3.schema.json;extproc 的请求体响应构造函数 buildRequestBodyContinueResponse 也接收 clearRouteCache 参数,说明“改写 header + 清缓存 + 触发重新路由”是同一条响应消息上联动的行为。如果不保持该值为 true,网关可能在 Router 改写 x-selected-model 之前就用旧路由缓存做了选路,导致语义选择被绕过。
逐层验证:不要止步于 HTTP 200
文档要求“一次只验证一层”,且不要依赖生成的 Pod 名称做检查。
第一层:资源状态。
kubectl get gateway,httproute -A
kubectl get inferencepools -A
kubectl get httproute code-pool -n inference \
-o jsonpath='{.status.parents[*].conditions[?(@.type=="ResolvedRefs")].status}{"\n"}'
e2e 自动化中的等待逻辑与之一致:waitHTTPRouteAccepted 与 waitHTTPRouteResolvedRefs 分别轮询 Accepted 和 ResolvedRefs 两个 condition,均为 True 才认为路由就绪(profile.go)。
第二层:发送一条走语义选择的请求。 使用当前 Router 配置暴露的虚拟模型(如 vllm-sr/auto):
curl -i "$GATEWAY_URL/v1/chat/completions" \
-H 'Content-Type: application/json' \
-d '{
"model": "vllm-sr/auto",
"messages": [{"role": "user", "content": "Review this function for a race condition."}]
}'
第三层:验证三个决策,而不是只看状态码。 文档列出三条必须全部满足的验证点:
- 响应包含期望的
x-vsr-selected-model值; - 匹配的
HTTPRoute报告ResolvedRefs=True; - llm-d 从预期的
InferencePool中选出了一个就绪端点。
这些响应头的来源在 headers.go 中有明确定义:VSRSelectedModel = "x-vsr-selected-model" 是成功响应上附加的 VSR 决策追踪头;同文件还定义了 x-vsr-selected-decision、x-vsr-selected-confidence 等,可用于确认命中的是哪条决策。e2e 测试用例 llmd_semantic_endpoint_selection.go 把这三层验证变成了断言:
- 每个池至少需要 2 个 Ready Pod(
readyPodNames按Ready=True过滤); - 每个用例连续发送 3 次请求(
vllm-sr/auto+ 领域 prompt),断言响应头x-vsr-selected-decision与x-vsr-selected-model符合预期(例如 math prompt 必须命中math_decision/phi4-mini); - 断言
x-inference-pod头非空,且该 Pod 属于对应池的 Ready Pod 集合——这正是“llm-d 在池内选了副本”这一层的服务端证据; - 最终把
decision、model_pool、ready_pods、selected_pods汇总进测试详情,可观察池内副本的实际选择分布。
另有健康检查用例 llm-d-inference-gateway-health(llmd_inference_gateway_health.go)覆盖网关基线,两个用例与 Router 冒烟测试一起注册在 profile.go 的 GetTestCases 中。
常见故障速查
| 症状 | 检查项 |
|---|---|
| Route never matches | 对比 x-selected-model 与 HTTPRoute 中的值,包括大小写与命名空间。 |
ResolvedRefs=False |
检查 InferencePool 的 name、group、port 以及跨命名空间的引用权限。 |
| Correct pool, wrong served model | 让 provider 的模型身份与副本接受的模型名对齐。 |
| Semantic Router is bypassed | 确认网关在路由匹配之前调用 ExtProc。 |
| EPP has no endpoints | 诊断 llm-d 池的 selector、Pod 就绪状态,以及版本匹配的插件配置。 |
几点与源码/清单呼应的补充:
- “Route never matches”一行对应 header 精确匹配语义:
x-selected-model是 extproc 以OVERWRITE_IF_EXISTS_OR_ADD写入的,因此若客户端或上游预置了不同值,最终生效的是 Router 写入值;HTTPRoute侧type: Exact区分大小写。 - “Semantic Router is bypassed”通常意味着 ExtProc 没挂在下游请求路径上,或网关用了先路由后处理的模式。e2e 中专门 patch EnvoyFilter 让 ext-proc 匹配 Gateway listener 上下文,就是为了保证这一点。
- “EPP has no endpoints”指向 llm-d 一侧的池选择器与副本就绪问题,与 Router 无关,回到“先独立验证 llm-d”的前提即可定位。
生产边界
文档在结尾给出四条生产化要求,建议直接作为上线 checklist:
- 锁定版本:把 Semantic Router、llm-d、网关、CRD 与模型服务镜像全部 pin 住,保证整套制品配套。
- 凭据隔离:provider 凭据不要写进 Router YAML;由持有凭据的组件使用 Secret 回退的绑定方式。
- 显式定义故障行为:fail-open 的 ExtProc 策略可能绕过语义策略;fail-closed 策略则会在 Router 不可用时阻断全部流量。二者各有权衡,必须按业务显式选择而不是依赖默认。
- 分层回归:在整体上线前,分别测试直接访问池、语义选择、端点调度三条路径。这与“逐层验证”的原则一致——e2e profile 的 Setup 也是按 CRD → 运行时 → 路由 → 端点就绪的顺序逐级校验的。
参考路径汇总
| 资料 | 路径 |
|---|---|
| 集成文档(本文主体) | website/docs/installation/k8s/llm-d.md |
| llm-d 场景 Helm values 参考 | deploy/kubernetes/llm-d/semantic-router-values/values.yaml |
| e2e profile 与部署编排 | e2e/profiles/llm-d/profile.go、values.yaml |
| InferencePool / HTTPRoute 基线清单 | deploy/kubernetes/llmd-base/ |
| 端点选择测试用例 | e2e/testcases/llmd_semantic_endpoint_selection.go |
| 头常量定义 | src/semantic-router/pkg/headers/headers.go |
| extproc 路由头写入与清缓存响应 | src/semantic-router/pkg/extproc/processor_req_body_routing.go |
clear_route_cache schema 定义 |
src/semantic-router/pkg/configschema/router-config-v0.3.schema.json |
configOverride Helm 语义 |
deploy/helm/semantic-router/templates/_helpers.tpl、README |