路由与容灾：请求怎么选线路，出问题怎么切换

VisionCoder 大模型 API 网关的路由与容灾原理：请求怎么过滤选路、同一会话怎么保持在同一线路、失败怎么自动切换、异常线路怎么熔断恢复，以及没有产出的失败请求不收费的规则。

每个模型背后是多家供应商的线路。这一页说明网关怎么给线路打分选路、同一会话怎么保持在同一线路、失败时怎么切换、异常线路怎么熔断和恢复。数值标注「默认」的，平台可以调整。

一次请求怎么选线路

• 先过滤：只保留对你的空间开放、渠道和模型都支持本次请求协议、能力满足这次请求（带图片的请求排除不支持图片的线路，超长提示词排除上下文不够的线路）的线路，并去掉正在熔断的。
• 再分层：线路分主力、备用、兜底三层。先在主力层里选，主力层全部熔断或满载时才溢出到备用层，再到兜底层。
• 层内按得分加权随机选：得分由成功率、速度、成本和余量算出，不会把所有流量压在同一条线路上。你可以在 API 密钥上选调用偏好：速度优先、均衡、省钱。
• 网关只在这些线路之间转发，不做协议转换：模型没有声明的协议会直接返回 400，并提示它支持的接口路径。

同一会话走同一线路

• 会话标识优先取客户端自带的（Claude Code 的 metadata.user_id、Codex 的 prompt_cache_key 等），没有就用系统提示加第一轮对话的前缀算出，并限定在你的 API 密钥内。
• 会话第一次请求按得分选线路并记住；之后只要那条线路仍然健康、没有满载，就继续用它，让上游的上下文缓存持续命中，省钱也更快。
• 线路明显变差时才会换：近 5 分钟样本不少于 20 个且成功率低于 90% 时立即换；首字明显变慢并持续一段时间也会换。换到的线路成为新的记忆。
• 记忆默认保留 30 分钟（滑动续期）。记忆只用于选线路，丢失只会多一次缓存未命中，不影响调用。

失败时怎么切换

• 只在首字节发给你之前切换：连接失败、上游 5xx、上游 429、首字超时，以及上游返回 2xx 但实际是空响应或错误体，都会换下一条线路重试。
• 一次请求通常最多试 4 个线路，每次尽量换到不同的上游账号和厂商渠道；全部都失败时返回错误：常见的是 503「当前没有可用的模型通道」，全部被上游限流时是 429 并带 Retry-After。
• 参数错误这类 4xx 换线路结果也一样，不会重试，错误原样返回给你。
• 首字节发出后不再切换：失败时按协议发一个错误事件结束流，已经产出的部分照常结算。
• 请求的首字节迟迟没到时，网关会向下一个候选线路再发一份，谁先出字用谁；这类救援有按模型的预算上限，只针对真正卡住的请求。

熔断与恢复

• 熔断以「线路 × 协议」为单位：某条线路的 chat 协议出问题，不影响它的 responses 协议，也不影响同一渠道上的其他模型。
• 默认连续 3 次真实失败（5xx、超时、连接错误）会熔断，成功一次清零；近 5 分钟至少 10 个样本且成功率低于 50% 也会熔断。客户端 4xx 不计。
• 熔断时长默认从 15 秒起，探测失败就翻倍，最长 2 分钟；冷却后只放小流量去探测，探测成功才恢复，恢复后流量立即按得分回来。
• 上游 429 或 529 不算熔断失败：该线路按上游给的 Retry-After 冷却（上游没给时默认 5 秒，最多 60 秒），请求换别的线路。
• 上游返回 401、402、403（凭据失效、欠费）时，这个渠道账号上的所有模型一起摘掉，换凭据后才恢复。
• 多个网关副本共享熔断状态；平台运营也可以手动熔断或恢复某条线路，必须写原因，留有记录。

失败请求怎么计费

• 一次请求只预留一次额度，最终只按成功的那次结算；中间失败的尝试成本由平台承担，不向你收费。没有产出的失败请求不收费，已经产出的部分按实际用量计费。
• 各种情况的精确规则见计费规则页的「失败不收费」。

查看计费规则 接入教程 返回首页