调度是怎么做的
这一页讲内部机制。不了解也能正常使用，但排查「为什么走了这个凭据」时会很有用。
一次请求的完整路径§
请求进来之后，网关依次做这几件事：
- 认证——校验访问密钥是否有效、是否被停用
- 协议检查——这把密钥允许用当前协议吗
- 选分组——在密钥授权的分组里，找出能提供该模型的
- 选凭据——在分组的凭据池里，挑一个可用的
- 转发——必要时做协议转换，发往上游
- 失败则重试——换一个凭据再来，直到成功或用完次数
任何一步选不出目标，请求就会失败并给出原因码—— 这些码在路由检查和请求日志里都能看到，见本页最后一节。
先选分组§
候选分组要同时满足：
- 在这把访问密钥的授权范围内
- 处于启用状态
- 已开放请求里的那个模型
- 有效权重大于 0
满足条件的分组不止一个时，按权重挑。 这就是同一个模型配多个来源能自动容灾的原理： 一个分组的凭据全挂了，另一个还能接住。
再选凭据§
选定分组后，在它的凭据池里筛：
- 状态为可用（不是停用、冷却中、已拉黑）
- 订阅账号还需授权状态正常
- 有效权重大于 0
剩下的候选里按权重随机选一个。不是简单轮询—— 轮询在有凭据反复失败时会一直撞上它，加权随机配合冷却机制更稳。
权重§
权重决定相对分到多少流量，分组和凭据两级都支持自动与手动模式：
- 分组自动——使用默认权重
- 凭据自动——根据近期成功与失败情况动态计算
- 手动——范围为 1–100，数值越大，相对获得的流量越多
当前管理台和管理 API 都不接受手动权重 0。 需要暂时停止流量时，请停用对应分组或凭据；配置和历史统计仍会保留。
会话亲和§
开启后，网关会根据访问密钥、客户端协议以及请求中的指令或首个用户输入前缀 生成软亲和键。具有相同稳定前缀的后续请求，会优先复用之前成功的凭据。
亲和机制不会读取 previous_response_id、conversation 或其他上游资源 ID，也不保证有状态资源一定回到原凭据。 可靠使用这类资源时，请让分组只保留一个凭据， 或确认上游允许不同凭据共享同一资源。
亲和记录有 TTL 和容量上限（默认记一万条），超出后按老旧程度淘汰。亲和不是绝对的：如果记住的那个凭据已经冷却或拉黑， 网关仍会换一个可用的，保证请求能发出去。
参数配置见 运行时设置。
失败之后§
请求失败时，网关换一个凭据重试，直到成功或达到重试次数上限。
关键在于「什么算失败」：
- 会重试——上游限流、服务端错误、网络超时这类换个凭据可能就好的问题
- 不重试——请求本身有问题（参数错误、模型不存在）， 换凭据也一样失败，重试只是浪费时间
流式请求一旦开始输出，就不能再重试了—— 客户端已经收到前半段内容，换凭据重发会导致内容错乱。 所以网关只在第一个数据块到达之前做安全切换， 之后出错只能如实返回给客户端。
冷却与拉黑§
两级保护机制，避免坏凭据反复拖慢请求：
- 冷却——凭据出错后暂时跳过， 到点自动恢复。上游限流时最常见，属于正常现象
- 拉黑——连续失败次数超过阈值后自动摘除， 不再自动恢复，需要人工确认
区别在于：冷却是临时避让，假设问题会自己好； 拉黑是判定这个凭据坏了，比如密钥被吊销、账号欠费。
成功一次就会重置连续失败计数—— 偶发抖动不会累积到拉黑。
阈值配置见 运行时设置， 当前状态在 监控与排障 的健康页看。
选不中时的原因码§
路由检查和请求日志会给出具体原因码。对照表：
| 原因码 | 含义 | 怎么处理 |
|---|---|---|
| access_key_disabled | 访问密钥被停用 | 去访问密钥页启用它 |
| access_key_expired | 访问密钥已过期 | 新建一把或延长有效期 |
| protocol_filtered | 这把密钥没勾选该协议 | 在密钥里补勾对应协议 |
| model_filtered | 请求的模型不在允许范围 | 检查密钥的模型限制 |
| model_required_by_filter | 密钥限制了模型范围，但请求没带模型名 | 请求里显式指定模型，或去掉密钥的模型限制 |
| operation_unsupported | 渠道不支持该协议下的这个操作 | 换一个支持该能力的分组，见协议与转换边界 |
| native_route_required | 该请求要求原生路由，这个分组只能靠转换提供 | 改用与客户端协议一致的分组 |
| no_route_target | 找不到可路由的目标 | 确认密钥授权了至少一个分组 |
| group_disabled | 分组被停用 | 启用该分组 |
| group_filtered | 分组不在这把密钥的授权范围 | 在密钥里补上该分组 |
| no_available_group | 没有分组能提供这个模型 | 确认模型已在某个分组里开放 |
| no_credentials | 分组里一个凭据都没有 | 往分组里添加凭据 |
| group_weight_zero | 旧配置中的分组权重为 0 | 改为自动权重或 1–100 的手动权重 |
| credential_disabled | 凭据被停用 | 启用它，或依赖其他凭据 |
| credential_auth_unavailable | 订阅账号授权失效 | 重新授权，见订阅账号页 |
| credential_blacklisted | 凭据已被拉黑 | 确认凭据本身有效后恢复它 |
| credential_cooldown | 凭据正在冷却 | 等待自动恢复，或加更多凭据分担 |
| credential_weight_zero | 旧配置中的凭据权重为 0 | 改为自动权重或 1–100 的手动权重 |
| credential_not_allowed | 本次请求已经排除了这个凭据 | 正常现象，重试时不会再撞上刚失败的那个 |
| no_available_credential | 所有凭据都不可用 | 看健康页，多半是集体限流或密钥失效 |
看到原因码后，用 路由检查 改条件再试一次，能快速确认修改是否生效—— 不需要真的发一个请求。