vLLM Semantic Router 与 AIBrix 集成部署指南：在 Kubernetes 上构建可编程模型决策层-开发者社区

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

【免费下载链接】semantic-router

An open, programmable decision layer for models and compute.

项目地址：https://gitcode.com/gh_mirrors/sem/semantic-router

本指南完整讲解如何将 vLLM Semantic Router（开源可编程决策层）与 vLLM AIBrix（云原生 LLM 推理基础设施）在 Kubernetes 上集成部署：从 kind 本地集群的创建、Semantic Router 的 Helm 安装与路由配置详解，到 AIBrix 网关组件、演示 LLM 与 Gateway API 资源的逐步落地，最终通过curl验证语义路由、系统提示词注入等端到端效果。读完本文，你将掌握一套可直接复制的「Semantic Router + AIBrix + Envoy Gateway」生产级推理网关部署方案，并能独立定制领域决策、关键词信号与响应缓存策略。

关于 vLLM AIBrix

AIBrix 是一个开源项目，旨在为构建可扩展的 GenAI 推理基础设施提供关键组件。它面向企业级需求，提供一套云原生解决方案，用于部署、管理和扩展大语言模型（LLM）推理服务。

核心特性

高密度 LoRA 管理：对模型的轻量级低秩适配（LoRA）提供流式管理支持，便于在同一基座模型上挂载多个领域专家适配器；
LLM 网关与路由：高效管理并调度跨多个模型与副本的流量；
LLM 应用专属自动扩缩器：基于实时负载动态伸缩推理资源；
统一 AI 运行时：一个多用途 sidecar，支持指标标准化、模型下载与管理；
分布式推理：可跨多个节点扩展以承载大规模工作负载的可扩展架构；
分布式 KV Cache：支持大容量、跨引擎的 KV 复用；
高性价比异构推理：通过混合 GPU 推理降低成本，同时满足 SLO 保障；
GPU 硬件故障检测：主动发现 GPU 硬件问题。

集成收益：为什么让 Semantic Router 与 AIBrix 协同工作

将 vLLM Semantic Router 与 AIBrix 集成可以获得以下优势：

智能请求路由：Semantic Router 基于内容理解分析入站请求并将其路由到最合适的模型，AIBrix 网关则负责在模型副本间高效分配流量——前者解决「路由到哪个模型」，后者解决「流量如何分发」；
增强的可扩展性：AIBrix 的自动扩缩器与 Semantic Router 协同工作，可根据路由模式和实时需求动态调整资源；
成本优化：将 Semantic Router 的智能路由与 AIBrix 的异构推理能力结合，可优化 GPU 利用率、降低基础设施成本，同时维持 SLO 保障；
生产级基础设施：AIBrix 提供分布式 KV Cache、GPU 故障检测、统一运行时管理等企业级能力，让 Semantic Router 在生产环境中部署更加可靠；
简化运维：该集成充分利用 Kubernetes 原生模式与 Gateway API 资源，为 DevOps 团队提供了熟悉的运维模型。

前置条件

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

工具	用途	安装参考
kind	在 Docker 中运行 Kubernetes，用于本地测试（可选）	kind 官方 Quick Start 文档
kubectl	Kubernetes 命令行工具，管理集群资源	Kubernetes 官方安装文档
Helm	Kubernetes 包管理器，用于安装 Semantic Router Chart	Helm 官方安装文档

此外，本地环境需要能够访问 ghcr.io（GHCR OCI Registry，用于拉取 Semantic Router Helm Chart 与镜像）以及 GitHub Releases 提供的 AIBrix 清单文件。

Step 1：创建 kind 集群（可选）

如果尚未具备可用的 Kubernetes 集群，可用 kind 快速创建一个针对 semantic router 工作负载优化的本地集群：

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

semantic-router-cluster是任意指定的集群名，后续清理时需保持一致。

Step 2：部署 vLLM Semantic Router

使用 Helm 从 GHCR OCI Registry 部署 Semantic Router 及其全部必要组件：

