模型回退

​

工作原理

• 一个名称：暴露于路由 https://gateway.smith.langchain.com/routes/{name}。客户端调用此 URL，而非特定提供商的路径。
• 一个或多个回退链：每条链都是一个按优先级顺序排列的模型配置列表，网关会依次尝试。
• 触发条件：应导致网关转到链中下一个模型的上游 HTTP 状态码。例如，429 表示速率限制，500、502、503、504 表示其他提供商错误。

1. 根据请求路径确定传输格式，并仅考虑该格式的链（参见传输格式）。
2. 从这些链中选择一条（参见选择链）。
3. 调用该链的第一个模型配置。
4. 如果响应状态码与配置的触发条件匹配，则丢弃该响应并调用链中的下一个模型配置。
5. 重复此过程，直到某个候选模型返回非触发响应，或者链已遍历完毕——此时，将把最后一个候选模型的响应返回给调用方。

​

传输格式

​

创建回退配置

1. 前往 设置 → 网关 → LLM 网关，然后选择 模型回退 选项卡。
2. 点击 创建配置。
3. 输入 配置名称。此名称将成为网关 URL https://gateway.smith.langchain.com/routes/{name} 中的 {name}。
4. 选择该配置所属的工作区。模型配置是工作区范围的，因此只有该工作区的配置可供添加到链中。工作区之后无法更改——要移动它，需删除并重新创建配置。
5. 在回退触发条件下，查看应触发回退的 HTTP 状态码列表。该列表预先填充了其他提供商可能返回的临时代码（如 429、500 和 503）；您可以根据需要添加或移除代码。
6. 在模型回退链下，点击 添加链，然后按网关应尝试的顺序添加两到五个模型配置。链中的第一个模型决定了其传输格式；后续只能添加相同格式的配置。网关会按格式对链进行分组，每组中的第一条链即为该格式的默认链，当请求的模型未选择其他链时，网关将使用该默认链。
7. 点击 创建配置。

​

发起调用

curl https://gateway.smith.langchain.com/routes/my-route/v1/chat/completions \
    -H "Authorization: Bearer $LANGSMITH_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"messages":[{"role":"user","content":"ping"}]}'

curl https://gateway.smith.langchain.com/routes/my-route/v1/messages \
    -H "Authorization: Bearer $LANGSMITH_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"max_tokens":1024,"messages":[{"role":"user","content":"ping"}]}'

​

选择链

1. 如果 model 匹配某条链的别名，则使用该链。
2. 否则，如果 model 匹配某条链的主（第一个）模型配置的底层模型名称，则使用该链。
3. 如果 model 被省略，或与两者都不匹配，则使用该格式的第一条（默认）链。

• 一个 "model": "gpt-5.5" 的 /v1/chat/completions 请求将使用链 1，该链会在 OpenAI、Azure OpenAI 和自托管端点之间进行故障转移。
• 一个 "model": "gpt-4o-mini" 的 /v1/chat/completions 请求将使用链 2，该链会在 OpenAI 和 Fireworks 之间进行故障转移。
• 一个模型名称无法识别或被省略的 /v1/chat/completions 请求将使用该格式的默认链，即链 1。
• 无论其 model 字段是什么，任何 /v1/messages 请求都将使用链 3，因为它是唯一的 Anthropic 兼容链。链 1 和链 2 在该路径上永远不符合条件。

​

后续步骤

• 自定义模型提供商：直接调用相同的模型配置，一次一个，无需回退链。
• 消费策略：在回退路由之外应用成本限制。