AI API 接入前，先做好这 7 项准备

AI API 的第一个 Demo 往往只需要几十行代码，但把它安全地放进生产环境，需要考虑的事情远不止 Base URL 和 API Key。下面这份清单，适合在项目正式接入模型前逐项确认。

1. 先确定协议，而不是先选 SDK

不同模型平台使用的请求结构并不完全相同。常见入口包括 OpenAI 兼容的 Chat Completions / Responses、Anthropic Messages，以及 Gemini 原生的 generateContent。

如果项目已经有稳定的 SDK 和业务封装，优先选择与现有协议匹配的入口，通常比重新封装整条调用链更可靠。

2. 模型名应该是配置，不是常量

模型清单会随着渠道、分组和平台更新而变化。把模型名放到环境变量或配置中心，可以避免每次切换都重新发布代码。

MOONGPT_API_KEY=YOUR_API_KEY
MOONGPT_MODEL=YOUR_MODEL_NAME

不要把真实密钥写进 .env.example，更不要提交到公开仓库。

3. 按环境隔离 API Key

开发、测试和生产环境应使用不同 Key。这样做有三个直接好处：

• 用量更容易区分；
• 测试脚本不会消耗生产凭证；
• 单个 Key 泄露时，可以局部停用而不影响全部业务。

4. 为每个请求设置超时

模型生成时间比普通数据库查询更长，但这不等于请求可以无限等待。应用应同时设置连接超时、首字节超时和总超时，并把取消信号传递给下游。

5. 重试要有限且有条件

网络中断和部分 5xx 可以在有限次数内重试；无效 Key、错误模型名或请求体问题通常不应该重试。对于流式请求，还要判断已经展示给用户的内容能否安全重放。

6. 日志必须脱敏

日志可以记录接口路径、状态码、耗时、模型名和 request ID，但不要记录完整 Authorization、x-api-key、x-goog-api-key 或包含敏感业务数据的完整提示词。

7. 为失败准备业务降级

API Gateway 能降低部分单点波动，但无法消除所有故障。上线前应明确：失败时是切换模型、返回缓存结果、进入人工流程，还是提示用户稍后重试。

一套可控的失败策略，往往比“永远成功”的假设更接近稳定系统的真实样子。