企业官网建设流程全解析

• 后端
• API网关
• 模型推理服务
• AI Agent

本篇技术指南讲解如何在 Kubernetes 集群中，把 vLLM Semantic Router（简称 vsr）与 LLM-D 分布式推理平台组合部署，并以 Istio Gateway（基于 Envoy 的 Kubernetes Gateway API 实现）作为推理网关。核心设计模式是双层分工：vsr 扮演「模型选择器（model picker）」，负责在多个完全不同的 LLM 模型之间挑选合适的后端；LLM-D 扮演「副本调度器（replica scheduler）」，负责在每个被选中的模型池（model pool）内部，把请求调度到等价模型的多个副本上。读完本文，你将掌握：两层路由各自职责的边界、从 Istio 基线部署增量叠加 LLM-D 的完整操作步骤、InferencePool/EPP 与 HTTPRoute 的配置方法，以及如何用model: auto验证语义路由与显式模型路由两种行为。

架构概览

本次部署由以下组件构成：

• vLLM Semantic Router：基于 Envoy External Processing（ExtProc）协议，为网关提供智能请求路由与处理决策；
• LLM-D：分布式推理平台，用于大规模 LLM 推理的水平扩展（scaleout）调度；
• Istio Gateway：Istio 对 Kubernetes Gateway API 的实现，底层使用 Envoy 代理；
• Gateway API Inference Extension：通过 ExtProc 服务器扩展 Gateway API 的推理相关附加 API（InferencePool、EndpointPicker 等 CRD）；
• 两个 vLLM 实例各服务一个模型：用于演示本拓扑中的语义路由。

理解本架构的关键在于区分两类路由决策：

因此，vsr 的模型选择能力与 LLM-D 的后端调度能力天然互补，二者并不重复。LLM-D 存在多种部署配置，其中一部分需要较大的硬件环境，本文演示的是 LLM-D 的 baseline 版本与 vsr 的组合，用于引入核心概念；这些概念同样适用于更复杂的 LLM-D 配置与 LLM-D 仓库中描述的生产级 well-lit paths。LLM-D 通常也把 Istio 作为默认网关（有无 vsr 均可），因此本文在 Istio 部署示例 的步骤与硬件基础之上继续叠加。

请求在两条路径上的流转关系（参考 llmd-base 目录说明）：

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

前置条件

开始之前，请确保已安装以下工具：

• Docker —— 容器运行时；
• minikube —— 本地 Kubernetes（minikube 与 kind 二选一即可）；
• kind —— Kubernetes in Docker；
• kubectl —— Kubernetes 命令行工具；
• istioctl —— Istio 命令行工具（本文清理阶段会用到）。

本文以 minikube 为例说明。与 Istio 部署指南 一致，本实验需要一台至少具备 2 块 GPU 的机器，以便在两个不同的 LLM base model 之间演示 vsr 的模型路由。若要在 CPU 环境运行，可以使用更小的模型并相应调整资源声明。

第一步：复用 Istio 指南的公共步骤

本指南建立在 vsr + Istio 部署之上，因此先按照 Istio 部署指南 的步骤创建本地 minikube 集群，推荐的创建参数如下：

# 创建集群 $ minikube start \ --driver docker \ --container-runtime docker \ --gpus all \ --memory no-limit \ --cpus no-limit # 验证集群就绪 $ kubectl wait --for=condition=Ready nodes --all --timeout=300s

第二步：安装 Istio Gateway、Gateway API 与 Inference Extension CRDs

按照 Istio 部署指南 中的描述，安装 Kubernetes Gateway API、Gateway API Inference Extension、Istio 控制平面以及一个 Istio Gateway 实例，并使用与指南相同的 Istio 版本。如果遵循 LLM-D 的 well-lit paths，这部分通常由 LLM-D 仓库中的 Gateway provider Helm charts 完成；本文手动搭建是为了与仓库内 Istio 指南保持通用、可复用，同时帮助读者理解 GIE/EPP 类部署与 LLM-D 部署之间公共的部分，以及 vsr 在两种场景下的用法。

