AIBrix 语义路由实战：基于 Envoy ext_proc 与 MoM 虚拟模型实现多模型智能分发
【免费下载链接】aibrixCost-efficient and pluggable Infrastructure components for GenAI inference项目地址: https://gitcode.com/GitHub_Trending/ai/aibrix
语义路由（Semantic Routing）让网关根据用户提示词的语义内容，自动把请求分发到最合适的模型。本指南以 AIBrix 仓库中 samples/semantic-router 的完整样例为主线，讲解如何用 vLLM Semantic Router 作为 Envoy Gateway 的 External Processor（ext_proc），通过一个虚拟模型名MoM（Model of Models）透明地在qwen3-8b（STEM/推理任务）与llama3-8b-instruct（商务/法律/通用任务）之间按领域自动路由，并支持动态开启链式推理（chain-of-thought）。读完本文，你将掌握从零部署语义路由、理解其配置体系、扩展自定义路由规则以及排查问题的完整实战能力。
一、核心概念：MoM 虚拟模型与按语义分发的动机
传统网关按 URL 或模型名做静态路由，客户端必须显式指定调用哪个模型；一旦业务希望“数学题走推理模型、日常问答走轻量模型”，就需要客户端感知后端模型拓扑。语义路由的解法是引入一个虚拟模型名：
- 客户端永远只请求
"model": "MoM"，无需关心背后是哪个真实模型； - 网关侧的路由器对每个请求做嵌入（embedding）相似度分类与关键词扫描，选出最高优先级的匹配决策（decision）；
- 路由器把请求中的
model字段改写为真实后端模型名（如qwen3-8b），并在必要时注入系统提示词与推理参数，然后由 Envoy 转发给对应后端。
正如官方特性文档 docs/source/features/semantic-router.rst 所述：“Clients always call the same endpoint with the same API — the router handles the rest.” 这种设计让“数学和物理题自动发给推理优化模型、日常对话发给更快更轻的模型”完全对客户端透明。
本样例的两个后端模型及其分工如下：
| 模型 | 定位 | 是否开启推理（use_reasoning） |
|---|---|---|
qwen3-8b | 数学、物理、计算机科学、生物、化学、工程等 STEM 领域 | true（注入chat_template_kwargs.enable_thinking: true） |
llama3-8b-instruct | 商务、法律、心理、健康、经济、历史、哲学及兜底（other） | false（标准模式，不注入额外参数） |
二、架构原理：作为 Envoy ext_proc 的语义路由器
2.1 什么是 ext_proc
External Processing（ext_proc） 是 Envoy 的一个 HTTP 过滤器：它把请求/响应的各个部分（请求头、请求体、响应头、响应体）以 gRPC 流的方式发给外部服务，并应用外部服务返回的修改（mutation），从而实现不修改 Envoy 本身的任意请求改写能力。语义路由器正是这样一个 gRPC 外部处理器。
2.2 系统整体链路
Client │ ▼ Envoy Gateway (aibrix-eg) ←── EnvoyPatchPolicy 注入 ext_proc 过滤器 │ │ gRPC (ext_proc 协议, 端口 50051) ▼ Semantic Router (vllm-semantic-router-system 命名空间) │ 分类 prompt → 选择决策 → 改写请求 │ 将 model 字段从 MoM 替换为选中模型（如 qwen3-8b / llama3-8b-instruct） │ │ 返回改写后的请求给 Envoy ▼ AIBrix Gateway Plugins (aibrix-gateway-plugins, ext_proc) │ 应用网关级插件（限流、鉴权等） │ ▼ ├──► llama3-8b-instruct.default.svc.cluster.local:8000 └──► qwen3-8b.default.svc.cluster.local:8000该架构图出自样例的设计文档 samples/semantic-router/DESIGN.md。语义路由器以标准 KubernetesDeployment形态部署在vllm-semantic-router-system命名空间，它纯粹是请求路径上的 HTTP 改写器，从不终结客户端连接：Envoy 持有原始请求，通过 gRPC 交给路由器，收到一组变更（新请求头、新请求体）后，再把改写后的请求转发给路由器选定的后端。
2.3 EnvoyPatchPolicy：两段 JSON 补丁接入网关
samples/semantic-router/gwapi-resources.yaml 通过一个EnvoyPatchPolicy向aibrix-system/aibrix-eg网关注入两段 JSON 补丁：
补丁 1：在监听器过滤器链上添加 ext_proc HTTP 过滤器
name: semantic-router-extproc typedConfig: '@type': type.googleapis.com/envoy.extensions.filters.http.ext_proc.v3.ExternalProcessor grpcService: envoyGrpc: clusterName: semantic-router authority: semantic-router.vllm-semantic-router-system:50051 timeout: 60s processing_mode: request_header_mode: SEND request_body_mode: BUFFERED # 完整请求体先缓冲再分类 response_header_mode: SEND response_body_mode: BUFFERED # 完整响应体缓冲，供语义缓存使用其中BUFFERED请求体模式意味着 Envoy 会先把完整的/v1/chat/completionsJSON 载荷累积起来再交给路由器，这样路由器无需处理流式分段即可读取全部消息内容。
补丁 2：注册路由器对应的上游集群
name: semantic-router type: STRICT_DNS connect_timeout: 60s http2_protocol_options: {} # gRPC 需要 HTTP/2 load_assignment: cluster_name: semantic-router endpoints: - lb_endpoints: - endpoint: address: socket_address: address: semantic-router.vllm-semantic-router-system.svc.cluster.local port_value: 50051两段补丁合起来，既把路由器注册为网关监听器上的 ext_proc 过滤器，又告诉 Envoy 如何通过 DNS 解析并建立 HTTP/2 连接到达路由器。
2.4 请求流转的完整时序
按 DESIGN.md 的定义，一次请求经过如下 8 个步骤：
1. Client ──POST /v1/chat/completions──► Envoy（端口 80/8080） { "model": "MoM", "messages": [...] } 2. Envoy ──ProcessingRequest（请求头 + 缓冲请求体）──► Semantic Router（gRPC :50051） 3. Router a. 解析 JSON 请求体 → 提取 messages[].content b. 运行领域分类器（embedding 模型 → 余弦相似度 → 最近领域） c. 运行关键词扫描器（在内容中查找关键词组，如 "step by step"） d. 应用 priority 策略：选出优先级最高的匹配决策 e. 应用决策插件（system_prompt、semantic-cache） f. 改写请求： - 替换/前置 system 消息到 messages[] - 将 "model" 字段改为目标后端模型名 - 若 use_reasoning: true 则注入推理参数 4. Router ──ProcessingResponse（改写后的请求头 + 请求体）──► Envoy 4a. Envoy ──ProcessingRequest（改写后请求）──► AIBrix Gateway Plugins（ext_proc） （在此应用限流、鉴权等网关级插件） 4b. AIBrix Gateway Plugins ──ProcessingResponse──► Envoy 5. Envoy ──POST /v1/chat/completions──► 后端模型服务 { "model": "qwen3-8b", "messages": [{"role":"system",...}, ...], "chat_template_kwargs": {"enable_thinking": true} } 6. Backend ──response──► Envoy 7. Envoy ──ProcessingRequest（响应头 + 缓冲响应体）──► Semantic Router （semantic-cache 决策可能在此存储或返回缓存响应） 8. Envoy ──response──► Client注意第 4a 步：在 AIBrix 体系中，语义路由器并非唯一的 ext_proc 处理器。AIBrix 自身的网关插件服务（aibrix-gateway-plugins，gRPC 端口 50052）同样以 ext_proc 形态参与链路，负责限流、鉴权等网关级能力，其实现位于 pkg/plugins/gateway/gateway.go（Server结构体及Process处理逻辑），接入方式见 config/gateway/gateway-plugin/gateway-plugin.yaml 中的EnvoyExtensionPolicy（请求体 Buffered、响应体 Streamed）。两个 ext_proc 串联形成了“先语义路由、再网关策略”的完整请求管道。
三、前置条件
开始部署前需要准备：
- 一个运行中的 Kubernetes 集群，已安装 AIBrix（包含 Envoy Gateway），可参考 config/gateway/gateway.yaml 了解网关与 EnvoyProxy 的默认配置（该配置声明了
aibrix-egGateway、Envoy v1.33.2 镜像等）； kubectl已正确配置并指向该集群；- 用于模型服务的 GPU 节点；样例中的
qwen3-8b与llama3-8b-instruct各需至少 48 GB 显存的 GPU； - 一个 Hugging Face 账号及 API Token（用于下载嵌入模型权重，路由器启动时会自动拉取）；
- 模型权重已预置在节点
/data01/models/目录，或具备从 HuggingFace 拉取的能力。
四、分步部署指南
第 1 步：创建命名空间与 Hugging Face Token 密钥
kubectl create namespace vllm-semantic-router-system export HF_TOKEN="<your-huggingface-token>" kubectl create secret generic hf-token-secret \ --from-literal=token="${HF_TOKEN}" \ -n vllm-semantic-router-system该密钥在 semantic-router.yaml 中被Deployment以secretKeyRef（key 为token，optional: true）的方式挂载为HF_TOKEN与HUGGINGFACE_HUB_TOKEN两个环境变量，用于下载受控（gated）模型。
第 2 步：部署两个后端模型服务
kubectl apply -f samples/semantic-router/models/llama3-8b-instruct.yaml kubectl apply -f samples/semantic-router/models/qwen3-8b.yaml每个清单会创建 1 个Deployment（3 副本）与 1 个Service，均位于default命名空间。模型服务带有 AIBrix 约定的标签（如model.aibrix.ai/name: llama3-8b-instruct、model.aibrix.ai/port: "8000"、model.aibrix.ai/kv-events-enabled: "true"），AIBrix 控制器会据此自动为每个模型创建HTTPRoute，使 Envoy Gateway 能够发现它们。注意清单中的注释要求：Service 名称必须与 Deployment 上model.aibrix.ai/name标签的值保持一致。
两个清单都使用aibrix-public-release-cn-beijing.cr.volces.com/vllm/vllm-openai:0.11.0镜像启动vllm serve，通过--served-model-name声明对外模型名，并挂载宿主路径/data01/models作为模型目录。其中 qwen3-8b.yaml 额外通过--kv-events-config以 JSON 方式开启 KV cache 事件发布（{"enable_kv_cache_events":true,"publisher":"zmq","endpoint":"tcp://*:5557","replay_endpoint":"tcp://*:5559"}），这是 vLLM 0.11 在VllmConfig中启用 KV ZMQ 的标准姿势。
等待两个部署就绪：
kubectl rollout status deployment/llama3-8b-instruct -n default kubectl rollout status deployment/qwen3-8b -n default第 3 步：部署语义路由器（ConfigMap + Deployment）
kubectl apply -f samples/semantic-router/semantic-router-configmap.yaml kubectl apply -f samples/semantic-router/semantic-router.yamlsemantic-router.yaml 的内容包括：
ServiceAccount+ClusterRole+ClusterRoleBinding：使用ClusterRole 而非 Role是因为路由器需要跨命名空间 watchIntelligentPool、IntelligentRoute这两个集群范围的 CRD（vllm.aiAPI 组）；Service semantic-router：暴露 50051（gRPC ext_proc 接口）与 8080（classify 分类 REST API）；Service semantic-router-metrics：暴露 9190 Prometheus 指标端口；Deployment：使用ghcr.io/vllm-project/semantic-router/extproc:latest镜像，启动参数--secure=false（关闭 ext_proc gRPC 连接的 TLS，仅适用于集群内流量的样例环境，生产环境应移除该参数并启用 TLS）。
路由器容器暴露的三个端口：
| 端口 | 协议 | 用途 |
|---|---|---|
| 50051 | gRPC | ext_proc 接口——接收来自 Envoy 的请求 |
| 8080 | HTTP | 分类 REST API（调试/测试用） |
| 9190 | HTTP | Prometheus 指标 |
ConfigMap 中的config.yaml与tools_db.json分别挂载到/app/config/config.yaml与/app/config/tools_db.json。嵌入模型（embeddinggemma-300m 等）由路由器启动时自动下载（约需 60 秒），无需 initContainer。为此Deployment配置了宽裕的探针：startupProbe每 10 秒探测一次 50051 端口、failureThreshold: 360（最多重试约 60 分钟），livenessProbe与readinessProbe均为 30 秒后开始、每 30 秒一次。资源请求为 1 CPU / 3Gi 内存，上限为 2 CPU / 7Gi 内存。
观察启动进度：
kubectl logs -f deployment/semantic-router -n vllm-semantic-router-system第 4 步：应用 Gateway API / Envoy 资源
kubectl apply -f samples/semantic-router/gwapi-resources.yaml即 2.3 节所述的EnvoyPatchPolicy。可验证补丁是否被接受：
kubectl describe envoypatchpolicy ai-gateway-prepost-extproc-patch-policy -n aibrix-system在Conditions中应看到Status: True。
第 5 步：端口转发 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生产环境可改为使用 LoadBalancer 的外部 IP：
LB_IP=$(kubectl get svc -n envoy-gateway-system \ -l "gateway.envoyproxy.io/owning-gateway-name=aibrix-eg" \ -o jsonpath='{.items[0].status.loadBalancer.ingress[0].ip}')五、路由规则全表（15 条规则）
所有规则定义在 semantic-router-configmap.yaml 的routing.decisions中。路由器把每个提示词分类到某个领域（domain）或命中关键词（keyword），再转发到对应模型：
| 领域 / 关键词 | 匹配类型 | 模型 | 推理 | 优先级 |
|---|---|---|---|---|
thinking（关键词：step by step, think step, chain of thought, reason through, show your work, walk me through） | keyword | qwen3-8b | on | 15 |
business | domain | llama3-8b-instruct | off | 10 |
law | domain | llama3-8b-instruct | off | 10 |
psychology | domain | llama3-8b-instruct | off | 10 |
biology | domain | qwen3-8b | on | 10 |
chemistry | domain | qwen3-8b | on | 10 |
history | domain | llama3-8b-instruct | off | 10 |
health | domain | llama3-8b-instruct | off | 10 |
economics | domain | llama3-8b-instruct | off | 10 |
math | domain | qwen3-8b | on | 10 |
physics | domain | qwen3-8b | on | 10 |
computer science | domain | qwen3-8b | on | 10 |
philosophy | domain | llama3-8b-instruct | off | 10 |
engineering | domain | qwen3-8b | on | 10 |
other（兜底） | domain | llama3-8b-instruct | off | 5 |
优先级规则：优先级更高的规则先被评估；thinking关键词规则（优先级 15）优先于所有领域规则（优先级 10）。当多个决策优先级相同（如business与economics同为 10）时，YAML 中先声明的决策胜出——样例配置里business_decision先于economics_decision声明，因此金融分析类问题会命中business_decision并套用“顾问人设”系统提示词；若希望经济类问题走经济学家人设，需要把economics_decision的优先级提到 10 以上，或把它移到列表前面。
值得留意的是配置中对thinking关键词组的注释：关键词故意收窄以避免误路由——像 "think"、"careful" 这类宽泛词汇会命中普通日常用语（如 "I think..."、"be careful"），导致所有这类请求被静默升级到更慢的qwen3-8b链式推理路径。代价是：用户若想获得分步推理，必须在提示词中包含上述显式信号之一，或经由 math/physics/computer-science/engineering 等始终开启推理的领域路由。
六、验证语义路由
所有请求统一使用虚拟模型名"MoM"。以下两个测试与 README 一致，但将max_tokens按官方特性文档调整为 200 以获取更完整输出。
数学题 → 路由到 qwen3-8b
curl http://localhost:8080/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "MoM", "messages": [ {"role": "user", "content": "What is the derivative of x^3 + 2x?"} ], "max_tokens": 200 }'路由器把该提示词分类为math领域，选择qwen3-8b，注入数学专家系统提示词，并开启链式推理（chat_template_kwargs.enable_thinking: true）。
商务题 → 路由到 llama3-8b-instruct
curl http://localhost:8080/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "MoM", "messages": [ {"role": "user", "content": "What are the key factors to consider when entering a new market?"} ], "max_tokens": 200 }'该请求命中business领域，转发到llama3-8b-instruct，不注入任何推理参数，以标准模式响应。
显式推理触发 → 覆盖领域分类
curl http://localhost:8080/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "MoM", "messages": [ {"role": "user", "content": "Walk me through how to structure a business merger proposal."} ], "max_tokens": 300 }'尽管这是商务问题，但 "walk me through" 命中了thinking关键词组（优先级 15，配置中最高），因此仍然路由到qwen3-8b并开启推理。这演示了关键词规则对领域分类的硬性覆盖能力。
七、路由配置深度解析
所有路由行为由 semantic-router-configmap.yaml 控制，其顶层结构为global（全局设置）、providers（后端模型与推理族）、routing（决策与信号）、listeners、version五个部分。
7.1 决策（decision）结构
routing: decisions: - name: math_decision description: Mathematics and quantitative reasoning priority: 10 # 更高优先；平局 → 列表中先声明者胜出 rules: operator: OR conditions: - name: math # 必须与 routing.signals 中声明的领域/关键词一致 type: domain # 或 type: keyword modelRefs: - model: qwen3-8b use_reasoning: true # 是否激活推理模式 plugins: - type: system_prompt configuration: enabled: true mode: replace # replace | prepend | append system_prompt: "You are a mathematics expert. ..."7.2 两种规则类型（rule types）
type | 匹配方式 |
|---|---|
domain | 基于嵌入的相似度：路由器计算提示词与各领域标签嵌入的余弦相似度，取最近领域 |
keyword | 精确子串搜索（默认大小写不敏感），提示词中出现关键词组中任一词汇即命中 |
7.3 优先级策略（priority strategy）
global.router.strategy: priority（默认策略）的含义：
- 收集所有规则匹配的决策；
priority值最高的决策胜出；- 若多个决策优先级相同，YAML 中先声明的胜出。
thinking关键词决策优先级为 15，因此始终覆盖任何领域匹配（优先级 10）。
7.4 信号目录（signals catalog）
规则引用的每个领域或关键词组，都必须先在routing.signals中声明：
routing: signals: domains: - name: math - name: physics - name: business # ... 在此追加新领域标签 keywords: - name: thinking case_sensitive: false operator: OR keywords: - step by step - chain of thought - reason through # ... 在此扩展关键词组样例声明了 14 个领域（business、law、psychology、biology、chemistry、history、other、health、economics、math、physics、computer science、philosophy、engineering）和 1 个关键词组thinking（6 个关键词，case_sensitive: false、operator: OR）。
7.5 全局设置：批处理分类、可观测性与存储
global.services.api.batch_classification配置了请求批处理分类的参数：concurrency_threshold: 5、max_batch_size: 100、max_concurrency: 8，并带有一组 Prometheus 直方图桶（duration_buckets从 0.001s 到 30s、size_buckets从 1 到 200），metrics.enabled: true。global.services.observability.tracing默认关闭，可通过enabled: true配合 OTLP exporter 端点启用 OpenTelemetry 追踪。global.stores定义了memory存储（embedding_model: mmbert）与semantic_cache的全局参数（见下文插件章节）。global.integrations.tools开启了工具集成（tools_db_path: config/tools_db.json、top_k: 3、similarity_threshold: 0.2），对应 ConfigMap 中内置的tools_db.json（包含 weather、search、math、communication、productivity 五类函数的 schema 描述）。
八、模型推理（Reasoning）的动态激活
modelRef上的use_reasoning: true/false控制路由器是否向转发请求注入推理激活参数，具体机制取决于模型的reasoning_family。
8.1 推理族（reasoning families）
定义于providers.defaults.reasoning_families：
providers: defaults: default_reasoning_effort: high reasoning_families: qwen3: parameter: enable_thinking type: chat_template_kwargs # 注入 {"chat_template_kwargs": {"enable_thinking": true}} deepseek: parameter: thinking type: chat_template_kwargs gpt: parameter: reasoning_effort type: reasoning_effort # 注入 {"reasoning_effort": "high"} gpt-oss: parameter: reasoning_effort type: reasoning_effort可见不同类型模型家族的推理开关参数不同：Qwen3/DeepSeek 走chat_template_kwargs，GPT/GPT-OSS 走顶层reasoning_effort。
8.2 为模型指定推理族
providers: models: - name: qwen3-8b reasoning_family: qwen3 # 关联 qwen3 推理族 backend_refs: - endpoint: qwen3-8b.default.svc.cluster.local:8000 name: aibrix-vllm weight: 1 - name: llama3-8b-instruct # 无 reasoning_family → 该模型永远不会激活推理 backend_refs: - endpoint: llama3-8b-instruct.default.svc.cluster.local:8000 name: aibrix-vllm weight: 18.3 端到端推理激活
当use_reasoning: true的决策命中qwen3-8b（其reasoning_family: qwen3）时，路由器向出站请求体追加：
{ "chat_template_kwargs": { "enable_thinking": true } }vLLM 读取该字段后激活 Qwen3 内置的链式思维路径。当use_reasoning: false（或模型没有reasoning_family）时，不注入任何额外参数，模型以标准模式响应。
各决策的推理注入汇总：
| 决策 | 模型 | use_reasoning | 注入参数 |
|---|---|---|---|
thinking_decision | qwen3-8b | true | chat_template_kwargs.enable_thinking = true |
math_decision | qwen3-8b | true | chat_template_kwargs.enable_thinking = true |
physics_decision | qwen3-8b | true | chat_template_kwargs.enable_thinking = true |
computer_science_decision | qwen3-8b | true | chat_template_kwargs.enable_thinking = true |
biology_decision | qwen3-8b | true | chat_template_kwargs.enable_thinking = true |
chemistry_decision | qwen3-8b | true | chat_template_kwargs.enable_thinking = true |
engineering_decision | qwen3-8b | true | chat_template_kwargs.enable_thinking = true |
business_decision | llama3-8b-instruct | false | （无） |
law_decision | llama3-8b-instruct | false | （无） |
other_decision（兜底） | llama3-8b-instruct | false | （无） |
九、插件机制：system_prompt 与 semantic-cache
决策被选中后，其plugins按声明顺序依次应用。
9.1 system_prompt 插件
向messages[]注入或替换系统消息：
plugins: - type: system_prompt configuration: enabled: true mode: replace # replace | prepend | append system_prompt: "You are a mathematics expert. ..."mode | 行为 |
|---|---|
replace | 移除已有系统消息，前置一条新的{"role": "system", ...} |
prepend | 插入到已有系统消息之前 |
append | 插入到已有系统消息之后 |
样例中每个决策都配了专属人设，例如business_decision是“资深商业顾问与战略顾问”，health_decision强调“仅供教育目的、不构成医疗建议”，philosophy_decision要求“呈现多种视角并鼓励批判性思考”等，从而让同一个模型在不同领域表现出不同的专家风格。
9.2 semantic-cache 插件
按提示词嵌入相似度缓存响应；命中时路由器直接短路后端调用，把缓存响应返回给 Envoy：
plugins: - type: semantic-cache configuration: enabled: true similarity_threshold: 0.92 # 0.0–1.0；越高要求匹配越严格缓存全局参数位于global.stores.semantic_cache：
global: stores: semantic_cache: enabled: true backend_type: memory embedding_model: mmbert similarity_threshold: 0.8 # 全局默认；决策级阈值会覆盖它 ttl_seconds: 3600 max_entries: 1000 eviction_policy: fifo样例中health_decision的缓存阈值为 0.95（非常严格）、psychology_decision为 0.92、other_decision为 0.75（更宽松）——对于健康类（用户措辞相似但略有差异的高频问题）和兜底类场景，语义缓存能显著减少重复调用后端模型的开销。
十、扩展：添加一条新路由
以新增 "cybersecurity"（网络安全）领域为例，只需三步加一次配置重载：
1. 在routing.signals.domains下声明领域：
- name: cybersecurity2. 在routing.decisions下添加决策：
- name: cybersecurity_decision description: Cybersecurity and network security topics priority: 10 rules: operator: OR conditions: - name: cybersecurity type: domain modelRefs: - model: qwen3-8b use_reasoning: true plugins: - type: system_prompt configuration: enabled: true mode: replace system_prompt: "You are a cybersecurity expert with deep knowledge of network security, threat modeling, and secure coding practices. ..."3. 应用并重载：
kubectl apply -f samples/semantic-router/semantic-router-configmap.yaml # 滚动重启以立即加载新配置 kubectl rollout restart deployment/semantic-router -n vllm-semantic-router-system路由器只在启动时读取配置，因此更新 ConfigMap 后必须滚动重启才会生效。
十一、可观测性与故障排查
11.1 指标与追踪
路由器在 9190 端口暴露 Prometheus 指标，可本地抓取：
kubectl port-forward -n vllm-semantic-router-system \ deployment/semantic-router 9190:9190访问http://localhost:9190/metrics或将其接入 Prometheus。如需启用 OpenTelemetry/Jaeger 分布式追踪，在 ConfigMap 中开启：
global: services: observability: tracing: enabled: true exporter: endpoint: jaeger:4317 insecure: true type: otlp（样例 ConfigMap 中tracing.enabled默认为false，并预置了jaeger:4317、provider: opentelemetry、sampling.type: always_on、sampling.rate: 1等参数。）
11.2 常见问题
路由器 Pod 启动缓慢：嵌入模型下载最长约 60 秒，startupProbe 的failureThreshold: 360会持续重试最多约 60 分钟，Pod 最终会就绪。用kubectl logs -f deployment/semantic-router -n vllm-semantic-router-system观察进度。
Envoy 无法连接路由器：确认EnvoyPatchPolicy被接受（kubectl describe envoypatchpolicy ai-gateway-prepost-extproc-patch-policy -n aibrix-system中Status: True），并检查路由器 Service 是否可达（kubectl get svc -n vllm-semantic-router-system）。
所有请求都落到兜底模型：other_decision（优先级 5）会接住任何未命中已知领域的提示词。可通过分类 REST API 直接排查领域嵌入是否已加载：
kubectl port-forward -n vllm-semantic-router-system deployment/semantic-router 9080:8080 curl http://localhost:9080/classify \ -H "Content-Type: application/json" \ -d '{"text": "What is the integral of sin(x)?"}'配置变更不生效：路由器启动时读取配置，更新 ConfigMap 后需kubectl rollout restart deployment/semantic-router -n vllm-semantic-router-system。
十二、样例文件索引
本文涉及的全部清单均位于仓库的 samples/semantic-router 目录：
- README.md — 快速上手指南（本文主体来源）；
- DESIGN.md — 架构与配置深度参考（ext_proc 接入、请求流程、决策结构）；
- semantic-router-configmap.yaml — 完整路由配置，含全部 15 条规则与全局设置；
- semantic-router.yaml — 路由器 Deployment、Service 与 RBAC；
- gwapi-resources.yaml — 把路由器接入网关的 EnvoyPatchPolicy；
- models/llama3-8b-instruct.yaml 与 models/qwen3-8b.yaml — 两个后端模型的 Deployment 与 Service 清单。
若希望进一步理解语义路由在 AIBrix 整体架构中的定位，可查阅官方特性文档 docs/source/features/semantic-router.rst；想深入链路中第二级 ext_proc（AIBrix 网关插件）的实现，可阅读 pkg/plugins/gateway/gateway.go 及其接入配置 config/gateway/gateway-plugin/gateway-plugin.yaml。
【免费下载链接】aibrixCost-efficient and pluggable Infrastructure components for GenAI inference项目地址: https://gitcode.com/GitHub_Trending/ai/aibrix
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