# 使用 GHCR OCI Registry 中的自定义 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 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 的完整配置——模型设置、领域（domains）与路由规则。你可以下载该文件并按需定制，仓库中的对应源文件位于 deploy/kubernetes/aibrix/semantic-router-values/values.yaml。

深入解析 values.yaml：一套可编程的路由配置骨架

这个 values 文件是整个集成方案的核心，它把 Semantic Router 的「决策层」能力完整映射到了 AIBrix 部署场景。逐段拆解如下：

网关接入模式（ext_proc）

# The gateway in front of the Router calls it over ext_proc. gateway: mode: extproc

Semantic Router 以 Envoy 外部处理器（External Processor，ext_proc）的形式挂载在网关数据面，请求先到达网关，再经 gRPC 交由 Router 决策，这与 gwapi-resources.yaml 中 EnvoyPatchPolicy 配置的envoy.extensions.filters.http.ext_proc.v3.ExternalProcessor过滤器一一对应。

模型提供商（Providers）

config: version: v0.3 providers: defaults: model: vllm-llama3-8b-instruct reasoning_effort: high models: - name: vllm-llama3-8b-instruct reasoning: family: qwen3 backend_refs: - name: aibrix-vllm provider: vllm endpoint: vllm-llama3-8b-instruct.default.svc.cluster.local:8000 weight: 1

defaults.model：未命中任何决策时的默认后端模型；
defaults.reasoning_effort：默认推理强度（high），对应 Qwen3 系列模型的思考模式；
models[].reasoning.family: qwen3：声明该模型的推理族为 qwen3，用于兼容其原生 reasoning 协议；
backend_refs[].endpoint：指向 Step 4 部署的演示 LLM 的集群内 DNS 地址与端口（服务名.命名空间.svc.cluster.local:8000）；
weight：同一后端多副本时的负载权重。该配置结构与仓库根级 config/config.yaml 的providers段保持一致，后者还支持reliability（lb_policy、retry_count、健康检查）、pricing等更细粒度字段。

路由决策（Routing Decisions）

values 中定义了 14 个决策，每个决策包含名称、描述、优先级、规则（信号条件）、模型引用与插件。以数学领域决策为例：

- 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

要点说明：

rules.operator: OR：条件间的组合逻辑。仓库 config/fragments/decision 提供了 AND/OR/NOT 及复合决策的官方示例，例如 business-or-law.yaml 演示了用 OR 让一个决策同时覆盖 business 与 law 两个领域，urgent-business.yaml 则演示了 AND 组合；
use_reasoning: true：该决策触发时启用模型的推理模式（math、chemistry、physics、thinking 决策均开启），其余决策为false；
plugins.system_prompt：命中决策后按replace模式替换系统提示词，将通用助手切换为领域专家人格。仓库 system-prompt/expert.yaml 还展示了insert模式（追加而非替换）的用法。

除 math 外，values 还定义了 business、law、psychology、biology、chemistry、history、other、health、economics、physics、computer_science、philosophy、engineering 等决策，其中 psychology、other、health 决策额外挂载了response_cache插件，而thinking_decision通过priority: 15成为所有普通决策之上的最高优先级（普通决策 priority 为 10）。

信号（Signals）

signals: keywords: - name: thinking operator: OR keywords: - urgent - immediate - asap - think - careful case_sensitive: false domains: - name: business - name: law ...

keywords：基于关键词的信号。thinking信号命中 urgent/immediate/asap/think/careful 之一即触发（不区分大小写），进而命中thinking_decision决策启用深度推理。类似的官方示例见 signal/keyword/regex.yaml，其中还包含敏感数据关键词（ssn、credit card 等）的配置范式；
domains：领域信号，是各决策conditions中type: domain的判定来源。仓库 signal/domain/mmlu.yaml 提供了带mmlu_categories映射的完整领域定义（business、law、math、health 等），显示领域分类可对接 MMLU 类别体系。

模型卡与 LoRA（Model Cards）

