OpenAI API 生产最佳实践

从“调用 OpenAI API”到“在生产中运行它”之间有一份众所周知的清单：超时/重试行为、结构化输出、成本监控，以及你尚未遇到的那些故障模式。本指南就是这份清单，包含重要的代码细节。（大部分内容可直接迁移到任何提供商——Claude API 对比涵盖了差异。）

客户端配置：默认值不适合生产

python
from openai import OpenAI, AsyncOpenAI
client = AsyncOpenAI(
    timeout=30.0,        # 默认值高得多——限制尾部延迟
    max_retries=3,       # SDK 自动重试 429/5xx 并退避
)

服务中使用异步客户端——在异步 Web 处理器中调用同步方法会阻塞事件循环（详见同步 vs 异步决策）；并发量用信号量限制。

按路由设置超时：交互式 10-30 秒，仅在无法流式传输时设置更长。

每个进程一个客户端实例（连接池），密钥来自环境变量/密钥管理器——绝不在每次请求时创建。

可靠性模式

让 SDK 重试临时错误；你处理其余部分。 429/5xx → SDK 退避。400s → 你的 bug，不要重试。内容过滤结果 → 产品决策，不是重试。

在你的层实现幂等性：LLM 调用不是幂等的（相同输入，不同输出）——对于“恰好一次”语义（计费相关操作），基于你自己的请求 ID 进行控制，而不是依赖重试行为。

跨提供商故障回退：提供商状态页面每月都证明其必要性——网关架构使其可配置，回退链覆盖了请求级模式。

流式传输任何长内容——既为了用户体验（首 token 时间），也为了避免大输出时的 HTTP 超时（流式传输配方）。检查 finish_reason：length 结束意味着截断，你必须处理，而不是当作答案。

结构化输出：使用真正的特性

使用模式强制结构化输出（而不是“请返回 JSON”这样的提示，也不是传统的 json-mode-and-pray）：

python
from pydantic import BaseModel
class Ticket(BaseModel):
    category: str
    urgency: str
    summary: str
resp = client.chat.completions.parse(      # SDK 根据模式验证
    model='gpt-5-mini',
    messages=[{'role': 'user', 'content': f'分类此工单：{body}'}],
    response_format=Ticket,
)
ticket = resp.choices[0].message.parsed

模式强制保证*形状*，而非*语义*——语义验证（此 ID 是否存在？数学计算正确吗？）仍由你负责（验证指南）。

成本工程（真正影响账单的实践）

按路由选择合适的模型——最大的杠杆。分类/提取使用 mini/nano 层级；仅当评估证明需要时才使用前沿模型。

提示缓存：稳定的系统提示 + 工具在前，易变内容在后——重复前缀折扣是自动的，但前提是你的提示构造对缓存友好（不要在早期加入时间戳/UUID；与自托管服务相同的前缀规范）。

对可等待的任务使用 Batch API——固定 50% 折扣（何时及如何使用）。

从第一天起按特性监控成本：记录每次调用的模型、token（输入/输出/缓存）、延迟、特性标签。无法归因的账单飙升才是最痛苦的（可观测性选项）。

按路由限制 max_tokens——格式错误的提示导致失控生成是一种真实的成本事件。

安全与正确性

提示注入是时间问题，不是是否问题：任何进入提示的用户/网络内容都可能携带指令。严格分离系统/用户角色，将模型输出视为下游操作的不可信数据，并对关键工具调用进行验证或人工审批。

PII 规范：在可行的情况下发送前脱敏；了解你的保留设置（GDPR 工程）。

在生产中固定模型版本（如果提供，使用 gpt-5-2026-xx 风格的快照），并在移动固定版本前重新运行评估——静默的模型漂移会破坏调优后的提示（提示敏感性）。

评估作为回归门：一个包含 100 个案例的评估套件集成到 CI 中，是“我们认为它还能工作”和“知道它还能工作”之间的区别（工作流程）。

常见问题

Chat Completions 还是 Responses API？ 新项目：Responses（新特性会落在这里，Assistants API 用户正在迁移到它）。现有的 Chat Completions 代码继续工作——机会性地迁移。

组织密钥还是项目密钥？ 使用项目级密钥，配合按项目预算/限制——当密钥泄露或服务失控时控制爆炸半径。

速率限制余量？ 监控速率限制头部，在持续超过层级 70% 时告警，并在发布前请求提升，而不是发布期间。

---

*最后更新：2026 年 6 月。参数名称和模型层级会变化——请对照 platform.openai.com/docs 验证。*