OpenAI 兼容 API 格式详解与实战

大模型时代，API 已经成为连接应用与智能的血管。众多模型厂商为了降低开发者的接入成本，纷纷选择对齐 OpenAI 的接口规范——只需修改 `base_url` 和 `api_key`，就能在 GPT、Claude、DeepSeek、Qwen 等模型间无缝切换。这篇文章带你深入理解这套“兼容格式”，并给出可直接运行的实战代码。

## 为什么 OpenAI 格式成为事实标准

OpenAI 率先定义了 Chat Completions 的请求/响应结构，其简洁性与可扩展性迅速被社区接受。如今，绝大多数托管平台和本地推理框架（如 vLLM、Ollama）都支持以 OpenAI 兼容模式提供服务。这意味着，你掌握的是一套语法，却能调用整个生态。

## 核心端点与请求结构

最常用的端点只有一个：

``` POST /v1/chat/completions ```

一个典型的请求体长这样：

```json { "model": "gpt-4o", "messages": [ {"role": "system", "content": "你是严谨的技术翻译。"}, {"role": "user", "content": "将'attention mechanism'译成中文。"} ], "temperature": 0.3, "max_tokens": 200, "stream": false } ```

关键字段说明：

- `model`：模型名称，各平台不同，如 `deepseek-chat`、`claude-3-opus`。 - `messages`：对话列表，角色必须为 `system`、`user`、`assistant` 之一。 - `temperature`：控制随机性，0~2，越低越确定，翻译、代码生成建议 0.2 左右。 - `max_tokens`：限制输出长度，避免意外消耗。 - `stream`：是否启用流式输出，开启后响应会以 SSE 事件流返回。

## 响应解析

非流式响应返回 JSON：

```json { "id": "chatcmpl-xxx", "object": "chat.completion", "created": 1717000000, "model": "gpt-4o", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "注意力机制" }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 18, "completion_tokens": 4, "total_tokens": 22 } } ```

我们需要的内容通常在 `choices[0].message.content` 中。`finish_reason` 为 `stop` 表示正常结束，`length` 表示因达到最大 token 而截断。

## 实战：用 Python 调用兼容 API

官方 `openai` 库本身就支持自定义 base_url。以下示例展示如何使用 DeepSeek 模型，只需替换地址和密钥即可用于任意兼容服务。

```python from openai import OpenAI

client = OpenAI( base_url="https://api.your-provider.com/v1", # 替换为兼容API地址 api_key="your-key" )

response = client.chat.completions.create( model="deepseek-chat", messages=[ {"role": "system", "content": "你是一个幽默的助手。"}, {"role": "user", "content": "讲一个程序员笑话。"} ], temperature=0.8, max_tokens=100 )

print(response.choices[0].message.content) ```

如果你想获得逐 token 输出的打字机效果，开启流式：

```python stream = client.chat.completions.create( model="deepseek-chat", messages=[{"role": "user", "content": "用Python写快排"}], stream=True ) for chunk in stream: if chunk.choices[0].delta.content: print(chunk.choices[0].delta.content, end="", flush=True) ```

## 参数扩展与多模态

除了基础文本对话，兼容 API 正在向多模态延伸。图片输入可通过 `messages` 中的 `content` 数组实现，例如：

```json "content": [ {"type": "text", "text": "描述这张图片"}, {"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg"}} ] ```

只要平台支持视觉模型，这套格式依旧适用。

## 一键接入更多前沿模型

掌握 OpenAI 兼容格式，你就拥有了通往数十个顶尖模型的万能钥匙。不过，当我们需要同时调用 DeepSeek、Qwen、Claude、Gemini 等模型时，逐一申请各家 API 既繁琐又难以统一计费。

推荐使用 [TokenPocket API 中转站](https://tokenpocket.site)，它完整支持 OpenAI 兼容范式，一行代码不改即可在 DeepSeek、Qwen、Claude、Gemini 等模型间切换。平台按量计费、USDT 直接支付，新用户注册即送免费体验额度，非常适合开发调试与高频调用的项目集成。