modelCards: - name: vllm-llama3-8b-instruct loras: - name: science-expert description: 'Specialized for science domains: biology, chemistry, physics, health, engineering' - name: math-expert description: Fine-tuned for mathematics and quantitative reasoning ...

modelCards 声明了基座模型可挂载的 LoRA 适配器（science-expert、social-expert、math-expert、law-expert、humanities-expert、general-expert），对应 AIBrix 的「高密度 LoRA 管理」能力。Step 4 的演示 LLM 会以--lora-modules参数加载这 6 个适配器，语义路由的领域决策可与专家 LoRA 协同，实现「领域路由 + 专家适配」的组合推理。

全局策略与存储（Global / Stores）

global: router: strategy: priority services: api: batch_classification: max_batch_size: 100 max_concurrency: 8 stores: response_cache: enabled: true backend_type: memory similarity_threshold: 0.8 max_entries: 1000 ttl_seconds: 3600 eviction_policy: fifo embedding_model: mmbert

router.strategy: priority：路由策略为按优先级匹配决策，与各决策的priority字段配合；
batch_classification：分类 API 的批处理参数（最大批大小 100、最大并发 8），并带完整的 metrics 配置（duration_buckets、size_buckets、采样率）；
response_cache：内存型响应缓存，全局相似度阈值 0.8、最多 1000 条、TTL 3600 秒、FIFO 淘汰策略，使用 mmbert 作为嵌入模型。values 中各决策插件内的similarity_threshold（如 psychology 的 0.92、health 的 0.95、other 的 0.75）会覆盖此全局值。仓库 response-cache/memory.yaml 展示了更精细的缓存配置（exact 模式、scope: user、personalized 禁用等）；
integrations.tools：工具选择集成（top_k=3、相似度阈值 0.2、工具库路径config/tools_db.json）；
observability.tracing：OpenTelemetry 追踪配置（默认关闭，可启用后导出至 jaeger:4317）。

Step 3：安装 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 # 等待相关 deployment 就绪 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

aibrix-dependency清单负责安装 AIBrix 依赖的底层组件（如 Envoy Gateway），aibrix-core清单则部署 AIBrix 自身的控制器、元数据服务与网关插件等核心组件，统一运行在aibrix-system命名空间。

Step 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，该文件定义了一个vllm-llama3-8b-instructDeployment 与同名 Service，关键点：

模型标识一致性：Deployment 的 labelmodel.aibrix.ai/name: vllm-llama3-8b-instruct必须与 Service 名称完全一致，AIBrix 网关据此发现模型副本（注释中明确要求该 label 值必须与 Service 名称匹配）；
推理模拟器：容器镜像为ghcr.io/llm-d/llm-d-inference-sim:v0.5.0，通过--model、--port 8000、--max-loras 6、--lora-modules（加载 math-expert、science-expert、social-expert、humanities-expert、law-expert、general-expert 六个 LoRA）参数模拟 vLLM 推理服务，无需真实 GPU；
健康检查三件套：startupProbe（2s 周期、30 次失败阈值）、livenessProbe（10s 周期）、readinessProbe（5s 周期）均探测/health端点；
服务发现：ClusterIP Service 暴露 8000 端口，selector 匹配model.aibrix.ai/name标签，并带有 Prometheus 抓取注解（prometheus.io/scrape: "true"、端口 8000）。

Step 5：创建 Gateway API 资源

为 Envoy 网关创建必要的 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，它包含两份关键资源：

EnvoyPatchPolicy：把 Semantic Router 挂进网关数据面

该策略通过 JSONPatch 在aibrix-system/aibrix-eg/http监听器的默认过滤器链首部注入semantic-router-extproc过滤器：

name: semantic-router-extproc typedConfig: '@type': type.googleapis.com/envoy.extensions.filters.http.ext_proc.v3.ExternalProcessor mutation_rules: allow_expression: regex: "^x-envoy-(upstream-rq-timeout-ms|upstream-rq-per-try-timeout-ms|max-retries|retry-on|retriable-status-codes)$" allow_mode_override: true grpcService: envoyGrpc: authority: semantic-router.vllm-semantic-router-system:50051 clusterName: semantic-router timeout: 60s message_timeout: 60s processing_mode: request_body_mode: BUFFERED request_header_mode: SEND response_body_mode: BUFFERED response_header_mode: SEND

