路由与可靠性
Monoize 如何选择路由、重试失败、前进回退和熔断。
路由选择
对每个请求，Monoize 按以下顺序解析路由：
- 模型重定向。 先执行 API 密钥规则，再执行全局规则。第一条匹配的规则重写模型名。
- Provider 选择。 Monoize 收集 API 密钥允许的 Group 中，已启用且通过内嵌 Channel 映射该模型并具备完整价格的 Provider。
- Channel 选择。 每个 Provider 只有一个内嵌 Channel。该 Channel 已启用且健康时，Monoize 使用它。
重试与回退
Monoize 先尝试所选 Provider 的 Channel，再前进到同一 Group 中的下一个 Provider。
- 每个 Channel 获得
channel_max_retries + 1次尝试。默认为 1 次尝试，不做 Channel 内重试。 channel_retry_interval_ms在 Channel 内重试之间插入等待。默认为0。- 一个 Provider 耗尽后，Monoize 继续尝试下一个符合条件的 Provider。
- 所有 Provider 都耗尽后，客户端收到 HTTP
502，错误码为upstream_error。
哪些错误会重试同一 Channel
| 错误 | 同 Channel 重试 | 前进到下一路由 |
|---|---|---|
HTTP 408、429、5xx | 是 | 是，Channel 预算耗尽后 |
| 超时、连接被拒绝或重置 | 是 | 是，Channel 预算耗尽后 |
其他上游错误（如 400、401、404） | 否 | 是，立即前进 |
| Monoize 自身错误（认证、余额、校验、计费） | 否 | 否；路由终止 |
所有路由都失败时
请求的模型没有可用路由，或者所有路由在产生任何输出前都失败时，Monoize 直接返回错误，不会改用别的模型。客户端收到的回复，一定来自它请求的模型。
流式保证
Monoize 发出首个协议数据事件或错误事件后停止回退。SSE 注释和保活事件不锁定上游。在此边界之前，Monoize 可以切换 Channel 和 Provider。一次可见生成始终来自同一次上游尝试。
流式超时
使用 monoize_stream_idle_timeout_ms 限制两次上游流事件之间的等待时间。默认值为 120000 毫秒。
Monoize 等待响应头的时限为有效 request_timeout_ms 的十倍，且不低于 600000 毫秒。
读取上游 HTTP 错误响应体时共用此时限。
收到成功响应头后，持续输出的流没有总时长限制。
此规则也适用于图像流，以及收集后转为非流式响应的上游流。
非流式上游请求仍受总请求超时限制。
熔断器
每个 Provider 有 circuit_breaker_enabled 开关。启用时：
- 一个 Channel 在
window_seconds（默认30）内出现failure_count_threshold（默认3）次可重试失败后变为不健康。 - 不健康的 Channel 在
cooldown_seconds（默认60）内被跳过。由 HTTP429引起的失败使用rate_limit_cooldown_seconds（默认15）。 - 开启
per_model_circuit_break后，健康状态按(Channel, 模型)组合跟踪，而不是按 Channel。 - 开启主动探测后，Monoize 在后台探测冷却结束的 Channel，达到成功阈值后恢复。
将 Provider 的 circuit_breaker_enabled 设为 false 可忽略其健康状态。该 Provider 的被动熔断和主动探测随之停止。
会话亲和
Monoize 可以优先选择此前服务该会话的 Channel。可在全局或 Channel 层配置亲和。优先 Channel 仍须满足资格和健康规则。Responses 的 previous_response_id 历史由 Monoize 在内部解析，不要求上游保存状态。
时间指标
请求日志中的每一行记录总耗时、首字节时间和可见输出的每秒 Token 数。修改 Group 优先级之前，用这些数值比较 Provider。