当调用一个大语言模型时,调用方实际上是在选择一种与模型协作的方式 ,不同的 API 不仅仅是接口参数不同,它们背后是对"应用程序应该如何使用语言模型 "这个问题的不同回答。
Chat Completions、Messages API 和 Responses API 这三种不同的 API 反映了三种不同的应用架构理念,本文深入分析它们的设计哲学、核心差异以及选型策略。
概述
目前(2026-05-13)主流的三套 API 对比:
Chat Completions
设计背景
2023 年 3 月,OpenAI 随 GPT-3.5-turbo 发布了 Chat Completions API(v1/chat/completions)。
它的前身是 Text CompletionsAPI(v1/completions),一个"给我续写这段文字"的接口,专门为单轮文本补全设计的,适用于 text-davinci-003 等较早的模型。
Chat Completions 的核心转变是:把续写的对象从"文本"变成了"对话" 。
f(text) → text f(messages[]) → message
角色三元组(system / user / assistant)是这套设计最成功的地方——简单到不需要文档,人人都能直觉理解"对话"是什么。
事实标准
任何想兼容 OpenAI 生态的模型,只需实现最小 schema,就能几乎零成本接入:
`messages[]` 进,`choices[0].message.content` 出,
这是 HTTP/1.1 式的胜利:不是最优雅的,但协调成本最低,摩擦最小,网络效应使其成为事实上的行业标准。
使用局限
1. 随着对话历史的增长,请求负载会变得庞大,
以下是一个典型的 Chat Completions API 请求示例:
{ "model" : "gpt-4o" , "messages" : [ { "role" : "system" , "content" : "你是一个专业的技术顾问。" } , { "role" : "user" , "content" : "解释一下 API 是什么?" } , { "role" : "assistant" , "content" : "API(应用程序编程接口)是..." } , { "role" : "user" , "content" : "有哪些常见的认证方式?" } ] , "temperature" : 0.7 , "max_tokens" : 150 , "stream" : false }
这种结构要求开发者负责跟踪和管理整个对话历史,随着对话的进行,每次请求都要传完整的 messages[],随着对话轮次增加,请求体会越来越大,网络传输和 Token 消耗都会显著增加。
2. 结构化输出仍然是字符串,必须手动解析
在现代软件工程中,系统之间的数据传递依赖于强类型对象,LLM 的底层本质是一个 Text Completer,它唯一的输出格式就是概率性的字符串流,早期的结构化约束输出完全靠 Prompt Engineering 去告诉模型"请输出合法的 JSON",即使后来推出了 response_format,模型底层仍然在逐个 token 吐出字符串,OpenAI 是在模型的输出端加了一个语法拦截器,如果模型下一个 Token 敢吐出不符合 JSON 规范的字符,就强行把它的嘴捂住,逼它选择符合 Schema 的下一个字符。
这依然不是真正的类型化对象,而是通过高密度的工程护栏,硬生生把一个概率性的文本流裁剪成了看起来合规的字符串。后端依然需要做一次手动反序列化,去承受字符串解析失败的风险。
r = client.chat.completions.create( model="gpt-5.4" , messages=[...], response_format={"type" : "json_schema" , "json_schema" : {"schema" : SCHEMA}}, ) data = json.loads(r.choices[0 ].message.content)
3. 工具调用的角色错位,把"工具执行结果"硬塞进"对话消息"的隐喻中
最初的 Chat Completions 设计中,大模型被隐喻为一个对话参与者。角色极其简单,只有两种:
user(提问的真实人类)
assistant(回答问题的大模型)
当引入 Function Calling 时,大模型不再只是“说话”,它开始需要干活,比如查天气、跑代码、预览文件等。但在现有的 Chat 隐喻里,没有一个"外部系统执行引擎"的位置。为了不颠覆原有的代码框架,使用这套 API 把外部程序执行返回的数据,伪装成第三个"说话者" (role: "tool")。
这就使得结构化输出是"格式合规的字符串"而非真正的类型化对象。新需求被迫挤进旧隐喻里。
代码示例
点击展开
from openai import OpenAIclient = OpenAI(base_url="..." , api_key="..." ) r = client.chat.completions.create( model="gpt-5.4" , messages=[ {"role" : "system" , "content" : "你是一个代码审查助手" }, {"role" : "user" , "content" : "帮我审查这段 Python 代码:..." }, ], max_tokens=500 , ) print (r.choices[0 ].message.content)import jsonr = client.chat.completions.create( model="gpt-5.4" , messages=[{"role" : "user" , "content" : "帮我评估问题缺陷的风险" }], response_format={ "type" : "json_schema" , "json_schema" : { "name" : "risk_report" , "schema" : { "type" : "object" , "properties" : { "level" : {"type" : "string" , "enum" : ["low" , "medium" , "high" ]}, "score" : {"type" : "number" }, "reasons" : {"type" : "array" , "items" : {"type" : "string" }}, }, "required" : ["level" , "score" , "reasons" ], "additionalProperties" : False , }, "strict" : True , }, }, max_tokens=400 , ) data = json.loads(r.choices[0 ].message.content) tools = [{ "type" : "function" , "function" : { "name" : "get_weather" , "description" : "获取城市天气" , "parameters" : { "type" : "object" , "properties" : {"city" : {"type" : "string" }}, "required" : ["city" ], }, }, }] messages = [{"role" : "user" , "content" : "北京今天天气怎么样?" }] r1 = client.chat.completions.create(model="gpt-5.4" , messages=messages, tools=tools) tool_call = r1.choices[0 ].message.tool_calls[0 ] weather_result = get_weather(json.loads(tool_call.function.arguments)["city" ]) messages += [ r1.choices[0 ].message, { "role" : "tool" , "tool_call_id" : tool_call.id , "content" : json.dumps(weather_result), }, ] r2 = client.chat.completions.create(model="gpt-5.4" , messages=messages, tools=tools) print (r2.choices[0 ].message.content)with client.chat.completions.create( model="gpt-5.4" , messages=[{"role" : "user" , "content" : "介绍一下量子计算" }], stream=True , max_tokens=300 , ) as stream: for chunk in stream: print (chunk.choices[0 ].delta.content or "" , end="" , flush=True ) r = client.chat.completions.create( model="gpt-5.4" , messages=[ {"role" : "system" , "content" : LONG_SYSTEM_PROMPT}, {"role" : "user" , "content" : user_question}, ], max_tokens=200 , ) cached = r.usage.prompt_tokens_details.cached_tokens print (f"cached={cached} " )
Messages API
设计背景
2024 年初,Anthropic 随 Claude 3 系列发布了 Messages API(v1/messages)。它从根本上重新定义了"消息内容",它不是字符串,而是 类型化内容块(typed content blocks) 的列表。
text block → 文本 image block → 图片 tool_use block → 模型要调用某个工具 tool_result block → 工具执行结果 thinking block → 模型思考过程
工具调用在这里是一等公民 ,不是附加字段。模型"想要调用工具"这件事被建模为内容流的一部分,而非消息上的额外属性。
核心设计
1. 显式(Explicit)优于隐式(Implicit)
OpenAI 的缓存是完全自动、隐式的,发起请求后台默默去匹配文本,匹配上了就便宜,没匹配上就贵。开发者在发请求前,无法精确预测这次到底能不能命中,只能碰运气。
Anthropic 则认为,既然代码是程序员写的,那么什么时候该省钱、什么时候该建立断点,应该由程序员在代码里明确说了算。
system=[{ "type" : "text" , "text" : LONG_SYSTEM_PROMPT, "cache_control" : {"type" : "ephemeral" }, }]
比如上面代码里给这一段长文本贴上了"缓存标签",Anthropic 的服务器看到这个标签,就会强制把这一段 100k 字的系统提示词或核心文档钉在内存缓存里,从而在工程上能够做出精准的成本和性能预算。
2. 类型安全优于字符串约束
结构化输出用 tool_use 实现,返回的是已解析的 dict,不需要 json.loads。这不是字符串约束,而是协议层面的类型保证,由模型底层和输出采样器直接生成结构数据,在模型吐出 Token 的时候填充工具的参数槽。
r = ac.messages.create( model="claude-sonnet-4-6" , tools=[{"name" : "output" , "input_schema" : SCHEMA}], tool_choice={"type" : "tool" , "name" : "output" }, messages=[...], ) data = r.content[0 ].input
Chat Completions 的结构化是"告诉模型输出合法 JSON 字符串",这是字符串层面的语义;
Messages API 的结构化是"模型填写函数参数对象",这是对象类型层面的语义。
代码示例
点击展开
import anthropicac = anthropic.Anthropic(base_url="..." , api_key="..." ) r = ac.messages.create( model="claude-sonnet-4-6" , max_tokens=500 , system="你是一个代码审查助手" , messages=[{"role" : "user" , "content" : "帮我审查这段 Python 代码:..." }], ) print (r.content[0 ].text)r = ac.messages.create( model="claude-sonnet-4-6" , max_tokens=400 , tools=[{ "name" : "risk_report" , "description" : "输出结构化风险评估结果" , "input_schema" : { "type" : "object" , "properties" : { "level" : {"type" : "string" , "enum" : ["low" , "medium" , "high" ]}, "score" : {"type" : "number" }, "reasons" : {"type" : "array" , "items" : {"type" : "string" }}, }, "required" : ["level" , "score" , "reasons" ], }, }], tool_choice={"type" : "tool" , "name" : "risk_report" }, messages=[{"role" : "user" , "content" : "评估这个供应商的风险" }], ) data = r.content[0 ].input r1 = ac.messages.create( model="claude-sonnet-4-6" , max_tokens=300 , tools=[{ "name" : "get_weather" , "description" : "获取城市天气" , "input_schema" : { "type" : "object" , "properties" : {"city" : {"type" : "string" }}, "required" : ["city" ], }, }], messages=[{"role" : "user" , "content" : "北京今天天气怎么样?" }], ) tool_use = next (b for b in r1.content if b.type == "tool_use" ) weather_result = get_weather(tool_use.input ["city" ]) r2 = ac.messages.create( model="claude-sonnet-4-6" , max_tokens=300 , tools=[...], messages=[ {"role" : "user" , "content" : "北京今天天气怎么样?" }, {"role" : "assistant" , "content" : r1.content}, { "role" : "user" , "content" : [{ "type" : "tool_result" , "tool_use_id" : tool_use.id , "content" : [{"type" : "text" , "text" : str (weather_result)}], }], }, ], ) print (r2.content[0 ].text)with ac.messages.stream( model="claude-sonnet-4-6" ,便利性用控制权换来的。工具在 server 侧执行,中间过程不可见;`previous_response_id` 的上下文是黑盒,把透明度换成了自动化。 max_tokens=300 , messages=[{"role" : "user" , "content" : "介绍一下量子计算" }], ) as stream: for text in stream.text_stream: print (text, end="" , flush=True ) r = ac.messages.create( model="claude-sonnet-4-6" , max_tokens=500 , system=[{ "type" : "text" , "text" : LONG_SYSTEM_PROMPT, "cache_control" : {"type" : "ephemeral" }, }], messages=[{"role" : "user" , "content" : user_question}], ) u = r.usage print (f"cache_write={u.cache_creation_input_tokens} cache_read={u.cache_read_input_tokens} " )
Responses API
设计背景
2025 年 3 月,OpenAI 发布了 Responses API(v1/responses)。这是三套 API 中抽象层级最高的,client 不再管理消息列表,不再执行工具,不再维护对话历史,只是下达任务 ,等待结果。
OpenAI 在官方博客中解释了设计动机:
"怎样让开发者以最简单、最强大的方式调用模型?"
核心设计转变在于:内置工具的执行从客户端移到了服务端 。web_search、code_interpreter 等内置工具由 server 自主执行,模型自己决定何时调用、如何组合,客户端看不到中间过程。
模型在一轮请求中可能既说了话(Text)、又思考了(Reasoning)、还跑了代码(Code)、最后调用了自定义工具(Tool Call),Responses API 的返回对象变成了一个极其规范的类型化数组(Typed Items Array)。
核心设计
1. 服务端状态
previous_response_id 引用上一轮,server 自动带入历史。客户端不再传 messages[],传的是"接着上次继续"。
便利性用控制权换来的。工具在 server 侧执行,中间过程不可见;previous_response_id 的上下文是黑盒,把透明度换成了自动化。
r1 = client.responses.create( model="gpt-4o" , input =[ {"role" : "user" , "content" : "我叫张三,订单号 #A1234" } ], store=True ) r2 = client.responses.create( model="gpt-4o" , input =[ {"role" : "user" , "content" : "我的订单状态怎么样?" } ], previous_response_id=r1.id , store=True , )
2. 推理控制
reasoning.effort: low/medium/high 让程序员在延迟、成本、质量之间按需权衡,这是显式控制"模型需要思考多久"的接口。
r = client.responses.create( model="o1" , input =[ {"role" : "user" , "content" : "分析这段代码的时间复杂度和潜在 Bug:..." } ], reasoning_effort="low" , max_output_tokens=1500 , )
3. 内置工具
以前要在 Chat Completions 里让模型"联网搜索"或"运行代码",需要自己写 Google 爬虫、自己在后端用 Docker 跑 Python,再伪装成 role: "tool" 喂回去。
在 Responses API 里,OpenAI 把这些能力做成了类似操作系统的系统调用程序员只需要在 tools 里像开关一样显式声明:
response = client.responses.create( model="gpt-4o" , input =[ { "role" : "user" , "content" : "查一下今天特斯拉的股价,并用 Python 画出近五天的趋势图。" } ], tools=[ {"type" : "web_search" }, {"type" : "code_interpreter" }, {"type" : "computer_use" } ] )
Responses API 的便利性用控制权换来的,工具在 server 侧执行,中间过程不可见,previous_response_id 的上下文是黑盒,高墙之内是全自动化的乐园,而高墙之外的程序员则交出了灵魂的控制权。
代码示例
点击展开
from openai import OpenAIclient = OpenAI(base_url="..." , api_key="..." ) r1 = client.responses.create( model="gpt-5.4" , input ="我叫张三,订单号 #A1234" , store=True , max_output_tokens=80 , ) r2 = client.responses.create( model="gpt-5.4" , input ="我的订单状态怎么样?" , previous_response_id=r1.id , store=True ,ub 的很多基础接口用了十几年,路径里依然是 /v1。/v1 max_output_tokens=200 , ) print (r2.output_text) import uuidRUN_NONCE = uuid.uuid4().hex [:8 ] r = client.responses.create( model="gpt-5.4" , input =f"[nonce={RUN_NONCE} session={session_id} ] 我叫张三" , store=True , max_output_tokens=80 , ) r = client.responses.create( model="gpt-5.4" , input ="今天 A 股收盘情况如何?" , tools=[{"type" : "web_search_preview" }], max_output_tokens=400 , timeout=45 , ) print (r.output_text) r = client.responses.create( model="gpt-5.4" , input ="分析这段代码的时间复杂度和潜在 Bug:..." , reasoning={"effort" : "low" }, text={"format" : {"type" : "json_object" }}, max_output_tokens=1500 , ) import jsonr = client.responses.create( model="gpt-5.4" , input ="评估供应商 Acme Corp 的合规风险" , text={"format" : { "type" : "json_schema" , "name" : "risk_report" , "schema" : SCHEMA, "strict" : True , }}, max_output_tokens=400 , ) data = json.loads(r.output_text) import asyncior = await client.responses.create( model="gpt-5.4" , input ="生成完整的市场分析报告..." , background=True , store=True , max_output_tokens=800 , timeout=10 , ) for _ in range (30 ): await asyncio.sleep(2 ) r = await client.responses.retrieve(r.id ) if r.status in ("completed" , "failed" , "cancelled" ): break print (r.output_text)import httpxasync def stream_response (prompt: str ): async with httpx.AsyncClient(timeout=60 ) as http: async with http.stream( "POST" , "https://litellm.ecarxgroup.com/v1/responses" , headers={"Authorization" : f"Bearer {KEY} " , "Content-Type" : "application/json" }, json={"model" : "gpt-5.4" , "input" : prompt, "stream" : True , "max_output_tokens" : 300 }, ) as resp: async for line in resp.aiter_lines(): if line.startswith("data:" ): obj = json.loads(line[5 :].strip()) if obj.get("type" ) == "response.output_text.delta" : print (obj["delta" ].get("text" , "" ), end="" , flush=True )
横向对比
核心差异总览
维度
Chat Completions
Messages API
Responses API
核心隐喻
对话补全
内容编排
任务委托
模型角色
对话伙伴
类型化处理器
自主代理人
状态管理
客户端传 messages[]
客户端传 messages[]
服务端 previous_response_id
工具执行
客户端(字符串参数)
客户端(typed dict 参数)
内置工具→服务端;自定义函数→客户端
结构化输出
字符串
dict
字符串
缓存控制
后台自动识别
显式断点 cache_control
prompt_cache_key 命名
可审计性
高(每步可见)
高(每步可见)
低(工具执行不可见)
控制粒度
中
高
低
便利程度
中
低
高
模型覆盖
全部
claude-* 专用
gpt-* 专用
复杂度分布
客户端复杂度 服务端复杂度 Chat Completions 中(管消息历史) 低(无状态) Messages API 高(管历史+工具调度) 低(无状态) Responses API 低(只传任务) 高(管状态+执行工具)
显式 vs 隐式
三套 API 反映了不同的设计取向:
Messages API 最"显式" ——你标记缓存断点、你传 typed 内容块、你执行工具
Responses API 最"隐式" ——大量决策委托给 server
Chat Completions 居中 ——客户端管历史,但缓存全自动
选型指南
需要多模型兼容(gpt/gemini/deepseek/claude 统一入口)? └─ 是 → Chat Completions 只用 claude-*,且需要以下任一: - 结构化输出直接得 dict(无需 json.loads) - 精确控制缓存断点(费用降至 10%) - 工具调用类型安全 └─ 是 → Messages API 只用 gpt-*,且需要以下任一: - 有状态多轮(省去传完整历史) - 内置工具(web_search / code_interpreter) - 推理深度控制(reasoning.effort) - 后台异步任务 └─ 是 → Responses API 其他一切场景 → Chat Completions(更稳定,覆盖最广)
演化路径
Text Completions "给我续写这段文字" f(text) → text │ ▼ Chat Completions(对话隐喻) "给我续写这段对话" f(messages[]) → message ─ 内容是字符串,角色是 system/user/assistant/tool ─ 工具调用是附加字段,结构化输出是"格式合规的字符串" │ ▼ Messages API(类型化内容模型) "给我处理这些内容块" f(messages[content_blocks[]]) → content_blocks[] ─ 内容是类型化对象(text / image / tool_use / tool_result) ─ 工具调用是一等公民,缓存控制内联在内容块里 │ ▼ Responses API(代理隐喻) "帮我完成这个任务" agent.do(input, tools=[built-ins], memory=server_side) → output ─ server 维护状态,server 执行内置工具 ─ 客户端只看最终结果
> **Chat Completions** 是 LLM 的 TCP/IP——不是最优雅的,但因为协调成本最低而成为通用语; > **Messages API** 是给"想掌控每一步"的工程师设计的精密工具; > **Responses API** 是给"想把问题甩给模型"的产品开发者设计的高层抽象。
参考文档