调度是怎么做的
这一页讲内部机制。不了解也能正常使用，但排查「为什么走了这个凭据」时会很有用。
一次请求的完整路径§
请求进来之后，网关依次做这几件事：
- 认证——校验访问密钥是否有效、是否被停用
- 协议检查——这把密钥允许用当前协议吗
- 筛选分组——在密钥授权的分组里，找出能提供该模型的
- 选凭据——先按分组优先级选层，再按路由策略和权重选择可用凭据
- 转发——必要时做协议转换，发往上游
- 失败则重试——换一个凭据再来，直到成功或用完次数
路由检查会说明访问密钥、分组或凭据为什么不能成为候选。 它的 reason_code 与客户端响应 code、 请求日志 error_code 是不同的信息，见本页最后一节。
候选分组§
候选分组要同时满足：
- 在这把访问密钥的授权范围内
- 处于启用状态
- 已开放请求里的那个模型
- 有效权重大于 0
分组优先级默认 0，可为负数，数值越大越优先。满足上述条件且有可用凭据时，先选最高优先级层；高层不可用时直接使用较低的可用层。
可用凭据§
继续筛选这些分组中的凭据：
- 状态为可用（不是停用、冷却中、已拉黑）
- 订阅账号还需授权状态正常
- 有效权重大于 0
同一优先级内，先按路由策略筛选，再按「分组权重 × 凭据权重」加权轮询。软亲和只在该层允许的候选中复用，实际流量不保证严格按权重分配。
权重§
分组和凭据权重默认均为 50，可设置为 1–100；在同层候选中，数值越大，相对获得的流量越多，不再根据成功率自动计算。
当前管理台和管理 API 都不接受手动权重 0。 需要暂时停止流量时，请停用对应分组或凭据；配置和历史统计仍会保留。
会话亲和§
开启后，网关会根据访问密钥、客户端协议以及请求中的指令或首个用户输入前缀 生成软亲和键。在当前优先级和路由策略允许的候选中，具有相同稳定前缀的后续请求会优先复用之前成功的凭据。
Chat Completions 与 Responses 也可通过有效的 prompt_cache_key 形成软亲和，但亲和命中不代表上游缓存必然命中。 Responses 的响应 ID 续接独立于软亲和，边界见协议页。
亲和记录有 TTL 和容量上限（默认记一万条），超出后按老旧程度淘汰。亲和不是绝对的：如果记住的那个凭据已经冷却或拉黑， 网关仍会换一个可用的，保证请求能发出去。
参数配置见 运行时设置。
失败之后§
安全允许换目标重试时，优先降到下一个更低的可用层，不先耗尽同层凭据；没有更低层时才继续当前层的其他凭据。降层后，本次请求不再回到更高层。跨组和跨层切换仍共用全局重试预算。
以下为内置默认行为；自定义处理见 上游错误规则：
- 会重试——上游限流、服务端错误、网络超时这类换个凭据可能就好的问题
- 不重试——明确的参数错误、上下文超限或内容政策拒绝， 换凭据也一样失败，重试只是浪费时间
明确的模型或能力拒绝可在安全边界内切换候选；已经输出或执行结果未知时，不盲目重放。响应 ID 续接不会换用其他凭据。
流式响应一旦提交给客户端，就不能再切换候选。开启空响应重试时，网关可短暂保留尚未产出内容的前导事件，因此收到上游数据块不等于已经向客户端输出。具体适用范围与计费限制见运行时设置。
冷却与拉黑§
两级保护机制，避免坏凭据反复拖慢请求：
- 冷却——凭据出错后暂时跳过， 到点自动恢复。上游限流时最常见，属于正常现象
- 拉黑——连续失败次数超过阈值后自动摘除；API Key 验活成功后可自动恢复，订阅凭据需人工处理
模型级限流只冷却该凭据的对应模型，其他模型仍可参与调度；明确的凭据级限制仍影响整份凭据。恢复凭据会清除其模型冷却。
订阅额度恢复可提前解除内置额度冷却；成功使用重置额度也会触发恢复。未记录冷却原因的历史状态仍保留原截止时间，可用显式恢复凭据操作处理。
区别在于：冷却是临时避让，假设问题会自己好； 拉黑是判定这个凭据坏了，比如密钥被吊销、账号欠费。
成功一次就会重置连续失败计数—— 偶发抖动不会累积到拉黑。
阈值配置见 运行时设置， 当前状态在 监控与排障 的健康页看。
选不中时的原因码§
路由检查按访问密钥、分组和凭据返回分层 reason_code。 完整原因、所属层级和处理方式统一收录在错误参考页。