大模型应用开发必读：OpenAI 接口格式全方位详解与生产最佳实践

本文面向开发者，系统梳理 OpenAI 及 OpenAI-Compatible API 的常见接口格式：认证、模型列表、Chat Completions、Responses、Embeddings、工具调用、流式输出、错误处理与最佳实践。

文章目录

• • 1. 什么是 OpenAI 接口格式
  • 2. 基础请求规范
  • • 2.1 Base URL
    • 2.2 请求头
  • 3. 常见接口总览
  • 4. 模型列表接口：GET /v1/models
  • • 4.1 请求示例
    • 4.2 响应示例
    • 4.3 字段说明
  • 5. Chat Completions 接口
  • • 5.1 请求路径
    • 5.2 最小请求示例
    • 5.3 cURL 示例
    • 5.4 messages 格式
    • 5.5 content 的几种形态
    • • 纯文本 content
      • 多模态 content
  • 6. Chat Completions 常用参数
  • • 参数选择建议
  • 7. Chat Completions 响应格式
  • • 7.1 非流式响应示例
    • 7.2 核心响应字段
    • 7.3 finish_reason 常见值
  • 8. 流式输出格式
  • • 8.1 SSE 返回格式
    • 8.2 流式解析要点
  • 9. 工具调用 Tool Calling
  • • 9.1 定义工具
    • 9.2 模型返回工具调用
    • 9.3 回传工具结果
  • 10. 结构化输出 JSON
  • • 10.1 JSON Object 模式
    • 10.2 JSON Schema 模式
    • 10.3 实践建议
  • 11. Responses 接口简介
  • • 11.1 请求路径
    • 11.2 简单请求示例
    • 11.3 多模态输入示例
    • 11.4 Responses 与 Chat Completions 对比
  • 12. Embeddings 接口
  • • 12.1 请求路径
    • 12.2 请求示例
    • 12.3 响应示例
    • 12.4 字段说明
  • 13. 错误响应格式
  • • 13.1 常见错误响应
    • 13.2 常见 HTTP 状态码
    • 13.3 重试策略
  • 14. Token 与上下文窗口
  • • 14.1 Token 是什么
    • 14.2 usage 字段
    • 14.3 上下文窗口
  • 15. SDK 调用示例
  • • 15.1 Python 示例
    • 15.2 Node.js 示例
    • 15.3 OpenAI-Compatible Base URL
  • 16. 兼容不同服务商时的注意事项
  • 17. 生产环境最佳实践
  • • 17.1 安全
    • 17.2 稳定性
    • 17.3 成本控制
    • 17.4 输出质量
  • 18. 一份标准请求模板
  • 19. 快速排查清单
  • 20. 总结

1. 什么是 OpenAI 接口格式

OpenAI 接口格式通常指以 OpenAI REST API 为参考的一套请求与响应约定。很多大模型服务商会提供 OpenAI-Compatible API，即尽量复用 OpenAI 的路径、请求字段和响应结构，方便开发者低成本迁移。

典型特征包括：

• 使用 HTTP REST 接口。

• 使用 JSON 作为主要请求与响应格式。

• 使用 Authorization: Bearer API_KEY 进行鉴权。

• 以 model 字段指定模型。

• Chat 类任务使用 messages 数组表达上下文。

• 支持非流式和流式输出。

• 支持工具调用、结构化输出、Embedding 等能力。

2. 基础请求规范

2.1 Base URL

官方 OpenAI API 常见基础地址：

https://api.openai.com/v1

OpenAI-Compatible 服务一般会提供自己的 Base URL，例如：

https://api.example.com/v1

调用时通常只需要替换 Base URL 和 API Key，业务代码可以尽量复用。

2.2 请求头

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

常见请求头说明：

不要把 API Key 写进前端代码、Git 仓库、日志或报错信息中。生产环境应通过服务端代理、环境变量或密钥管理服务读取。

3. 常见接口总览

4. 模型列表接口：GET /v1/models

4.1 请求示例

curl https://api.openai.com/v1/models \\
-H "Authorization: Bearer $OPENAI_API_KEY"

4.2 响应示例

{
"object": "list",
"data": [
{
"id": "gpt-4.1",
"object": "model",
"created": 1715367049,
"owned_by": "openai"
}
]
}

4.3 字段说明

5. Chat Completions 接口

