随笔
Search K

Appearance

从 Completions 到 Responses：大模型 API 协议演进 ​

随着大模型应用从“聊天机器人”发展到“AI Agent”，模型调用协议也经历了一次重要演进。从最早的文本补全 API，到 ChatGPT 时代的 Chat Completions，再到 Agent 时代的 Responses API，背后反映的是大模型应用形态的变化。

但在实际工程中，一个常见的困惑是：既然 DeepSeek、Qwen 这些模型都宣称“兼容 OpenAI API”，为什么 Codex 不能直接换上 DeepSeek？为什么 Claude Code 反而更容易适配多种模型？这其实都和三代 API 协议的差异有关。

本文总结 /v1/completions、/v1/chat/completions、/v1/responses 的区别，以及为什么 Claude Code、Codex、DeepSeek 在 API 兼容方面表现不同。

一、大模型 API 的三代演进 ​

整体演进路径是这样的：

text
/v1/completions
      ↓
/v1/chat/completions
      ↓
/v1/responses

这不是简单的版本升级，而是模型使用方式的变化：

text
文本生成
  ↓
聊天交互
  ↓
智能 Agent

每一代解决的是上一代在新的应用形态下暴露出来的不足。下面分别看这三代 API。

二、第一代：/v1/completions ​

1. 核心思想 ​

给模型一段文本，让模型继续补全。早期 GPT API 类似高级自动补全。

请求：

text
POST /v1/completions

示例：

json
{
  "model": "text-davinci-003",
  "prompt": "写一个快速排序算法："
}

模型：

text
输入:
写一个快速排序算法：

输出:
def quick_sort(arr):
    ...

抽象：

text
prompt
  ↓
模型
  ↓
completion text

2. 缺点 ​

这个阶段模型并不知道：

  • 谁是用户
  • 什么是系统规则
  • 什么是历史消息

开发者只能手动拼 prompt：

text
你是代码助手

用户:
写一个函数

助手:

维护困难。这一代 API 适合“单次补全”，不适合“持续对话”。

三、第二代：/v1/chat/completions ​

ChatGPT 时代出现。

1. 核心思想 ​

模型不是补全文本，而是在理解一段对话。

请求：

text
POST /v1/chat/completions

格式：

json
{
  "messages": [
    {
      "role": "system",
      "content": "你是代码助手"
    },
    {
      "role": "user",
      "content": "写一个排序算法"
    }
  ]
}

消息有角色：

text
system
user
assistant

模型知道：

  • 系统要求
  • 用户输入
  • 历史上下文

2. 优势 ​

多轮对话 ​

以前需要自己拼：

text
用户: 你好
助手: 你好
用户: 继续

现在直接用消息数组表达：

text
messages: [
  user,
  assistant,
  user
]

Tool Calling ​

后来 Chat Completions 增加了对工具调用的支持：

text
用户
  ↓
模型
  ↓
调用函数
  ↓
返回结果
  ↓
继续回答

例如模型可以返回：

json
{
  "tool_calls": [
    {
      "name": "search"
    }
  ]
}

可以调用：

  • 搜索
  • 数据库
  • API
  • 文件系统

3. 影响 ​

由于简单、生态成熟，大量模型兼容它：

text
DeepSeek
Qwen
Mistral
Groq
Ollama

形成事实标准：

text
OpenAI-compatible API = chat/completions

也就是说，今天说“兼容 OpenAI API”，绝大多数情况下指的就是 /v1/chat/completions 这一代。

四、第三代：/v1/responses ​

随着 AI Agent 出现，Chat Completions 不够用了。

因为 Agent 不只是回答问题。例如“帮我修复项目”，真实流程是这样的：

text
读取文件
  ↓
分析代码
  ↓
修改文件
  ↓
运行测试
  ↓
发现错误
  ↓
继续修复
  ↓
返回结果

这已经不是简单聊天。于是 OpenAI 推出：

text
POST /v1/responses

请求：

json
{
  "model": "gpt-5",
  "input": "修复我的项目",
  "tools": [
    {
      "type": "computer"
    }
  ]
}

返回：

json
{
  "output": [
    {
      "type": "tool_call"
    },
    {
      "type": "message"
    }
  ]
}

核心变化在于抽象层级。Chat Completions 的流程是：

