OpenAI 现在提供两套模型调用接口。Chat Completions 走 /v1/chat/completions,请求体是一串 messages,返回 choices;Responses 走 /v1/responses,输入叫 input,输出是一组带类型的 output 项。底下是同一批模型,差别在接口如何组织请求、状态和工具。
官方对两者的定位已经写进文档:Chat Completions 继续支持,新项目推荐 Responses。
1. 两套接口的分工
| 对比 | Chat Completions | Responses |
|---|---|---|
| 端点 | POST /v1/chat/completions | POST /v1/responses |
| 定位 | 对话补全 | 统一的模型交互接口 |
| 输入 | messages 数组 | input,字符串或 items 数组 |
| 输出 | choices[].message | output items 数组 |
| 文本读取 | choices[0].message.content | output_text,或遍历 output |
| 多轮对话 | 应用自己维护 messages | previous_response_id、Conversations API,或手动回传 items |
| 工具调用 | 开发者写循环 | 内置工具加开发者循环 |
| 多模态 | 视模型支持图片、音频输入 | 输入输出统一为 items |
同一批模型大多在两个端点上都能调,模型能力没有变化,差别在接口层怎么组织请求。少数推理配置只在 Responses 上提供,比如 reasoning.mode: pro,迁移时需要单独核对。
2. 同一个 Hello 的两种写法
Chat Completions 把系统提示放在 messages 的第一条:
from openai import OpenAI
client = OpenAI()
completion = client.chat.completions.create( model="gpt-6-astra", messages=[ {"role": "system", "content": "你是一个助手"}, {"role": "user", "content": "你好"}, ],)print(completion.choices[0].message.content)Responses 把系统提示提到顶层 instructions,用户输入直接给 input:
from openai import OpenAI
client = OpenAI()
response = client.responses.create( model="gpt-6-astra", instructions="你是一个助手", input="你好",)print(response.output_text)对应的字段映射:
| Chat Completions | Responses |
|---|---|
client.chat.completions.create() | client.responses.create() |
messages | input |
choices[0].message.content | output_text |
role: "system" | instructions |
max_tokens / max_completion_tokens | max_output_tokens |
response_format | text.format |
output_text 是 SDK 提供的便捷属性,把 output 里所有文本 message 拼起来。它只覆盖纯文本场景。一旦模型产生推理项、工具调用或多模态输出,就得按 item.type 遍历 output,不能假设第一项是 message。
3. 从 messages 到 items
Chat Completions 的 message 是一个把多种信息粘在一起的对象:role 决定它是谁说的,content 放文本或图片,tool_calls 挂在 assistant message 上,工具结果则以 role: "tool" 的消息、用 tool_call_id 关联回调用。
Responses 把这一层拆开,input 和 output 都是 item 的联合类型:
| item 类型 | 含义 |
|---|---|
message | 一段对话消息,带 role 和 content |
reasoning | 模型的推理项,可加密后回放 |
function_call | 模型请求调用某个函数,带 call_id、name、arguments |
function_call_output | 应用回传的工具结果,用 call_id 对应调用 |
拆开之后,历史记录更接近带类型的执行日志。工具调用、工具结果、推理过程各自是独立的 item,可以单独保留、裁剪或回放。代价是解析端必须按类型分支处理。
工具定义也跟着变平。Chat Completions 把函数描述嵌在 function 字段里:
tools = [{ "type": "function", "function": { "name": "get_weather", "description": "查询城市天气", "parameters": { "type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"], }, },}]Responses 把 name、description、parameters 放到工具对象的顶层:
tools = [{ "type": "function", "name": "get_weather", "description": "查询城市天气", "parameters": { "type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"], "additionalProperties": False, }, "strict": True,}]要开启严格模式,schema 必须写全 required,并显式加上 additionalProperties: false。
4. 上下文存在谁那里
Chat Completions 没有服务端会话概念,第二轮请求要把第一轮的 message 全部带上。Responses 给了三种存法:
| 方式 | 历史保存在哪 | 代价 |
|---|---|---|
| 手动回传 items | 应用内存或数据库 | 裁剪最自由,代码量最大 |
previous_response_id | OpenAI 服务端 | instructions 不会继承,每轮都要重发;链上的历史 token 照常计费 |
| Conversations API | OpenAI 服务端的会话对象 | 适合长期会话,多一层对象要管理 |
previous_response_id 只解决“不用重发历史”,不解决计费和指令继承。官方迁移文档写得很直接:即使使用 previous_response_id,链上此前的输入 token 仍然按输入计费;上一轮的顶层 instructions 也不会自动带过来。
存储默认是开的。Responses 默认落库,Chat Completions 对新账号也默认落库,两边都可以用 store: false 关闭。有零数据保留(ZDR)要求的环境不能以有状态方式使用 Responses,这时要设 store: false,并保留、回放每轮返回的 reasoning item 里的 encrypted_content,否则推理上下文会断。
5. 工具循环由谁驱动
Chat Completions 的工具调用是一个由应用驱动的循环,步骤固定:
- 把工具定义放进请求。
- 收到
tool_calls后逐个执行。 - 把结果以
role: "tool"消息追加回messages。 - 再次请求模型。
- 没有新的
tool_calls时结束。
Responses 的客户端函数调用仍然是这个循环,只是消息换成了 item,关联键换成了 call_id:
import json
input_items = [{"role": "user", "content": "查一下北京今天的天气"}]
while True: response = client.responses.create( model="gpt-6-astra", input=input_items, tools=tools, ) input_items += response.output
calls = [item for item in response.output if item.type == "function_call"] if not calls: print(response.output_text) break
# run_tool 由应用实现,按 name 分发到本地函数 for call in calls: result = run_tool(call.name, json.loads(call.arguments)) input_items.append({ "type": "function_call_output", "call_id": call.call_id, "output": result, })flowchart LR U["用户输入"] --> R["Responses"] R --> Q{"output 里有<br/>function_call?"} Q -- 有 --> T["执行工具"] T --> O["function_call_output<br/>带 call_id"] O --> R Q -- 没有 --> A["最终回答"]和 Chat Completions 不同的是,Responses 的 tools 里可以直接放内置工具:web_search、file_search、code_interpreter、image_generation、computer_use、shell 和 mcp。搜索、检索、代码执行由 OpenAI 侧完成,MCP 则由平台连到你配置的服务器。模型自己决定调几次,max_tool_calls 限制内置工具的调用总数;自定义函数工具仍然在本地执行,数量不受这个参数约束。一次请求里可以混用内置工具和函数工具。
6. Responses 成为推荐接口的原因
官方的推荐理由可以落到四条:
- Assistants API 已于 2026-08-26 关闭,替代方案是 Responses 加 Conversations API,官方迁移指南直接指向这两者。
- 从 GPT-5.4 起,Chat Completions 在
reasoning_effort不是none时不支持工具调用。推理模型加工具的组合,实际上只剩 Responses 一条路。 - 内置工具、MCP 和多模态输入都挂在同一个请求结构上,不需要为每种能力接一套旁路接口。
- 流式返回改成语义事件,比如文本增量、函数参数增量各自有事件类型,客户端不用再从 chunk 里猜结构。官方迁移包还把缓存利用率的提升列为收益之一,重复上下文能省一部分成本。
这些理由指向同一个范围:一次问答之外的多轮推理和工具执行。
7. 迁移时的差异清单
| 项目 | Chat Completions | Responses |
|---|---|---|
| 端点 | /v1/chat/completions | /v1/responses |
| 输出长度上限 | max_tokens 或 max_completion_tokens | max_output_tokens |
| 结构化输出 | response_format | text.format |
| 工具定义 | 嵌在 function 字段下 | 顶层平铺 name、parameters |
| 工具结果 | role: "tool" 加 tool_call_id | function_call_output 加 call_id |
| 多候选 | n | 不支持,拆成多次请求 |
| 随机种子 | seed | 已移除 |
| 流式 | 在 chunk 里拼 delta | 消费带类型的事件 |
| 读取文本 | choices[0].message.content | output_text 或遍历 output |
| 上下文 | 自己维护 messages | 手动回传、previous_response_id、Conversations |
最常见的四个错误出在解析侧:把 output 的每一项都当成 message;回传工具结果时漏掉 call_id 或漏掉对应的 function_call item;沿用 Chat Completions 的 chunk 处理逻辑;以为 previous_response_id 会免掉历史 token 的费用。
迁移不必一次做完。Chat Completions 还在维护,可以按 flow 逐个切:先切纯文本生成,确认输出解析、计费和延迟都正常,再切带工具的部分。
8. 对自研 Harness 的影响
| 场景 | 建议 |
|---|---|
| 简单文本生成、分类、抽取 | Chat Completions 够用 |
| 已经在跑的稳定服务 | 没有明确收益就不迁 |
| 多工具调用、多轮推理 | Responses |
| 需要内置搜索、文件检索、代码执行 | Responses |
| 有 ZDR 或数据驻留要求 | 两者都行,注意 store: false 与加密推理项 |
| 自研 Agent Runtime | Responses 的 item 结构更接近轨迹数据 |
Responses 简化的是模型交互层,不是 Agent 框架。拿到 item 流之后,下面这些事仍然在 Harness 里:
- 任务规划与执行循环的终止条件。
- 工具权限、沙箱和人工确认。
- 上下文裁剪与压缩策略。
- token 与成本核算。
- 失败重试和错误恢复。
- 轨迹记录、回放与评测。
工具在服务端跑得再多,谁决定什么时候停、哪些工具允许调用、超长上下文怎么裁,仍然是 Harness 的职责。接口层变简单了,这些事没有变少。