Chat Completions 是目前 OpenAI-Compatible 生态中最常见的接口格式，适合聊天、问答、摘要、分类、代码生成、Agent 工具调用等场景。

5.1 请求路径

POST /v1/chat/completions

5.2 最小请求示例

{
"model": "gpt-4.1-mini",
"messages": [
{
"role": "user",
"content": "用一句话解释什么是向量数据库"
}
]
}

5.3 cURL 示例

curl https://api.openai.com/v1/chat/completions \\
-H "Authorization: Bearer $OPENAI_API_KEY" \\
-H "Content-Type: application/json" \\
-d '{
"model": "gpt-4.1-mini",
"messages": [
{"role": "user", "content": "写一个 Python 快速排序"}
]
}'

5.4 messages 格式

messages 是 Chat Completions 的核心字段，用于表达上下文。

示例：

{
"model": "gpt-4.1-mini",
"messages": [
{
"role": "system",
"content": "你是一个资深后端工程师，回答要准确、简洁。"
},
{
"role": "user",
"content": "解释 HTTP 429 的含义。"
}
]
}

5.5 content 的几种形态

纯文本 content

{
"role": "user",
"content": "总结下面这段文章"
}

多模态 content

部分模型支持数组形式的 content，用于同时传入文本和图片。

{
"role": "user",
"content": [
{
"type": "text",
"text": "请描述这张图片"
},
{
"type": "image_url",
"image_url": {
"url": "https://example.com/image.png"
}
}
]
}

OpenAI-Compatible 服务对多模态字段的支持差异较大。接入第三方服务时，应优先查看该服务的模型能力说明。

6. Chat Completions 常用参数

参数选择建议

稳定、可控任务

• 分类

• 信息抽取

• JSON 生成

• 代码转换

建议：

{
"temperature": 0,
"top_p": 1
}

创意、发散任务

• 文案创作

• 头脑风暴

• 故事生成

• 命名方案

建议：

{
"temperature": 0.7,
"top_p": 0.9
}

7. Chat Completions 响应格式

7.1 非流式响应示例

{
"id": "chatcmpl-abc123",
"object": "chat.completion",
"created": 1710000000,
"model": "gpt-4.1-mini",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "向量数据库是一种专门存储和检索向量表示的数据系统，常用于语义搜索和推荐。"
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 20,
"completion_tokens": 28,
"total_tokens": 48
}
}

7.2 核心响应字段

7.3 finish_reason 常见值

8. 流式输出格式

流式输出适合聊天界面、长文本生成、实时交互等场景。请求时设置：

{
"model": "gpt-4.1-mini",
"messages": [
{"role": "user", "content": "写一段 200 字的产品介绍"}
],
"stream": true
}

8.1 SSE 返回格式

OpenAI 流式响应通常使用 Server-Sent Events，每个片段形如：

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"delta":{"content":"你好"},"index":0,"finish_reason":null}]}

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"delta":{"content":"，世界"},"index":0,"finish_reason":null}]}

data: [DONE]

8.2 流式解析要点

• 按行读取，以 data: 开头的行为有效数据。

• 遇到 data: [DONE] 表示结束。

• 每个 chunk 中的增量内容通常位于 choices[0].delta.content。

• 工具调用流式返回时，函数名和参数可能分片到达，需要拼接。

9. 工具调用 Tool Calling

工具调用允许模型在需要时输出结构化的函数调用请求，由业务系统执行真实工具，再把工具结果返回给模型。

9.1 定义工具

{
"model": "gpt-4.1-mini",
"messages": [
{
"role": "user",
"content": "北京今天适合跑步吗？"
}
],
"tools": [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "查询指定城市的天气",
"parameters": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "城市名称"
}
},
"required": ["city"]
}
}
}
],
"tool_choice": "auto"
}

9.2 模型返回工具调用

{
"role": "assistant",
"content": null,
"tool_calls": [
{
"id": "call_123",
"type": "function",
"function": {
"name": "get_weather",
"arguments": "{\\"city\\":\\"北京\\"}"
}
}
]
}

9.3 回传工具结果

执行工具后，将结果以 tool 消息追加进 messages：

{
"role": "tool",
"tool_call_id": "call_123",
"content": "{\\"city\\":\\"北京\\",\\"temperature\\":28,\\"air_quality\\":\\"良\\",\\"suggestion\\":\\"适合傍晚慢跑\\"}"
}

