AI API 生产环境配置指南：超时、重试、429、降级与日志

开发环境里“一次请求成功”不等于生产可用。AI API 的生产问题通常来自超时、限流、上游波动、流式连接中断、Key 泄露和重试放大，而不是 SDK 语法本身。

本文给出一套与 OpenAI-compatible API 兼容的工程检查清单。通过 api.clawsocket.com 接入时，具体限额、模型列表、计费和上游路由请以控制台与服务公告为准。

生产配置总表

项目	建议起点	必须监控的指标
连接超时	5-10 秒	连接失败率
总请求超时	按模型和任务设定，避免无限等待	P50/P95/P99
重试次数	仅对可重试错误，最多 2-3 次	重试率、重试后成功率
429 处理	读取 Retry-After，指数退避加抖动	限流次数、排队时间
5xx 处理	短暂退避，必要时切备用模型	上游错误率
幂等性	为可重试任务生成请求 ID	重复执行数
日志	脱敏记录元数据，不记录密钥和敏感 Prompt	脱敏命中率、关联 ID

超时：区分连接、首 token 和总时长

至少把超时拆成三类：连接超时、首 token 超时、总响应超时。一个流式请求可能很快建立连接，但模型迟迟没有输出；也可能首 token 很快，后续输出卡住。

const controller = new AbortController()
const timeout = setTimeout(() => controller.abort(), 60_000)

try {
  const response = await fetch('https://api.clawsocket.com/v1/chat/completions', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.CLAWSOCKET_API_KEY}`,
      'Content-Type': 'application/json',
      'X-Request-Id': crypto.randomUUID()
    },
    body: JSON.stringify({
      model: process.env.AI_MODEL,
      messages: [{ role: 'user', content: 'health check' }]
    }),
    signal: controller.signal
  })
  if (!response.ok) throw new Error(`AI API status ${response.status}`)
} finally {
  clearTimeout(timeout)
}

超时值应根据任务类型配置：短文本问答、代码 Agent、长文档总结和批处理不应共用一个固定值。

重试：只重试确定安全的错误

不是所有失败都能重试：

错误	是否默认重试	原因
DNS、连接重置、408	是	请求可能尚未到达上游
429	是	按 Retry-After 或退避等待
500、502、503、504	谨慎重试	可能是短暂上游故障
400	否	请求格式或参数需要修复
401、403	否	Key、权限或账户配置问题
404 model not found	否	先修正模型 ID

建议使用指数退避并加入随机抖动，避免大量请求在同一时间再次打到网关：

function backoff(attempt: number) {
  const base = Math.min(8_000, 500 * 2 ** attempt)
  return base + Math.floor(Math.random() * 300)
}

对写入数据库、发送邮件、执行代码等有副作用的工具调用，重试前必须有幂等键或业务去重，否则可能重复执行。

429 限流：不要把重试变成流量放大器

收到 429 时应：

1. 优先读取响应中的 Retry-After。
2. 没有该字段时使用指数退避。
3. 在应用侧设置并发上限和队列。
4. 超过最大等待时间后返回可理解的降级结果。
5. 记录模型、Key 分组、租户和请求类型，定位是哪一层限流。

不要在客户端、任务队列和网关 SDK 三层同时无限重试。总重试预算应由一个地方统一控制。

降级与模型路由

降级不是“失败后随便换模型”，而是预先定义质量和成本边界：

主任务	备用路线	适用条件
复杂代码分析	更快或更低成本模型	可接受质量下降
长文档总结	支持长上下文的备用模型	保留必要上下文
实时客服	低延迟模型	先保证响应速度
图片输入	支持视觉的备用模型	先检查模态能力

模型 ID、能力和价格可能变化。通过 ClawSocket 控制台 查看当前可用模型后，再固化路由表，不要把文章里的示例名称直接用于生产。

流式响应的生产注意事项

流式输出要处理：

• 客户端断开时取消上游请求，避免继续消耗资源。
• 记录首 token 时间和完整响应时间。
• 对半截响应标记为失败，不要当作成功缓存。
• 处理 SSE 心跳、结束事件和代理缓冲。
• 对重连设计幂等策略，避免重复显示或重复执行工具。

日志与 API Key 安全

推荐记录以下元数据：request_id、租户 ID、模型 ID、状态码、输入输出 Token、首 token 延迟、总耗时、重试次数和错误分类。

不应记录：完整 API Key、Authorization Header、用户原始隐私数据、完整系统 Prompt、工具调用中的凭据。

Key 管理最低要求：

做法	建议
存储	Secret Manager 或部署平台密钥
权限	按项目、环境和团队拆分
轮换	定期轮换，旧 Key 设置过渡期
暴露	浏览器和移动端不要放长期 Key
泄露	立即吊销并检查调用日志

上线前检查清单

• [ ] 已在 快速接入 跑通最小请求
• [ ] 已确认模型 ID、协议、模态和计费
• [ ] 已区分 4xx、429、5xx 和网络超时
• [ ] 已设置总超时、并发上限和重试预算
• [ ] 已为有副作用的请求设计幂等键
• [ ] 已验证流式中断与客户端取消
• [ ] 已为主模型定义可接受的备用路线
• [ ] 已脱敏日志并配置告警
• [ ] 已准备 Key 轮换和紧急回滚流程

如果你的项目还处在迁移阶段，先看 OpenAI SDK 迁移到统一 API 网关，再把本文的稳定性配置加入灰度环境。

参考资料

• OpenAI API Reference
• OpenAI Cookbook: Handling rate limits
• ClawSocket 控制台
• FAQ