logo

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 找到上一轮上下文:

  1. from openai import OpenAI
  2. client = OpenAI() # 读取环境变量 OPENAI_API_KEY
  3. first = client.responses.create(
  4. model="gpt-4.1",
  5. instructions="你是严谨的技术文档助手,回答需给出依据。",
  6. input="列出三种主流的关系型数据库",
  7. )
  8. second = client.responses.create(
  9. model="gpt-4.1",
  10. previous_response_id=first.id, # 关键:串联上一轮
  11. input="第二种的默认端口是多少?",
  12. )
  13. 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,以官方文档为准):

  1. resp = client.responses.create(
  2. model="gpt-4.1",
  3. tools=[{"type": "web_search"}],
  4. input="汇总本周 AI 推理成本的变化趋势",
  5. )

文件搜索 (基于 Vector Store 做 RAG):

  1. resp = client.responses.create(
  2. model="gpt-4.1",
  3. tools=[{
  4. "type": "file_search",
  5. "vector_store_ids": ["vs_abc123"],
  6. "max_num_results": 5,
  7. }],
  8. input="根据制度文档回答:差旅报销的审批层级是什么?",
  9. )

计算机使用 (computer_use_preview)让模型输出鼠标键盘动作序列,由你在沙箱中执行并回传截图,适合 UI 自动化、网页表单填写等 RPA 场景。这类能力务必跑在隔离容器里,并设置人工确认环节。

重点:远程 MCP 服务器接入

MCP(Model Context Protocol)为模型提供了标准化的外部工具接入协议。Responses API 把 MCP 客户端能力内置后,接入外部系统从「写一堆 function schema + 胶水代码」变成一次配置:

  1. resp = client.responses.create(
  2. model="gpt-4.1",
  3. tools=[{
  4. "type": "mcp",
  5. "server_label": "stripe",
  6. "server_url": "https://mcp.stripe.com/",
  7. "require_approval": "never", # 只读场景可放开
  8. }],
  9. input="查询客户 cus_xxxx 最近三笔支付的状态",
  10. )
  11. for item in resp.output:
  12. if item.type == "mcp_call":
  13. 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 条目
迁移成本 — 端点与载荷结构变化,需改造

迁移时的四个常见坑

  1. 输出解析方式变了。 不要再用 resp.choices.message.content,改为遍历 resp.output,筛选 type == "message" 的条目取 content[].text,SDK 里可直接用 resp.output_text。
  2. 流式事件结构不同。 Responses API 使用细粒度语义事件(如 response.output_text.delta、response.completed),原有的 SSE 解析逻辑需要重写。
  3. 工具调用循环从隐式变显式。 内置工具由服务端闭环,自定义函数仍需你实现「调用—回传—再请求」,但回传格式改为 function_call_output 条目。
  4. 状态化带来的数据合规问题。 默认 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 的关键。

发表评论

活动