安装正确后，可以通过以下命令确认 Gateway API 与 Inference Extension 的 CRD，以及 Istio Gateway 和 istiod 的 Pod 均已就绪：

kubectl get crds | grep gateway

kubectl get crds | grep inference

kubectl get pods | grep istio

kubectl get pods -n istio-system

第三步：部署两个 LLM 模型

与 Istio 部署指南 类似，部署两个不同的 LLM：meta-llama/Llama-3.1-8B-Instruct（别名llama3-8b）与microsoft/Phi-4-mini-instruct（别名phi4-mini），分别由两个独立的 vLLM 实例服务。LLM-D 部署文档中与之对应的部分是 LLM-D Model Service 的搭建；为简化起见，本指南不需要 LLM-D Model Service。

首先用环境变量HF_TOKEN中保存的 HuggingFace token 创建 Secret，然后依次应用清单（注意：清单路径以仓库根目录为基准，命令须在仓库根目录下执行）：

kubectl create secret generic hf-token-secret --from-literal=token=$HF_TOKEN

# 创建运行 llama3-8b 的 vLLM 服务 kubectl apply -f deploy/kubernetes/istio/vLlama3.yaml

首次运行时，模型下载加上 vLLM Pod 进入 READY 状态可能需要 10 分钟以上。同样地部署第二个 LLM（phi4-mini）并等待其 Pod 就绪：

# 创建运行 phi4-mini 的 vLLM 服务 kubectl apply -f deploy/kubernetes/istio/vPhi4.yaml

两个 vLLM 清单都包含 PVC（llama 为 40Gi、phi4-mini 为 20Gi）、Deployment（每份声明nvidia.com/gpu: 1，镜像vllm/vllm-openai:v0.17.0）、8000 端口以及/health探针，参见 vLlama3.yaml 与 vPhi4.yaml。其中 llama 启动参数启用了--enable-chunked-prefill与--max_num_batched_tokens 1024，并通过 Secret 注入HUGGING_FACE_HUB_TOKEN。

部署完成后，可以用下面的命令确认两个 vLLM Pod 已 READY 并正在服务模型，同时看到暴露模型 IP/端口的 Kubernetes Service（示例中 llama3-8b 通过 Service IP 10.108.250.109、端口 80 对外服务）：

kubectl get pods NAME READY STATUS RESTARTS AGE llama-8b-57b95475bd-ph7s4 1/1 Running 0 9d phi4-mini-887476b56-74twv 1/1 Running 0 9d kubectl get service NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE kubernetes ClusterIP 10.96.0.1 <none> 443/TCP 36d llama-8b ClusterIP 10.108.250.109 <none> 80/TCP 18d phi4-mini ClusterIP 10.97.252.33 <none> 80/TCP 9d

第四步：部署 InferencePool 与 LLM-D schedulers

LLM-D（以及 Kubernetes IGW）使用一个名为InferencePool的 API 资源，配套一个调度器（在 LLM-D 与 Gateway API Inference Extension 的资料中常缩写为EPP，即 Endpoint Picker）。

要完整展示「模型选择 + 副本调度」的组合，通常需要至少 2 个 InferencePool、每个池至少 2 个副本，这在本实验中将意味着 4 个 vLLM Pod 与 4 块 GPU。为了控制硬件需求，本指南为两个 InferencePool 各部署 1 个模型端点，用于展示 vsr 模型选择与 LLM-D 调度器行为的核心设计。

应用仓库提供的清单，为实验中的两个 base model 分别创建 InferencePool 与 LLM-D 推理调度器：

# 为 Llama3-8b 模型创建 LLM-D 调度器与 InferencePool kubectl apply -f deploy/kubernetes/llmd-base/inferencepool-llama.yaml

# 为 phi4-mini 模型创建 LLM-D 调度器与 InferencePool kubectl apply -f deploy/kubernetes/llmd-base/inferencepool-phi4.yaml

以 inferencepool-llama.yaml 为例，该清单包含以下几个关键资源：

