企业官网建设流程全解析

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

本指南以 Semantic Router 官方文档中「使用 vLLM AIBrix 安装」章节为主体，完整讲解如何将 Semantic Router 以 ext_proc 模式接入 vLLM AIBrix 网关，在 Kind 本地集群上完成端到端部署：从 Helm 安装、AIBrix 组件部署、演示 LLM 与 Gateway API 资源创建，到端口转发与推理请求验证。读完本文，你将掌握基于 Gateway API + Envoy ext_proc 的语义路由网关的完整搭建与调试方法，并能读懂仓库中配套的配置清单（values.yaml、base-model.yaml、gwapi-resources.yaml）与 E2E 验证逻辑。

一、vLLM AIBrix 与 Semantic Router：为什么要集成

vLLM AIBrix 是一个开源项目，致力于提供构建可扩展 GenAI 推理基础设施的基本构建块。AIBrix 提供了一套云原生解决方案，专为部署、管理和扩展大语言模型（LLM）推理而优化，并针对企业需求量身定制。其核心能力包括：

• 高密度 LoRA 管理：简化对模型轻量级低秩适配（LoRA）的支持；
• LLM 网关与路由：高效管理和引导跨多个模型与副本的流量；
• LLM 应用定制自动扩缩器：根据实时需求动态扩展推理资源；
• 统一 AI 运行时：多功能边车，支持指标标准化、模型下载与管理；
• 分布式推理：可扩展架构，处理跨多节点的大型工作负载；
• 分布式 KV 缓存：支持高容量、跨引擎的 KV 重用；
• 经济高效的异构服务：支持混合 GPU 推理以降低成本，同时保证 SLO；
• GPU 硬件故障检测：主动检测 GPU 硬件问题。

将 vLLM Semantic Router 与 AIBrix 集成，可以获得以下五方面收益：

1. 智能请求路由：Semantic Router 基于内容理解分析传入请求并将其路由到最合适的模型，而 AIBrix 的网关高效管理跨模型副本的流量分配——两者分工互补，语义决策与流量调度各司其职；
2. 增强的可扩展性：AIBrix 的自动扩缩器与 Semantic Router 无缝协作，根据路由模式和实时需求动态调整资源；
3. 成本优化：结合 Semantic Router 的智能路由与 AIBrix 的异构服务能力，可以优化 GPU 利用率并降低基础设施成本，同时保持 SLO 保证；
4. 生产就绪的基础设施：AIBrix 提供企业级功能，如分布式 KV 缓存、GPU 故障检测和统一运行时管理，使在生产环境中部署 Semantic Router 更加容易；
5. 简化运维：集成利用 Kubernetes 原生模式和 Gateway API 资源，为 DevOps 团队提供熟悉的运维模式。

从仓库代码看，这一集成是经过完整验证的官方路径：E2E 测试框架中专门提供了aibrix测试 profile（见 e2e/profiles/aibrix/profile.go），其职责描述即 "Tests Semantic Router with vLLM AIBrix integration"。

二、部署架构：ext_proc 模式下的数据面

在进入操作步骤前，先理解本次部署的整体数据流。Semantic Router 的 Helm chart（见 deploy/helm/semantic-router/values.yaml）支持两种网关模式：

• standalone（默认）：Router 自身提供 OpenAI 兼容 API 监听端口，不依赖 Envoy；
• extproc：Router 作为 Envoy 的 ext_proc gRPC 服务运行，网关（Envoy Gateway、Envoy AI Gateway、Istio、KServe、llm-d 等）负责流量转发。

本次与 AIBrix 的集成使用extproc 模式，数据面架构如下：

客户端 → Envoy Gateway（aibrix-eg，Gateway API） │ ext_proc gRPC（:50051） ▼ Semantic Router（vllm-semantic-router-system 命名空间） │ 语义路由决策（域分类 / 关键词 / jailbreak / PII …） ▼ AIBrix 网关 → vllm-llama3-8b-instruct（default 命名空间，模拟器 + 6 个 LoRA 专家）

Gateway 与 Router 之间的 ext_proc 接线定义在 deploy/kubernetes/aibrix/aigw-resources/gwapi-resources.yaml 的EnvoyPatchPolicy中：它将一个名为semantic-router-extproc的 ExternalProcessor 过滤器注入aibrix-eg网关的 HTTP 过滤器链，并新建一个指向semantic-router.vllm-semantic-router-system:50051的 gRPC Cluster。关于该清单的逐字段解析见「步骤 5」。

