在 2026 年的 AI 开发生态中，开发者们正经历一场从“聊天模型”向“智能体模型”的协议大迁移。如果你在调用 API 时收到了 Unsupported legacy protocol 的错误提示，这意味着你正在使用的供应商已经全面转向了 /v1/responses 协议。
本文将带你深入了解这一新标准的由来、优势以及如何进行适配。
一、 背景：为什么旧协议被淘汰了？
自 2023 年以来，/v1/chat/completions 一直是 AI 行业的通用语言。它简单直观：发送 messages 数组，获取 content 字符串。
然而，随着 GPT-5、Gemini 2.0+ 等高性能模型的发布，旧协议的局限性日益凸显：
- 缺乏状态管理：每次请求都必须发送完整的历史记录，导致 Token 浪费和延迟增加。
- 推理过程不透明：新一代推理模型（Reasoning Models）在输出前有复杂的“思维链”，旧协议难以结构化展示这些中间步骤。
- 工具调用受限：复杂的 Agent 协作（如 MCP 协议对接）超出了旧协议的设计初衷。
二、 核心差异：新旧协议对比
/v1/responses 不仅仅是路径的改变，它代表了从 “单次往返” 到 “会话管理” 的思想转变。
| 特性 | 旧版 (/v1/chat/completions) | 新版 (/v1/responses) |
|---|---|---|
| 交互逻辑 | 无状态（Stateless），需手动传历史 | 有状态（Stateful），支持 store: true |
| 数据结构 | 核心字段为 messages | 核心字段变为 input 或 instructions |
| 推理展示 | 仅输出最终结果 | 原生支持 reasoning_content (思维链) |
| 性能优化 | 依赖客户端缓存 | 支持服务器端上下文压缩 (Compaction) |
| 工具扩展 | 简单的 Function Call | 深度集成 MCP (Model Context Protocol) |
三、 如何判断供应商的支持情况？
- 观察 Endpoint：检查 API 文档中的 Base URL。如果包含
/openai/v1/且路径强制要求/responses，说明已完成进化。 - 模型后缀：关注模型列表中是否有
-legacy。没有该后缀的新模型通常优先适配新协议。 - 技术探测：使用 Curl 测试
/v1/responses路径。若返回401或参数错误而非404，说明协议已部署。
四、 迁移指南：代码层面如何适配？
当你准备从旧协议迁移时，主要需要调整请求体的结构。以下是一个典型的对比示例：
旧版请求 (Legacy)
{
"model": "gpt-4o",
"messages": [{"role": "user", "content": "你好"}]
}
新版请求 (Responses API)
{
"model": "gpt-5-preview",
"input": "你好",
"store": true,
"metadata": { "user_id": "elixia_01" },
"tools": [{ "type": "web_search" }]
}
注意：新协议通常支持
store: true参数。开启后，你无需在下一次请求中发送之前的对话，服务器会自动关联session_id。
五、 总结与展望
/v1/responses 的普及标志着 AI Agent 时代的正式到来。它通过标准化的状态管理和推理展示，让开发者能够构建更聪明、更省钱、响应更快的应用。
对于开发者而言，目前的最佳实践是：
- 前端工具（如 ChatBox、LobeChat）：请及时更新到 2026 年以后的版本。
- 自研后端：建议封装一个适配层，同时兼容两种协议，并优先为高性能模型启用
/v1/responses。
