Smart Routing 智能路由
Smart Routing 是一个按需启用的跨厂商回退机制。当请求发往主厂商失败时，网关可以在同一能力档位内将该请求重试到另一个厂商——不需要你改客户端代码。
该功能默认关闭。 每个 API key 创建时 Smart Routing 均为禁用状态。你可以在 dashboard 中按 key 开启，也可以随时关闭。
Smart Routing 做什么、何时回退
当某个 API key 开启了 Smart Routing 时，网关先将请求发往你的 model 参数所映射的厂商（即"原始厂商"）。如果该次尝试因下列任一条件失败，网关会按回退链将同一请求重试到下一个厂商：
触发条件 | 说明 |
|---|---|
| 上游限流 |
| 上游服务端错误 |
| 上游请求超时（同时涵盖网络级故障与 HTTP 408） |
| 上游配额耗尽 |
| 熔断器因连续失败而打开——网关直接跳过该厂商 |
其他任何 4xx 错误（如 400、401、403、404、422）视为客户端问题，原样透传给你的——Smart Routing 不会重试这些错误。
哪些厂商参与回退
Smart Routing 目前在 Anthropic ⇄ OpenAI ⇄ DeepSeek 之间做同能力档位映射（高档 / 中档 / 低档）。回退不会降档到更低能力档位。
其他厂商的模型——Gemini、GLM、Kimi 等——不在回退矩阵内。如果请求发往这些厂商失败，错误会直接返回给你，不存在跨厂商重试。
如果没有任何可用的回退目标（例如原始厂商不在矩阵内且已失败），网关返回 `502`，响应头 X-Served-By: none。
如何开启 / 关闭
Smart Routing 按 API key 在 dashboard 中控制：
打开 Dashboard → 你的 workspace → API Keys（
/dashboard/{workspace-slug}/api-keys）。找到你要配置的 key。
点击该 key 行内的路由开关，控件标签为 "跨厂商路由"（英文界面为 "Cross-provider routing"）。
开关即时生效。显示 "路由已开启"（"Routing enabled"）时，使用该 key 的请求参与 Smart Routing；显示 "路由已关闭"（"Routing disabled"）时，请求直接发往
model参数指定的厂商。
你可以随时关闭 Smart Routing。关闭后即恢复直连——不需要修改客户端配置；关闭期间请求不会被重试到其他厂商。
该设置存储在 API key 上（api_keys.routing_enabled，默认值 0）。使用未开启该标志的 key 发出的请求永远不会进入回退路径。
如何识别实际服务的模型
当请求启用了 Smart Routing 时，响应会携带四个 X-Served-By* 响应头，精确告诉你响应体由哪个厂商、哪个模型产出。
响应头 | 格式 | 含义 |
|---|---|---|
|
| 实际服务本次响应的厂商与模型。示例： |
| 逗号分隔的厂商列表 | 网关尝试过的所有厂商，按顺序。示例： |
|
| 你原始请求的厂商与模型。示例： |
|
| 回退原因。 |
示例
curl -sD - -o /dev/null https://api.codegateway.dev/v1/chat/completions \
-H "Authorization: Bearer $CODEGATEWAY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-sonnet-4-6",
"messages": [{"role": "user", "content": "hello"}]
}'响应头（原始厂商返回 5xx，触发回退）：
X-Served-By: openai:gpt-4o
X-Served-By-Fallback-Chain: anthropic,openai
X-Served-By-Original: anthropic:claude-sonnet-4-6
X-Served-By-Reason: 5xx当原始厂商成功时，X-Served-By 与 X-Served-By-Original 一致，X-Served-By-Reason 为 none。
流式响应
对于流式（SSE）响应，这些响应头在 body 之前发送。你可以先读到它们，再决定是否消费后续流——例如先记录实际模型，或中止处理。
curl -sN -D - https://api.codegateway.dev/v1/chat/completions \
-H "Authorization: Bearer $CODEGATEWAY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-sonnet-4-6",
"stream": true,
"messages": [{"role": "user", "content": "hello"}]
}'X-Served-By* 响应头出现在初始 HTTP 响应头中，在 SSE 流的任何 data: 行之前。
注意：通过 /v1/chat/completions 请求 Anthropic 系模型时，请求走跨端点翻译通路，不经 Smart Routing，也不返回 X-Served-By* 头；需要读取这些头请使用 /v1/messages。
对工具调用 / 输出格式的影响（开启时）
发生回退后，请求由不同厂商服务。跨厂商的响应不保证行为一致。如果你的集成依赖以下任何一项，请在生产依赖之前先对回退路径做测试：
工具调用 / function-call 语法——各厂商的工具定义与工具调用响应格式不同。
Stop reason——指示生成结束原因的字段，不同厂商可能使用不同取值或命名。
Token 计数——同等请求在不同厂商下的输入/输出 token 统计可能有差异。
延迟——回退目标厂商的响应速度可能更快或更慢。
当 `X-Served-By` 与 `X-Served-By-Original` 不一致时，说明响应由与你请求不同的厂商产出。 解析响应结构（工具调用、stop reason、token 用量）的自动化流程，在服务厂商发生变化时应重新验证行为——或者通过不开启 Smart Routing 来固定路径。
计费
按实际服务该请求的厂商计费——即 X-Served-By 中显示的厂商。如果回退将请求从一个厂商转移到了另一个厂商，你按目标厂商的费率计费，而非原始厂商。
要审计某次请求实际由哪个模型服务，打开 Dashboard → 你的 workspace → Logs（/dashboard/{workspace-slug}/logs）。每条日志在你请求的模型旁显示实际厂商与模型（actual_provider / actual_model），便于你在回退发生后核对成本与用量。