三、前置条件

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

• kind —— Kubernetes in Docker（可选，仅本地测试需要）；
• kubectl —— Kubernetes CLI；
• Helm —— Kubernetes 包管理器。

需要说明的是，本指南使用 Kind 仅在本地复现验证路径；仓库的 E2E 框架（e2e/profiles/aibrix/profile.go）在 CI 中对这套部署做了自动化演练，因此你可以在任何标准 Kubernetes 集群上按相同步骤复现。

四、步骤 1：创建 Kind 集群（可选）

创建针对 Semantic Router 工作负载优化的本地 Kubernetes 集群：

kind create cluster --name semantic-router-cluster # 验证集群就绪 kubectl wait --for=condition=Ready nodes --all --timeout=300s

五、步骤 2：部署 vLLM Semantic Router

使用 Helm 部署包含所有必需组件的 Semantic Router 服务。官方方式是从 GHCR OCI 仓库安装，并附加values.yaml自定义配置（该文件包含 Semantic Router 的完整配置，包括模型设置、类别和路由规则）：

# 从 GHCR OCI 仓库安装自定义配置 # （可选）如果使用镜像代理，请添加：--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 https://raw.githubusercontent.com/vllm-project/semantic-router/refs/heads/main/deploy/kubernetes/aibrix/semantic-router-values/values.yaml # 等待部署就绪（模型下载可能需要几分钟） kubectl wait --for=condition=Available deployment/semantic-router -n vllm-semantic-router-system --timeout=600s # 验证部署状态 kubectl get pods -n vllm-semantic-router-system

注意：values 文件包含 Semantic Router 的配置，包括模型设置、类别和路由规则。在本地仓库中，该文件位于 deploy/kubernetes/aibrix/semantic-router-values/values.yaml，你可以下载后按需自定义。若使用仓库内的 Helm chart 源码安装，也可改为本地路径：

helm install semantic-router deploy/helm/semantic-router \ --namespace vllm-semantic-router-system \ --create-namespace \ --set gateway.mode=extproc \ -f deploy/kubernetes/aibrix/semantic-router-values/values.yaml

5.1 关键配置解读：AIBrix 集成的 values.yaml

AIBrix 集成使用的 values 文件结构与 Helm chart 默认值（deploy/helm/semantic-router/values.yaml）保持一致，核心差异在于以下几块：

网关模式与后端模型。gateway.mode必须为extproc（此时 Router 在 gRPC 端口 50051 上为 Envoy 提供 ext_proc 服务，不再使用config.listeners）。providers.models声明了路由器的模型后端，指向 AIBrix 托管的演示模型：

gateway: mode: extproc config: version: v0.3 listeners: [] # extproc 模式下不使用 listeners providers: defaults: model: vllm-llama3-8b-instruct reasoning_effort: high models: - name: vllm-llama3-8b-instruct reasoning: family: qwen3 # 推理风格族，决定 reasoning 请求的组装方式 backend_refs: - name: aibrix-vllm provider: vllm endpoint: vllm-llama3-8b-instruct.default.svc.cluster.local:8000 weight: 1

其中backend_refs.endpoint即 Kubernetes 集群内服务地址（Service 名vllm-llama3-8b-instruct，命名空间default，端口 8000）。

域路由决策（domain decisions）。routing.decisions定义语义路由规则：每个决策包含规则（conditions）、优先级（priority）、目标模型与插件。以math_decision为例，请求被分类为math域后命中该决策，并启用reasoning：

routing: decisions: - name: math_decision description: Mathematics and quantitative reasoning priority: 10 rules: operator: OR conditions: - type: domain name: math modelRefs: - model: vllm-llama3-8b-instruct use_reasoning: true 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

该 values 文件共定义了 15 个决策：business_decision、law_decision、psychology_decision、biology_decision、chemistry_decision、history_decision、other_decision（priority 5，兜底域）、health_decision、economics_decision、math_decision、physics_decision、computer_science_decision、philosophy_decision、engineering_decision以及关键词触发的thinking_decision（priority 15，高于域决策）。多数决策通过system_prompt插件以mode: replace注入领域专家角色提示词；部分决策（如psychology_decision、other_decision、health_decision）还叠加了response_cache插件，通过similarity_threshold（0.92 / 0.75 / 0.95）对相似提问命中语义缓存。

