从 Chat Completions 迁到 Responses API发布前至少做这 7 个验收很多项目迁移 OpenAI 接口时会先改一行代码messages - input这一步只能说明你开始迁移了不能说明你已经可以发布。Chat Completions 和 Responses API 的差异不只在字段名还会影响资源路径、输出读取、流式事件、工具调用、会话状态、网关兼容和回滚方式。如果你维护的是 SDK wrapper、内部 API 网关、AI 编程工具配置或者给客户提供 OpenAI-compatible endpoint发布前至少要做一张迁移验收表。否则很容易出现这种情况最小文本请求能 200真实业务一开流式、一接工具、一走中转就开始 404、解析失败或前端不更新。先明确迁移目标是什么不要把“迁移 Responses API”写成抽象目标。先选一个具体范围范围 A只迁移非流式纯文本 范围 B纯文本 流式 范围 C加工具调用 范围 D保留多轮状态 范围 E通过内部中转网关暴露给多个客户端如果今天只做范围 A就不要在发布说明里写“已完整支持 Responses API”。读者、同事或客户会按你写的边界使用。验收 1资源路径不能混Chat Completions 的典型资源是POST /v1/chat/completionsResponses API 的典型资源是POST /v1/responses迁移时先记录最终请求路径。不要只看配置文件里的base_url因为 SDK 会在基地址后面追加资源路径。如果你把资源路径也写进base_url最终可能出现这种重复/v1/responses/responses发布前验收标准chat path /v1/chat/completions responses path /v1/responses bad path blocked or returns expected 404验收 2输入形状要分层Chat Completions 常见输入是messages{model:your-model,messages:[{role:user,content:hello}]}Responses API 使用input并且可以配合instructions、工具、状态等字段{model:your-model,input:hello}如果你的业务代码里有统一 wrapper不要在一个函数里偷偷兼容所有形状。更稳的方式是显式传入协议protocolopenai-chat protocolopenai-responses然后进入各自的请求构造器。这样日志里能直接看出哪一层出了问题。验收 3输出读取不能继续读choices旧代码经常读completion.choices[0].message.content迁到 Responses 后纯文本可以优先读 SDK 或响应对象提供的文本聚合字段需要处理工具或 reasoning 时则应遍历类型化输出项。发布前不要只测“HTTP 200”还要测应用真正读取到文本。验收标准HTTP_STATUS200 TEXT_READok WRONG_READERblocked by test如果错误读取仍然静默返回空字符串前端就可能显示“生成中”或空结果但日志里只有 200。这类问题比 404 更难排查。验收 4流式事件要单独测Chat Completions 流式和 Responses 流式不是同一套事件形状。迁移前端或 SSE 解析器时至少验证三件事首个事件到达后 UI 是否进入输出状态。文本增量事件是否能追加到同一个消息。完成事件是否能关闭 loading并写入最终 usage / request id。不要只用非流式请求证明流式已经可用。非流式 200 只能证明路由和基本请求体没坏。验收 5工具调用不是普通文本如果你的业务用函数调用、文件检索、代码执行或自定义工具迁移时要把工具调用当成独立输出类型处理而不是拼进文本。一个最小验收表可以这样写tool_call_detectedyes tool_nameget_weather tool_args_json_validyes tool_result_roundtripnot_tested / passed今天没有测工具结果回传就不要写“工具调用完整支持”。最多写“已能识别 tool_call item工具结果回传待测”。验收 6多轮状态要决定谁保存旧的 Chat Completions 代码通常由应用自己累积messages。Responses API 的状态使用方式会让你重新选择继续由应用保存完整上下文。使用响应 ID 或会话能力承接上一轮。混合方式业务关键消息自己保存临时推理状态交给 API。这不是代码洁癖问题而是数据边界问题。发布前要写清楚用户隐私、审计日志、失败重试和回滚时到底以哪份状态为准。验收 7中转网关要按能力矩阵放行如果你通过中转服务暴露 OpenAI-compatible endpoint不要因为/v1/chat/completions成功就默认/v1/responses、工具调用、图像、流式和状态都成功。建议维护一张能力矩阵能力验收状态证据Chat Completions 非流式passed最小请求 200文本读取成功Responses 非流式passed / pending/v1/responses最小请求Responses 流式pending事件解析截图或日志工具调用pendingtool_call item 和结果回传状态延续pendingprevious response / conversation 读写计费与用量pendingusage readback回滚到 Chatpassedfeature flag 或路由开关这张表比一句“兼容 OpenAI”更有价值。它能告诉调用方今天能放心用什么哪些只是下一阶段。本地实测用夹具跑一遍验收表为了避免把线上服务能力写成未经验证的结论我用标准库写了一个只监听127.0.0.1的本地夹具。它模拟 7 个检查项Chat 路径、Responses 路径、错误路径、文本读取、流式事件、工具调用 item、状态字段。执行python3 06-evidence/probe_responses_migration_checklist.py本次输出PYTHON_VERSION... CHAT_ENDPOINT200 TEXTchat fixture RESPONSES_ENDPOINT200 TEXTresponses fixture BAD_RESPONSES_BASE404 PATH/v1/responses/responses STREAM_EVENTS3 FINALcompleted TOOL_ITEMpresent NAMElookup_config STATEFUL_FIELDprevious_response_id ONLINE_PROVIDER_REQUESTNO SUMMARYpass checks7/7本地实测图Responses 迁移验收夹具结果已生成平台草稿保存后可按需要再上传正文图。这组输出证明的是迁移验收思路每一项都能被单独检查。它不证明任何线上中转服务已经完整支持 Responses API也不证明某个模型在生产环境可用。发布前建议保留一个回滚开关迁移最容易忽略的是回滚。你可以在配置里显式保留OPENAI_PROTOCOLchat OPENAI_PROTOCOLresponses或者在网关路由里为不同客户端保留协议模式。上线后如果发现流式事件、工具结果或状态延续有问题可以把部分客户端回到 Chat Completions而不是在生产上临时改代码。回滚不是退步它是迁移验收的一部分。没有回滚路径的迁移本质上还没准备好进入真实用户流量。CodeLink 相关的正确写法如果你使用 CODELINK API 中转服务测试这类迁移建议把它放在能力矩阵里写清楚今天测了哪个 endpoint、哪个模型、是否流式、是否有 usage readback、是否真实计费。没有这些证据时就只写“可作为 OpenAI 兼容调用场景之一”不要写“完整支持 Responses API”。在 CSDN 文章里CodeLink 更适合通过审核通过的官方网站卡承接下一步而不是在正文里放注册链接或充值入口。读者读完这篇文章后真正需要的是一份可复制的迁移验收脚本和技术落地页。总结从 Chat Completions 迁到 Responses API不是把messages改成input就结束。发布前至少验收资源路径 输入形状 输出读取 流式事件 工具调用 状态延续 网关能力矩阵 回滚路径每一项都要有自己的成功信号。这样你才能区分到底是 SDK 配置错、端点没实现、前端解析错、工具调用没接上还是中转网关还没有放行某个能力。迁移最好的状态不是“全部一次性改完”而是每一层都能独立证明、独立回滚、独立记录证据。