简介:Responses API 的核心价值不在于"多了一个聊天接口",而在于把上下文、工具调用、多模态输入、流式事件和后台任务统一进一个 response 对象,让 AI 应用从"一问一答"升级为可编排的任务流程。本文拆解它的能力边界、代码写法与迁移要点,并说明国内开发者如何低成本对比和接入同类接口。如果你正在做多模型选型或成本评估,可以先看看[百度智能云词元所](https://cloud.baidu.com/product-s/token_exchange.html?from=article),它提供模型能力对比、价格对比与统一 API 接入,能省掉大量逐个平台试跑的时间。
Chat Completions 的心智模型是”无状态的文本补全”:你负责把 messages 拼完整,模型返回一条 assistant message,剩下的上下文管理、工具结果回填、文件解析、流式事件拼装、长任务轮询,全部由业务层自己实现。
Responses API 把这一层收进协议:一次请求可以携带文本、图片、文件等多种输入;返回值不是一段纯文本,而是一个结构化的 response 对象,里面包含多个 output item(消息、工具调用、推理项等);工具调用、流式事件、后台任务状态都有了原生表达。
所以判断要不要迁移,标准很简单: 如果你的应用只是”用户问一句、模型答一句”,Chat Completions 完全够用;一旦进入客服、知识库问答、数据分析、Agent、自动化办公这类多步骤场景,Responses API 的收益会迅速放大。
1. 输入输出统一为 item 列表
input 不再局限于 role/content 的纯文本结构,可以是字符串,也可以是 item 数组,混入 input_text、input_image、input_file。这意味着”用户上传一份 PDF 再追问”不再需要你先接一个 OCR/解析服务把内容塞进 prompt,而是作为文件输入项直接交给模型侧处理。
2. 工具调用从”回填”变成”追加”
Chat Completions 的工具流程是:模型返回 tool_calls → 你执行 → 你构造一条 role: "tool" 的消息 → 重新提交完整历史。Responses API 中,函数调用结果作为一种 output/input item 追加进上下文,配合 previous_response_id 可以直接引用上一轮响应,不必自己维护并全量回传消息数组。对多轮工具链(查库 → 计算 → 再查库)来说,代码量和出错面都明显下降。
3. 内置工具与托管执行
检索、代码执行、联网搜索这类能力被建模为 tools 中的内置类型,由服务端托管执行,调用过程本身也作为 output item 返回,天然可审计。国内同类平台也是这个思路,例如百度智能云千帆的 /v2/responses 就支持 knowledge_search 工具,通过 knowledgebase_ids 指定知识库即可完成检索增强,且兼容 OpenAI SDK 的调用习惯。
{"model": "deepseek-v3.2","tools": [{ "type": "knowledge_search", "knowledgebase_ids": "f015fff6-05d7-4192-b581-xxxx" }],"input": [{ "role": "user", "content": "总结智能体客服搭建过程" }]}
4. 流式是”语义事件”而非”字符增量”
Chat Completions 的流式返回是 delta 文本块,前端要自己判断”这段是正文、那段是工具参数、那段是推理过程”。Responses API 的流式采用带类型的事件(如文本增量、item 完成、工具调用参数增量、响应完成等),UI 可以直接按事件类型渲染:正文进气泡、工具调用进折叠面板、状态进 loading 条。做对话式产品时,这部分前端逻辑能省掉一大坨字符串解析。
| 维度 | Chat Completions | Responses API |
|---|---|---|
| 抽象单位 | message(消息) | item(条目)+ response(响应对象) |
| 多模态输入 | 需按 content parts 拼装 | input item 原生支持文本/图片/文件 |
| 多轮上下文 | 业务层全量回传 messages | 可用 previous_response_id 链式引用 |
| 工具调用 | 需手动回填 tool 消息 | 调用与结果均为一等 output item |
| 内置工具 | 基本没有 | 检索、代码执行、联网搜索等托管执行 |
| 流式协议 | 文本 delta | 带类型的语义事件 |
| 长任务 | 自行轮询 | 支持后台执行 + 状态查询 |
| 适用场景 | 单轮问答、简单改写、分类抽取 | Agent、RAG、数据分析、自动化流程 |
from openai import OpenAIclient = OpenAI() # 读取 OPENAI_API_KEYresp = client.responses.create(model="gpt-4.1",tools=[{"type": "web_search"}],input="对比一下向量检索和关键词检索在客服场景的取舍",)# 结构化输出:遍历所有 output item,而不是只取 textfor item in resp.output:if item.type == "message":print(item.content.text)elif item.type == "web_search_call":print("已执行联网检索:", item.status)print("token 用量:", resp.usage)
如果换成兼容 OpenAI 协议的第三方平台,通常只需替换 base_url 与 api_key,模型名换成平台支持的 model 值:
client = OpenAI(api_key="your_APIKey",base_url="https://qianfan.baidubce.com/v2/",)
previous_response_id 依赖服务端存储,涉及数据留存合规、存储周期和额外计费,敏感业务要评估清楚,必要时改回显式传上下文。Responses API 解决的是”怎么调”,但工程落地前往往先卡在”调哪个”。同一个 Agent 场景里,规划环节倾向推理能力强的模型,工具调用环节看重函数调用的稳定性,摘要和分类环节则希望单价足够低——混用两三个模型是常态,而不是例外。
这也是词元所比较实用的地方:它把不同模型的能力定位和调用价格放在同一张表上做横向对比,你可以按环节筛选候选模型、估算整体调用成本,再通过统一 API 接入完成集成,避免为每个模型单独对接一套 SDK 和鉴权。对需要同时维护多模型路由的团队,这种大模型 API 服务平台的价值主要在集成成本和调用管理上,而不是替代你自己的架构设计。
Responses API 的意义,是让”模型调用”这件事从函数级的 API 调用,逐步变成流程级的任务编排。真正决定收益的不是接口本身,而是你的应用里有多少复杂度原本花在拼消息、回填工具结果和解析流式文本上。