• InferencePool：apiVersion: inference.networking.k8s.io/v1，targetPorts指向 8000（vLLM 服务端口），通过selector.matchLabels.app: vllm-llama3-8b-instruct圈定池内 Pod，并通过endpointPickerRef指向名为vllm-llama3-8b-instruct-epp的 Service（端口 9002）；
• EPP Service：appProtocol: http2、端口 9002 的 ClusterIP Service；
• EPP Deployment：镜像ghcr.io/llm-d/llm-d-router-endpoint-picker:v0.10.0，启动参数包括--pool-name vllm-llama3-8b-instruct、--pool-namespace default、--grpc-port 9002、--grpc-health-port 9003，并挂载plugins-configConfigMap；liveness/readiness 探针通过 gRPC 9003 端口执行；
• plugins-config ConfigMap：LLM-D EndpointPicker 的调度插件配置，schedulingProfiles.default中给queue-scorer（权重 2）、kv-cache-utilization-scorer（权重 2）、prefix-cache-scorer（权重 3）加权，体现 LLM-D 依据队列长度、KV cache 利用率与前缀缓存等实时指标选择副本的策略。

phi4 的清单结构相同，只是池名、标签与绑定对象不同，参见 inferencepool-phi4.yaml。两个清单同时创建了只读 Pod 信息的 Role 与 RoleBinding，用于 EPP 观察池内 Pod 状态。

注意：修改模型别名时，必须把 Router model card、HTTPRoute的 header match、InferencePool、EPP 启动参数以及后端标签作为一个整体契约同步更新，参见 llmd-base 目录说明。

第五步：为 LLM-D 连接补充 Istio 配置

为每个 EPP/LLM-D 调度器添加 DestinationRule，允许其使用不带 TLS 的 ExtProc（当前 Istio 的限制）：

# Llama3-8b 池调度器的 Istio destinationrule kubectl apply -f deploy/kubernetes/llmd-base/dest-rule-epp-llama.yaml

# phi4-mini 池调度器的 Istio destinationrule kubectl apply -f deploy/kubernetes/llmd-base/dest-rule-epp-phi4.yaml

对应的 dest-rule-epp-llama.yaml 与 dest-rule-epp-phi4.yaml 内容为：host指向对应的 EPP Service，trafficPolicy.tls.mode: SIMPLE且insecureSkipVerify: true。

第六步：更新 vsr 配置

由于本指南沿用 Istio 部署指南 的同一组后端模型，因此直接复用该指南中的 deploy/kubernetes/istio/config.yaml，无需修改。如果 LLM-D 部署中使用了不同的后端模型，则必须更新该文件。

该配置文件是 vsr 的核心路由策略（version: v0.3），关键结构如下：

• providers.models：声明两个模型别名，llama3-8b与phi4-mini，各自带backend_refs（vllm provider、endpointllama-8b:80/phi4-mini:80、权重 1），defaults.model为llama3-8b；
• routing.decisions：按 domain 信号定义 14 个决策（business、law、psychology、biology、chemistry、history、other、health、economics、math、physics、computer science、philosophy、engineering），每个决策的modelRefs指向对应模型，例如math决策路由到phi4-mini，其余大多路由到llama3-8b；chemistry、physics决策还启用了use_reasoning: true；多数决策附带system_prompt插件（默认enabled: false），部分附带response_cache插件（similarity_threshold取值 0.75~0.95）；
• signals.domains：声明全部 domain 信号，并声明两张modelCards（llama3-8b、phi4-mini）；
• global.router.clear_route_cache: true：要求网关在每次请求路径上调用 ExtProc、保留其清除路由缓存的响应，并在 vsr 写入x-selected-model后重新评估HTTPRoute；
• global.services.api.batch_classification：批量分类参数（max_batch_size: 100、max_concurrency: 8）与 metrics 配置；
• global.stores：response_cache、memory、vector_store 的存储后端设置（embedding 模型为mmbert）。

第七步：部署 vLLM Semantic Router

部署语义路由器服务及其全部必需组件：

# 使用 Kustomize 部署 semantic router kubectl apply -k deploy/kubernetes/istio/ # 等待部署就绪（模型下载可能需要数分钟） kubectl wait --for=condition=Available deployment/semantic-router -n vllm-semantic-router-system --timeout=600s # 验证部署状态 kubectl get pods -n vllm-semantic-router-system

