Semantic Router Router API 参考：数据面入口、前端推理接口与后端协议路由实战

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

Semantic Router 将"路由决策"做成了一条可编程的开放决策层：客户端只面向一套 OpenAI 风格的推理接口，路由决策之后再由 Router 把请求翻译并转发到不同协议的上游模型。本指南以 v0.3 版 Router API 参考文档（website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-v0.3/api/router.md）为骨架，系统讲解数据面入口、前端 API 表面、后端模型协议，以及providers配置如何把逻辑模型绑定到物理上游。读完你将掌握：哪些端口承载哪类流量、Chat Completions 与 Responses API 如何被路由、Anthropic 与 vLLM Omni 后端如何接入，以及backend_refs、api_format、pricing等配置项的底层含义。

一、Router 数据面 API 在项目中的位置

Router 是通常通过 Envoy 暴露的数据面 HTTP 接口，职责是接收客户端推理请求、执行路由决策、把请求翻译成目标后端的协议并转发、再将响应翻译回客户端的原始协议。

与数据面相对的是控制面：健康检查、配置与发现等管理端点由 Router apiserver 提供，详见 Router Apiserver API。理解这一点是使用本 API 的前提——模型流量和管理流量永远走两套不同的表面，端口不同、权限策略也不同。

二、三个入口与默认端口

v0.3 参考文档给出的入口划分如下：

• 8801（Envoy 公网入口）：客户端推理流量的唯一入口。在 Operator 拓扑中，Router 独立（standalone）运行时也是直接服务8801，这正是原来 Envoy sidecar 所服务的端口，参见 standalone-mode 发布说明。
• 50051（ExtProc gRPC）：Router 的 gRPC external processing 钩子端口。在 runtime_bootstrap.go 中可以看到它的默认定义：flag.Int("port", 50051, "Port to listen on for gRPC ExtProc")。当以--gateway extproc运行时，Envoy 负责承接客户端流量，再通过该端口回调 Router 做请求改写与路由。
• 8080（Router apiserver）：控制面管理端口，默认绑定127.0.0.1。启动参数--api-port（默认取配置中的8080）与--api-bind（默认127.0.0.1）可以调整，参见 runtime_bootstrap.go。

两个网关模式的本质区别在 main.go 的启动标志中有明确注释：extproc指"ext_proc gRPC 服务器位于 Envoy 网关之后"，standalone指"在配置的 listener 上提供 OpenAI 兼容 API"。也就是说，8801/50051是 Envoy 网关形态的端口分工，而 standalone 模式下 Router 自己在监听器地址上直接提供推理 API。

三、前端 API：面向客户端的推理入口

Router 对客户端暴露的是标准 OpenAI 风格的推理接口，全部走公网入口：

关键点：

• POST /v1/chat/completions是主入口，绝大多数路由推理流量都走这里。
• Responses API 是一组对象生命周期接口：POST创建、GET/DELETE按{id}读写、GET .../input_items读取输入项。这些"存储型"操作依赖 Response API 服务与存储，未启用时集合端点会返回404。
• GET /v1/models默认由 apiserver（:8080）提供，而不是公网入口；如果客户端需要，可以在 Envoy 上再次暴露。这与 apiserver 文档 中"OpenAI-compatible model list"端点相互印证。

四、后端模型 API：路由决策之后的上游协议

路由决策完成之后，请求可能被指向不同协议的上游模型。这些后端属于面向后端的集成，不一定是公网客户端入口：

默认使用 OpenAI 兼容 chat-completions 的 provider 族包括openai、azure-openai、bedrock、gemini、vertex-ai。也就是说，openai等族名描述的是上游请求/响应形态（wire contract），而不是某个特定厂商的运行时；这一点在 protocol-compatibility.md 中有更严格的区分：模型的api_format选择编解码器，backend_refs[].protocol选择 HTTP/HTTPS 传输，backend_refs[].provider只提供认证与路径默认值，并不证明端点实现了某个 API 格式。

五、前端行为详解

5.1 OpenAI Chat Completions：路由推理的主入口

• 公开请求路径：POST /v1/chat/completions
• 这是路由推理的主入口。
• 请求可使用显式模型名（直接命中某模型），也可使用路由自动模型名（如MoM或auto），由 Router 根据信号与决策自动选择后端。

最小请求示例：

{ "model": "auto", "messages": [ { "role": "user", "content": "What is the derivative of x^2?" } ] }

model: "auto"是最典型的用法：Router 不直接指定后端，而是把请求送入路由管线，由决策引擎挑选模型。当前仓库的测试 route_models_test.go 也验证了模型列表会包含自动入口（如vllm-sr/auto）与显式模型名，说明两种寻址方式在 Router 中并行存在。

5.2 OpenAI Responses API：内部转换到 Chat Completions

• 公开请求路径：
  • POST /v1/responses
  • GET /v1/responses/{id}
  • DELETE /v1/responses/{id}
  • GET /v1/responses/{id}/input_items
• Router 在内部将POST /v1/responses转为 Chat Completions，再将后端响应转回 Responses API 格式。
• 检索与删除路径需要启用 Response API 服务/存储。

最小请求示例：

{ "model": "auto", "input": "Summarize the benefits of retrieval-augmented generation." }

