在 Kubernetes 上集成 vLLM Production Stack 与 Semantic Router:MoM 语义路由生产部署实战
在 Kubernetes 上集成 vLLM Production Stack 与 Semantic Router:MoM 语义路由生产部署实战
本篇技术指南完整讲解如何在 Kubernetes 集群中,将 vLLM Semantic Router(智能 Mixture-of-Models 路由器)作为 Envoy 外部处理器(ExtProc)接入 vLLM Production Stack,构建「语义智能层 + 基础设施优化层」的统一推理栈。读完本文,你将掌握 vLLM Production Stack 的 Helm 部署、Semantic Router 的 OCI Chart 安装、Envoy AI Gateway 路由配置,以及通过 OpenAI 兼容 API 验证端到端语义路由的完整操作流程。
一、背景:什么是 vLLM Semantic Router?
vLLM Semantic Router 是一个智能的 Mixture of Models(MoM)路由器,以 Envoy 外部处理器的形式运行,将 OpenAI API 兼容请求按语义路由到最合适的后端模型。借助基于 BERT 的分类能力,它把请求(如 math、code、creative、general 等类别)匹配到专业模型,从而同时提升响应质量与成本效率。
其核心能力包括:
- 模型自动选择:将数学、创意写作、代码和通用查询路由到最匹配的模型,实现请求级模型混排;
- 安全与隐私:PII(个人身份信息)检测、Prompt Guard(越狱/注入防护)以及敏感提示词的定向安全路由;
- 性能优化:语义缓存(Semantic Cache)与更精准的工具选择,降低延迟和 Token 消耗;
- 架构特性:与 Envoy ExtProc 紧密集成;同时提供 Go 与 Python 两种实现;生产就绪且可水平扩展;
- 监控:Grafana 仪表板、Prometheus 指标与分布式追踪,提供全链路可见性。
在 deploy/helm/semantic-router 目录下,仓库提供了一整套 Helm Chart(含 values、CRD、模板与 README),覆盖 standalone(独立网关)与 extproc(接入外部网关)两种部署模式,本教程使用的正是 extproc 模式。
二、为什么集成:构建统一的推理堆栈
vLLM Production Stack 是面向大规模 vLLM 部署的云原生参考系统,它提供了多种部署方式来启动 vLLM 服务器、将流量定向到不同模型,通过 Kubernetes API 执行服务发现和容错,并原生支持轮询(round-robin)、基于会话(session-based)、前缀感知(prefix-aware)、KV 感知(KV-aware)以及分解预填充(disaggregated-prefill)等多种路由逻辑,且原生支持 LMCache。
Semantic Router 则在此基础上叠加了一个系统智能层:对每个用户请求进行分类,从模型池中选出最合适的模型,注入领域特定的系统提示词(System Prompt),执行语义缓存,并强制执行企业级安全检查(如 PII 与越狱检测)。
两者的分工可以概括为:Semantic Router 决定用户「问什么」(请求语义与模型选择),Production Stack 优化请求「如何执行」(基础设施与推理效率)。结合后,它们共同提供:
| 维度 | 说明 |
|---|---|
| 系统级智能 | 理解用户意图、选择正确模型、注入合适的系统提示词并预过滤工具 |
| 基础设施效率 | 无需修改应用代码即可从单实例扩展到分布式 vLLM 部署;在多个模型间路由流量并享受 LMCache 原生支持 |
| 安全与合规 | 在 PII 与越狱提示词到达模型之前将其拦截 |
| 可观测性 | 通过 Production Stack 的 Grafana 仪表板监控请求、延迟和 GPU 使用情况,并追踪 Semantic Router 的决策 |
更详细的集成设计可参考仓库中的设计方案文档 production-stack-integration.md,其中明确列出了集成目标与非目标:Semantic Router 增强而非替换 Production Stack 路由,当 Semantic Router 不可用时,Production Stack 会回退到默认模型路由继续服务;集成仅使用 Envoy ExtProc gRPC 或 HTTP 标头注入等标准 API,不修改 vLLM 或 Production Stack 内部。
三、端到端架构与请求流程
3.1 四层架构
从设计方案看,集成系统由四个层级组成:
- 网关与语义智能层:Envoy 网关接收 OpenAI 兼容请求,并通过 ExtProc gRPC 转发给 Semantic Router;Semantic Router 是无状态的 gRPC 服务,执行分类、安全过滤、语义缓存查找、模型/工具选择与请求丰富;Milvus(或 Redis)作为语义缓存向量库。
- 基础设施优化层(Production Stack):vLLM-router 服务负责服务发现、负载均衡和 KV Cache 感知路由,它解析 Semantic Router 注入的
model字段,将 Worker 过滤为提供该模型的实例;LMCache 可选地将 KV Cache 卸载到远程存储。 - 执行层(vLLM Worker):每个模型对应独立的 Worker 池(StatefulSet + 无头服务),由 Horizontal Pod Autoscaler 按 QPS 与 GPU 利用率弹性扩缩容。
- 存储层:语义缓存使用持久卷(Milvus)存储嵌入与响应;KV Cache 使用 GPU 内存(热)、系统内存或 NVMe(温/冷),LMCache 可在实例间卸载共享。
3.2 请求处理流水线
一次完整的 chat completions 请求会经历:
- 客户端向网关发送
POST /v1/chat/completions请求; - Envoy 通过 ExtProc gRPC 将请求体与标头交给 Semantic Router;
- Semantic Router 依次执行:安全过滤(PII/Jailbreak)→ 语义缓存查找 → 多信号分类(关键字匹配 + 嵌入相似性 + BERT 分类)→ 模型与工具选择 → 请求丰富(注入系统提示词、改写
model字段、附加X-VSR-Category/X-VSR-Model等路由标头)→ 返回给 Envoy; - Envoy 将丰富后的请求转发给 Production Stack 路由;
- vLLM-router 做服务发现,按轮询/会话/前缀/KV 感知策略选择 Worker;
- 选中的 vLLM Worker 使用注入的系统提示词完成推理,复用 KV Cache 减少预填充;
- Semantic Router 将查询嵌入与响应写入语义缓存(可配置 TTL);
- Envoy 将响应返回客户端,并可选附带可观测性标头。
3.3 双层缓存策略
集成利用了互补的两层缓存:
| 场景 | 语义缓存 | KV Cache | 结果 |
|---|---|---|---|
| 精确语义匹配 | 命中 | 不适用 | 立即返回缓存响应,零推理 |
| 部分匹配/重叠 | 未命中 | 命中 | 执行推理但复用 KV Cache,降低延迟 |
| 全新查询 | 未命中 | 未命中 | 完整推理,正常分类与 Worker 路由 |
四、前置条件
开始部署前,请确认环境已具备:
- kubectl:Kubernetes CLI 工具;
- Helm:Kubernetes 包管理器;
- Kubernetes 集群:kind、minikube、GKE 等均可(本教程以 kind 为例)。
五、步骤 1:部署 vLLM Production Stack
首先使用 Helm 部署一个最小化的 vLLM Production Stack,并指定 values 文件(示例 values 文件 tutorials/assets/values-23-SR.yaml 位于 vLLM Production Stack 上游教程中,以下为其参考内容):
helm repo add vllm-production-stack https://vllm-project.github.io/production-stack
helm install vllm-stack vllm-production-stack/vllm-stack -f ./tutorials/assets/values-23-SR.yaml
示例 values 文件内容如下(可对照注释理解每个字段):
servingEngineSpec:
runtimeClassName: ""
strategy:
type: Recreate
modelSpec:
- name: "qwen3" # 模型池名称
repository: "lmcache/vllm-openai" # vLLM 推理镜像
tag: "v0.3.7"
modelURL: "Qwen/Qwen3-8B" # HuggingFace 模型
pvcStorage: "50Gi" # 模型权重持久卷大小
vllmConfig:
# maxModelLen: 131072
extraArgs: ["--served-model-name", "Qwen/Qwen3-8B", "qwen3"]
replicaCount: 2 # 该模型的 Worker 副本数
requestCPU: 8
requestMemory: "16Gi"
requestGPU: 1
routerSpec:
repository: lmcache/lmstack-router # Production Stack 路由镜像
tag: "latest"
resources:
requests:
cpu: "1"
memory: "2G"
limits:
cpu: "1"
memory: "2G"
routingLogic: "roundrobin" # 路由逻辑:轮询
sessionKey: "x-user-id" # 基于会话路由的会话键
部署完成后,识别 chart 创建的路由服务的 ClusterIP 与端口(服务名称可能略有差异):
kubectl get svc vllm-router-service
# 记录路由服务的 ClusterIP 和端口(例如 10.97.254.122:80)
注意:该地址(<vllm-router-service-ip>:80)将在下一步中作为 Semantic Router 的后端 endpoint 使用。
六、步骤 2:部署 vLLM Semantic Router 并指向 vLLM Router 服务
Semantic Router 的部署采用「Helm OCI Chart 安装 Router + Envoy Gateway / Envoy AI Gateway 提供网关能力」的组合方式。相关清单文件均可在仓库中找到:
- Semantic Router 的 AI Gateway values:deploy/kubernetes/ai-gateway/semantic-router-values/values.yaml;
- 演示 LLM 后端:deploy/kubernetes/ai-gateway/aigw-resources/base-model.yaml;
- Gateway API 路由资源:deploy/kubernetes/ai-gateway/aigw-resources/gwapi-resources.yaml。
6.1 安装 Semantic Router
# 从 GHCR OCI 仓库部署 vLLM Semantic Router 并使用自定义 values
# (可选)如果使用镜像代理,请添加:--set global.imageRegistry=<your-registry>
helm install semantic-router oci://ghcr.io/vllm-project/charts/semantic-router \
--version v0.0.0-latest \
--namespace vllm-semantic-router-system \
--create-namespace \
-f deploy/kubernetes/ai-gateway/semantic-router-values/values.yaml
# 等待部署可用(模型下载可能需要数分钟)
kubectl wait --for=condition=Available deployment/semantic-router \
-n vllm-semantic-router-system --timeout=600s
注意:values 文件包含 Semantic Router 的完整配置(模型、类别、路由规则等),请下载 values.yaml 后按你的 vLLM Production Stack 设置自定义,尤其是其中
providers.models[].backend_refs[].endpoint需指向你在步骤 1 中记录的 vllm-router-service 地址。
6.2 安装 Envoy Gateway 与 Envoy AI Gateway
# 安装 Envoy Gateway
helm upgrade -i eg oci://docker.io/envoyproxy/gateway-helm \
--version v0.0.0-latest \
--namespace envoy-gateway-system \
--create-namespace \
-f deploy/kubernetes/ai-gateway/envoy-gateway-values.yaml # 若本地无此文件,请从 Envoy AI Gateway 官方 manifests 获取
# 安装 Envoy AI Gateway
helm upgrade -i aieg oci://docker.io/envoyproxy/ai-gateway-helm \
--version v0.0.0-latest \
--namespace envoy-ai-gateway-system \
--create-namespace
# 安装 Envoy AI Gateway CRDs
helm upgrade -i aieg-crd oci://docker.io/envoyproxy/ai-gateway-crds-helm \
--version v0.0.0-latest \
--namespace envoy-ai-gateway-system
# 等待 AI Gateway Controller 就绪
kubectl wait --timeout=300s -n envoy-ai-gateway-system \
deployment/ai-gateway-controller --for=condition=Available
6.3 创建演示 LLM 后端与 AI Gateway 路由
# 应用 LLM 演示后端(vllm-llama3-8b-instruct 部署 + Service + AIServiceBackend + Backend)
kubectl apply -f deploy/kubernetes/ai-gateway/aigw-resources/base-model.yaml
# 应用 AI Gateway 路由(GatewayClass/Gateway/ClientTrafficPolicy/AIGatewayRoute/EnvoyPatchPolicy)
kubectl apply -f deploy/kubernetes/ai-gateway/aigw-resources/gwapi-resources.yaml
6.4 关键清单文件解读
base-model.yaml(查看完整文件)定义了一个演示推理后端:
Deployment vllm-llama3-8b-instruct:运行ghcr.io/llm-d/llm-d-inference-sim:v0.5.0推理模拟器,通过--lora-modules预注册 6 个专家 LoRA(math-expert、science-expert、social-expert、humanities-expert、law-expert、general-expert),端口 8000,并配置了 startup/liveness/readiness 探针;Service:ClusterIP 类型,暴露 8000 端口;AIServiceBackend:声明后端使用 OpenAI schema;Backend(gateway.envoyproxy.io):将 FQDNvllm-llama3-8b-instruct.default.svc.cluster.local:8000绑定为网关可寻址端点。
gwapi-resources.yaml(查看完整文件)定义了网关控制面:
GatewayClass与Gateway:由 Envoy Gateway 控制器驱动,HTTP 监听 80 端口;ClientTrafficPolicy:将连接 buffer 上限从默认 32KiB 提升到 50MiB——这是 AI 负载(大请求体)所必需的,默认值不足以承载 LLM 请求;AIGatewayRoute:按请求头x-ai-eg-model的精确值(math-expert、science-expert、social-expert、humanities-expert、law-expert、general-expert)将流量路由到对应后端,并为每个规则设置 60s 请求超时;EnvoyPatchPolicy:以 JSONPatch 方式在 Gateway 的默认过滤器链中注入semantic-router-extproc过滤器(type 为envoy.extensions.filters.http.ext_proc.v3.ExternalProcessor),通过envoyGrpc连接到semantic-router.vllm-semantic-router-system:50051,并设置message_timeout: 60s、请求/响应体均为 BUFFERED 模式。mutation_rules.allow_expression限定了 ext_proc 只能修改x-envoy-upstream-rq-timeout-ms等少量 Envoy 路由头,从而保证可靠性块(reliability block)能安全传递到 Envoy 路由器。
七、理解 AI Gateway values:路由决策与信号配置
deploy/kubernetes/ai-gateway/semantic-router-values/values.yaml 是本次集成中 Semantic Router 的核心配置,包含以下关键区块:
7.1 网关模式与 Provider
gateway:
mode: extproc # 网关通过 ext_proc 调用 Router
config:
version: v0.3
providers:
defaults:
model: general-expert # 默认兜底模型
reasoning_effort: high
models:
- name: base-model
reasoning:
family: qwen3
backend_refs:
- name: local-vllm
provider: vllm
endpoint: vllm-llama3-8b-instruct.default.svc.cluster.local:8000
weight: 1
gateway.mode: extproc:Router 不再自行监听 HTTP,而是向 Envoy 提供 ext_proc gRPC(端口 50051);providers.models[].backend_refs[].endpoint:对接你的 vLLM Production Stack 时,把这里改成步骤 1 记录的vllm-router-service地址(如10.97.254.122:80),即可让 Router 把选中的模型请求转发给 Production Stack 路由;weight:后端权重,用于负载分配。
7.2 路由决策(decisions)
values 中预置了 14 个决策,覆盖 business、law、psychology、biology、chemistry、history、health、economics、math、physics、computer science、philosophy、engineering 等专业领域,外加 thinking_decision(复杂推理)与 general_decision(兜底)。以 math 为例:
- name: math_decision
description: Mathematics and quantitative reasoning
priority: 10
rules:
operator: OR
conditions:
- type: domain
name: math
modelRefs:
- model: base-model
lora_name: math-expert # 命中后挂载 math-expert LoRA
use_reasoning: true # 启用深度推理(chain-of-thought)
plugins:
- type: system_prompt
configuration:
enabled: true
system_prompt: You are a mathematics expert. Provide step-by-step solutions, show your work clearly, and explain mathematical concepts in an understandable way.
mode: replace # 替换默认系统提示词
关键字段含义:
priority:决策优先级,数值越大优先级越高(thinking_decision为 20,general_decision为 1,兜底最低);rules.operator/rules.conditions:条件组合(OR/AND),条件类型为domain(领域分类)或keyword(关键字命中);modelRefs[].lora_name:命中后使用哪个专家 LoRA 适配器;modelRefs[].use_reasoning:是否启用推理模式(chemistry/math/physics/thinking 等启用,其余关闭);plugins:请求增强插件,system_prompt注入领域系统提示词(mode: replace表示整体替换),response_cache启用响应语义缓存(如similarity_threshold: 0.8)。
部分决策(如 psychology、health、general)使用 response_cache 插件而非 system_prompt,用于高频相似问题的语义缓存命中。
7.3 信号(signals)
signals 定义分类所需的信号源:
signals:
keywords:
- name: thinking
operator: OR
keywords: [urgent, immediate, asap, think, careful]
case_sensitive: false
domains:
- name: business
description: Business, corporate strategy, management, finance, marketing
# ... 共 14 个领域定义
- name: other
description: General knowledge and miscellaneous topics
keywords:快速路径的关键字信号,命中即可触发对应决策(如thinking_decision);domains:由 BERT/ModernBERT 分类器输出的领域类别,与 decisions 中的conditions.type: domain一一对应。
7.4 模型卡(modelCards)与全局配置
modelCards:
- name: base-model
loras:
- name: science-expert
description: 'Specialized for science domains: biology, chemistry, physics, health, engineering'
# ... math-expert / social-expert / law-expert / humanities-expert / general-expert
global:
router:
strategy: priority # 决策策略:按优先级匹配
services:
response_api:
enabled: true
store_backend: memory
ttl_seconds: 86400
max_responses: 1000
api:
batch_classification:
max_batch_size: 100
max_concurrency: 8
metrics: { enabled: true, sample_rate: 1.0, duration_buckets: [...], size_buckets: [...] }
stores:
response_cache:
enabled: true
backend_type: memory
similarity_threshold: 0.8
max_entries: 1000
ttl_seconds: 3600
eviction_policy: fifo
embedding_model: mmbert
integrations:
tools:
enabled: true
top_k: 3
similarity_threshold: 0.2
tools_db_path: config/tools_db.json
fallback_to_empty: true
modelCards:声明模型及其可挂载的 LoRA 专家列表;global.router.strategy: priority:按决策优先级路由;response_api:响应记录 API(内存后端,TTL 86400s);response_cache:语义缓存(内存后端,相似度阈值 0.8,FIFO 淘汰,最多 1000 条,TTL 3600s),使用mmbert嵌入模型;tools集成:工具预选择(top_k=3),减少不必要的工具调用。
若使用 responses-state.yaml 这类面向 ext_proc 的轻量 values,则通过
configOverride原子替换示例路由配置,只保留协议元数据(openai/gpt-oss-20b)并关闭路由决策、缓存与工具集成,适合网关完全接管路由策略的场景。
八、步骤 3:测试部署
8.1 端口转发到 Envoy 服务
export ENVOY_SERVICE=$(kubectl get svc -n envoy-gateway-system \
--selector=gateway.envoyproxy.io/owning-gateway-namespace=default,gateway.envoyproxy.io/owning-gateway-name=semantic-router \
-o jsonpath='{.items[0].metadata.name}')
kubectl port-forward -n envoy-gateway-system svc/$ENVOY_SERVICE 8080:80
8.2 发送对话补全请求
curl -i -X POST http://localhost:8080/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "MoM",
"messages": [
{"role": "user", "content": "What is the derivative of f(x) = x^3?"}
]
}'
请求中的 "model": "MoM" 是语义路由入口:网关将该请求交给 Semantic Router 分类(这里会命中 math 领域),Router 注入数学专家系统提示词、选择 math-expert 模型并改写 model 字段,随后 Production Stack 路由把请求送达承载 math-expert 的 vLLM Worker。返回 200 即表示整条语义路由链路已打通。
九、生产化要点(基于 Helm Chart values)
除上述集成配置外,deploy/helm/semantic-router/values.yaml 还提供了一批直接影响生产运行的参数:
gateway.mode:standalone(Router 自行监听config.listeners,默认)或extproc(接入 Envoy Gateway / Envoy AI Gateway / Istio / KServe / llm-d 等外部网关)。从旧版本升级时,若原有部署依赖外部网关,必须在升级前显式设置--set gateway.mode=extproc,否则旧监听端口(grpc-50051/http-8080)会与 ext_proc 及 Router API 冲突导致渲染失败;persistence:默认启用,size: 10Gi,Router 首次启动会在该 PVC 上自动下载内置模型(Vela Omni Mini 单独占用约 4.3GB);storageClassName留空用集群默认,设"-"表示渲染为空;startupProbe:failureThreshold: 360×periodSeconds: 10= 60 分钟模型下载总预算;下载期间会暂时禁用 liveness/readiness 探针,避免模型加载阶段被误杀;resources:默认 requests 3Gi/1 CPU、limits 7Gi/2 CPU——多副本部署需评估内存是否足够加载两套模型,否则可能 OOMKilled(参见下方 E2E 佐证);observability.alerts:可渲染 PrometheusRule,内置告警阈值如requestErrorRate: 0.05、completionLatencyP95Seconds: 30、cacheHitRate: 0.2、routingLatencyP95Seconds: 0.1等;safetyGuards.rejectMultiReplicaLocalLearningState: true:当 Router Learning 使用请求级本地状态时拒绝多副本部署,防止副本间学习状态发散;env.HF_TOKEN:通过hf-token-secret注入,用于下载 gated 模型(如embeddinggemma-300m),Secret 缺失时optional: true允许部署继续;global.imageRegistry:为镜像配置代理前缀(如国内镜像registry.cn-hangzhou.aliyuncs.com);- 依赖组件:可通过
dependencies.semanticCache.redis/milvus、dependencies.responseApi.redis/milvus、dependencies.observability.jaeger/prometheus/grafana按需启用 Redis/Milvus 语义缓存后端、响应 API 存储与可观测性组件。
十、清理
按依赖逆序删除整个部署:
# 删除 Gateway API 资源和演示 LLM
kubectl delete -f deploy/kubernetes/ai-gateway/aigw-resources/gwapi-resources.yaml
kubectl delete -f deploy/kubernetes/ai-gateway/aigw-resources/base-model.yaml
# 删除 Semantic Router
helm uninstall semantic-router -n vllm-semantic-router-system
# 删除 AI Gateway
helm uninstall aieg -n envoy-ai-gateway-system
helm uninstall aieg-crd -n envoy-ai-gateway-system
# 删除 Envoy Gateway
helm uninstall eg -n envoy-gateway-system
# 删除 vLLM Production Stack
helm uninstall vllm-stack
# 删除 kind 集群(可选)
kind delete cluster --name semantic-router-cluster
十一、故障排除
- 网关无法访问:检查 Gateway 状态(
kubectl get gateway semantic-router -n default)与 Envoy 服务(kubectl get svc -n envoy-gateway-system),确认 GatewayClass 已被 Envoy Gateway 控制器接受; - 推理池未就绪:
kubectl describeInferencePool(或对应 CR),并检查 controller 日志; - Semantic Router 无响应:检查其 Pod 状态与日志(
kubectl logs -n vllm-semantic-router-system deployment/semantic-router),重点关注模型下载是否完成、startupProbe 是否通过; - 返回错误代码:检查 production stack 路由日志,确认
backend_refs.endpoint指向的 vllm-router-service 可达且模型名称匹配。
十二、仓库中的端到端验证实现
本教程对应的集成流程在仓库中有一整套自动化测试实现可作为参考:e2e/profiles/production-stack/profile.go 定义了 production-stack 测试 profile,其执行流程与本教程一一对应:
- 部署共享网关栈(Semantic Router + Envoy AI Gateway + 演示 LLM);
- 将
semantic-router与vllm-llama3-8b-instruct扩缩容到 2 副本验证高可用; - 部署 Prometheus 采集指标;
- 等待栈稳定(包含 OOM 重启检测与回退逻辑,验证了生产化要点中「多副本内存评估」的现实意义);
- 执行测试矩阵:
multi-replica-health、load-balancing-verification、failover-during-traffic、performance-throughput、resource-utilization-monitoring,以及路由器智能层用例domain-classify、pii-detection、jailbreak-detection、semantic-cache。
这些用例覆盖了本教程部署形态下的高可用、负载均衡、故障转移、吞吐与语义智能(分类、安全、缓存)能力,是验证生产环境集成质量的现成工具。
至此,你已经完成了「vLLM Production Stack + vLLM Semantic Router + Envoy AI Gateway」三件套的完整部署,并理解了两层架构的分工、values 中决策/信号/模型卡的核心配置,以及如何通过 x-ai-eg-model 路由头与 ExtProc 过滤器打通语义路由链路。若需在真实环境中替换演示后端,只需将 values 中 backend_refs.endpoint 指向你的 vllm-router-service,并按业务领域增删 decisions 即可。