你天天在填的那个 /v1/chat/completion

你这个每天在填的 /v1/chat/completions —— 它到底凭什么？

嘿，我写AI应用三年多了，见过太多人把这个接口当咒语念。项目里配一遍，Dify里配一遍，Cursor里配一遍，本地搭个vLLM还是得配一遍。翻来覆去就是model、messages、temperature、max_tokens这几个字段。可你要真问一句：“它究竟是怎么来的？”大多数人，包括当年的我，都只能挠挠头。

我一开始接OpenAI API时也一样。想得特简单：不就是发个请求，等个返回吗？后来踩了三次坑，才明白——这个接口背后藏着一整套设计哲学，搞懂它，市面上90%的AI API，你都能无痛切换。

最早的大模型接口，长什么样？

你先猜一下。是 /v1/completions。

少了个 chat。这个接口的逻辑，朴实到有点粗暴——你塞一段文本进去，模型就往后接着写。完了。没有角色，没有系统消息，没有对话历史。模型眼里只有一串字符，它的任务就是猜下一个token该是什么。

你想让它当个助手跟你聊天？行。你得自己在prompt里手动拼这些东西：

System: 你是一个有帮助的助手
User: 今天天气怎么样？
Assistant: 让我查一下天气数据。
User: 北京今天会下雨吗？

方案能用，但问题太明显了。模型得靠猜来区分——哪句话是系统指令，哪句话是用户说的，哪句话是自己上次的回复。猜对了还好，猜错了，整个对话逻辑就崩了。更别提想传一张图片进去，或者让模型调用个工具——纯文本prompt里，没有任何优雅的方式表达这些。

所以，/v1/completions 慢慢就退居二线了。

我当时亲自测试过这个接口，用的是GPT-3的早期版本。你想象一下，我得在prompt里手写一个表格，告诉模型“用JSON格式回复”，然后祈祷它不要把系统指令当用户输入给理解。说实话，那体验就跟你用记事本写代码差不多——能跑，但每一步都让你想骂人。

真正的转折点，来了。

OpenAI后来做了一件对整个行业影响巨大的事——把对话结构化。什么结构？从一整段杂乱无章的prompt，变成了一个messages数组。每条消息都有一个明确的role：system是系统指令，user是用户输入，assistant是模型之前的回复，tool是工具返回的结果。

这个变化，看起来就多了一个词 chat，对吧？

但你仔细想想——后面几乎所有AI应用的开发方式，都跟着变了。

你看现在的请求体，多清晰：

{
 "model": "gpt-4",
 "messages": [
 {"role": "system", "content": "你是一个编程助手"},
 {"role": "user", "content": "帮我写一个Python函数"}
 ]
}

各角色各归其位。系统指令不会被当成用户输入，模型知道自己说的是“助手的话”，用户也不用在文本里画特殊标记了。

一旦上下文变成结构化的消息数组，你就获得了精确的控制权——模型看到什么、以什么身份看到、按什么顺序看到，全都由你说了算。多轮对话、角色设定、工具调用，都有了落脚点。

说到这儿，我真心觉得，2023年初第一次用这个接口写聊天机器人时，最大的感受就是：终于不用在prompt里堆砌System:/User:/Assistant:这些占位符了！代码干净了，不是一点半点——是整个人都清爽了。

为什么它成了事实标准？

你猜怎么着？这套协议，后来被整个行业整体接受了。

OpenAI用 /v1/chat/completions，Mistral也用，xAI也用，DeepSeek用 /v1/chat/completions 但格式完全兼容，Groq用 /openai/v1/chat/completions，OpenRouter用 /api/v1/chat/completions。

路径前缀不一样，但协议内核是同一套。

这就带来一个极其实际的好处：你用OpenAI的SDK写完代码，想切到别的平台，很多时候只需要改三个变量——base_url、api_key、model_name。剩下的SDK调用代码，一行不用动。

我上个月做一个项目，原本用OpenAI，后来临时换到Groq跑测试。我把 base_url 从 https://api.openai.com/v1 改成 Groq 的地址，换了 api_key，把模型改成 mixtral-8x7b-32768，跑了三行测试代码——全部通过！看到测试结果的那一刻，我愣了一下，然后笑了。

说真的，/v1/chat/completions 能成为事实标准，主要是因为出现得够早，生态铺得够快。SDK、IDE、前端聊天界面、RAG框架，全都围着它转了一圈。后面的人想推新协议？可以，你得先说服所有工具链的开发者改代码。这事儿有多难？基本等同于让所有人从微信切到另一个聊天软件。

但有一件事，必须说清楚。

兼容，不等于完全兼容。

