AI API 可靠路由与请求诊断

可靠的 AI API 路由不是简单地写一个重试循环，而是为 API Key 明确主分组、备选分组、模型能力和请求限制，并在请求变慢或失败时保留足够的用户侧证据。

好的路由设计既要让结果可解释，也要防止切换分组时静默改变请求模型或计费策略。

从明确的 Key 策略开始

Modelflare 提供两种路由方式：

• 普通 API Key 使用一个明确的主分组，以及一份有顺序的回退分组列表；
• Smart API Key 在账户当前可用的分组中，按自身策略继续评估符合条件的候选项。

备选顺序不是流量拆分，而是一条优先级链路。当主分组无法正常使用时，请求会按顺序继续尝试后面的分组。

不同应用和环境应使用不同 Key。相比所有环境共享一个 Key，这样更容易理解分组权限、Quota、有效期和用量记录。

回退必须保持请求契约

把一个分组加入回退列表前，确认它：

1. 包含目标模型；
2. 支持相同端点和流式行为；
3. 允许请求所需的 Service Tier 或供应商私有字段；
4. 其用量倍率和请求频率限制可以接受；
5. 当前账户确实已经解锁该分组。

回退并不意味着可以随意换模型。请求中的模型和协议仍然决定最终 Wire Contract。

理解分组请求限制

请求频率限制会根据账户和实际使用的分组执行。为不同应用创建独立 API Key 有助于分析用量，但不会自动绕过账户或分组的限制。

当当前分组达到限制时，配置了备选分组的 API Key 可以继续尝试下一个可用分组。如果没有可用的备选项，请求会返回 429。客户端应使用有上限的退避，而不是立刻制造一批新的请求。

使用面向请求的性能指标

用量日志提供的是理解一次请求所需的产品级指标：

指标	可以帮助判断什么
响应总耗时	请求从提交到完成所用的时间
首次响应	第一段有效文本、推理或工具事件出现的时间
首次可见文本	本应输出文本的请求何时开始显示内容
可见输出速度	输出开始后的生成速度
输出 Token	本次请求产生的输出规模

首次响应较慢通常说明请求在开始生成前等待较久；首次响应正常但输出速度较低，则更接近生成阶段本身较慢。结合状态码、模型、分组和时间范围，可以判断问题是单次波动还是持续现象。

只有工具调用的响应可能没有可见文本，因此对 Responses 请求来说，“首次响应”比“首次可见文本”更适合作为第一段有效输出指标。

保留安全且有效的证据

Modelflare 的时序元数据不包含提示词、响应正文、原始请求体、API Key、邮箱或明文 IP。这样既能保留运维证据，也不会把延迟诊断变成第二个内容存储系统。

调查一次事故时，建议记录：

• Request ID 与时间；
• 请求模型和最终分组；
• 端点与流式模式；
• 下游状态；
• 状态码、响应总耗时和首次响应；
• 客户端是否在请求完成前取消。

这些证据足以让支持团队核对分组切换、模型生成变慢和客户端取消，同时不向普通日志暴露内部服务拓扑。

生产稳定性检查表

• 每个应用使用独立 API Key；
• 主分组和回退顺序有明确理由；
• 每个候选分组都验证模型与协议能力；
• 客户端超时能够覆盖真实工作负载；
• 仅对可重试错误使用带抖动的有限重试；
• 不把鉴权、Quota 或模型权限错误当成瞬时故障反复重试；
• 分别测试非流式和流式请求；
• 监控 429、首次响应、生成速度和取消；
• 把回退视为等价路径前，先检查分组计价。

稳定性来自两个条件：切换分组时仍然保持请求契约，失败时又能保留足够证据。有序备选可以减少对单一分组的依赖，而性能与用量记录让仍然发生的失败可以被解释。