Semantic Router 集成 llm-d:让语义路由选模型池,llm-d 在池内调度副本

原创2026-10-11 17:38:531,818 阅读
文章标签:后端API网关模型推理服务AI Agent

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 网关集成 并列。当请求需要同时做出“选哪个池”和“选池内哪个副本”两个决策时,采用如下拓扑:

  1. Semantic Router 从请求意图、策略与 recipe 状态中选择逻辑模型或模型池;
  2. 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 流程依次为:

  1. 安装 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)按最佳努力处理;
  2. 安装 Istio(测试中版本 1.28.0),并通过 ENABLE_GATEWAY_API_INFERENCE_EXTENSION=true 启用 Inference Extension 支持;
  3. 部署模型仿真器(inference-sim.yaml)、llm-d 调度器与两个 InferencePool(llama3-8b 与 phi4-mini);
  4. 部署 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."}]
  }'

第三层:验证三个决策,而不是只看状态码。 文档列出三条必须全部满足的验证点:

  1. 响应包含期望的 x-vsr-selected-model 值;
  2. 匹配的 HTTPRoute 报告 ResolvedRefs=True;
  3. 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
登录后查看全文
semantic-router