2073 字
10 分钟
Chat Completions 与 Responses:两种模型调用接口

OpenAI 现在提供两套模型调用接口。Chat Completions 走 /v1/chat/completions,请求体是一串 messages,返回 choices;Responses 走 /v1/responses,输入叫 input,输出是一组带类型的 output 项。底下是同一批模型,差别在接口如何组织请求、状态和工具。

官方对两者的定位已经写进文档:Chat Completions 继续支持,新项目推荐 Responses。

1. 两套接口的分工#

对比Chat CompletionsResponses
端点POST /v1/chat/completionsPOST /v1/responses
定位对话补全统一的模型交互接口
输入messages 数组input,字符串或 items 数组
输出choices[].messageoutput items 数组
文本读取choices[0].message.contentoutput_text,或遍历 output
多轮对话应用自己维护 messagesprevious_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 CompletionsResponses
client.chat.completions.create()client.responses.create()
messagesinput
choices[0].message.contentoutput_text
role: "system"instructions
max_tokens / max_completion_tokensmax_output_tokens
response_formattext.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_idOpenAI 服务端instructions 不会继承,每轮都要重发;链上的历史 token 照常计费
Conversations APIOpenAI 服务端的会话对象适合长期会话,多一层对象要管理

previous_response_id 只解决“不用重发历史”,不解决计费和指令继承。官方迁移文档写得很直接:即使使用 previous_response_id,链上此前的输入 token 仍然按输入计费;上一轮的顶层 instructions 也不会自动带过来。

存储默认是开的。Responses 默认落库,Chat Completions 对新账号也默认落库,两边都可以用 store: false 关闭。有零数据保留(ZDR)要求的环境不能以有状态方式使用 Responses,这时要设 store: false,并保留、回放每轮返回的 reasoning item 里的 encrypted_content,否则推理上下文会断。

5. 工具循环由谁驱动#

Chat Completions 的工具调用是一个由应用驱动的循环,步骤固定:

  1. 把工具定义放进请求。
  2. 收到 tool_calls 后逐个执行。
  3. 把结果以 role: "tool" 消息追加回 messages。
  4. 再次请求模型。
  5. 没有新的 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 CompletionsResponses
端点/v1/chat/completions/v1/responses
输出长度上限max_tokens 或 max_completion_tokensmax_output_tokens
结构化输出response_formattext.format
工具定义嵌在 function 字段下顶层平铺 name、parameters
工具结果role: "tool" 加 tool_call_idfunction_call_output 加 call_id
多候选n不支持,拆成多次请求
随机种子seed已移除
流式在 chunk 里拼 delta消费带类型的事件
读取文本choices[0].message.contentoutput_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 RuntimeResponses 的 item 结构更接近轨迹数据

Responses 简化的是模型交互层,不是 Agent 框架。拿到 item 流之后,下面这些事仍然在 Harness 里:

  • 任务规划与执行循环的终止条件。
  • 工具权限、沙箱和人工确认。
  • 上下文裁剪与压缩策略。
  • token 与成本核算。
  • 失败重试和错误恢复。
  • 轨迹记录、回放与评测。

工具在服务端跑得再多,谁决定什么时候停、哪些工具允许调用、超长上下文怎么裁,仍然是 Harness 的职责。接口层变简单了,这些事没有变少。

Chat Completions 与 Responses:两种模型调用接口
https://blog.xqcherry.top/posts/ai/chat-completions-vs-responses/
作者
xqcherry
发布于
2026-11-14
许可协议
CC BY-NC-SA 4.0