需要留意：在 E2E 使用的 e2e/profiles/aibrix/values.yaml 中，决策列表还额外包含两个高优先级的安全决策——block_jailbreak（priority 1000，通过fast_response插件直接拒绝越狱尝试）与block_pii（priority 999，拒绝含个人敏感信息的请求），并配套注册了jailbreak_standard（threshold 0.75）与pii_deny_all（threshold 0.01）信号。生产环境建议参照该配置补齐安全防线。

信号（signals）与 LoRA 模型卡（modelCards）。routing.signals声明分类所用的域清单与关键词规则：

signals: keywords: - name: thinking operator: OR keywords: [urgent, immediate, asap, think, careful] case_sensitive: false domains: - name: business - name: law # ... 共 14 个域 modelCards: - name: vllm-llama3-8b-instruct loras: - name: science-expert # 面向生物/化学/物理/健康/工程 - name: social-expert # 面向商业/经济 - name: math-expert # 面向数学推理 - name: law-expert # 面向法律问题 - name: humanities-expert # 面向心理/历史/哲学 - name: general-expert # 通用适配器

modelCards与步骤 4 中演示 LLM 的 6 个 LoRA 模块一一对应，构成「域分类 → 专家 LoRA」的路由能力。

全局运行时配置。文件尾部还配置了global.router.strategy: priority（决策按优先级匹配）、global.services.api.batch_classification（批量分类：max_batch_size: 100、max_concurrency: 8，及一组时长/大小分桶指标）、global.stores.response_cache（内存后端、similarity_threshold: 0.8、max_entries: 1000、ttl_seconds: 3600、FIFO 淘汰、mmbert 嵌入模型）以及global.integrations.tools（语义工具检索，top_k: 3）。这些参数与 deploy/helm/semantic-router/values.yaml 中的默认值保持一致，可按需调整。

六、步骤 3：安装 vLLM AIBrix

安装核心 vLLM AIBrix 组件（依赖清单与核心清单分别来自 AIBrix 项目 v0.4.1 发布包）：

# 安装 vLLM AIBrix kubectl create -f https://github.com/vllm-project/aibrix/releases/download/v0.4.1/aibrix-dependency-v0.4.1.yaml kubectl create -f https://github.com/vllm-project/aibrix/releases/download/v0.4.1/aibrix-core-v0.4.1.yaml # 等待部署就绪 kubectl wait --timeout=2m -n aibrix-system deployment/aibrix-gateway-plugins --for=condition=Available kubectl wait --timeout=2m -n aibrix-system deployment/aibrix-metadata-service --for=condition=Available kubectl wait --timeout=2m -n aibrix-system deployment/aibrix-controller-manager --for=condition=Available

值得说明的是，仓库 E2E 框架（e2e/profiles/aibrix/profile.go）默认使用 AIBrixv0.5.0，并支持通过AIBRIX_VERSION环境变量覆盖版本；其核心部署组件与文档一致：aibrix-gateway-plugins、aibrix-metadata-service、aibrix-controller-manager（该组件带 webhook，等待超时更长，E2E 中设置为 5 分钟）。E2E 还会对aibrix-gateway-plugins的资源配置做降级补丁（将默认的 2 CPU / 8Gi 请求降为 500m / 1Gi），以适配 CI 环境——若你的本地集群资源受限，可参考该做法。

七、步骤 4：部署演示 LLM

创建一个演示 LLM 作为 Semantic Router 的后端：

# 部署演示 LLM kubectl apply -f https://raw.githubusercontent.com/vllm-project/semantic-router/refs/heads/main/deploy/kubernetes/aibrix/aigw-resources/base-model.yaml kubectl wait --timeout=2m -n default deployment/vllm-llama3-8b-instruct --for=condition=Available

在本地仓库中，该清单位于 deploy/kubernetes/aibrix/aigw-resources/base-model.yaml。其结构值得关注：

• Deployment 与 Service 通过model.aibrix.ai/name标签关联，清单注释明确要求标签值必须与 Service 名一致，这是 AIBrix 发现模型服务的约定；
• 镜像为ghcr.io/llm-d/llm-d-inference-sim:v0.5.0推理模拟器，并非真实 vLLM 引擎，它接受--max-loras 6并加载 6 个 LoRA 专家模块（math-expert、science-expert、social-expert、humanities-expert、law-expert、general-expert），与 values.yaml 中的modelCards.loras对应；
• 三探针齐全：startupProbe（/health，periodSeconds 2、failureThreshold 30）优先保障慢启动，livenessProbe与readinessProbe（periodSeconds 5）维持稳态健康检查；
• Service 附带 Prometheus 发现注解（prometheus-discovery: "true"、prometheus.io/scrape: "true"），便于接入可观测性。

