Semantic Router 与 llm-d 双层路由调度:Kubernetes 上分离模型池选择与副本调度的完整实战
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 专属资源之前,必须先完成两件事:
- 完整走通 Istio 示例:模型后端(vLlama3 / vPhi4)、Gateway、Semantic Router(含 ExtProc 挂载)均就绪;
- 独立部署并验证 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/ 目录下的资源按职责可分为三组:
- 模型池与端点选择器:inferencepool-llama.yaml、inferencepool-phi4.yaml;
- 池路由:httproute-llama-pool.yaml、httproute-phi4-pool.yaml;
- EPP 流量策略:dest-rule-epp-llama.yaml、dest-rule-epp-phi4.yaml。
此外目录内还有两个可选用文件: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 后端引用这一个契约点衔接,边界清晰、可独立演进,这正是该拓扑在生产环境中的核心优势。