Kustomize 清单 kustomization.yaml 聚合了 namespace、serviceaccount、rbac、pv-models、deployment、service 等资源，通过configMapGenerator把 config.yaml 与tools_db.json生成名为semantic-router-config的 ConfigMap（disableNameSuffixHash: true，因为运行中的 Router 会通过 Kubernetes API 直接 patch 该 ConfigMap，参见 issue #3688），并 patch Deployment 启动参数为--secure=false。

deployment.yaml 中的 vLLM Semantic Router 容器（镜像ghcr.io/vllm-project/semantic-router/vllm-sr:latest）暴露三个端口：50051（gRPC ExtProc）、9190（metrics）、8080（classify-api），并带有一个model-downloader init 容器：首次启动时把all-MiniLM-L12-v2、category_classifier_modernbert-base_model、pii_classifier_modernbert-base_model、jailbreak_classifier_modernbert-base_model、Qwen3-Embedding-0.6B等模型下载到 PVC（semantic-router-models），已存在则跳过下载；liveness/readiness 探针在 50051 端口上以 TCP 方式探测，initialDelaySeconds: 300等待模型加载。路由器的 Service 定义参见 service.yaml。

第八步：为 VSR 连接补充 Istio 配置

安装 Istio Gateway 使用 ExtProc 接口与 vLLM Semantic Router 通信所需的 destinationrule 与 envoy filter：

kubectl apply -f deploy/kubernetes/istio/destinationrule.yaml kubectl apply -f deploy/kubernetes/istio/envoyfilter.yaml

• destinationrule.yaml：对semantic-router.vllm-semantic-router-system.svc.cluster.local设置tls.mode: DISABLE；
• envoyfilter.yaml：通过workloadSelector选中带gateway.networking.k8s.io/gateway-name: inference-gateway标签的工作负载（即 Istio Gateway），在 GATEWAY 上下文的envoy.filters.network.http_connection_manager中INSERT_FIRST插入envoy.filters.http.ext_proc过滤器，其grpc_service指向outbound|50051||semantic-router.vllm-semantic-router-system.svc.cluster.local。processing_mode设置为请求头 SEND、响应头 SEND、请求体 BUFFERED；mutation_rules.allow_expression限定 ext_proc 只能修改x-envoy-upstream-rq-timeout-ms、x-envoy-upstream-rq-per-try-timeout-ms、x-envoy-max-retries、x-envoy-retry-on、x-envoy-retriable-status-codes等受控头；failure_mode_allow: true表示 vsr 不可用时放行流量。修改 Gateway 或 Router 名称时，需要同步更新该 filter。

第九步：安装网关路由（指向 InferencePool）

在 Istio Gateway 中安装 HTTPRoute。与之前 vsr + Istio 指南的一个关键区别是：这里的backendRefs不再直接指向 vLLM Service 端点，而是指向 InferencePool，再由 InferencePool 指向对应池的 LLM-D 调度器：

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

以 httproute-llama-pool.yaml 为例：HTTPRoutevsr-llama8b挂在inference-gateway上，matches为路径前缀/且请求头x-selected-model: llama3-8b（Exact 匹配），backendRefs指向group: inference.networking.k8s.io、kind: InferencePool、name: vllm-llama3-8b-instruct，request超时 300s。phi4 版本与之对称，匹配x-selected-model: phi4-mini并指向vllm-phi4-mini池。

注意：不要同时应用 Istio 示例中的直连 Service 路由（httproute-llama3-8b.yaml 与 httproute-phi4-mini.yaml）。两套路由匹配相同的x-selected-model值会造成歧义所有权，导致路由行为不可预期，参见 llmd-base 目录说明。

数据流与集成契约

x-selected-model请求头是连接两层路由的「接力棒」。从源码测试可以印证这一契约：model_resolution_test.go 中注释明确指出 "known model should set x-selected-model header"，即 vsr 在 ExtProc 处理中对已知模型写入x-selected-model头；response_log_redaction_test.go 则把x-selected-model与x-vsr-destination-endpoint一同列为需要处理的响应头。