gRPC 接入：envoyGrpc.authority指向 Step 2 部署的 Semantic Router 服务（semantic-router.vllm-semantic-router-system:50051）；
处理模式：请求/响应体均 BUFFERED（缓存后交由 ext_proc 处理），请求/响应头 SEND，trailer SKIP；
头修改白名单：mutation_rules限定 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这组与可靠性（重试/超时）相关的 Envoy 头，注释明确说明「决策的可靠性块通过这些 per-request 头到达 Envoy router，ext_proc 不得设置其他 x-envoy-* 头」——这正是 Semantic Router 在决策层实现重试、超时等可靠性策略的通道。

该策略还同步新增了一个 STRICT_DNS 类型、ROUND_ROBIN 负载策略的semantic-router集群，指向semantic-router.vllm-semantic-router-system.svc.cluster.local:50051。

EnvoyProxy：定制 Envoy 网关运行形态

aibrix-custom-proxy-config定义网关数据面部署参数：单副本 RollingUpdate（maxUnavailable/maxSurge 均为 1）、Pod 反亲和（优先将 Envoy 副本分散到不同主机）、Node 亲和（nvidia.com/gpu.presentNotIn true，避免占用 GPU 节点），并通过 StrategicMerge 将 Envoy 镜像固定为envoyproxy/envoy:v1.33.2、资源请求设为 1 CPU / 1Gi 内存。

测试部署

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

# 获取 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

这里通过 Envoy Gateway 的 owner 标签（gateway.envoyproxy.io/owning-gateway-name=aibrix-eg）精确找到属于aibrix-eg网关的 Envoy Service，再将其 80 端口转发到本地 8080。

发送测试请求

网关可访问后，测试推理端点：

# 测试 math 领域 chat completions 端点 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"是 Gateway 的路由标识，content为数学求导问题。你会看到来自演示 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-4a73-b019-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"}}]}

响应头中的x-vsr-*前缀字段是 Semantic Router 决策层工作过程的直接证据：

响应头	含义
`x-vsr-selected-category: math`	请求被分类为 math 领域，命中`math_decision`
`x-vsr-selected-reasoning: on`	该决策配置了`use_reasoning: true`，启用推理模式
`x-vsr-selected-model: vllm-llama3-8b-instruct`	实际选中的后端模型
`x-vsr-injected-system-prompt: true`	已按`replace`模式注入数学专家系统提示词
`x-inference-pod`	处理请求的推理副本 Pod 名（AIBrix 网关流量分发的结果）
`request-id`	请求链路标识，可关联日志与追踪

清理

移除整个部署：

# 移除 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

若不再需要 AIBrix 组件，可再执行kubectl delete对应的 aibrix-dependency 与 aibrix-core 清单。

后续步骤

完成基础部署与验证后，可以从以下方向继续深入：

监控与可观测性：values.yaml 中已内置 OpenTelemetry tracing 配置（provider: opentelemetry、OTLP exporter、目标 jaeger:4317），可启用后将路由决策链路接入 Jaeger；同时演示 LLM 的 Service 已带 Prometheus 抓取注解，可配合 AIBrix 的指标体系搭建监控面板；
认证与授权：Semantic Router 的监听器（见 config/config.yaml 的listeners段）支持api_keys、TLS 与可信来源限制，可在网关层接入认证鉴权；
生产规模扩展：将本地 kind 集群替换为生产集群，调整 AIBrix EnvoyProxy 副本数、为 Semantic Router 配置真实模型后端（将模拟器替换为真实 vLLM 推理服务），并按业务需要扩充 config/fragments/decision 与 config/fragments/signal 中的领域决策与信号定义——这些官方配置片段可作为 values.yaml 定制时的权威参考。