然后再次请求模型，让模型基于工具结果生成自然语言回答。

模型只负责“提出调用请求”，不能直接访问真实系统。是否执行工具、如何鉴权、如何校验参数，必须由业务服务端控制。

10. 结构化输出 JSON

很多业务希望模型稳定返回 JSON。常见做法是使用 response_format。

10.1 JSON Object 模式

{
"model": "gpt-4.1-mini",
"messages": [
{
"role": "user",
"content": "从句子中抽取姓名和城市：张三住在杭州。"
}
],
"response_format": {
"type": "json_object"
}
}

返回内容可能是：

{
"name": "张三",
"city": "杭州"
}

10.2 JSON Schema 模式

部分模型支持更严格的 JSON Schema：

{
"response_format": {
"type": "json_schema",
"json_schema": {
"name": "person_info",
"schema": {
"type": "object",
"properties": {
"name": {"type": "string"},
"city": {"type": "string"}
},
"required": ["name", "city"],
"additionalProperties": false
}
}
}
}

10.3 实践建议

• 对强结构化任务，设置 temperature: 0。

• 在 prompt 中明确“只输出 JSON，不要解释”。

• 服务端仍需做 JSON parse 和 Schema 校验。

• 不要假设模型永远返回合法 JSON，异常分支必须处理。

11. Responses 接口简介

Responses 是 OpenAI 新一代统一生成接口，目标是把文本生成、多模态输入、工具调用等能力统一到一个更灵活的格式中。

11.1 请求路径

POST /v1/responses

11.2 简单请求示例

{
"model": "gpt-4.1-mini",
"input": "用三点解释什么是 RAG。"
}

11.3 多模态输入示例

{
"model": "gpt-4.1-mini",
"input": [
{
"role": "user",
"content": [
{
"type": "input_text",
"text": "请分析这张图中的主要信息"
},
{
"type": "input_image",
"image_url": "https://example.com/chart.png"
}
]
}
]
}

11.4 Responses 与 Chat Completions 对比

如果你要兼容更多第三方模型服务，优先使用 Chat Completions；如果主要使用 OpenAI 官方新模型和复杂多模态能力，可以评估 Responses。

12. Embeddings 接口

Embedding 用于把文本转换为向量，常用于：

• 语义搜索

• RAG 检索增强生成

• 文本聚类

• 推荐系统

• 相似度计算

12.1 请求路径

POST /v1/embeddings

12.2 请求示例

{
"model": "text-embedding-3-small",
"input": [
"OpenAI 接口格式详解",
"如何调用 Chat Completions API"
]
}

12.3 响应示例

{
"object": "list",
"data": [
{
"object": "embedding",
"index": 0,
"embedding": [0.0123, -0.0456, 0.0789]
}
],
"model": "text-embedding-3-small",
"usage": {
"prompt_tokens": 12,
"total_tokens": 12
}
}

12.4 字段说明

13. 错误响应格式

13.1 常见错误响应

{
"error": {
"message": "Incorrect API key provided",
"type": "invalid_request_error",
"param": null,
"code": "invalid_api_key"
}
}

13.2 常见 HTTP 状态码

13.3 重试策略

建议只对以下情况自动重试：

• 429：限流

• 500/502/503/504：服务端或网关异常

• 网络超时、连接中断

不建议对以下情况盲目重试：

• 400：请求参数错误

• 401：鉴权失败

• 403：权限不足

• 404：资源不存在

14. Token 与上下文窗口

14.1 Token 是什么

Token 是模型处理文本的基本单位，可以近似理解为“词片段”。中文、英文、标点、空格都会被切分为 token。

14.2 usage 字段

{
"usage": {
"prompt_tokens": 1200,
"completion_tokens": 300,
"total_tokens": 1500
}
}

14.3 上下文窗口

每个模型都有上下文窗口限制。请求中的历史 messages、系统提示词、工具定义、图片描述和预期输出都会占用上下文。

优化建议：

• 长对话定期摘要历史。

• RAG 只放入最相关片段，不要整篇塞入。

• 工具定义保持简洁。

• 明确最大输出长度。

• 对日志、网页、代码等长文本先做切分和筛选。

15. SDK 调用示例

15.1 Python 示例

from openai import OpenAI

client = OpenAI(api_key="YOUR_API_KEY")

