Aether/docs/operations/routing-failover.md

调度策略级故障转移

调度策略的 default_policy 支持跨提供商的转移预算与错误规则。它们跟随当前请求的 routing_execution_policy 快照进入执行器，不依赖运行中修改全局系统设置。已有策略缺省为不限次数、不限累计时间、无全局错误规则。

{
  "default_policy": {
    "sticky_key_attempts": 2,
    "max_transfer_count": 3,
    "max_transfer_timeout_seconds": 90,
    "failover_rules": {
      "success_failover_patterns": [
        { "pattern": "(?i)capacity.*exhausted" }
      ],
      "error_stop_patterns": [
        { "status_codes": [400, 413], "pattern": "invalid.*parameter" },
        { "status_codes": [422] }
      ]
    }
  }
}

预算语义

• sticky_key_attempts 是首个粘性候选上的总尝试次数，2 表示首次请求加一次同 Key 重试。该行为保持不变。
• 全局 max_transfer_count 统计切换候选的次数，首次尝试不计数。同一提供商、端点、Key 上的重试不计数；改变该组合计一次。3 最多允许首次候选之后再切换三次。
• 全局 max_transfer_timeout_seconds 从首次候选开始执行时计时，覆盖后续重试与切换间的累计耗时。它在准备下一次尝试时检查，不会强制打断已经执行中的调用或已提交给客户端的流；单次连接、首字节、读取和非流式完整调用超时仍独立生效。
• 两个全局预算的 0 都表示不限制。被筛除、禁用或被提供商级预算跳过而未执行的候选不计数。
• 提供商自身的转移次数和时间预算继续生效。提供商预算耗尽只跳过该提供商，仍可尝试其他提供商；全局预算耗尽则不再执行任何提供商的新尝试。
• 预算仅约束当前请求，不能重置或替代客户端取消策略、权限校验及本地执行异常的终止行为。

错误规则

先匹配调度策略的全局显式规则；未匹配时继续使用提供商的规则及协议默认行为。本地执行函数真正返回 Err 时仍然终止，不做兜底重放。

• 成功转移规则：仅当 HTTP 200 响应匹配配置的正则时继续转移，不是对所有 200 进行重试。非流式请求匹配响应体；流式请求只匹配尚未交付业务输出的有界预读取内容。
• 结构化错误优先：标准流式请求统一在预读取阶段先解析完整 SSE 事件或 JSON 中的错误，再判断成功正则；不在半截错误载荷上提前触发成功转移，避免旧的 JSON 提前探测绕过错误终止规则。普通文本响应仍支持跨分片匹配。
• 图片成功保护：openai:image 的成功响应保留不重放行为，不因全局或提供商的成功正则再次生成图片；正常错误响应仍按错误规则处理。
• 错误终止规则：适用于 400–599 错误。状态码与正则都填写时要求同时满足；只填状态码表示该状态一律终止；只填正则表示在所有错误状态上匹配。流内错误使用解析后的错误状态，而不是外层 200。
• 网络错误：没有上游 HTTP 状态的连接、TLS、DNS、提交前超时等错误统一继续转移；提供商级别若单独配置了停止规则，仍按提供商规则处理。
• 正则使用 Rust regex 语法，支持 (?i) 等内联标志。服务端拒绝无效正则、无意义的空规则以及错误状态范围。每组最多 64 条，每条表达式最多 4096 字节。

流式 200 的恢复窗口

上游 HTTP 200 响应头不再默认关闭标准文本 SSE 的恢复窗口。执行器先缓冲协议开场事件，例如 Responses 的 response.created、Chat 的 role-only 增量、Anthropic 的空 message_start / 文本块起始事件。openai:image 图片专用流保留原来的响应头提交行为，成功正则不打开重放窗口。

首个业务内容之前的结构化错误、过早 EOF、首字节超时以及 200 正则命中会进入统一故障转移判断。真实文本、思考、工具调用或正常结束事件确定后，缓冲内容按原顺序交付；之后发生的错误保持终止，不重新执行原请求。

预读取受单次首字节时间和既有字节上限约束。达到字节上限时保守提交，避免无限缓冲；这意味着不能承诺识别响应任意位置的错误或正则。原始 HTTP 状态与最终执行结果是不同观测值，不能因流内失败而伪改已经发送的 HTTP 状态码。

排查

• routing_transfer_limit_reached：当前调度策略的累计次数或时间预算耗尽。
• provider_transfer_limit_reached：提供商自身的预算耗尽。
• local_stream_candidate_retry_scheduled：输出前的流内错误或 200 规则触发了继续调度。
• local_stream_transport_retry_scheduled：输出前传输错误触发了继续调度。