Semantic Router 与 llm-d 双层路由调度:Kubernetes 上分离模型池选择与副本调度的完整实战

原创2026-10-11 13:34:191,968 阅读
文章标签:后端API网关模型推理服务AI Agent

Semantic Router 与 llm-d 双层路由调度:Kubernetes 上分离模型池选择与副本调度的完整实战

本篇技术指南以仓库 deploy/kubernetes/llmd-base 目录下的 llm-d 集成示例为主线,讲解如何在 Kubernetes 集群中把"语义层选模型池"与"llm-d 端点选择器选副本"两级路由决策解耦部署。读完本文,你将掌握 InferencePool、Endpoint Picker(EPP)与 HTTPRoute 的编排关系、完整的 kubectl 部署/验证/诊断命令,以及两层路由故障的定位方法,并了解如何在同一拓扑上叠加托管(hosted)模型后端。

架构:一次请求,两次路由决策

llm-d 是 Semantic Router 支持的 Inference Router 之一(与 vLLM Router、AIBrix 网关并列,参见 Integrate with llm-d 的前置说明)。本示例把两次路由决策分离为:

  • Semantic Router:从请求信号(意图、策略、recipe 状态)中选出逻辑模型或模型池;
  • llm-d 端点选择器(EPP):在选定的池内,依据负载、前缀缓存、KV 缓存利用率等端点信息选出一个健康副本。

原文档给出的数据流如下:

client -> Istio Gateway -> Semantic Router model choice
                              |
                              +-> HTTPRoute -> InferencePool -> llm-d EPP -> replica

在部署时有一条重要边界:不要让两个系统做同一个决策。Semantic Router 不选 Pod,llm-d 不决定业务策略或模型族归属。Semantic Router 以 ExtProc 方式附着在网关下行路径上,把选中的 provider model 写入 x-selected-model 请求头;网关在收到该请求头后重新评估 HTTPRoute,把请求转发给对应的 InferencePool;池内的 llm-d 端点选择器最终把流量调度到具体副本。这与 Istio 示例 中"网关 -> HTTPRoute -> 模型 Service"的直连拓扑相比,多出了一层池内调度,因此可以在不改变语义路由策略的前提下,让 vLLM 副本的调度(负载均衡、KV/前缀缓存命中)独立演进。

部署前置条件

本示例复用 Istio 示例中的模型 Service 与标签,因此在应用 llm-d 专属资源之前,必须先完成两件事:

  1. 完整走通 Istio 示例:模型后端(vLlama3 / vPhi4)、Gateway、Semantic Router(含 ExtProc 挂载)均就绪;
  2. 独立部署并验证 llm-d 本身:其 release 工件、CRD、chart 与插件配置是整体演进的,应使用同一受支持的 llm-d release,而不是混用不同版本的清单。

端到端的集成契约(出自 Integrate with llm-d)要求以下名称对齐:

Name Owner Requirement
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 Model server 池内副本接受网关转发来的模型身份

本示例的具体映射关系如下(端点选择器清单当前使用的正是 Istio 示例的模型 Service 与标签):

Router alias InferencePool Backend selector
llama3-8b vllm-llama3-8b-instruct app: vllm-llama3-8b-instruct
phi4-mini vllm-phi4-mini app: phi4-mini

资源清单一览

deploy/kubernetes/llmd-base/ 目录下的资源按职责可分为三组:

此外目录内还有两个可选用文件:inference-sim.yaml(无 GPU 环境下的 llm-d 推理模拟器,见下文"模拟器选项")和 llmd+public-llm/(本地池 + 托管模型的扩展示例,见"延伸"小节)。

模拟器选项:inference-sim.yaml

从清单内容看,inference-sim.yaml 使用 ghcr.io/llm-d/llm-d-inference-sim:v0.6.1 镜像创建 llama3-8b 与 phi4-mini 两个各 2 副本的 Deployment 及同名 ClusterIP Service(监听 8000 端口)。它模拟模型服务的推理行为,适合在无 GPU 的开发/测试集群中先行验证 llm-d 控制面链路;生产环境仍应以真实 vLLM 后端(Istio 示例的 vLlama3/vPhi4)为准。

深入解析 InferencePool 与端点选择器

每个模型池清单都由五段组成:InferencePool、EPP 的 Service / ServiceAccount / Deployment、以及共用的插件 ConfigMap 与 RBAC Role/RoleBinding。以 inferencepool-llama.yaml 为例:

InferencePool 本体

apiVersion: inference.networking.k8s.io/v1
kind: InferencePool
metadata:
  name: vllm-llama3-8b-instruct