八、步骤 5：创建 Gateway API 资源

为 Envoy Gateway 创建必要的 Gateway API 资源：

kubectl apply -f https://raw.githubusercontent.com/vllm-project/semantic-router/refs/heads/main/deploy/kubernetes/aibrix/aigw-resources/gwapi-resources.yaml

本地仓库对应文件为 deploy/kubernetes/aibrix/aigw-resources/gwapi-resources.yaml，其中包含两个关键对象，它们是整条语义路由链路的核心接线：

8.1 EnvoyPatchPolicy：将 ext_proc 过滤器注入 aibrix-eg 网关

该EnvoyPatchPolicy（ai-gateway-prepost-extproc-patch-policy，位于aibrix-system命名空间）以 JSONPatch 方式对名为aibrix-eg的 Gateway 做两处修改：

1. 注入 ExternalProcessor 过滤器到网关 HTTP 过滤器链首位（/default_filter_chain/filters/0/typed_config/http_filters/0），名称为semantic-router-extproc，并通过grpcService.envoyGrpc指向semantic-router.vllm-semantic-router-system:50051；
2. 新增semantic-router集群（Cluster）：STRICT_DNS 类型、ROUND_ROBIN 负载均衡、HTTP/2，endpoint 为semantic-router.vllm-semantic-router-system.svc.cluster.local:50051。

其中两处细节值得注意：

• mutation_rules白名单：清单注释说明，决策的可靠性（reliability）块通过逐请求头到达 Envoy 的 router，ext_proc 不得设置其他x-envoy-*头，因此allow_expression正则严格限定为^x-envoy-(upstream-rq-timeout-ms|upstream-rq-per-try-timeout-ms|max-retries|retry-on|retriable-status-codes)$，这是从安全角度对 ext_proc 可改写 Envoy 控制头的最小权限约束；
• processing_mode：request_header_mode: SEND+request_body_mode: BUFFERED、response_header_mode: SEND+response_body_mode: BUFFERED，即请求与响应的头、体均交给 Router 处理（响应体缓冲用于语义缓存、幻觉/越狱检测等能力），并设置message_timeout: 60s。

8.2 EnvoyProxy：定制 Envoy 部署形态

EnvoyProxy（aibrix-custom-proxy-config）定制了网关 Envoy 的运行时形态：

• 副本与滚动更新：replicas 1，RollingUpdate（maxUnavailable/maxSurge 均为 1）；
• 调度偏好：Pod 反亲和（preferredDuringScheduling，按app.kubernetes.io/name=envoy、topologyKeykubernetes.io/hostname）避免同节点堆叠；节点亲和偏好排除nvidia.com/gpu.present=true的 GPU 节点（网关本身无需 GPU）；
• 镜像与资源：envoyproxy/envoy:v1.33.2与envoyproxy/gateway:v1.2.8（shutdown-manager 边车），Envoy 容器请求/限制均为 1 CPU / 1Gi 内存。

九、测试部署

9.1 方式 1：端口转发（推荐用于本地测试）

设置端口转发以在本地访问网关：

# 获取 Envoy 服务名称 export ENVOY_SERVICE=$(kubectl get svc -n envoy-gateway-system \ --selector=gateway.envoyproxy.io/owning-gateway-namespace=aibrix-system,gateway.envoyproxy.io/owning-gateway-name=aibrix-eg \ -o jsonpath='{.items[0].metadata.name}') kubectl port-forward -n envoy-gateway-system svc/$ENVOY_SERVICE 8080:80

这里通过 Gateway API 的gateway.envoyproxy.io/owning-gateway-*标签选择器定位 Envoy 服务；E2E 框架（e2e/profiles/aibrix/profile.go）同样使用该标签选择器，并通过PortMapping: "8080:80"建立本地访问。

9.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"是虚拟模型名（Mixture of Models 入口），由 Semantic Router 接管并按内容语义改写为目标模型。你将看到演示 LLM 的响应，以及 Semantic Router 注入的额外响应头：

