OpenAI 兼容 API 格式详解与实战
自从 OpenAI 发布 ChatGPT API 以来，其接口格式已经事实上成为大模型 API 的行业标准。无论是开源模型还是商业模型，几乎都提供了“OpenAI 兼容”模式的接入方式。这意味着你只需要掌握一套 API 调用逻辑，就能在各种模型之间无缝切换，极大降低了开发成本。本文将拆解 OpenAI 兼容 API 的核心格式，并带你在真实场景中调用一次大模型。
## 为什么需要兼容格式
在早期，每个模型提供商的 API 都各玩各的：请求体结构不同，响应字段不同，连鉴权方式都千奇百怪。当你尝试从 GPT-4 切换到 Claude，或者想测试 DeepSeek 时，往往需要重写整个客户端代码。OpenAI 兼容 API 的出现，统一了 Chat Completion 的交互范式，只要你按照 OpenAI 的请求规范发送数据，就可以用同一个 SDK 或同一段 `curl` 命令调用不同模型，只需修改 `base_url` 和 `model` 参数。
## 请求格式核心要素
一个标准的 Chat Completion 请求包含以下关键 JSON 字段：
- **model**：模型名称，如 `gpt-4o`、`deepseek-chat`。 - **messages**：对话列表，每个消息包含 `role`（system/user/assistant）和 `content`。 - **temperature**：控制随机性，0~2 之间。 - **max_tokens**：限制生成的最大 token 数。 - **stream**：流式开关，设为 `true` 时返回 SSE 事件流。
下面是使用 `curl` 发起的一次非流式请求示例：
```bash curl https://api.openai.com/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $API_KEY" \ -d '{ "model": "gpt-4o-mini", "messages": [ {"role": "system", "content": "你是一个简洁的助手"}, {"role": "user", "content": "解释一下量子纠缠"} ], "temperature": 0.7, "max_tokens": 200 }' ```
如果服务端兼容 OpenAI 格式，即便背后的模型是 Claude 或 Qwen，你只需要把 `https://api.openai.com` 换成对应厂商的 base_url，并换上他们的 API Key 即可。
## 响应结构一览
非流式响应的 JSON 结构通常如下：
```json { "id": "chatcmpl-xxx", "object": "chat.completion", "created": 1711000000, "model": "gpt-4o-mini", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "量子纠缠是..." }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 20, "completion_tokens": 150, "total_tokens": 170 } } ```
提取回复内容时，一般读取 `choices[0].message.content`。usage 中的 token 消耗信息则用于计费与监控。
若启用流式输出（`"stream": true`），响应的 Content-Type 为 `text/event-stream`，每一块数据以 `data: ` 开头，并以换行分隔。你需要在前端或后端逐行解析，再从每个 JSON 块的 `choices[0].delta.content` 中拼出完整回答，直到收到 `[DONE]` 标志。
## 多模型接入实战：一键切换三家模型
假设你在做一个 AI 应用，需要按场景选择不同模型。借助 OpenAI 兼容 API，只需维护一个配置表。以下是一段 Python 伪代码：
```python import requests import json
def chat_completion(base_url, api_key, model, messages): headers = { "Authorization": f"Bearer {api_key}", "Content-Type": "application/json" } payload = { "model": model, "messages": messages, "max_tokens": 500 } resp = requests.post(f"{base_url}/chat/completions", headers=headers, json=payload) return resp.json()["choices"][0]["message"]["content"]
# 配置不同的端点 configs = { "deepseek": {"base_url": "https://api.deepseek.com/v1", "api_key": "sk-xxx"}, "qwen": {"base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1", "api_key": "sk-yyy"}, "claude": {"base_url": "https://api.anthropic.com/v1", "api_key": "sk-zzz"} # 注意已经兼容OpenAI格式 }
messages = [{"role": "user", "content": "写一首关于秋天的五言绝句"}] print(chat_completion(configs["deepseek"]["base_url"], configs["deepseek"]["api_key"], "deepseek-chat", messages)) ```
真正要切换模型时，只需改动用到的配置键，其余代码完全不变。这就是开放标准带来的效率。
## 流式输出与客户端集成
目前几乎所有兼容接口都支持 Server-Sent Events 流式传输。在使用官方 `openai` Python 库时，只需设置 `stream=True` 并迭代响应：
```python from openai import OpenAI
client = OpenAI(api_key="your-key", base_url="https://your-compatible-endpoint/v1") stream = client.chat.completions.create( model="your-model", messages=[{"role": "user", "content": "讲个笑话"}], stream=True ) for chunk in stream: if chunk.choices[0].delta.content: print(chunk.choices[0].delta.content, end="") ```
只要 `base_url` 和模型名称到位，无论是 DeepSeek、Qwen 还是 Claude，都能用完全相同的模式流式输出，极大方便了接入多种模型的产品。
## 工具调用、多模态等扩展
现代化的 OpenAI 兼容 API 还广泛支持 function calling（工具调用）和多模态输入。在 messages 中携带图片或追加 `tools` 数组，即可让模型返回结构化 JSON 或根据图片内容作答。不同模型对这些特性的实现程度略有差异，但字段结构均遵循 OpenAI 的规范。实际使用前建议查看对应厂商的兼容性说明。
## 成本与便捷性取舍
如果你需要同时接入 DeepSeek、Qwen、Claude 和 Gemini 等多种模型，一一去申请各家 API 密钥、熟悉细微兼容差异仍然有门槛。这时可以借助 **TokenPocket API 中转站（https://tokenpocket.site）**，它已将这些模型的接口对齐为标准的 OpenAI 兼容格式，你只需一个端点、一套 Key，即可调用上述所有模型，且按量计费、无月费门槛。新用户注册即可领取免费体验额度，很适合快速验证想法和轻量级应用部署，省去多平台集成的烦恼。