生产环境实践

开发阶段“能调用”只是起点。生产接入还需要处理凭证隔离、超时、重试、日志、容量和降级。

环境隔离

建议至少区分：

development
staging
production

不同环境使用不同 API Key，不共享额度限制和路由策略。

配置而不是写死

以下内容应通过配置管理：

• Base URL
• API Key
• 模型 ID
• 超时时间
• 最大重试次数
• 并发限制
• 备用模型或降级策略

这样模型或路由调整时，不需要修改核心业务代码。

超时

不要只设置一个“总超时”。更理想的是区分：

• 建立连接
• 等待首字节
• 流式连接存活
• 整体任务时长

短文本对话与长推理、图像、音频、视频任务的合理超时不同。

重试

只对适合重试的错误进行有限重试，例如部分 429 和临时 5xx。

避免：

• 无限重试
• 毫秒级持续重放
• 对所有 4xx 重试
• 网络中断后无条件重复高成本生成请求

推荐指数退避并加入随机抖动。

并发与背压

业务突发流量不要直接无上限压向模型端点。

可以在自己的服务层加入：

• 并发上限
• 请求队列
• 用户级速率限制
• 超时取消
• 熔断或降级

降级

关键业务不要只依赖一个固定模型名称。

可根据业务设计：

Primary model
    ↓ unavailable
Fallback model
    ↓ unavailable
Graceful response / queue / manual review

备用模型应提前验证质量、协议和计费差异。

日志与可观测性

建议记录：

• 请求时间
• 业务请求 ID
• 模型
• 端点
• 状态码
• 延迟
• 重试次数
• Token 或成本相关摘要（按业务需要）

不要记录完整 API Key。Prompt 和 Response 是否记录，应由你自己的隐私与合规要求决定。

Key 轮换

生产 Key 应具备轮换流程：

1. 创建新 Key。
2. 同时部署新 Key。
3. 验证流量正常。
4. 撤销旧 Key。
5. 检查旧 Key 是否仍有调用。

这样可以减少直接替换导致的中断风险。

发布前检查

• [ ] 生产 Key 与开发 Key 分离
• [ ] 模型和 Base URL 可配置
• [ ] 429 / 5xx 有有限重试
• [ ] 请求有合理超时
• [ ] 日志不泄露密钥
• [ ] 有基本并发保护
• [ ] 有备用模型或业务降级方案
• [ ] 已验证实际模型价格与端点能力