text
messages
  ↓
answer

而 Responses 的流程是：

text
input
  ↓
reasoning
  ↓
tool_call
  ↓
tool_result
  ↓
message

它更像一个任务执行流，而不再是“一问一答”。

五、为什么 Codex 不能直接换 DeepSeek ​

很多人认为：

text
DeepSeek 兼容 OpenAI API，所以应该可以替换 Codex。

实际上不完全。原因在于协议层。

DeepSeek 主要兼容：

text
/v1/chat/completions

而 Codex 使用：

text
/v1/responses

两者协议不同。例如 Codex 发送：

json
{
  "input": ["..."],
  "tools": ["..."]
}

但是 DeepSeek 期待：

json
{
  "messages": ["..."]
}

字段不匹配。

更重要的是，Codex 不只是调用模型。它依赖一整套 Agent 能力：

text
Responses API
+ Tool Calling
+ Agent Loop
+ 代码执行环境
+ 状态管理

所以这里有一个关键结论：

text
API 兼容 ≠ Agent 兼容

一个模型能在 /v1/chat/completions 上跑通，不代表它能直接支撑一个依赖 /v1/responses 的 Agent 运行时。

六、为什么 Claude Code 可以适配更多模型 ​

这里容易误解：Claude Code 原生不是 /chat/completions。Anthropic 使用的是自己的协议：

text
/v1/messages

但是它更容易通过 Adapter 转换。例如：

text
Claude Code
  ↓
协议转换层
  ↓
DeepSeek / OpenAI

转换主要是字段映射：

text
Anthropic:
{
  "messages": []
}
  ↓
OpenAI:
{
  "messages": []
}

结构接近，转换成本较低。

而 Codex 依赖的 Responses API 是一种新的 Agent 抽象：

text
response items
tool calls
reasoning
state

要把这些映射回老的 /v1/chat/completions，转换成本要高得多。这也是为什么 Claude Code 比 Codex 更容易适配多种模型。

七、CC Switch 做了什么 ​

CC Switch 本质是：在客户端和模型之间增加一个代理层。

架构：

text
Claude Code
Codex
Cursor
  ↓
CC Switch
  ↓
-----------------
|       |       |
GPT   Claude  DeepSeek

它主要做三件事。

1. 配置切换 ​

修改：

text
API Key
Base URL
Model
Provider

让客户端无需改动，就能切换到不同模型供应商。

2. 协议转换 ​

例如 Claude 原生走的是：

text
/v1/messages

代理层把它转换成：

text
/v1/chat/completions

流程：

text
请求
  ↓
解析 JSON
  ↓
字段转换
  ↓
调用目标模型
  ↓
转换返回
  ↓
返回客户端

3. Tool Calling 映射 ​

不同协议对工具调用的表达不一样，代理层负责转换。例如：

text
Anthropic:
{
  "type": "tool_use"
}

OpenAI:
{
  "type": "tool_calls"
}

代理层就是处理这类字段差异。

八、/v1 为什么一直没有 v2 ​

很多人误解：

text
/v1/chat/completions
/v1/responses

认为 responses 是 v2。不是。

这里的 v1 表示 API 版本。下面的：

text
chat/completions
responses
embeddings
images

是不同功能接口。类似：

text
/api/v1/users
/api/v1/orders

它们不是版本不同，而是同一个 v1 版本下不同的资源接口。/v1/responses 和 /v1/chat/completions 同理，是并存的接口，不是新旧版本关系。

九、总结 ​

三代接口的对应关系如下：

接口时代抽象适合
/v1/completionsGPT 早期文本补全生成文本
/v1/chat/completionsChatGPT 时代消息对话聊天助手
/v1/responsesAgent 时代任务执行流AI Agent

核心变化用一句话概括：

text
Completion      = 帮我写一句话
Chat Completion = 和我聊天
Responses       = 帮我完成一个任务

未来 AI 编程工具的发展方向，也会越来越从 Chatbot 转向 Agent。因此 API 协议也会从“文本生成协议”逐渐演进为“任务执行协议”。

这也是为什么 Codex、Claude Code、Cursor、DeepSeek 在 API 兼容策略上会出现不同路线：它们各自处在三代协议的不同位置，转换的代价天然就不一样。

Last updated: