后端API网关模型推理服务AI Agent【免费下载链接】semantic-routerAn open, programmable decision layer for models and compute.项目地址https://gitcode.com/gh_mirrors/sem/semantic-router点击查看免费下载vLLM Semantic Router 是一款可编程的模型与算力决策层。本文聚焦其与 agentgateway 的集成方式agentgateway 作为 Kubernetes Gateway API 的数据平面承载 OpenAI 兼容流量Semantic Router 以 Envoy ExtProcexternal processing服务器形态运行在请求转发到 vLLM 之前完成分类、模型选择与请求体改写。读完本文你将掌握完整的 kind Helm Gateway API 部署流程、ExtProc 策略配置要点以及大提示词场景下 FullDuplexStreamed 流式处理的进阶方案。架构总览整个部署由三个组件构成vLLM Semantic Router通过 ExtProc 提供提示词分类prompt classification、模型选择model selection、请求改写request mutation与响应处理response processingagentgateway提供 Kubernetes Gateway API 代理能力包含AgentgatewayBackend、HTTPRoute、AgentgatewayPolicy三类资源Demo vLLM 兼容后端通过 OpenAI 兼容 API 同时提供基础模型base model与 LoRA 适配器服务。三者之间的数据流为客户端请求 → agentgateway proxy → ExtProc 将请求/响应阶段交给 Semantic Router → Semantic Router 分类并改写请求体写入所选模型或 LoRA 名→ agentgateway 将改写后的请求转发给 vLLM 兼容后端。仓库中 deploy/kubernetes/agentgateway 目录将本指南的各步骤固化成了可直接复用的清单文件包括 gateway.yaml、demo-llm.yaml、routing-resources.yaml 与 extproc-policy.yaml。前置条件开始之前需要安装以下工具kind——Docker 中的 Kubernetes可选用于本地测试kubectl——Kubernetes CLIHelm——Kubernetes 包管理器。版本要求本文使用 agentgatewayv1.3.0-alpha.1或更新版本因为它依赖 ExtProc 的processingOptions与allowModeOverride字段这两个字段在v1.2.1之后才被加入。仓库 E2E 测试中使用的 agentgateway 版本为v1.3.1见 e2e/profiles/agentgateway/profile.go。Step 1创建 Kind 集群可选为本地测试创建一个单节点的 Kubernetes 集群kind create cluster --name semantic-router-agentgateway # 验证集群就绪 kubectl wait --forconditionReady nodes --all --timeout300s如果已有可用集群可跳过本步骤。生产环境请使用真实集群并配合 LoadBalancer/NodePort 暴露 agentgateway proxy。Step 2安装 agentgateway依次安装 Kubernetes Gateway API CRD 与 agentgateway 控制平面export AGENTGATEWAY_VERSIONv1.3.0-alpha.1 kubectl apply --server-side --force-conflicts \ -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.5.0/standard-install.yaml helm upgrade -i agentgateway-crds oci://cr.agentgateway.dev/charts/agentgateway-crds \ --create-namespace \ --namespace agentgateway-system \ --version ${AGENTGATEWAY_VERSION} \ --set controller.image.pullPolicyAlways helm upgrade -i agentgateway oci://cr.agentgateway.dev/charts/agentgateway \ --namespace agentgateway-system \ --version ${AGENTGATEWAY_VERSION} \ --set controller.image.pullPolicyAlways \ --set controller.extraEnv.KGW_ENABLE_GATEWAY_API_EXPERIMENTAL_FEATUREStrue \ --wait kubectl get pods -n agentgateway-system要点说明--server-side --force-conflicts用于以服务端应用方式安装 Gateway API CRD避免本地配置冲突KGW_ENABLE_GATEWAY_API_EXPERIMENTAL_FEATUREStrue启用实验性的 Gateway API 特性ExtProc 依赖此项仓库 E2E 安装逻辑e2e/profiles/agentgateway/runtime.go与上述命令一致并对 Gateway API CRD 安装做了最多 3 次的重试gatewayAPIInstallAttempts 3网络抖动时可按相同思路处理。Step 3创建 agentgateway proxy创建一个使用 agentgateway GatewayClass 的 Gatewaykubectl apply -f- EOF apiVersion: gateway.networking.k8s.io/v1 kind: Gateway metadata: name: agentgateway-proxy namespace: agentgateway-system spec: gatewayClassName: agentgateway listeners: - protocol: HTTP port: 80 name: http allowedRoutes: namespaces: from: All EOF kubectl wait --forconditionAvailable deployment/agentgateway-proxy \ -n agentgateway-system \ --timeout300sallowedRoutes.namespaces.from: All允许任意命名空间的路由挂到该 Gateway 上后续HTTPRoute也部署在agentgateway-system命名空间。该清单的独立文件版本见 gateway.yaml。Step 4部署 Demo LLM部署一个轻量级的 OpenAI 兼容模拟器它提供base-model以及 Semantic Router Demo 配置中选择的 6 个 LoRA 适配器名kubectl apply -f- EOF apiVersion: apps/v1 kind: Deployment metadata: name: vllm-llama3-8b-instruct namespace: default spec: replicas: 1 selector: matchLabels: app: vllm-llama3-8b-instruct template: metadata: labels: app: vllm-llama3-8b-instruct spec: containers: - name: vllm-sim image: ghcr.io/llm-d/llm-d-inference-sim:v0.5.0 imagePullPolicy: IfNotPresent args: - --model - base-model - --port - 8000 - --max-loras - 6 - --lora-modules - {name: math-expert} - {name: science-expert} - {name: social-expert} - {name: humanities-expert} - {name: law-expert} - {name: general-expert} ports: - containerPort: 8000 name: http protocol: TCP readinessProbe: httpGet: path: /health port: http periodSeconds: 5 timeoutSeconds: 5 failureThreshold: 3 --- apiVersion: v1 kind: Service metadata: name: vllm-llama3-8b-instruct namespace: default labels: app: vllm-llama3-8b-instruct spec: type: ClusterIP ports: - port: 8000 targetPort: 8000 protocol: TCP selector: app: vllm-llama3-8b-instruct EOF kubectl wait --forconditionAvailable deployment/vllm-llama3-8b-instruct \ -n default \ --timeout300s--lora-modules参数注册了 6 个 LoRA 适配器名Semantic Router 后续选择的 LoRA 名必须出现在此列表中请求才能命中正确的适配器readinessProbe探测/health端点periodSeconds: 5、failureThreshold: 3意味着最多约 15 秒内判定后端不可用该清单的独立文件版本见 demo-llm.yaml。Step 5部署 vLLM Semantic Router将 Semantic Router 安装在agentgateway-system命名空间以便 agentgateway 的 ExtProc 策略可以直接引用semantic-router服务helm install semantic-router oci://ghcr.io/vllm-project/charts/semantic-router \ --version v0.0.0-latest \ --namespace agentgateway-system \ -f https://raw.githubusercontent.com/vllm-project/semantic-router/refs/heads/main/deploy/kubernetes/agentgateway/semantic-router-values/values.yaml kubectl wait --forconditionAvailable deployment/semantic-router \ -n agentgateway-system \ --timeout600s该 values 文件仓库内对应 semantic-router-values/values.yaml做了两件关键事情配置 Semantic Router 将流量发往vllm-llama3-8b-instruct.default.svc.cluster.local:8000定义路由决策选择诸如math-expert、science-expert、general-expert等适配器名。理解 values 文件的核心配置gateway.mode: extproc是集成 agentgateway 的前提。参考 Helm 图表文档deploy/helm/semantic-router/README.mdstandalone默认Router 自行在config.listeners上提供 OpenAI 兼容 API不运行 EnvoyextprocRouter 在service.grpc.port默认50051上为前端网关提供 Envoy ext_proc gRPC 服务config.listeners不被使用。本集成即为此模式。图表通过-gatewayextproc把模式传给 Routervllm-sr serve --target kubernetes --gateway ...写入的也是同样的值。在config.providers中providers.defaults.model: base-model指定默认模型名providers.models[0].backend_refs将base-model指向local-vllm后端endpoint 为vllm-llama3-8b-instruct.default.svc.cluster.local:8000。在config.routing.decisions中定义了 14 个路由决策每个决策由rules.conditionsdomain 或 keyword 信号、modelRefs模型 LoRA 是否启用 reasoning与pluginssystem_prompt 替换或 response_cache组成。典型示例math_decisiondomain 为math选择math-expertLoRAuse_reasoning: true并将系统提示词替换为数学专家提示词thinking_decisionpriority 为20匹配 keyword 信号thinking命中urgent、immediate、asap、think、careful等词选择general-expertLoRA 并启用 reasoninggeneral_decisionpriority 为1作为兜底路由覆盖other域并启用 response_cachesimilarity_threshold0.75。config.routing.decisions中的priority字段决定决策优先级priority 越高越先匹配router.strategy: priority启用该策略。signals定义了 keyword 信号与 14 个 domain 信号business、law、psychology、biology、chemistry、history、health、economics、math、physics、computer science、philosophy、engineering、other。modelCards则把 6 个 LoRA 适配器与对应专业领域一一映射供模型选择与分类使用。E2E 覆盖的扩展配置仓库 E2E 测试在安装 Semantic Router 时还叠加了 e2e/profiles/agentgateway/values.yaml见 e2e/profiles/agentgateway/runtime.go并显式开启了流式请求体处理config.global.router.streamed_body.enabled: true config.global.router.streamed_body.max_bytes: 10485760 config.global.router.streamed_body.timeout_sec: 30这三个参数在 config/config.yaml 中的默认值分别为enabled: true、max_bytes: 10485761 MiB、timeout_sec: 15。E2E 将max_bytes放宽到 10 MiB、超时延长到 30 秒以支撑 FullDuplexStreamed 大请求体场景。Step 6创建 agentgateway 路由资源为 vLLM 兼容后端创建AgentgatewayBackend并把 OpenAI 兼容请求路由到它kubectl apply -f- EOF apiVersion: agentgateway.dev/v1alpha1 kind: AgentgatewayBackend metadata: name: semantic-router-vllm namespace: agentgateway-system spec: ai: provider: openai: {} host: vllm-llama3-8b-instruct.default.svc.cluster.local port: 8000 --- apiVersion: gateway.networking.k8s.io/v1 kind: HTTPRoute metadata: name: semantic-router-vllm namespace: agentgateway-system spec: parentRefs: - name: agentgateway-proxy namespace: agentgateway-system rules: - backendRefs: - name: semantic-router-vllm namespace: agentgateway-system group: agentgateway.dev kind: AgentgatewayBackend EOF这里有意省略了openai.model字段。这样 agentgateway 会使用请求体中 Semantic Router 选择目标模型或 LoRA 适配器后写入的模型名而不是由网关硬编码模型。这是路由器改写模型名 → 网关透传链路成立的关键。清单文件版本见 routing-resources.yaml。Step 7将 Semantic Router 挂载为 ExtProc创建AgentgatewayPolicy把请求与响应两个处理阶段都发送到 Semantic Router 的 ExtProc 服务kubectl apply -f- EOF apiVersion: agentgateway.dev/v1alpha1 kind: AgentgatewayPolicy metadata: name: semantic-router-extproc namespace: agentgateway-system spec: targetRefs: - group: gateway.networking.k8s.io kind: Gateway name: agentgateway-proxy traffic: extProc: backendRef: name: semantic-router namespace: agentgateway-system port: 50051 processingOptions: requestHeaderMode: Send requestBodyMode: Buffered responseHeaderMode: Send responseBodyMode: Buffered allowModeOverride: true EOF关键配置解读backendRef指向 Semantic Router 的 gRPC 服务服务名semantic-router、命名空间agentgateway-system、端口50051与 Helm 图表中service.grpc.port默认值一致见 deploy/helm/semantic-router/values.yamlrequestHeaderMode: SendrequestBodyMode: Buffered发送请求头并缓冲请求体Semantic Router 在拿到完整请求体后执行分类与改写responseHeaderMode: SendresponseBodyMode: Buffered同样处理响应阶段使 Router 能处理/改写响应内容allowModeOverride: true允许 Router 在运行时覆盖处理模式这是需要v1.3.0-alpha.1及以上版本的原因之一。Demo 使用缓冲请求体与已有的 Envoy AI Gateway 和 Istio 示例保持一致。对于大提示词建议改用requestBodyMode: FullDuplexStreamed并配合开启流式请求体处理的 Semantic Router 配置。注意 agentgateway不支持Streamed模式FullDuplexStreamed是唯一的流式选项。仓库的 extproc-policy.yaml 使用的正是 FullDuplexStreamed 组合requestBodyMode: FullDuplexStreamed同时显式开启requestTrailerMode: Send与responseTrailerMode: Send。进阶PreRouting 阶段 FullDuplexStreamed 的多网关方案agentgateway 会在其默认的 PostRouting 阶段运行 ExtProc此时路由已经选定因此路由无法再匹配 Router 写入的头。为此仓库 E2E 提供了第二个 Gateway 方案e2e/profiles/agentgateway/full-duplex.yaml新建 Gatewayagentgateway-full-duplex其AgentgatewayPolicy将phase: PreRouting并启用requestBodyMode: FullDuplexStreamed——在路由选择之前运行 ExtProcRouter 在流式处理完请求体后设置x-selected-model响应头如full-duplex-providerHTTPRoute依据x-selected-model头匹配带该头的请求路由到full-duplex-selected后端其余请求落到full-duplex-default后端两个后端provider-mocker都会上报收到的路径与凭证E2E 用例agentgateway-full-duplex-routing据此验证 Router 选择的模型名、provider 路径与凭证是否正确透传见 e2e/testcases/full_duplex_routing.go。E2E 用例还覆盖了end-of-stream rejection场景请求体完整送达后若模型名如full-duplex-unknown没有对应 provider 可服务Router 会替换掉被暂存的应答并直接拒绝请求见 e2e/testcases/full_duplex_routing.go。验证部署将 agentgateway proxy 端口转发到本地kubectl port-forward -n agentgateway-system svc/agentgateway-proxy 8080:80在另一个终端发送一个model: auto的 OpenAI 兼容请求curl -i -X POST http://localhost:8080/v1/chat/completions \ -H Content-Type: application/json \ -d { model: auto, messages: [ {role: user, content: What is the derivative of f(x) x^3?} ], max_tokens: 64, temperature: 0 }Semantic Router 应完成如下动作将数学提示词分类为math域命中math_decision路由选择math-expertLoRA 并启用 reasoning改写请求体中的模型名auto→ 所选模型/LoRAagentgateway 将改写后的请求转发给 vLLM 兼容后端。使用-i查看响应头其中包含 Semantic Router 写入的所选模型元数据如x-selected-model头。仓库 E2E 用例 agentgateway_traffic_routing.go 与上述验证逻辑完全一致通过port-forward建立8080:80隧道后发送{model:vllm-sr/auto, ...}的 chat/completions 请求并断言 HTTP 200。故障排查agentgateway proxy 未就绪kubectl get gateway agentgateway-proxy -n agentgateway-system kubectl get deployment agentgateway-proxy -n agentgateway-system kubectl logs -n agentgateway-system deployment/agentgatewayHTTPRoute 或 agentgateway backend 未被接受kubectl describe httproute semantic-router-vllm -n agentgateway-system kubectl describe agentgatewaybackend semantic-router-vllm -n agentgateway-system重点查看Conditions中的Accepted状态与ResolvedRefs确认parentRefs与backendRefs引用无误。Semantic Router 未响应 ExtProckubectl get pods -n agentgateway-system kubectl get svc semantic-router -n agentgateway-system kubectl logs -n agentgateway-system deployment/semantic-router kubectl describe agentgatewaypolicy semantic-router-extproc -n agentgateway-system检查点时注意AgentgatewayPolicy的targetRefs是否指向正确的 GatewaybackendRef的端口是否与 Helm 图表service.grpc.port50051一致extproc 模式下startup/readiness 探针使用标准 gRPC health service 探测 Router 端口图表默认--securefalse明文 gRPC这是 Kubernetes gRPC 探针的要求见 deploy/helm/semantic-router/README.md。Demo LLM 无响应kubectl get pods -n default -l appvllm-llama3-8b-instruct kubectl logs -n default deployment/vllm-llama3-8b-instruct确认模拟器 Pod 处于 Running 且 readiness 通过同时检查--lora-modules中是否包含了 Router 将选择的全部 LoRA 名。清理删除整个部署kubectl delete agentgatewaypolicy semantic-router-extproc -n agentgateway-system kubectl delete httproute semantic-router-vllm -n agentgateway-system kubectl delete agentgatewaybackend semantic-router-vllm -n agentgateway-system kubectl delete gateway agentgateway-proxy -n agentgateway-system kubectl delete deployment vllm-llama3-8b-instruct -n default kubectl delete service vllm-llama3-8b-instruct -n default helm uninstall semantic-router -n agentgateway-system helm uninstall agentgateway -n agentgateway-system helm uninstall agentgateway-crds -n agentgateway-system kind delete cluster --name semantic-router-agentgateway删除顺序遵循依赖关系先删策略与路由资源再删 Gateway 与后端最后卸载 Helm release 与整个集群。仓库 E2E 的 Teardown 也遵循同样的逆序清理逻辑见 e2e/profiles/agentgateway/profile.go。小结本文完整演示了 vLLM Semantic Router 与 agentgateway 在 Kubernetes 上的集成从 kind 集群创建、agentgateway 与 Gateway API 安装、Gateway/后端/路由资源创建到 ExtProc 策略挂载、端到端验证与清理。核心要点可归纳为三点gateway.mode: extproc让 Semantic Router 以 ExtProc gRPC 服务形态运行供 agentgateway 在转发前调用省略openai.model字段让网关透传 Router 改写后的模型名实现动态模型/LoRA 选择大提示词场景使用requestBodyMode: FullDuplexStreamedagentgateway 不支持Streamed配合config.global.router.streamed_body的max_bytes/timeout_sec调优必要时借助 PreRouting 阶段在路由选择前完成分类改写。仓库中的 deploy/kubernetes/agentgateway 清单、semantic-router-values/values.yaml 配置以及 e2e/profiles/agentgateway 的 E2E 实现是深入理解与本方案落地时最直接的参考。赞分享后端API网关模型推理服务AI Agent【免费下载链接】semantic-routerAn open, programmable decision layer for models and compute.项目地址https://gitcode.com/gh_mirrors/sem/semantic-router点击查看免费下载相关推荐semantic-router 以 agentgateway 作为 Kubernetes 数据面ExtProc 服务部署全指南semantic router 以 agentgateway 作为 Kubernetes 数据面ExtProc 服务部署全指南 本指南围绕 semantic后端API网关模型推理服务AI Agent在 Kubernetes 上通过 Istio Gateway 部署 vLLM Semantic Router基于 Envoy ExtProc 的语义路由实战指南在 Kubernetes 上通过 Istio Gateway 部署 vLLM Semantic Router基于 Envoy ExtProc 的语义路由实战指后端API网关模型推理服务AI Agent在 Kubernetes 上使用 vLLM Production Stack 部署 Semantic Router完整实战指南在 Kubernetes 上使用 vLLM Production Stack 部署 Semantic Router完整实战指南 导读 本文基于 vLLM 官后端API网关模型推理服务AI Agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考