最近在排查内部网关日志时，又看到一行让人血压升高的报错：unexpected endpoint or method. (POST /chat/completions)。这不是我第一次遇到它，也不会是最后一次。说实话，OpenAI 的接口规范演进速度比大多数人的认知要快：从最早的 Completions，到一度成为行业默认标准的 Chat Completions，再到 2024 年下半年开始主推的 Responses API，三个名字、三套请求结构，表面都叫"OpenAI 接口"，底层逻辑完全不是一回事。
这篇文章不打算复读官方文档，而是把这几轮演进的设计意图、对现有代码的真实冲击，以及开源生态为什么至今死守/v1/chat/completions的底层原因梳理一遍。如果你正在做 LLM 应用接入、自建私有化网关，或者要给开源模型套一层 OpenAI 兼容接口，这篇文章应该能帮你少踩几个坑。我会从那个具体的报错开始讲，因为它恰恰是接口规范演进过程中各种断层的一个缩影。
1. 先解决那个让人头疼的 unexpected endpoint or method
1.1 这个报错到底是谁抛出来的
unexpected endpoint or method这种返回格式并不是 HTTP 标准状态码，而是 OpenAI 风格网关自己设计的一种错误响应。它通常出现在两种情况：一种是请求路径与网关路由不匹配，比如你本来要打/v1/chat/completions，但因为 base_url 拼接问题实际打到了/chat/completions，少了版本前缀，网关不认识这个路由，就直接把这个请求原样拒绝掉；另一种是目标服务根本没有实现这个端点，比如自建网关只做了/v1/responses的转发逻辑，而上层 SDK 还在走老接口，一个 POST 打过去自然就撞上了unexpected endpoint or method。
我先给一个最常用的验证命令，遇到类似问题不要急着改代码，先用 curl 直接打目标服务看看它到底认不认这个路径：
curl https://api.openai.com/v1/chat/completions \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "hello"}]}'如果这段 curl 能正常返回，说明官方端点没问题，问题出在你的客户端配置上；如果服务端也返回同样的unexpected endpoint or method，那基本可以确定是你的请求路径拼错了，或者你打的服务压根没这个路由。实际工程里最常见的场景反而不是官方 API，而是公司内部网关：底层用 vLLM 起模型，网关层只实现了/v1/chat/completions，结果上层某个新框架默认调用client.responses.create，一个/v1/responses请求过来，网关没有对应处理逻辑，直接给你一个 404 或这个unexpected endpoint or method。
这里有个很实用的排查技巧：先确认你的 SDK 调用方法对应哪个路径，再确认 base_url 最后该怎么拼。OpenAI 官方 Python 和 Node SDK 的默认 base_url 都带/v1，所以client.chat.completions.create请求的是/v1/chat/completions，client.responses.create请求的是/v1/responses。如果你自己包装了一层 HTTP 客户端，手动拼 base_url 时少写了/v1，就会出现这种让人摸不着头脑的报错。
看到这个报错，第一反应不要急着改代码，先用 curl 直接打目标服务确认它到底支持哪些路由。很多排查到最后根本不是 SDK 的问题，而是网关路由表的问题。
1.2 三个接口名，其实是三个时代
接口改名不是拍脑袋，Completions、Chat Completions、Responses，分别对应 OpenAI 产品能力的三个时代。Completions 时代模型做的是"续写"，你给一段 prompt，它返回一段文本，没有对话、没有角色、没有工具。Chat Completions 时代模型开始用 messages 组织上下文，user、system、assistant 这些角色成为协议的一部分，function calling 也在这个时期加入。Responses 时代则更进一步，OpenAI 想统一文本、工具调用、文件检索、网页搜索、多模态输入等一堆能力，给 Agent 应用一个更完整的接口。
这三个时代不是简单的版本升级，而是产品定位的迁移。早期用 Completions 的人，心态是"我在用一个高级文本生成器"；用 Chat Completions 的人，心态是"我在做对话系统"；到了 Responses 时代，心态变成了"我在搭一个会自己调用工具的智能体"。心智模型变了，接口设计自然要跟着变。如果你还拿 Chat Completions 时代的编程习惯去套 Responses API，会觉得它很多余、很多字段不知所谓；反过来，如果你已经习惯了 Responses API 的输出结构，再回去写 Chat Completions 的工具循环，又会觉得重复劳动太多。
1.3 演进背后的驱动力：从补全到智能体
更根本的驱动力是应用形态变了。最初的 API 是给"完形填空"用的，产品交互基本是用户输入一段话拿到一段输出。但到了 GPT-4 时代，大家开始做多轮对话、做插件调用，2024 年以后又流行 Agent，模型不光要回答问题，还要自己决定调用哪个工具、处理工具返回结果、继续推理。Chat Completions 的 messages 数组叠加 tools 参数确实能实现这些，但客户端要手动维护每一轮历史，还要自己写工具执行循环，代码量一大，各种边界问题就来了。
OpenAI 显然看到了这个趋势。从 Assistants API 开始，它就在尝试把"会话状态"和"工具循环"往服务端收拢；Responses API 则是把这些能力协议化、标准化，让任何语言的 SDK 都能通过同一个端点访问。换句话说，接口演进不是工程团队闲得没事干，而是 Agent 应用对协议提出了新的需求：更少的历史传输、更统一的事件流、更完整的工具抽象。理解了这层驱动力，再看 Responses API 里那些看起来陌生的字段，就会顺眼很多。
2. 拆开看：Chat Completions 和 Responses 到底差在哪
2.1 Completions 的"续写"思维：已经退场的旧协议
在聊两个新接口之前，值得先看一眼那个已经退场的 Completions 协议。它请求的核心字段是prompt，响应核心字段是choices[0].text。没有 messages，没有 role，没有 tools，模型看到什么就续写什么。当时的 text-davinci-003、code-davinci-002 都是这个套路，你也很难用这套协议做真正意义上的对话产品，因为多轮上下文完全要自己拼到 prompt 里，角色信息根本无处安放。
后来 GPT-3.5-turbo 和 GPT-4 时代到来，聊天模型成了主力，Completions 就变成了 legacy 接口。OpenAI 官方也建议迁移到 Chat Completions。现在它基本已经退出主流，只有一些老代码还在维护。如果你在旧项目里见过这种prompt字段，别奇怪，那是接口规范演进留下的时代印记。
2.2 Chat Completions 凭什么成为事实标准
回过头看，Chat Completions 的成功几乎是必然的。它把对话拆成最朴素的 messages 数组，每个元素带一个 role，system 给指令、user 提问题、assistant 给回复、tool 放工具结果。这个结构足够简单，简单到任何后端服务都能轻松映射；又足够表达对话场景的完整语义，多轮上下文就是按时间顺序排列 messages，不需要额外的状态管理。
它还在工具调用上做了一个巧妙的抽象：模型如果决定调用函数，返回的 message 里会带tool_calls，客户端执行完函数后把结果作为 role=tool 的消息放回 messages，再发一轮请求。这个"客户端循环"模式虽然原始，但非常透明，开发者能完全掌控每一轮发生了什么。我见过很多团队基于这套模式做了复杂的 Agent 编排系统，跑得也很稳。
更重要的是，Chat Completions 的请求结构可以直接用 curl 验证，协议不依赖任何特定平台能力。对于开源社区来说，"能用 curl 测通的接口就是好接口"。所以 vLLM、Ollama、llama.cpp 这些开源推理引擎，不约而同选择先实现/v1/chat/completions，不是没有道理的。
2.3 Responses 的新设计：统一输出、有状态、内置工具
Responses API 的官方定位是"下一代 Agent 接口"，它相比 Chat Completions 做了几个关键变化。第一个是统一输出结构：Chat Completions 返回的是choices[0].message，而 Responses 返回一个output数组，数组里的元素可以是 message、reasoning、function_call、web_search_call、file_search_call 等不同类型。这样设计的好处是，一个响应里可以混合出现"思考过程""工具调用""文本输出"，客户端可以按类型一一处理，而不是靠猜。
第二个关键变化是有状态。Chat Completions 是无状态的，每次请求都要把完整历史传进去；Responses 支持previous_response_id，服务端帮你存着会话状态，下一次请求只要带上上一个响应的 id，就能接着往下聊。用个不严谨但好懂的说法：Chat Completions 像每次把剧本全文递给演员，Responses 只是告诉服务器"接着上次演"。这对长对话、Agent 多轮任务特别有意义，因为省掉了大量的历史 token 传输。
第三个变化是内置工具。Responses API 直接支持web_search、file_search、code_interpreter、computer_use这类托管工具，你不需要自己实现搜索逻辑、文件解析逻辑，只要在请求里声明工具类型，OpenAI 平台就会帮你把结果塞回响应。这是 Chat Completions 时代完全做不到的，也是开源生态很难追赶的点。当然，对于自定义函数，Responses API 仍然保留了 function call 的模式，本质上还是客户端执行、结果回传，但整体协议表达比 Chat Completions 干净很多。
2.4 一张表看三个接口的对位差异
| 维度 | Completions（旧） | Chat Completions（现状） | Responses API（新） |
|---|---|---|---|
| 端点 | /v1/completions | /v1/chat/completions | /v1/responses |
| 请求核心 | prompt字符串 | messages数组 | input+instructions |
| 输出核心 | choices[].text | choices[].message | output[]数组 |
| 角色体系 | 无 | system / user / assistant / tool | messages 里保留，另有 instructions |
| 状态管理 | 无状态 | 无状态，每次传全量历史 | 支持previous_response_id服务端状态 |
| 工具调用 | 不支持 | tools+tool_calls客户端循环 | 内置托管工具 + function call |
| 流式事件 | 文本增量 | choices[].delta | response.output_text.delta 等事件 |
| 开源兼容现状 | 已淡出 | 事实标准，几乎全兼容 | 实验性，多数网关未实现 |
这张表应该能帮你快速定位自己处在哪个时代。很多团队嘴上说着"我们用的是 OpenAI 接口"，实际上用的是 Chat Completions；真正跑到 Responses API 的，多半是重度 Agent 应用或者用了官方最新的框架。
3. 官方为什么推 Responses，又为什么不废掉 Chat Completions
3.1 Responses 是给 Agent 场景设计的一体化协议
官方推 Responses 的动机，本质上是在为 Agent 时代"补协议"。Chat Completions 设计于 2023 年，那时候的应用主要是聊天和内容生成；但 2024 年以后，OpenAI 的模型能力开始走向"会使用工具、会搜索、会操作电脑"的智能体，包括后来推出的 Codex CLI 这类命令行编码代理，也把工具调用和长任务状态管理作为核心需求。旧的 Chat Completions 协议虽然能靠客户端循环硬撑，但撑得很勉强，尤其是多步骤工具调用、长会话回溯这些场景，代码复杂度会直线上升。
所以 OpenAI 推出了 Responses，本质上是把原来 Assistants API 里的 thread、run 概念做了协议化，收敛到一个/v1/responses端点里。它让 Agent 开发者可以用一套接口完成"多轮对话 + 工具调用 + 内置搜索 + 文件检索 + 结构化输出"的组合，而不用在 Chat Completions 和 Assistants API 之间来回折腾。对我个人来说，最直观的感受是：用 Responses API 写 Agent 代码，样板代码明显少了，处理工具调用的逻辑也更统一。
3.2 官方的兼容态度：旧协议继续活，新能力给新协议
OpenAI 在发布 Responses API 时，并没有要求大家立刻弃用 Chat Completions。官方文档也明确表示，Chat Completions 依然是可用且长期支持的接口，大量存量应用都跑在上面，强制迁移会造成巨大的生态扰动。这个策略我非常认可：新协议负责吸引新场景，旧协议负责承接存量生态，两条腿走路。
但要注意，OpenAI 把一些新能力只给了 Responses API，比如内置的 web_search 和 file_search 工具，Chat Completions 想做这些只能自己接第三方搜索服务或自建向量检索。也就是说，旧接口不会死，但"旧接口 + 新能力"这条路是走不通的。如果你要的只是稳定的对话功能，Chat Completions 完全够用；如果你要的是托管化 Agent 能力，那就必须上 Responses API。
3.3 SDK 里的暗坑：方法名决定路径，路径决定兼容
这个坑我踩过不止一次，值得单独拿出来说。OpenAI 官方 SDK 同时保留了client.chat.completions.create和client.responses.create两个方法，它们请求的路径完全不同。前者打/v1/chat/completions，后者打/v1/responses。如果你的应用接的是自建网关，而网关只实现了/v1/chat/completions，那上层框架一旦用了client.responses.create，立刻就会得到unexpected endpoint or method或者 404。
更隐蔽的是，很多 Agent 框架内部默认走 Responses API，比如官方开源的 Agents SDK 就是把 Responses 作为默认协议。你以为你把 API Key 和 base_url 都配置好了，结果框架在你看不见的地方调用了/v1/responses，自建网关根本不知道这个路由。遇到这类问题，最快的定位方式是在网关层加打印日志，把所有进来的请求路径和 method 记下来，一眼就能看出是哪个端点触发了报错。
4. 开源兼容的真相：为什么大家死守 /v1/chat/completions
4.1 开源推理引擎的协议选择逻辑
如果只看热度，你以为开源生态会紧跟 OpenAI 一起拥抱 Responses API。但现实是，你打开 vLLM、SGLang、Ollama、llama.cpp 这些主流项目的文档，翻到的 OpenAI 兼容接口基本都是/v1/chat/completions，有些顺带支持/v1/completions，但很少有把/v1/responses作为一等公民来做的。
原因不复杂。第一，需求决定供给，用户拿开源模型部署私有服务，绝大多数是通过 OpenAI SDK 的client.chat.completions.create来对接的，项目方自然优先做这个。第二，实现成本差异巨大，Chat Completions 的协议核心就是 messages 数组，后端只要把 messages 拼进模型的聊天模板，采样生成文本，再按 OpenAI 格式返回就行，整个链路非常短；而 Responses API 牵扯到服务端状态存储、工具事件流、内置工具调度，对推理引擎来说这些全是额外的平台级工作。
4.2 聊天模板决定了接口映射的天然成本
还有一个经常被忽略的技术细节：开源模型的 chat template 和 Chat Completions 的协议字段天生就是对得上的。比如很多开源模型使用或兼容 ChatML 格式的聊天模板，system、user、assistant 这些角色在模板里都有明确标记，工具调用和工具结果也有对应的模板表达方式。换句话说，Chat Completions 的协议字段几乎就是模型训练和推理模板的外层表示，映射成本极低。
反过来看 Responses API，它引入了instructions、previous_response_id、output数组、各种事件类型，这些不是模型模板层面的概念，而是平台应用层的抽象。开源推理引擎如果要原生支持 Responses API，等于要在自己项目里再造一套会话管理和工具编排系统，这已经超出了"推理引擎"的职责范围。所以不是开源项目没技术能力做兼容，而是它们普遍认为这块的成本收益不划算。
4.3 兼容网关的三种姿势
虽然开源引擎本身不做 Responses API，但生态里有很多网关项目在做协议转换，它们的思路大致可以分成三种。第一种是直通，网关只做路由和鉴权，上游和下游协议保持一致，最简单也最稳定。第二种是转换，把各家供应商不同的原生协议统一转换成 Chat Completions 格式，再暴露给上层，LiteLLM、one-api 这类项目就是这么干的，这也是 Chat Completions 成为"事实标准"的重要推手。
第三种是伪装，也是我们这里最关心的：客户端想要/v1/responses，后端只有/v1/chat/completions，网关就在中间把 Responses 请求映射成 Chat Completions 请求，再把 Chat Completions 响应或流式事件翻译回 Responses 格式。这种方案确实是能用的，但要注意，它只能模拟协议层，模拟不了 OpenAI 的托管工具。web_search这类内置工具在开源后端里没有对应实现，网关最多把它降级成普通文本回复，或者映射到一个自建搜索函数。
4.4 开源追不动 Responses 的真实原因
我把真实原因总结成四句话。第一，托管工具无法本地化，web_search、file_search、code_interpreter 这些能力绑定 OpenAI 平台服务，开源项目就算实现了协议外壳，也没有背后的搜索索引和沙箱执行环境。第二，有状态会话需要服务端存储，Chat Completions 是"请求-响应"一次算完，Responses 却要维护previous_response_id对应的历史状态，这对自托管部署的运维能力提出了额外要求。第三，协议变化节奏太快，Responses API 本身还在演进，output 里的 item 类型和事件类型一直在增加，兼容层维护起来很累。
第四点最关键，商业动机不足。开源模型的使用者要的是私有化、可掌控、低成本的推理能力，不是 OpenAI 的托管生态。Chat Completions 已经足够支撑绝大多数应用，除非有一天业界主流框架都强制要求 Responses API，否则开源项目没有动力去追这个新协议。所以"开源不兼容 Responses"不是技术上的绝对不可能，而是一个基于成本收益的理性选择。
5. 自己动手：做一个 Responses 到 Chat Completions 的兼容层
5.1 先判断：该让谁兼容谁
在写任何映射代码之前，先想清楚你属于哪种情况。如果你的上层 Agent 框架已经绑定了 Responses API，底层是 vLLM 或 Ollama 这种只支持 Chat Completions 的开源引擎，那你的唯一出路就是在网关层做一次协议转换，把/v1/responses翻译成/v1/chat/completions。反过来，如果你的应用是自己写的，没有强依赖 Responses，那最简单的方式是统一用 Chat Completions，完全没必要引入新的协议层。
还有一个常见的误区是"改 SDK 参数硬凑"。有人会在代码里手动把 Responses 请求体拆开，转成 Chat Completions 的 messages，再把返回值拼回去。这个思路没错，但放在业务代码里做会非常脏，而且每个接入方都这么搞一遍，后期维护会痛不欲生。正确做法是把协议转换下沉到网关层，业务方对协议差异无感知。
5.2 排查 unexpected endpoint 的完整链路
如果现在你眼前就有一个unexpected endpoint or method报错，按这个顺序排查，速度最快。第一步确认 SDK 调用方法：看看代码里到底调的是client.chat.completions.create还是client.responses.create，对应到期望路径。第二步检查 base_url：确认它是否包含/v1，有没有被网关前缀改写。第三步用 curl 分别请求这两个端点，直接看目标服务返回什么，这一步能区分"官方不可用"和"自家网关不认识"两种错误。第四步看网关日志：是不是请求根本没到后端就被路由拦截了。
| 可能原因 | 现象 | 解决方向 |
|---|---|---|
base_url 少了/v1 | 官方 API 也报 unexpected endpoint | 拼接路径补上/v1 |
| SDK 方法用错 | 自建网关报 404 / unexpected endpoint | 改用对应的 client 子客户端 |
网关未实现/v1/responses | 只有 responses 请求失败 | 在网关加协议转换层 |
| 上游模型不支持 tools 字段 | chat completions 请求报参数错误 | 检查模型是否开启 tool 支持 |
这套排查链路我每次遇到类似问题都会走一遍，基本十分钟内能定位到根因。
5.3 一个最小可用的映射方案
下面给一个最小可用的 Responses 到 Chat Completions 的映射伪代码，用 FastAPI 写，核心思路是把instructions和input转成 messages，然后转发给上游 Chat Completions 服务，再把上游响应包装成 Responses 格式。
from fastapi import FastAPI, Request import httpx app = FastAPI() UPSTREAM_CHAT_URL = "http://127.0.0.1:8000/v1/chat/completions" @app.post("/v1/responses") async def responses_to_chat(req: Request): body = await req.json() messages = [] if body.get("instructions"): messages.append({"role": "system", "content": body["instructions"]}) inp = body.get("input", []) if isinstance(inp, str): messages.append({"role": "user", "content": inp}) else: for item in inp: if item.get("type") == "message": messages.append({ "role": item.get("role", "user"), "content": item.get("content", ""), }) tools = [t for t in body.get("tools", []) if t.get("type") == "function"] payload = {"model": body.get("model"), "messages": messages} if tools: payload["tools"] = tools async with httpx.AsyncClient() as client: resp = await client.post(UPSTREAM_CHAT_URL, json=payload) data = resp.json() text = data["choices"][0]["message"].get("content") or "" return { "id": "resp_mock", "object": "response", "status": "completed", "output": [ { "type": "message", "role": "assistant", "content": [{"type": "output_text", "text": text}], } ], }这段代码只覆盖最简单的非流式、无工具调用场景，但它把映射的核心思路讲清楚了：Responses 的input/instructions拆成 Chat Completions 的messages，上游返回的choices[0].message.content包装成 Responses 的output数组。实际生产里要考虑模型字段映射、工具调用循环、流式 SSE、错误格式兼容等。
对于工具循环，更完整的做法是在适配层里循环：第一次调 Chat Completions 拿到tool_calls，适配层执行对应函数，把结果以 role=tool 追加到 messages，再调第二轮，直到模型不再返回tool_calls。最后把整个循环的最终文本和中间的工具调用过程按照 Responses 的 output 数组规范拼装出来。如果还想支持previous_response_id，可以在 Redis 里维护一个response_id -> messages 列表的映射，下次请求过来直接读取历史续接。
5.4 流式映射最容易翻车的三个点
流式场景是协议兼容层最容易翻车的地方，我有三个切身体会。第一个是事件名不对齐，Chat Completions 的流式 chunk 是choices[].delta，Responses API 的流式是response.output_text.delta、response.completed这一类事件，直接透传肯定不行，必须把 chunks 聚合成输出片段后再翻译成 Responses 事件。
第二个是工具调用的流式表达。Chat Completions 里工具调用的 delta 是按 index 拆开拼装function.name和function.arguments的，前端需要自己拼接；Responses 事件则有自己的call_id和事件序列。做映射的时候如果不自己维护拼接缓冲区，很容易出现工具参数被截断、事件顺序错乱的问题。
第三个是结束事件。Responses 客户端通常期待一个明确的response.completed事件，或者等 SSE 流结束；如果你只是把 Chat Completions 的finish_reason透传过去，客户端可能一直等不到终止信号。我个人的建议是：流式映射不要做"边收边转"这种极致优化，宁可攒一小段缓冲再输出，也要保证事件顺序和终止语义完整。
5.5 要不要迁移：我的判断标准
说句实话，Chat Completions 和 Responses API 在未来很长一段时间内会共存。我自己的判断标准很直接：如果你的应用就是聊天、补全、简单 RAG，Chat Completions 够用且稳，继续用，不用折腾；如果你在做多工具 Agent、需要内置搜索和文件检索、希望少传历史省 token，那直接上 Responses API，别在旧接口上硬憋。
我个人在实际项目里是两边都保留的：内部网关同时暴露/v1/chat/completions和/v1/responses，底层开源模型走 Chat Completions 协议，上层 Agent 框架走 Responses 协议，中间靠一层轻量映射把两边串起来。这套组合跑下来很稳，也让团队不用在"换协议"和"换框架"之间做二选一。接口演进是趋势，但兼容层不是耻辱，它是大型系统演进过程中最正常的工程现实。
