后端API网关模型推理服务AI Agent【免费下载链接】semantic-routerAn open, programmable decision layer for models and compute.项目地址https://gitcode.com/gh_mirrors/sem/semantic-router点击查看免费下载本指南以 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 推理以降低成本同时保证 SLOGPU 硬件故障检测主动检测 GPU 硬件问题。将 vLLM Semantic Router 与 AIBrix 集成可以获得以下五方面收益智能请求路由Semantic Router 基于内容理解分析传入请求并将其路由到最合适的模型而 AIBrix 的网关高效管理跨模型副本的流量分配——两者分工互补语义决策与流量调度各司其职增强的可扩展性AIBrix 的自动扩缩器与 Semantic Router 无缝协作根据路由模式和实时需求动态调整资源成本优化结合 Semantic Router 的智能路由与 AIBrix 的异构服务能力可以优化 GPU 利用率并降低基础设施成本同时保持 SLO 保证生产就绪的基础设施AIBrix 提供企业级功能如分布式 KV 缓存、GPU 故障检测和统一运行时管理使在生产环境中部署 Semantic Router 更加容易简化运维集成利用 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 监听端口不依赖 EnvoyextprocRouter 作为 Envoy 的 ext_proc gRPC 服务运行网关Envoy Gateway、Envoy AI Gateway、Istio、KServe、llm-d 等负责流量转发。本次与 AIBrix 的集成使用extproc 模式数据面架构如下客户端 → Envoy Gatewayaibrix-egGateway API │ ext_proc gRPC:50051 ▼ Semantic Routervllm-semantic-router-system 命名空间 │ 语义路由决策域分类 / 关键词 / jailbreak / PII … ▼ AIBrix 网关 → vllm-llama3-8b-instructdefault 命名空间模拟器 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 CLIHelm —— Kubernetes 包管理器。需要说明的是本指南使用 Kind 仅在本地复现验证路径仓库的 E2E 框架e2e/profiles/aibrix/profile.go在 CI 中对这套部署做了自动化演练因此你可以在任何标准 Kubernetes 集群上按相同步骤复现。四、步骤 1创建 Kind 集群可选创建针对 Semantic Router 工作负载优化的本地 Kubernetes 集群kind create cluster --name semantic-router-cluster # 验证集群就绪 kubectl wait --forconditionReady nodes --all --timeout300s五、步骤 2部署 vLLM Semantic Router使用 Helm 部署包含所有必需组件的 Semantic Router 服务。官方方式是从 GHCR OCI 仓库安装并附加values.yaml自定义配置该文件包含 Semantic Router 的完整配置包括模型设置、类别和路由规则# 从 GHCR OCI 仓库安装自定义配置 # 可选如果使用镜像代理请添加--set global.imageRegistryyour-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 --forconditionAvailable deployment/semantic-router -n vllm-semantic-router-system --timeout600s # 验证部署状态 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.modeextproc \ -f deploy/kubernetes/aibrix/semantic-router-values/values.yaml5.1 关键配置解读AIBrix 集成的 values.yamlAIBrix 集成使用的 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域后命中该决策并启用reasoningrouting: 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_decisionpriority 5兜底域、health_decision、economics_decision、math_decision、physics_decision、computer_science_decision、philosophy_decision、engineering_decision以及关键词触发的thinking_decisionpriority 15高于域决策。多数决策通过system_prompt插件以mode: replace注入领域专家角色提示词部分决策如psychology_decision、other_decision、health_decision还叠加了response_cache插件通过similarity_threshold0.92 / 0.75 / 0.95对相似提问命中语义缓存。需要留意在 E2E 使用的 e2e/profiles/aibrix/values.yaml 中决策列表还额外包含两个高优先级的安全决策——block_jailbreakpriority 1000通过fast_response插件直接拒绝越狱尝试与block_piipriority 999拒绝含个人敏感信息的请求并配套注册了jailbreak_standardthreshold 0.75与pii_deny_allthreshold 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 --timeout2m -n aibrix-system deployment/aibrix-gateway-plugins --forconditionAvailable kubectl wait --timeout2m -n aibrix-system deployment/aibrix-metadata-service --forconditionAvailable kubectl wait --timeout2m -n aibrix-system deployment/aibrix-controller-manager --forconditionAvailable值得说明的是仓库 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 --timeout2m -n default deployment/vllm-llama3-8b-instruct --forconditionAvailable在本地仓库中该清单位于 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/healthperiodSeconds 2、failureThreshold 30优先保障慢启动livenessProbe与readinessProbeperiodSeconds 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 网关该EnvoyPatchPolicyai-gateway-prepost-extproc-patch-policy位于aibrix-system命名空间以 JSONPatch 方式对名为aibrix-eg的 Gateway 做两处修改注入 ExternalProcessor 过滤器到网关 HTTP 过滤器链首位/default_filter_chain/filters/0/typed_config/http_filters/0名称为semantic-router-extproc并通过grpcService.envoyGrpc指向semantic-router.vllm-semantic-router-system:50051新增semantic-router集群ClusterSTRICT_DNS 类型、ROUND_ROBIN 负载均衡、HTTP/2endpoint 为semantic-router.vllm-semantic-router-system.svc.cluster.local:50051。其中两处细节值得注意mutation_rules白名单清单注释说明决策的可靠性reliability块通过逐请求头到达 Envoy 的 routerext_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_moderequest_header_mode: SENDrequest_body_mode: BUFFERED、response_header_mode: SENDresponse_body_mode: BUFFERED即请求与响应的头、体均交给 Router 处理响应体缓冲用于语义缓存、幻觉/越狱检测等能力并设置message_timeout: 60s。8.2 EnvoyProxy定制 Envoy 部署形态EnvoyProxyaibrix-custom-proxy-config定制了网关 Envoy 的运行时形态副本与滚动更新replicas 1RollingUpdatemaxUnavailable/maxSurge 均为 1调度偏好Pod 反亲和preferredDuringScheduling按app.kubernetes.io/nameenvoy、topologyKeykubernetes.io/hostname避免同节点堆叠节点亲和偏好排除nvidia.com/gpu.presenttrue的 GPU 节点网关本身无需 GPU镜像与资源envoyproxy/envoy:v1.33.2与envoyproxy/gateway:v1.2.8shutdown-manager 边车Envoy 容器请求/限制均为 1 CPU / 1Gi 内存。九、测试部署9.1 方式 1端口转发推荐用于本地测试设置端口转发以在本地访问网关# 获取 Envoy 服务名称 export ENVOY_SERVICE$(kubectl get svc -n envoy-gateway-system \ --selectorgateway.envoyproxy.io/owning-gateway-namespaceaibrix-system,gateway.envoyproxy.io/owning-gateway-nameaibrix-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 中查到响应头值语义x-inference-podvllm-llama3-8b-instruct-984659dbb-gp5l9网关注入标识实际处理请求的推理 Pod模拟器副本名x-went-into-req-headerstrue网关/代理链路标记说明请求经过了请求头处理阶段request-idb46b6f7b-...请求唯一标识用于全链路追踪x-vsr-selected-categorymath域分类器MMLU 类目选中的语义类别本例识别为数学域x-vsr-selected-reasoningon是否启用推理模式对应 values 中math_decision的use_reasoning: truex-vsr-selected-modelvllm-llama3-8b-instructRouter 最终选定的上游模型x-vsr-injected-system-prompttrue是否注入了系统提示词对应system_prompt插件的replace模式这些头部正是 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 的autoscalingHPA、persistence模型 PVCVela Omni Mini 模型约 4.3GB默认 10Gi、extraVolumes/extraVolumeMounts共享模型缓存等参数并将演示模拟器替换为真实 vLLM 引擎与真实 LoRA 权重。赞分享后端API网关模型推理服务AI Agent【免费下载链接】semantic-routerAn open, programmable decision layer for models and compute.项目地址https://gitcode.com/gh_mirrors/sem/semantic-router点击查看免费下载相关推荐Kubernetes 集成 vLLM AIBrix 部署 vLLM Semantic RouterExtProc 网关与智能路由实战指南Kubernetes 集成 vLLM AIBrix 部署 vLLM Semantic RouterExtProc 网关与智能路由实战指南 本指南完整讲解如何在后端API网关模型推理服务AI Agent基于 vLLM AIBrix 部署 vLLM Semantic RouterKubernetes 智能路由与推理网关集成实战指南基于 vLLM AIBrix 部署 vLLM Semantic RouterKubernetes 智能路由与推理网关集成实战指南 本文是一份面向 Kubern后端API网关模型推理服务AI Agent在 Kubernetes 上集成 vLLM Production Stack 与 Semantic RouterMoM 语义路由生产部署实战在 Kubernetes 上集成 vLLM Production Stack 与 Semantic RouterMoM 语义路由生产部署实战 本篇技术指南完整后端API网关模型推理服务AI Agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考