spec:
  targetPorts:
  - number: 8000
  selector:
    matchLabels:
      app: vllm-llama3-8b-instruct
  endpointPickerRef:
    name: vllm-llama3-8b-instruct-epp
    kind: Service
    port:
      number: 9002
  • selector.matchLabels.app 必须与 Istio 示例中模型 Service 的标签一致(本示例为 vllm-llama3-8b-instruct),llm-d 据此发现池内端点;
  • targetPorts 是池内副本(vLLM)的监听端口 8000;
  • endpointPickerRef 指向 EPP 的 gRPC Service(9002 端口),llm-d 的控制面通过该引用把池与调度器绑定。

EPP Deployment 与关键启动参数

池清单中同时定义了 EPP 服务与部署,镜像为 ghcr.io/llm-d/llm-d-router-endpoint-picker:v0.10.0。其启动参数含义如下:

参数 取值 说明
--pool-name vllm-llama3-8b-instruct 本 EPP 服务的池名,必须与 InferencePool 名称一致
--pool-namespace default 池所在命名空间
--pool-group inference.networking.k8s.io 池的 API 组
--grpc-port / --grpc-health-port 9002 / 9003 gRPC 调度端口与健康检查端口
--config-file /config/default-plugins.yaml 插件配置文件,挂载自 plugins-config ConfigMap
--zap-encoder json 结构化日志格式,便于采集
--metrics-endpoint-auth false 关闭 metrics 端点鉴权(本示例环境)

探针方面,liveness/readiness 均使用 grpc 协议探测 9003 端口,并显式声明 service: inference-extension(Inference Extension 的 gRPC 健康服务),initialDelaySeconds: 5、periodSeconds: 10;容器同时暴露 9090 端口作为 metrics。Pod 的 terminationGracePeriodSeconds: 130 是为了给排空中的请求留出完成窗口。

调度插件配置

两个池清单共享同一个 plugins-config ConfigMap,其内容为 llm-d.ai/v1alpha1 的 EndpointPickerConfig:

apiVersion: llm-d.ai/v1alpha1
kind: EndpointPickerConfig
plugins:
- type: queue-scorer
- type: kv-cache-utilization-scorer
- type: prefix-cache-scorer
- type: metrics-data-source
  parameters:
    scheme: http
    path: /metrics
    insecureSkipVerify: true
- type: core-metrics-extractor
schedulingProfiles:
- name: default
  plugins:
  - pluginRef: queue-scorer
    weight: 2
  - pluginRef: kv-cache-utilization-scorer
    weight: 2
  - pluginRef: prefix-cache-scorer
    weight: 3

默认调度配置 default 中 prefix-cache-scorer 权重最高(3),queue-scorer 与 kv-cache-utilization-scorer 各为 2,即池内选副本时优先考虑前缀缓存命中,其次兼顾队列长度与 KV 缓存占用;指标数据经 metrics-data-source(HTTP /metrics,跳过 TLS 校验)采集后由 core-metrics-extractor 提取。注意:插件类型、权重与 release 版本强相关,升级 llm-d 时应同步核对该配置。

RBAC 最小权限

pod-read Role 授予 EPP 对三类资源的 get/watch/list 权限:

  • inference.networking.x-k8s.io 组的 inferenceobjectives、inferencemodelrewrites、inferencepools;
  • llm-d.ai 组的 inferenceobjectives、inferencemodelrewrites;
  • inference.networking.k8s.io 组的 inferenceobjectives、inferencepools;
  • 核心组的 pods。

随后通过 RoleBinding(pod-read-binding-llama / pod-read-binding-phi4)分别绑定到各自 EPP 的 ServiceAccount,保证每个调度器只能读取自己池所需的元数据。

HTTPRoute 与 DestinationRule:把语义选择落到池

池路由 httproute-llama-pool.yaml 是两层决策之间的"接缝":

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: vsr-llama8b
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

关键点:

  • matches.headers 以 Exact 类型匹配 x-selected-model: llama3-8b,这是 Semantic Router 写入的请求头;phi4-mini 路由同理匹配 x-selected-model: phi4-mini;
  • backendRefs 的 group: inference.networking.k8s.io、kind: InferencePool 表明后端不再是普通 Service,而是 llm-d 的池——路由本身不配置池或端点选择器,那部分完全归属 llm-d release;
  • request: 300s 的超时设置与 Istio 示例保持一致。

DestinationRule 则为 EPP 服务建立 TLS 策略(dest-rule-epp-llama.yaml):

