Skip to content
AI Blog

OpenAI ChatGPT API 开发指南

最后更新：2026-08-12· 18 分钟阅读

🚀 快速通道

  • ChatGPT 国内版：点击直达↗
  • 稳定镜像站：打开镜像↗
  • 官方 ChatGPT：chatgpt.com ↗

OpenAI ChatGPT API 开发指南

更新时间：2026-08-12

导读

调通一次 curl 只是起点。生产接入需要：密钥隔离、可观测性、限流与重试、以及对 Responses API / Chat Completions 双轨并存的迁移预案——Assistants API 还可能处于 legacy 阶段。本文面向后端与全栈，假设你已读过 API 快速入门。字段与端点以 API Reference 为准。

推荐架构：BFF / Gateway

[Web / App] ──→ [你的 BFF / Gateway] ──→ api.openai.com
                      │
            租户鉴权、QPS 限流、
            Prompt 模板、RAG 注入、
            日志与 token 计量
层级应做禁止
客户端UI、会话 id持有 OpenAI Key
BFF组装 messages、合并检索结果把 Key 下发浏览器
Worker异步批处理、长任务无 timeout 裸 HTTP
OpenAI推理业务 RBAC

鉴权与 Key 生命周期

Authorization: Bearer sk-...
Content-Type: application/json
  • Key 从环境变量或 Vault 读取；启动时校验存在性。
  • 多租户 SaaS：不要让租户共享可被提取的 Key；由后端统一代理。
  • 轮换流程：新 Key 上线 → 双写验证 → 切流量 → 吊销旧 Key。

Platform 操作细节：Platform 概览。

选择 API 形态

形态端点（示例）适用
Responses API/v1/responses官方 Quickstart 常指向；工具调用
Chat Completions/v1/chat/completions存量、第三方示例多
Assistants API/v1/assistants 等有状态 Thread；查文档是否 legacy
Embeddings/v1/embeddings向量，见 embeddings 指南

新项目： 打开 Quickstart 跟随当前推荐。旧项目： 设迁移里程碑，避免无限期双栈。Assistants 迁移见 Assistants 开发指南。

请求设计：messages 与角色

{
  "model": "gpt-4o-mini",
  "messages": [
    {"role": "system", "content": "你是订单客服。仅回答物流与退换货；其他转人工。"},
    {"role": "user", "content": "订单 12345 到哪了？"}
  ],
  "temperature": 0.2,
  "max_tokens": 512
}

gpt-4o-mini 仅为示例 model ID，请替换为文档当前型号。若跟进旗舰换挡，见 GPT-6 Astra（gpt-6-astra）：生产路由务必保留回退到既有正式档，并记录核对日期。

角色用途
system规则、工具说明、输出格式
user终端用户或上游系统
assistant历史回复，多轮上下文
tool / function工具返回（视 API 版本）

多轮由你的服务维护 messages；接近上下文上限时摘要旧轮次。参数调优：文本生成。

流式输出（SSE）

聊天 UI 建议 stream: true 降低首字延迟：

curl https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "stream": true,
    "messages": [{"role": "user", "content": "用五言绝句描述清晨编程"}]
  }'

生产要点：

  • 客户端断开时取消上游请求，避免白烧 token。
  • 流式同样计费；拼接完整结果后再落库。
  • 网关正确处理 text/event-stream 与中间代理缓冲。

工具调用（Tools / Functions）

{
  "model": "gpt-4o-mini",
  "messages": [{"role": "user", "content": "查一下上海今天天气"}],
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "用户询问某城市当前天气时调用",
      "parameters": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"]
      }
    }
  }]
}
实践说明
schema 稳定便于 prompt 回归
服务端校验参数勿执行模型生成的 SQL/URL
超时与幂等外部 API 失败给降级文案

复杂编排：Agents SDK、Responses API。

错误处理与重试

import time
from openai import OpenAI, RateLimitError, APIStatusError

client = OpenAI()
RETRY = {429, 500, 502, 503, 504}

def chat_with_backoff(**kwargs):
    for i in range(5):
        try:
            return client.chat.completions.create(**kwargs)
        except RateLimitError:
            time.sleep(2 ** i)
        except APIStatusError as e:
            if e.status_code not in RETRY:
                raise
            time.sleep(2 ** i)
    raise RuntimeError("max retries")
  • 401 / 400：配置或请求体错误，勿盲目重试。
  • 429：尊重 Retry-After（若有）。
  • 日志保留 x-request-id。

限流、成本与缓存

  • 网关做租户级 QPS，避免单客户打满组织 RPM。
  • 长上下文单独限流；输入 token 常是成本大头。
  • 相同 FAQ + 相同 system 可考虑短 TTL 缓存（注意隐私与刷新）。
  • 按 model、route、tenant 聚合 token 与错误率。

结构化输出

  1. system 声明 JSON schema 与「只输出 JSON」。
  2. 使用官方 Structured Outputs / JSON mode（若 model 支持）。
  3. 服务端 JSON Schema 校验；失败则重试或降级。

Prompt 模板：Prompt Engineering。

生产上线清单

安全

  • Key 不进前端与移动端
  • 输入/输出日志脱敏
  • 高风险场景人工复核

可靠性

  • timeout（连接 + 读）
  • 429/5xx 退避
  • 连续失败时熔断降级

质量

  • golden prompts 发布前回归
  • system prompt 版本化（Git / CMS）

合规

  • 用户同意与数据留存政策
  • 按业务做内容安全过滤

与 Assistants API 的关系

Assistants 提供 Assistant / Thread / Run 有状态抽象，内置 File Search 等。官方可能引导至 Responses API 或 Agents SDK。新功能立项前阅读 Assistants 开发指南 的迁移说明，勿默认 Assistants 为长期主路径。

常见问题

多微服务共用一个 Key 可以吗？

可以但不推荐；至少按环境分 Key，最好按服务分，便于泄露隔离与配额分析。

如何实现多轮「记忆」？

自管 messages 或会话摘要；或用有状态 API（Assistants 等），并评估 vendor lock-in 与成本。

stream 与非 stream 质量一样吗？

同参数下模型相同；差异在体验与实现，非质量。

产品里让用户自带 Key（BYOK）？

可行但需严格隔离与审计；多数产品由后端统一代理。

如何对比 OpenAI 与 Claude 成本？

相同评测集分别记录 token 与延迟，查 OpenAI 定价 与 Anthropic 定价。

官方资源

下一步阅读

行动路径

今天：为现有调用加 timeout 与 429 退避。明天：接入 stream 并测首 token 延迟。本周：建立 20 条 golden prompts 回归集，写一页 gateway 架构说明供团队评审。

相关内容