我这两年测试了十几家平台的API，发现一个规律：大家都说自己 OpenAI-compatible，但兼容程度差太多了。基础的文本聊天几乎都能跑通，流式输出大部分也没问题。但到了tools工具调用、response_format结构化输出、vision图片输入、audio音频输入——这些能力，各家就参差不齐了。

我遇到过这样的情况：在平台A上，工具调用的参数写法和OpenAI完全一样；在平台B上，工具调用的返回值里多了一个字段；在平台C上，图片输入直接报错。

最坑的是，有些平台文档写得天花乱坠，实际跑起来就是另一回事。我去年被某个平台的vision功能狠狠坑过一次。文档上说支持图片输入，结果我传了图片URL，返回的是 model doesn't support this feature。后来查了他们的GitHub issues，才发现功能还在实验阶段，根本没正式上线。

所以，你千万别只看接口地址。一定要根据你的实际使用场景去验证。光聊天没问题，不代表工具调用也没问题。

一个更根本的设计思维

后来我同时接OpenAI、Anthropic、Gemini、Mistral、Groq、DeepSeek、OpenRouter这些接口，才终于发现一件事：你不能按“路径后缀大全”去记。

真正的线索只有一个：一次模型调用，到底被抽象成什么？

这句话听起来有点绕，但一旦想明白，很多字段就豁然开朗了。

• 如果一次调用被抽象成“一段文本续写”，那就是Completions。
• 如果一次调用被抽象成“对话历史里的下一条消息”，那就是Chat Completions。
• 如果一次调用被抽象成“由文本、图片、工具结果组成的内容块”，那就是Messages / content blocks / parts。
• 如果一次调用被抽象成“一个可以调用工具、产生事件、延续状态的任务执行过程”，那就是Responses。

路径只是门牌号。门里面的数据模型，才决定你怎么写代码、怎么解析响应、怎么做工具调用、怎么处理流式输出。

回到实际开发

我现在做AI应用，一般会这么选：

只是普通聊天，要最大生态兼容？就用 /v1/chat/completions。SDK、网关、前端、RAG框架支持最全面，基本不会踩坑。

接OpenAI且需要现代能力？优先 /v1/responses。这是OpenAI新推的接口，适合web_search、file_search、code_interpreter、agent这些场景，有服务端状态管理。

接Claude全功能？优先 /v1/messages。别为了省事强行套OpenAI兼容层——Claude的顶层system、content block、工具和流式都有自己的设计，强行兼容反而容易出问题。

接Gemini原生能力？就用 models/{model}:generateContent。关注contents / parts / systemInstruction这些字段。

想复用OpenAI SDK接Gemini或其它平台？用对应的OpenAI-compatible入口。注意base_url、模型名、兼容层能力范围，先在简单的场景测一下，别一上来就搞复杂调用。

最后一个坑，我真心想提醒你

填Base URL的时候，太容易出错了。

不同工具对Base URL的处理方式完全不一样。有些工具希望你填到 /v1，有些工具希望你填完整的 /v1/chat/completions，有些工具会在内部自动拼接 /chat/completions，还有些工具把Base URL和API URL分开。

如果你自己已经填了完整路径 /v1/chat/completions，而工具又自动拼接一遍，最终请求就会变成 /v1/chat/completions/chat/completions。

这种报错，我见过不下十次。每次看到，人都会怀疑人生——明明地址没错，怎么就404了？

所以，填Base URL时，别只问“地址是什么”，还得问清楚：“这个工具，希望我填到哪一层？”做工具开发的朋友，也请你注意一下这个细节。能帮用户省下的，可不只是排查时间——是他们的头发！

未来怎么看？

OpenAI最近推的 /v1/responses，确实在功能上比chat completions更强大，尤其适合做agent和工具调用场景。但这个接口能不能像chat completions一样成为行业标准，还得看生态跟不跟得上。

毕竟，当一个接口已经深入到所有工具链的血肉里，换个新接口的成本可就不只是改个路径那么简单了。

我看过一些平台已经开始支持responses风格，但真正的考验在于：SDK、IDE、聊天界面、RAG框架、客户端应用——这些全都在用chat completions的数据结构。要让它们都切换过来，短期内不太现实。

对于大多数开发者，我建议还是先把 /v1/chat/completions 吃透。这不仅是一个接口，更是一整套API设计的范本。搞懂了它，再去理解其他接口，你会觉得一切都是理所当然的。

说白了，/v1/chat/completions 的本质就是一句话：

它把一次对话交互的边界，用协议的形式，清晰地锁死了。

系统该说什么，用户该说什么，模型能说什么，哪句是历史，哪句是当前指令——全部用数据结构做保证，不用靠猜。

这一点看起来简单，但能做到，能做到被全行业接受——这就是本事！

所以说，你天天填的这个接口，你真得懂它。它藏着的，是整个AI时代的底层契约。