完整的请求链路为：

client -> Istio Gateway (Envoy) -> ext_proc 调用 vsr（语义分类/模型选择） -> vsr 写入 x-selected-model 请求头 -> HTTPRoute 按该 header 精确匹配 -> backendRefs 指向 InferencePool -> LLM-D EPP 在池内选择副本（依据队列/KV cache/前缀缓存评分） -> vLLM 副本响应

分层职责边界（参考 llm-d 集成文档）：vsr 不应选择具体 Pod，LLM-D 也不应决定请求适用于哪个业务策略或模型族，二者各司其职、互不越界。

第十步：测试部署

若需把 Istio Gateway 监听的 IP 暴露给集群外部，可使用任意标准的 Kubernetes 外部负载均衡方案。本仓库实测采用 metallb 作为 LoadBalancer provider。minikube 场景下通过以下命令获得外部 URL（每次输出可能不同，请以实际输出为准）：

minikube service inference-gateway-istio --url http://192.168.49.2:32293

现在可以通过 curl 向该 URL 发送 LLM 提示词，Istio Gateway 会结合 vLLM Semantic Router 的信息，把请求动态路由到两个后端 LLM 之一。请使用你minikube service命令实际输出的端口替换下面示例中的端口。

尝试以下带/不带模型auto选择的用例，确认 Istio + vsr 能协同把查询路由到合适的模型。响应内容会包含用于服务该请求的模型信息。

# 显式指定模型名 llama3-8b，不改写模型，发送到 llama 的 EPP 调度 curl http://192.168.49.2:32293/v1/chat/completions -H "Content-Type: application/json" -d '{ "model": "llama3-8b", "messages": [ {"role": "user", "content": "Linux is said to be an open source kernel because "} ], "max_tokens": 100, "temperature": 0 }'

# 模型名设为 "auto"，应分类为 "computer science" 并路由到 llama3-8b curl http://192.168.49.2:32293/v1/chat/completions -H "Content-Type: application/json" -d '{ "model": "auto", "messages": [ {"role": "user", "content": "Linux is said to be an open source kernel because "} ], "max_tokens": 100, "temperature": 0 }'

# 显式指定模型名 phi4-mini，不改写模型，发送到 phi4-mini 的 EPP 调度 curl http://192.168.49.2:32293/v1/chat/completions -H "Content-Type: application/json" -d '{ "model": "phi4-mini", "messages": [ {"role": "user", "content": "2+2 is "} ], "max_tokens": 100, "temperature": 0 }'

# 模型名设为 "auto"，应分类为 "math" 并路由到 phi4-mini curl http://192.168.49.2:32293/v1/chat/completions -H "Content-Type: application/json" -d '{ "model": "auto", "messages": [ {"role": "user", "content": "2+2 is "} ], "max_tokens": 100, "temperature": 0 }'

前两个用例使用llama3-8b与phi4-mini显式模型名，验证显式路由解析；后两个用例使用auto，验证语义分类后的自动模型选择。也可以使用脚本动态获取网关地址并发送自动选择请求，参见 llmd-base 目录说明 中的GATEWAY_URL="$(minikube service inference-gateway-istio --url)"示例。若需要验证池内副本选择，再为池增加多个后端副本。

故障排查

基础 Pod 验证

按上述步骤完成后，应看到类似下面的 READY Pod 作为快速初始验证，包括 LLM 模型 Pod、Istio Gateway Pod、LLM-D/EPP 调度 Pod、vsr Pod 与 istiod 控制面 Pod；同时应看到 InferencePool 与 HTTPRoute 实例，且路由状态显示为已解析（ResolvedRefs）：

$ kubectl get pods -n default NAME READY STATUS RESTARTS AGE inference-gateway-istio-6fc8864bfb-gbcz8 1/1 Running 0 14h llama-8b-6558848cc8-wkkxn 1/1 Running 0 3h26m phi4-mini-7b94bc69db-rnpkj 1/1 Running 0 17h vllm-llama3-8b-instruct-epp-7f7ff88677-j7lst 1/1 Running 0 134m vllm-phi4-mini-epp-6f5dd6bbb9-8pv27 1/1 Running 0 14h