apiVersion: networking.istio.io/v1
kind: DestinationRule
metadata:
  name: epp-llama-8b-insecure-tls
spec:
  host: vllm-llama3-8b-instruct-epp
  trafficPolicy:
    tls:
      mode: SIMPLE
      insecureSkipVerify: true

在 Istio 网格内,网关与 EPP 之间的 gRPC 流量以 SIMPLE 模式做 TLS origination 并跳过证书校验;phi4 版本对应 dest-rule-epp-phi4.yaml,host 为 vllm-phi4-mini-epp。

仓库的 e2e 测试 llmd_inference_gateway_health.go 正是围绕这套契约编写的:它逐一验证 InferencePool 存在、其 spec.endpointPickerRef.name 与 EPP Service 名一致(vllm-llama3-8b-instruct-epp / vllm-phi4-mini-epp)、HTTPRoute 的 backendRef 是预期的 InferencePool、路由中存在 x-selected-model 的 header 匹配,并检查 EPP Service 的 Pod 运行状态——可作为部署后自动校验的参照。

别名改动契约:如果修改模型别名,必须把 Router 的 model card、HTTPRoute 的 header match、InferencePool 名称、EPP 的 --pool-name 参数以及后端标签作为一个整体同步更新,任何一处脱节都会导致路由不匹配或 ResolvedRefs=False。

部署:应用 llm-d 资源

在完成 Istio 示例(模型、Gateway、Router 均已部署)之后,从仓库根目录执行:

kubectl apply -f deploy/kubernetes/llmd-base/inferencepool-llama.yaml
kubectl apply -f deploy/kubernetes/llmd-base/inferencepool-phi4.yaml

kubectl apply -f deploy/kubernetes/llmd-base/dest-rule-epp-llama.yaml
kubectl apply -f deploy/kubernetes/llmd-base/dest-rule-epp-phi4.yaml

kubectl apply -f deploy/kubernetes/llmd-base/httproute-llama-pool.yaml
kubectl apply -f deploy/kubernetes/llmd-base/httproute-phi4-pool.yaml

务必不要同时应用 Istio 示例中的"直连 Service 路由"(deploy/kubernetes/istio/httproute-llama3-8b.yaml 与 httproute-phi4-mini.yaml)。两套路由匹配的是相同的 x-selected-model 取值,会造成路由所有权歧义,流量可能在 Service 与 Pool 之间漂移。正确做法是:本示例只保留池路由,直连路由由 Istio 示例的清理流程移除。

验证两层路由

1. 检查资源状态

kubectl get inferencepools
kubectl get httproutes
kubectl get deployments,services
kubectl get pods --namespace vllm-semantic-router-system

检查路由与池的**条件(conditions)**而非与某个保存的示例对比 Pod 名称:

kubectl describe httproute vsr-llama8b
kubectl describe inferencepool vllm-llama3-8b-instruct

HTTPRoute 的 ResolvedRefs=True 且 InferencePool 状态正常,即代表池路由已被网关接受。

2. 发送自动选择请求

minikube 环境下动态获取网关地址,然后发送一条 model: auto 请求,让 Semantic Router 依据请求语义自动选择模型池:

GATEWAY_URL="$(minikube service inference-gateway-istio --url)"
curl --fail-with-body "$GATEWAY_URL/v1/chat/completions" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "auto",
    "messages": [{"role": "user", "content": "Explain a Linux process."}],
    "max_tokens": 64,
    "temperature": 0
  }'

3. 分层验证

用 model: llama3-8b 与 model: phi4-mini 分别发送请求,可以把显式路由解析与语义模型选择隔离开来:显式请求直接命中对应 HTTPRoute,若这条链路失败,说明问题出在池/EPP 层而非语义层;auto 请求则额外覆盖了 Router 的决策与 x-selected-model 写入。

验证时应同时核对三个结论(而不是只看 HTTP 200):

  • 响应中带有所选模型(x-vsr-selected-model 等路由头/追踪信息);
  • 对应的 HTTPRoute 报告 ResolvedRefs=True;
  • llm-d 从预期的 InferencePool 中选出了一个就绪端点。

多副本注意:本示例每个池只有 1 个副本,主要演示控制面集成,无法体现副本级调度收益。只有当池内存在多个后端副本时,才适合验证 llm-d 的端点选择逻辑(队列、前缀缓存评分等)。

故障诊断

原文档给出的排查思路可归纳为下表:

