大语言模型服务接口设计解析

  • 当调用一个大语言模型时,调用方实际上是在选择一种与模型协作的方式,不同的 API 不仅仅是接口参数不同,它们背后是对"应用程序应该如何使用语言模型"这个问题的不同回答。
  • Chat Completions、Messages API 和 Responses API 这三种不同的 API 反映了三种不同的应用架构理念,本文深入分析它们的设计哲学、核心差异以及选型策略。

概述

目前(2026-05-13)主流的三套 API 对比:

API Endpoint 设计者 发布时间 核心隐喻
Chat Completions v1/chat/completions OpenAI 2023.03 对话补全
Messages API v1/messages Anthropic 2024 初 内容编排
Responses API v1/responses OpenAI 2025.03 任务委托

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, // 限制生成的最大 token 数量
"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) # 字符串 → dict,手动转换

3. 工具调用的角色错位,把"工具执行结果"硬塞进"对话消息"的隐喻中

最初的 Chat Completions 设计中,大模型被隐喻为一个对话参与者。角色极其简单,只有两种:

  • user(提问的真实人类)
  • assistant(回答问题的大模型)

当引入 Function Calling 时,大模型不再只是“说话”,它开始需要干活,比如查天气、跑代码、预览文件等。但在现有的 Chat 隐喻里,没有一个"外部系统执行引擎"的位置。为了不颠覆原有的代码框架,使用这套 API 把外部程序执行返回的数据,伪装成第三个"说话者" (role: "tool")。

这就使得结构化输出是"格式合规的字符串"而非真正的类型化对象。新需求被迫挤进旧隐喻里。

代码示例

点击展开
from openai import OpenAI
client = 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 json
r = 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, # assistant 的 tool_calls 消息
{
"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)

# ── Prompt Cache(全自动,无需任何标记)────────────────────
# 前缀稳定且 ≥ 1024 tokens 时,后台自动建立缓存,命中后费用约降 50%
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}") # 首次为 0,后续命中后 > 0

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 的时候填充工具的参数槽。

# 结构化输出:类型语义 → dict
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 # 直接是 dict,类型保证在协议层,不会 JsonParseEcxeption

Chat Completions 的结构化是"告诉模型输出合法 JSON 字符串",这是字符串层面的语义; Messages API 的结构化是"模型填写函数参数对象",这是对象类型层面的语义。

代码示例

点击展开
import anthropic
ac = 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)

# ── 结构化输出(tool use,返回已解析的 dict)───────────────
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 # ← 直接是 dict,无需 json.loads

# ── 工具调用(两轮交互,内容块形式)────────────────────────
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"]) # input 已是 dict

# 工具结果是内容块,类型化
r2 = ac.messages.create(
model="claude-sonnet-4-6",
max_tokens=300,
tools=[...],
messages=[
{"role": "user", "content": "北京今天天气怎么样?"},
{"role": "assistant", "content": r1.content}, # 含 tool_use 块
{
"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)

# ── Prompt Caching(显式断点,内联在内容块里)───────────────
# cache_control 标记"缓存到此为止的所有前缀"
# 命中后输入 token 费用降至约 10%,TTFT 明显下降
r = ac.messages.create(
model="claude-sonnet-4-6",
max_tokens=500,
system=[{
"type": "text",
"text": LONG_SYSTEM_PROMPT, # 数千字的详细规则
"cache_control": {"type": "ephemeral"}, # ← 程序员来标断点,显式控制
# 低频任务加 "ttl": "1h"
}],
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}")
# 首次:cache_write > 0 | 命中:cache_read > 0,实际费用大幅下降

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, # ← 核心:无需在 input 里传第一句,服务器自动关联
store=True,
)

2. 推理控制

reasoning.effort: low/medium/high 让程序员在延迟、成本、质量之间按需权衡,这是显式控制"模型需要思考多久"的接口。

r = client.responses.create(
model="o1", # 涉及 reasoning 通常使用 o 系列模型
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 取代了旧的 messages,接收结构化的角色对话
input=[
{
"role": "user",
"content": "查一下今天特斯拉的股价,并用 Python 画出近五天的趋势图。"
}
],
# 显式声明开启的系统原生工具箱,无需手动编写工具代码
tools=[
{"type": "web_search"}, # 开启联网搜索
{"type": "code_interpreter"}, # 开启云端 Python 代码沙箱
{"type": "computer_use"} # 开启自动化屏幕操作能力
]
)

Responses API 的便利性用控制权换来的,工具在 server 侧执行,中间过程不可见,previous_response_id 的上下文是黑盒,高墙之内是全自动化的乐园,而高墙之外的程序员则交出了灵魂的控制权。

代码示例

点击展开
from openai import OpenAI
client = OpenAI(base_url="...", api_key="...")

# ── 有状态多轮(server 维护历史)────────────────────────────
# ⚠️ store=True 是必要条件,否则后续轮次无法引用
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, # ← 无需传完整历史,server 自动带入
store=True,ub 的很多基础接口用了十几年,路径里依然是 /v1。/v1
max_output_tokens=200,
)
print(r2.output_text) # → "您好张三,关于您的订单 #A1234..."

# ⚠️ 并发陷阱:LiteLLM 代理层缓存忽略 previous_response_id
# 相同 input 字符串跨会话会命中同一缓存,导致上下文混淆
# 规避:每条 input 加运行级 nonce
import uuid
RUN_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,
)

# ── 内置工具(server 自主执行,客户端只看结果)──────────────
r = client.responses.create(
model="gpt-5.4",
input="今天 A 股收盘情况如何?",
tools=[{"type": "web_search_preview"}],
max_output_tokens=400,
timeout=45, # web_search 通常 8-15s,token 消耗约 4000-8000/次
)
print(r.output_text) # 已包含搜索结果,client 无需感知搜索过程

# ── 推理控制 ──────────────────────────────────────────────
# 实测(同一代码分析任务):
# effort=low 11s, ~440 tokens — 简单任务
# effort=medium 26s, ~580 tokens — 中等复杂度
# effort=high 46s, ~1600 tokens — 高精度需求(约 4x tokens)
r = client.responses.create(
model="gpt-5.4",
input="分析这段代码的时间复杂度和潜在 Bug:...",
reasoning={"effort": "low"},
text={"format": {"type": "json_object"}},
max_output_tokens=1500, # ⚠️ 推理 + 输出共享 token 预算,设小了 output_text 为空
)

# ── 结构化输出(Responses API 语法,仍需 json.loads)────────
import json
r = 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 asyncio
r = await client.responses.create(
model="gpt-5.4",
input="生成完整的市场分析报告...",
background=True, # 立即返回,status="queued"
store=True,
max_output_tokens=800,
timeout=10,
)
# 轮询——用 status 判断,不要对比 ID(LiteLLM 每次重签 ID)
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)

# ── 流式:⚠️ OpenAI SDK 有兼容问题,改用 httpx ──────────────
import httpx

async 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** 是给"想把问题甩给模型"的产品开发者设计的高层抽象。

参考文档