$ kubectl get pods -n vllm-semantic-router-system NAME READY STATUS RESTARTS AGE semantic-router-bf6cdd5b9-t5hpg 1/1 Running 0 5d23h

$ kubectl get pods -n istio-system NAME READY STATUS RESTARTS AGE istiod-6f5ccc65c-vnbg5 1/1 Running 0 15h

$ kubectl get inferencepools NAME AGE vllm-llama3-8b-instruct 139m vllm-phi4-mini 15h

$ kubectl get httproutes NAME HOSTNAMES AGE vsr-llama8b 13h vsr-phi4-mini 13h

$ kubectl get httproute vsr-llama8b -o yaml | grep -A 1 "reason: ResolvedRefs" reason: ResolvedRefs status: "True"

建议不要依赖与保存示例相同的 Pod 名称进行比较，而是用kubectl describe httproute vsr-llama8b与kubectl describe inferencepool vllm-llama3-8b-instruct检查路由与池的条件状态。

常见问题

网关/前端不工作：

# 检查 istio gateway 状态 kubectl get gateway # 检查 istio gw service 状态 kubectl get svc inference-gateway-istio # 检查 Istio 的 Envoy 日志 kubectl logs deploy/inference-gateway-istio -c istio-proxy

语义路由器无响应或路由不正确：

# 检查 semantic router pod kubectl get pods -n vllm-semantic-router-system # 检查 semantic router service kubectl get svc -n vllm-semantic-router-system # 检查 semantic router 日志 kubectl logs -n vllm-semantic-router-system deployment/semantic-router

针对 LLM-D 集成场景的专项排查（参见 llmd-base 目录说明）：

• HTTPRoute 引用未解析：核对已安装的 Inference Extension API 版本与InferencePool名称；
• EPP 未就绪：检查 EPP Deployment 日志及其 RBAC 资源；
• 请求绕过池：删除同一x-selected-model值对应的直连 Service 路由；
• 进入错误的模型池：比对 Router 别名与发出的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

清理

# 移除 semantic router kubectl delete -k deploy/kubernetes/istio/ # 移除 Istio istioctl uninstall --purge # 移除 LLM kubectl delete -f deploy/kubernetes/istio/vLlama3.yaml kubectl delete -f deploy/kubernetes/istio/vPhi4.yaml # 停止 minikube 集群 minikube stop # 删除 minikube 集群 minikube delete

仅移除 LLM-D 层时，可按依赖顺序删除 llmd-base 目录 中的 httproute、destinationrule 与 inferencepool 清单；共享的 Router、Gateway 与模型资源按 Istio 指南清理。

后续与扩展方向

• 试验 vLLM Semantic Router 的不同功能特性（如 PromptGuard、ToolCalling、response cache 等，config.yaml 中相关插件默认关闭，可按需开启）；
• 试验更复杂的 LLM-D 配置与 well-lit paths；
• 为池内副本调度验证增加多副本后端；
• 设置监控与可观测性（Router 提供 9190 metrics 端口，config.yaml 中预留了 OpenTelemetry OTLP tracing 配置）；
• 实现认证与授权；
• 将语义路由器部署水平扩展以支撑生产工作负载；
• 若需同时路由本地池与托管模型，可参考 llmd-base/llmd+public-llm 示例：通过ExternalNameService 与 Istio egress 把gpt-4o-mini之类托管端点加入拓扑，其 config.yaml.openai 与 httproute-openai.template 展示了完整的配置形态（该示例是集成演示而非推荐的密钥管理方式，生产环境应通过网关扩展或读取 Kubernetes Secret 的 egress 代理注入凭据）；
• 生产化边界：固定 Semantic Router、LLM-D、网关、CRD 与模型服务镜像版本；Provider 凭据不要写入 Router YAML；明确定义失败行为（fail-open 可能绕过语义策略，fail-closed 可能在 Router 不可用时阻断全部流量）；在组合上线前分别测试直连池访问、语义选择与端点调度，参见 llm-d 集成文档。

• 后端
• API网关
• 模型推理服务
• AI Agent