症状 检查方向
HTTPRoute 存在未解析引用 核对已安装的 Inference Extension API 版本与 InferencePool 名称/命名空间
EPP 未就绪 查看 EPP Deployment 日志与其 RBAC 资源
请求绕过池 删除指向同一 x-selected-model 的直连 Service 路由
选错模型池 比对 Router 的 alias 与发出的 x-selected-model 值,以及 HTTPRoute 的 header match(含大小写)

常用日志命令:

kubectl logs deployment/llm-d-inference-scheduler-llama3-8b
kubectl logs deployment/inference-gateway-istio -c istio-proxy
kubectl logs deployment/semantic-router \
  --namespace vllm-semantic-router-system

其中 llm-d-inference-scheduler-llama3-8b 是池清单定义的 EPP Deployment 名称(phi4 对应 llm-d-inference-scheduler-phi4-mini);网关侧日志重点看 istio-proxy 容器的 ext_proc 调用与路由匹配结果。若 Semantic Router 被绕过(未触发决策),还需回到 envoyfilter.yaml 核对网关工作负载标签与 Router 的 gRPC Service 地址。

清理

按依赖逆序删除本示例资源(先删路由,再删策略,最后删池):

kubectl delete -f deploy/kubernetes/llmd-base/httproute-phi4-pool.yaml
kubectl delete -f deploy/kubernetes/llmd-base/httproute-llama-pool.yaml
kubectl delete -f deploy/kubernetes/llmd-base/dest-rule-epp-phi4.yaml
kubectl delete -f deploy/kubernetes/llmd-base/dest-rule-epp-llama.yaml
kubectl delete -f deploy/kubernetes/llmd-base/inferencepool-phi4.yaml
kubectl delete -f deploy/kubernetes/llmd-base/inferencepool-llama.yaml

共享的 Router、Gateway 与模型资源,请按 Istio 示例 的清理流程移除(deploy/kubernetes/istio/ 下的 gateway.yaml、envoyfilter.yaml、destinationrule.yaml 及 vLlama3/vPhi4 等)。

延伸:在 llm-d 拓扑上叠加托管模型后端

deploy/kubernetes/llmd-base/llmd+public-llm/(参见其 README)把上述拓扑扩展到"本地池 + 托管 OpenAI 兼容后端"的混合场景:Semantic Router 可任选本地 llama3-8b(池 + EPP 支撑)或 gpt-4o-mini(由 Istio 出口 Service + HTTPRoute 表示)。涉及文件与作用:

文件 用途
config.yaml.openai Router 的 model cards、provider 元数据与决策(新增 openai provider 及 gpt-4o-mini)
svc-openai.yaml 指向 api.openai.com 的 ExternalName Service(443 端口)
svc-entry-openai.yaml Istio ServiceEntry 出口注册(MESH_EXTERNAL、DNS 解析)
dest-rule-openai.yaml 托管端点的 TLS origination(SIMPLE 模式)
httproute-openai.template 匹配 x-selected-model: gpt-4o-mini、改写 Host 与 Authorization 头的路由模板

其 README 特别强调安全边界:httproute-openai.template 中的授权头是占位符,直接替换凭据会把它写入 Kubernetes API 对象,可能经 Git、shell 历史、日志或可读 HTTPRoute 的用户泄露;共享集群应通过读取 Secret 的网关扩展或出口代理注入凭据。托管模型可能产生费用并把请求内容发送给第三方,启用前需确认数据治理要求。该扩展示例的正确落地顺序是:先完成 Istio 示例 与本 llm-d 示例,再接入托管后端。

生产化要点

  • 版本钉扎:Semantic Router、llm-d、网关、CRD 与模型服务镜像应固定版本,llm-d 的清单与插件配置需配套升级;
  • 凭据管理:provider 凭据不要放进 Router YAML,交由持有凭据的组件(如 Secret 绑定的出口代理)管理;
  • 失败语义:明确失败策略——fail-open 的 ExtProc 策略可能绕过语义策略,fail-closed 则会在 Router 不可用时阻断全部流量;
  • 分层验证:先直连池、再测语义选择、最后测端点调度,分阶段验证后再做联合发布。

综上所述,deploy/kubernetes/llmd-base 示例的价值在于把"选什么模型"与"选哪个副本"两类关注点彻底解耦:语义路由策略的调整不再牵动副本调度逻辑,而 llm-d 的调度插件升级也无需改动 Router 的决策配置。两套系统仅通过 x-selected-model 请求头与 InferencePool 后端引用这一个契约点衔接,边界清晰、可独立演进,这正是该拓扑在生产环境中的核心优势。

登录后查看全文
semantic-router