告别 Chat Completions：深度解析 AI 接口新标准 `/v1/responses`

在 2026 年的 AI 开发生态中，开发者们正经历一场从"聊天模型"向"智能体模型"的协议大迁移。如果你在调用 API 时收到了 Unsupported legacy protocol 的错误提示，这意味着你正在使用的供应商已经全面转向了 /v1/responses 协议。

本文将带你深入了解这一新标准的由来、优势以及如何进行适配。

---

一、 背景：为什么旧协议被淘汰了？

自 2023 年以来，/v1/chat/completions 一直是 AI 行业的通用语言。它简单直观：发送 messages 数组，获取 content 字符串。

然而，随着 GPT-5 、Gemini 2.0+ 等高性能模型的发布，旧协议的局限性日益凸显：

1. 缺乏状态管理：每次请求都必须发送完整的历史记录，导致 Token 浪费和延迟增加。
2. 推理过程不透明：新一代推理模型（Reasoning Models）在输出前有复杂的"思维链"，旧协议难以结构化展示这些中间步骤。
3. 工具调用受限：复杂的 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)

---

三、 如何判断供应商的支持情况？

1. 观察 Endpoint ：检查 API 文档中的 Base URL。如果包含 /openai/v1/ 且路径强制要求 /responses，说明已完成进化。
2. 模型后缀 ：关注模型列表中是否有 -legacy。没有该后缀的新模型通常优先适配新协议。
3. 技术探测 ：使用 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。