HTTP/1.1 200 OK server: fasthttp date: Thu, 06 Nov 2025 06:38:08 GMT content-type: application/json x-inference-pod: vllm-llama3-8b-instruct-984659dbb-gp5l9 x-went-into-req-headers: true request-id: b46b6f7b-5645-470f-9868-0dd8b99a7163 x-vsr-selected-category: math x-vsr-selected-reasoning: on x-vsr-selected-model: vllm-llama3-8b-instruct x-vsr-injected-system-prompt: true transfer-encoding: chunked {"id":"chatcmpl-f390a0c6-b38f-4b73-a019-9374a3c5d69b","created":1762411088,"model":"vllm-llama3-8b-instruct","usage":{"prompt_tokens":42,"completion_tokens":48,"total_tokens":90},"object":"chat.completion","do_remote_decode":false,"do_remote_prefill":false,"remote_block_ids":null,"remote_engine_id":"","remote_host":"","remote_port":0,"choices":[{"index":0,"finish_reason":"stop","message":{"role":"assistant","content":"I am your AI assistant, how can I help you today? To be or not to be that is the question. Alas, poor Yorick! I knew him, Horatio: A fellow of infinite jest Testing, testing 1,2,3"}}]}

9.3 响应头语义解析

上述响应头中，x-vsr-*前缀的头部是 Semantic Router 的决策跟踪头，其定义与语义可在源码 src/semantic-router/pkg/headers/headers.go 中查到：

这些头部正是 E2E 测试的断言对象：例如 e2e/testcases/domain_classify.go 会发送分类问题并读取x-vsr-selected-category与期望类别比对，计算分类准确率；e2e/testcases/aibrix_control_plane_health.go 则验证 AIBrix 控制面三个 Deployment 的健康状态、vllm-llama3-8b-instruct服务标签与后端 Pod 就绪情况。整个aibrixprofile 由RouterSmoke冒烟用例与aibrix-control-plane-health用例组成（见 e2e/profiles/aibrix/profile.go 的GetTestCases）。

十、清理

删除整个部署：

# 删除 Gateway API 资源和演示 LLM kubectl delete -f https://raw.githubusercontent.com/vllm-project/semantic-router/refs/heads/main/deploy/kubernetes/aibrix/aigw-resources/gwapi-resources.yaml kubectl delete -f https://raw.githubusercontent.com/vllm-project/semantic-router/refs/heads/main/deploy/kubernetes/aibrix/aigw-resources/base-model.yaml # 删除 Semantic Router helm uninstall semantic-router -n vllm-semantic-router-system # 删除 kind 集群（可选） kind delete cluster --name semantic-router-cluster

若你使用本地清单与本地 chart 部署，则对应改为kubectl delete -f deploy/kubernetes/aibrix/aigw-resources/gwapi-resources.yaml、kubectl delete -f deploy/kubernetes/aibrix/aigw-resources/base-model.yaml、helm uninstall semantic-router -n vllm-semantic-router-system。仓库 E2E 框架的 Teardown 顺序与此一致（先删 Gateway 资源、再删 AIBrix 组件、最后卸载 Semantic Router），并额外删除 AIBrix 的 core 与 dependency 发布清单。

十一、后续步骤

完成本次 AIBrix 集成部署后，可以继续深化以下几个方面：

• 设置监控和可观测性：Semantic Router 的 metrics Service 默认暴露在 9190 端口（service.metrics.port，见 deploy/helm/semantic-router/values.yaml），可kubectl port-forward svc/<release>-metrics 9190:9190后访问/metrics；同时 chart 支持通过observability.alerts渲染 PrometheusRule（请求错误率、P95 延迟、缓存命中率等告警阈值），并可启用 OTel 追踪（global.services.observability.tracing）；
• 实施身份验证和授权：结合 Envoy Gateway / Authorino 等外部授权服务注入用户级密钥与身份头（如x-user-openai-key、x-authz-user-id，定义见 src/semantic-router/pkg/headers/headers.go），实现按用户路由与安全隔离；
• 为生产工作负载扩展 Semantic Router 部署：参考 Helm chart 的autoscaling（HPA）、persistence（模型 PVC，Vela Omni Mini 模型约 4.3GB，默认 10Gi）、extraVolumes/extraVolumeMounts（共享模型缓存）等参数，并将演示模拟器替换为真实 vLLM 引擎与真实 LoRA 权重。

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