resp = client.chat.completions.create(
model="gpt-4.1-mini",
messages=[
{"role": "system", "content": "你是一个严谨的技术助手。"},
{"role": "user", "content": "解释 OpenAI Chat Completions 的 messages 字段。"},
],
temperature=0.2,
)

print(resp.choices[0].message.content)

15.2 Node.js 示例

import OpenAI from "openai";

const client = new OpenAI({
apiKey: process.env.OPENAI_API_KEY,
});

const resp = await client.chat.completions.create({
model: "gpt-4.1-mini",
messages: [
{ role: "system", content: "你是一个严谨的技术助手。" },
{ role: "user", content: "给我一个 OpenAI API 请求示例。" },
],
temperature: 0.2,
});

console.log(resp.choices[0].message.content);

15.3 OpenAI-Compatible Base URL

很多第三方服务可以通过 SDK 的 baseURL 参数接入：

import OpenAI from "openai";

const client = new OpenAI({
apiKey: process.env.PROVIDER_API_KEY,
baseURL: "https://api.example.com/v1",
});

const resp = await client.chat.completions.create({
model: "provider-model-name",
messages: [
{ role: "user", content: "你好" },
],
});

16. 兼容不同服务商时的注意事项

虽然很多服务号称 OpenAI-Compatible，但兼容程度并不完全一致。

建议在业务代码里抽象一层 LLM Provider Adapter，把模型名映射、参数裁剪、错误处理、流式解析统一封装，避免业务层到处写兼容逻辑。

17. 生产环境最佳实践

17.1 安全

• API Key 只保存在服务端。

• 使用环境变量或密钥管理服务。

• 不把完整请求和响应直接打进日志，尤其是用户隐私和密钥。

• 对用户输入做内容隔离，避免把外部文本当成系统指令。

• 工具调用必须有白名单、参数校验和权限控制。

17.2 稳定性

• 设置请求超时。

• 对 429 和 5xx 做指数退避重试。

• 对长任务使用流式输出或异步任务。

• 提供备用模型或备用服务商。

• 记录 request id、模型名、耗时、token 用量。

17.3 成本控制

• 限制最大输出 token。

• 对长上下文做摘要和裁剪。

• 缓存稳定问题的结果。

• Embedding 批量处理，避免逐条请求。

• 为不同任务选择合适尺寸的模型，不要所有任务都用最大模型。

17.4 输出质量

• system prompt 写清角色、目标、边界。

• 对结构化任务使用 JSON Schema。

• 对复杂任务拆步骤，必要时工具化。

• 对关键业务输出做人审或规则校验。

• 保存失败样本，用于持续优化 prompt 和参数。

18. 一份标准请求模板

下面是一份比较通用的 Chat Completions 请求模板：

{
"model": "gpt-4.1-mini",
"messages": [
{
"role": "system",
"content": "你是一个严谨、简洁、可靠的技术助手。回答必须基于用户提供的信息，不确定时说明不确定。"
},
{
"role": "user",
"content": "请总结下面的接口文档，并列出调用注意事项：…"
}
],
"temperature": 0.2,
"top_p": 1,
"max_tokens": 1200,
"stream": false
}

如果需要 JSON 输出：

{
"model": "gpt-4.1-mini",
"messages": [
{
"role": "system",
"content": "你只输出合法 JSON，不要输出 Markdown。"
},
{
"role": "user",
"content": "从文本中抽取字段：姓名、公司、职位。文本：李雷在星辰科技担任产品经理。"
}
],
"temperature": 0,
"response_format": {
"type": "json_object"
}
}

19. 快速排查清单

• Base URL 是否正确，是否包含 /v1。

• API Key 是否有效，Header 是否是 Authorization: Bearer xxx。

• model 是否是当前服务商支持的模型名。

• 请求体是否是合法 JSON。

• messages 中 role 是否正确。

• 多模态字段是否被当前模型支持。

• 是否超过上下文窗口或输出 token 限制。

• 429 是否需要限流和退避。

• 流式输出是否正确处理 \\[DONE\\]。

• 工具调用参数是否经过服务端校验。

20. 总结

OpenAI 接口格式的核心是：

如果只是做通用文本生成和兼容多家模型服务，优先掌握 Chat Completions；如果要使用 OpenAI 新一代多模态与复杂工具能力，再进一步评估 Responses 接口。