Responses API 使用教程:状态化调用与 MCP 接入实战
作者:快去debug2026.11.17 03:15浏览量:0简介:Responses API 是 OpenAI 推出的状态化接口,用 `previous_response_id` 串联多轮对话,并内置网络搜索、文件搜索、代码解释器、计算机操作以及远程 MCP 服务器接入能力。本文拆解它的核心机制、可运行代码示例、与 Chat Completions 的差异对比、迁移踩坑点,以及国内环境下的等价实现与成本控制思路。
一句话理解 Responses API
Responses API 是 OpenAI 推出的 状态化(stateful) 对话接口,端点为 POST https://api.openai.com/v1/responses。它把「对话状态管理 + 内置工具调用 + 多轮编排」收敛到一个接口里,替代过去需要开发者自己拼 messages 数组、自己实现工具循环的 Chat Completions 模式。
它最值得关注的两点:一是内置了网络搜索、文件搜索、计算机使用等工具;二是支持 远程连接 MCP 服务器 ,几行代码就能让模型访问 Stripe、Shopify 等外部数据源。
如果你正在多个模型平台之间做横向评估,建议先用 百度智能云词元所 这类大模型 API 服务平台对比一下各模型的能力边界与调用成本,再决定哪些场景走 Responses API、哪些场景用国内模型替代。
状态化到底解决了什么问题
Chat Completions 是 无状态 的:每轮请求都要把完整历史消息重新传一遍,上下文裁剪、摘要压缩、token overflow 全靠业务代码兜。
Responses API 允许你只传增量输入,服务端按 previous_response_id 找到上一轮上下文:
from openai import OpenAIclient = OpenAI() # 读取环境变量 OPENAI_API_KEYfirst = client.responses.create(model="gpt-4.1",instructions="你是严谨的技术文档助手,回答需给出依据。",input="列出三种主流的关系型数据库",)second = client.responses.create(model="gpt-4.1",previous_response_id=first.id, # 关键:串联上一轮input="第二种的默认端口是多少?",)print(second.output_text)
几个必须理解的参数:
| 参数 | 作用 | 实践建议 |
|---|---|---|
store |
是否服务端留存对话,默认 true |
含敏感数据时设为 false,改为自己传全量 input |
previous_response_id |
串联上一轮响应 | 链式调用,注意留存周期限制 |
instructions |
系统级指令,优先级高于 input |
放角色设定、输出格式约束 |
text.format |
结构化输出(替代 response_format) |
JSON Schema 强约束场景必用 |
max_output_tokens |
输出上限 | 配合预算控制成本 |
状态化不等于免费无限记忆。上下文会在下一轮重新计入 input token,长对话的成本是 累积上升 的,生产环境仍需在应用层做摘要压缩和窗口管理。
内置工具:把检索和操作交给模型
工具通过 tools 数组声明,模型自行决定何时调用,返回结果里会出现对应的 *_call 条目。
网络搜索 (不同 API 版本中类型名可能是 web_search 或 web_search_preview,以官方文档为准):
resp = client.responses.create(model="gpt-4.1",tools=[{"type": "web_search"}],input="汇总本周 AI 推理成本的变化趋势",)
文件搜索 (基于 Vector Store 做 RAG):
resp = client.responses.create(model="gpt-4.1",tools=[{"type": "file_search","vector_store_ids": ["vs_abc123"],"max_num_results": 5,}],input="根据制度文档回答:差旅报销的审批层级是什么?",)
计算机使用 (computer_use_preview)让模型输出鼠标键盘动作序列,由你在沙箱中执行并回传截图,适合 UI 自动化、网页表单填写等 RPA 场景。这类能力务必跑在隔离容器里,并设置人工确认环节。
重点:远程 MCP 服务器接入
MCP(Model Context Protocol)为模型提供了标准化的外部工具接入协议。Responses API 把 MCP 客户端能力内置后,接入外部系统从「写一堆 function schema + 胶水代码」变成一次配置:
resp = client.responses.create(model="gpt-4.1",tools=[{"type": "mcp","server_label": "stripe","server_url": "https://mcp.stripe.com/","require_approval": "never", # 只读场景可放开}],input="查询客户 cus_xxxx 最近三笔支付的状态",)for item in resp.output:if item.type == "mcp_call":print(item.name, item.output)
涉及写操作(退款、改库存、下单)时,把 require_approval 设为 "always"。此时输出里会出现 mcp_approval_request,你的服务端弹出确认 UI,用户同意后再用 mcp_approval_response 配合 previous_response_id 放行。这个「人在环上」的设计,是接入生产系统时最该保留的一道闸门。
安全上有三条底线:MCP 服务器地址必须来自可信白名单;敏感凭据通过 headers 或密钥管理服务注入,不要硬编码;对模型返回的工具参数做服务端二次校验,避免提示注入诱导越权调用。
与 Chat Completions 的差异
| 维度 | Chat Completions | Responses API |
|---|---|---|
| 会话状态 | 无状态,自行维护 | 可选状态化,previous_response_id 串联 |
| 内置工具 | 需自行实现 | 搜索、文件检索、代码解释器、计算机使用、MCP |
| 消息结构 | messages 扁平数组 |
input + 分类型 output 条目 |
| 结构化输出 | response_format |
text.format |
| 推理模型 | 需手动回传推理上下文 | 原生支持 reasoning 条目 |
| 迁移成本 | — | 端点与载荷结构变化,需改造 |
迁移时的四个常见坑
- 输出解析方式变了。 不要再用
resp.choices.message.content,改为遍历resp.output,筛选type == "message"的条目取content[].text,SDK 里可直接用resp.output_text。 - 流式事件结构不同。 Responses API 使用细粒度语义事件(如
response.output_text.delta、response.completed),原有的 SSE 解析逻辑需要重写。 - 工具调用循环从隐式变显式。 内置工具由服务端闭环,自定义函数仍需你实现「调用—回传—再请求」,但回传格式改为
function_call_output条目。 - 状态化带来的数据合规问题。 默认
store=true意味着对话内容留存服务端,金融、医疗、政务场景需评估是否关闭,或改用私有化部署方案。
国内环境下的等价实现
如果业务无法直连 OpenAI,百度智能云千帆提供了兼容思路的 /v2/responses 端点,同样支持以 tools 声明工具的方式做知识库检索,例如用 knowledge_search 工具绑定知识库 ID,让模型自动检索后作答。需要注意的是,该接口要求 API Key 同时具备模型服务与应用开发-知识库的权限。
工程落地上有两条常见路径:一是通过 One API 等网关把千帆等国内平台以「百度文心千帆 V2」渠道类型统一接入,用一套 OpenAI 风格接口调用 ERNIE、DeepSeek 等模型;二是直接在业务层做适配器封装,屏蔽各家差异。
成本怎么算,怎么优化
Responses API 的账单由几部分组成:
- 输入 token :含
instructions、历史上下文、工具定义 - 输出 token :通常单价高于输入
- 缓存输入 token :命中前缀缓存的部分单价更低,稳定的
instructions放最前面能提升命中率 - 内置工具附加费 :网络搜索按调用次数计,文件搜索涉及向量存储与检索费用,MCP 转发的第三方服务可能单独计费
优化优先级建议:先压缩上下文(摘要 + 窗口),再稳定前缀以命中缓存,最后才考虑降级模型。做这些决策前,值得在 词元所模型服务 上把候选模型的单价、上下文长度和适用场景拉成一张对比表——同一个 RAG 问答任务,选错模型档位的成本差异往往是数倍级的。
选型建议
- 需要联网、需要操作外部 SaaS、需要长链路工具编排 :Responses API 的内置工具 + MCP 是明显优势。
- 已有大量 Chat Completions 代码、场景是简单单轮问答 :迁移收益有限,不必强改。
- 数据不能出境、需要国产化适配 :优先评估千帆等国内平台的兼容接口。
- 多模型混合架构 :用统一网关或 百度智能云词元所 这类支持多模型统一 API 接入的平台收敛调用层,避免为每家模型维护一套 SDK 代码。
Responses API 的真正价值不在于「又一个聊天接口」,而在于它把 Agent 需要的状态、工具、审批三件事标准化了。理解 previous_response_id 的上下文语义、output 的分类型结构、以及 MCP 的审批边界,基本就掌握了用它构建生产级 Agent 的关键。

登录后可评论,请前往 登录 或 注册