注意这里的input字段是 Responses API 的输入形式（而非 Chat Completions 的messages）。Router 会完成"客户端 Responses → 后端 Chat Completions → 客户端 Responses"的往返翻译，客户端感知到的始终是统一的 Responses 协议形态。

六、后端行为详解

6.1 Anthropic API 后端

• 当模型配置为api_format: anthropic时，Router 可路由到 Anthropic 后端。
• Anthropic 支持位于后端模型 API 层。
• 客户端入口仍是 OpenAI 风格的 Chat Completions 或 Responses API，而不是POST /v1/messages。
• Router 将上游请求转为 AnthropicPOST /v1/messages，再将响应转回 OpenAI 兼容输出。
• 上游主机、路径及可选extra_headers来自backend_refs与端点 provider profile（base_url、可选chat_path）。
• OpenAI 风格的tools、tool_calls与tool消息会转换为 Anthropic 后端格式。
• 基于 Anthropic 的路由不支持流式（此条以 v0.3 参考文档为准；后续版本在跨协议矩阵中已进一步扩展，见 protocol-compatibility.md 的客户端-后端矩阵与功能可移植性表）。

从源码看，跨协议投影逻辑集中在 processor_protocol_anthropic_projection.go：projectAnthropicRequestForBackend在"保持公网请求原样"的前提下，推导出不同后端线格式可以承载的控制项，并且同一投影逻辑复用于选择、最终资格判定与编码三个环节。也就是说，Anthropic 转换不是一次性字符串改写，而是贯穿"选择后端 → 资格确认 → 编码请求"的完整管线。

6.2 vLLM Omni 与多模态/图像生成

• Router 支持通过 omni 模型与图像生成后端进行多模态/图像生成路由。
• vllm_omni是支持的图像生成后端类型之一。
• 当模态决策解析到 omni 模型时：
  • Chat Completions 请求返回原始 omni Chat Completions 响应。
  • Responses API 请求会规范为 Responses API 输出项；若生成了图像，可包含image_generation_call等项。
• 多模态或图像生成走上述路径，而不是单独的公开协议。

这意味着客户端协议面没有为图像生成新增专用端点——多模态能力被"折叠"进 Chat Completions 与 Responses 这两条既有路径中，由路由决策与后端类型共同决定行为。

七、配置关联：把模型绑定到上游目标

上游目标与各 provider 行为来自标准 router 配置：

providers: models: - name: claude-sonnet api_format: anthropic pricing: currency: USD prompt_per_1m: 3.0 completion_per_1m: 15.0 backend_refs: - base_url: https://api.anthropic.com provider: anthropic

• 上游路由目标配置在providers.models[].backend_refs[]。
• 可选的成本感知策略可使用pricing:。
• Response API 行为在global.services.response_api下配置。
• 模态与图像生成行为通过路由决策与vllm_omni等图像生成后端配置。

7.1 配置结构的源码视角

canonical_providers.go 定义了CanonicalProviderModel的字段，其中name（逻辑别名，供决策与客户端使用）、provider_model_id（实际发送给上游的模型 ID）、backend_refs（物理端点列表）、pricing（成本元数据）、api_format（上游线格式）是五个核心字段。而 canonical_providers.go 中的CanonicalBackendRef给出了backend_refs支持的具体维度：

这些字段在 JSON Schema 中也有一一对应，参见 router-config-v0.3.schema.json。

7.2 pricing 的语义边界

pricing是操作者填写的部署成本元数据，不是实时报价：currency可选、缺省按USD计；prompt_per_1m与completion_per_1m是每百万 token 的价格，必须为非负数。可选字段cached_input_per_1m与cache_write_per_1m显式为零表示免费。成本相关的响应头x-vsr-cost/x-vsr-cost-currency正是基于这些配置值计算的估算，而非供应商账单，详见 vsr-headers.md。

八、协议格式与翻译边界

api_format声明上游线格式，这是"后端行为"章节的底层机制：

数据面翻译遵循"客户端任意协议 × 后端任意协议"的全配对原则：客户端格式与后端格式各三种，每一种组合都由 Router 拥有请求、响应、传输错误与流式翻译路径——protocol-compatibility.md 给出了完整的 3×3 客户端到后端矩阵，并强调"Supported"只代表 Router 承担翻译，不保证每个字段都能跨协议无损表达。

跨协议发生时，请利用以下响应头定位问题（详见 vsr-headers.md）：

九、端口与表面选择速查

最后一条重要警示：不要把管理端口当作公网推理入口的替代品。apiserver 的端点会暴露配置与运行数据，甚至允许状态变更操作；管理端口默认绑定127.0.0.1，远程场景应使用内网或 SSH 隧道而不是直接发布端口。

总结

Router API 的设计核心是"一个数据面、两套协议面"：客户端永远面向 OpenAI 风格接口（Chat Completions 或 Responses），路由决策之后再由 Router 依据providers.models[].api_format把请求翻译为openai/responses/anthropic（以及 omni 图像生成）后端线格式。掌握8801 / 50051 / 8080三个端口的职责划分、前端四条 Responses 路径的存储依赖、backend_refs与pricing的配置语义，以及跨协议时的x-vsr-*可观测头，即可在生产环境安全地接入多协议、多后端的推理路由。

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