AI智能体研发 | 什么是OpenAI API协议

一个 Demo，秒懂使用 OpenAI API 协议

一行命令，直连模型。没有 SDK，没有抽象层------你面对的是最原始的 HTTP 与 JSON，这正是 OpenAI API 协议的真正面貌。

curl -X POST 'https://tokenhub.tencentmaas.com/v1/chat/completions' \
  -H 'Authorization: Bearer sk-xxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{"model": "deepseek-v4-flash","messages": [{"role": "user", "content": "你好"}]}'

把这段敲进终端，按回车，你就完成了一次标准的大模型推理调用。下面我们逐层拆解协议栈。

端点 (Endpoint) /v1/chat/completions这是遵循 OpenAI 接口规范的聊天补全端点。所有对话请求都 POST 到这里，网关 (此处为腾讯 TokenHub) 根据 model 字段将流量路由到具体的推理后端。它本质上就是一个 RESTful 资源定位符。

认证头 (Authorization Header) Authorization: Bearer $API_KEY Bearer 是 HTTP 认证框架中的一种 Token 类型，定义于 RFC 6750 (OAuth 2.0)，继承自 HTTP/1.0 就存在的通用认证机制。服务器从该头中提取 Token，校验通过后赋予本次请求的调用权限。Token 即你的 API Key，不记名，持有即授权。

请求体 (Request Body)

一个 JSON 对象，承载本次调用的全部参数。核心字段只有两个：

• model --- 指定模型标识符。这里用的是 deepseek-v4-flash，一个在延迟与能力之间取得平衡的版本。
• messages --- 对话上下文数组。数组元素为消息对象，最少包含 role 与 content。role 可以是 system、user 或 assistant，content 即消息正文。此例仅一条 {"role": "user", "content": "你好"}，代表单轮用户输入。若传入多轮历史消息，模型将基于完整上下文生成响应。

发送后，你会立即收到 HTTP 200 响应，body 类似：

{
  "choices": [{
      "message": {
        "role": "assistant",
        "content": "你好呀！很高兴见到你！有什么可以帮你的吗？无论是学习、工作还是日常小问题，都可以随时问我哦～"
      }}],
  "usage": {
    "prompt_tokens": 5,
    "completion_tokens": 167,
    "total_tokens": 172
  }
}

响应解析

• choices[0].message.content --- 模型生成的回答文本，对应 role: "assistant"。
• usage --- Token 用量审计，这是计费的根本依据。prompt_tokens 为输入消耗的 token 数，completion_tokens 为输出消耗的 token 数，total_tokens 是两者之和。模型按每千 token 定价，你的账单就由这个字段决定。

一切的核心不过是：构造一个符合协议的 HTTP POST，把对话历史塞进 JSON，在 Authorization 头里带上密钥。这串简单的 curl 命令，就是整个大模型应用层的底层原语。

什么是 OpenAI API 协议

把大模型视为一个计算单元，那 API 就是它的指令集架构。OpenAI API 这套指令集并非一开始就长这样------它是随着 OpenAI 的 GPT 产品线，在一次迭代中生长、定型、扩展出来的。要回答 "什么是OpenAI API 协议？" 不妨回看下演化的过程，大致可切分为三个阶段，每个阶段都在前一阶段约定上抽象出新的一层"协议"。

阶段一：纯文本补全协议（2020 年）

2020 年 6 月，GPT-3 发布，OpenAI 同时抛出了史上第一个公开可用的 API 端点：/v1/completions。这就是 OpenAI API 协议栈的 1.0------最底层、最原始的那条指令。在此之前，GPT-2 的能力有目共睹，但出于安全考量，官方从未开放远程调用，开发者能做的只有下载权重、本地拉起推理进程，门槛高得足以劝退大多数人。

当时的请求体简单到近乎赤裸：

{
  "model": "text-davinci-003",
  "prompt": "请用一句话介绍人工智能\n\n",
  "max_tokens": 100,
  "temperature": 0.7
}

协议语义不加任何修饰：你喂入一段文本（prompt），模型在 token 空间里沿着概率分布续写出下文。核心数据结构仅一个字符串，没有角色体系，没有消息对象------在模型眼中，一切输入都是 token 序列，唯一要做的就是执行"下一个 token 预测"这一个原语。本质上是文本补全协议：人负责给定前缀，模型负责生成后缀。

这样纯粹的简洁性也带来了结构性局限。当需求上升到多轮对话时，你无法把"用户"和"助手"当作一等公民交给 API，只能手动将所有历史交互挤压进一个扁平的 prompt 里：

你是一个手机客服。用户：我的手机开不了机。客服：请尝试长按电源键10秒。用户：还是没反应。客服：

这是一种"伪对话"------上下文状态完全由调用方在外部拼接维护，角色边界靠字符串约定，既脆弱又容易漂移。1.0 版本解决的核心命题是"能不能调用"，它为模型赋予了一个可编程的网络入口；而"如何让对话流畅自然"这个体验层的问题，则留给了协议栈的下一层抽象去回答。

阶段二：结构化对话协议（2022-2023 年）

2022 年 11 月 30 日，ChatGPT 上线。不到两个月，月活破亿。支撑这场爆发的技术底层，是一次 API 协议栈的彻底重构------/v1/chat/completions 端点登场，messages 数组成为新的核心原语。

请求体被重新设计为：

{
  "model": "gpt-3.5-turbo",
  "messages": [
    {"role": "system", "content": "你是一个手机售后客服。"},
    {"role": "user", "content": "我的手机开不了机。"},
    {"role": "assistant", "content": "请尝试长按电源键10秒。"},
    {"role": "user", "content": "还是没反应。"}
  ]
}

这次升级不是在旧接口上打补丁，而是从底层重新定义了"对话"的数据模型。协议不再把交流压扁成一个无结构的文本串，而是显式引入了三个带类型标记的角色消息：

• system --- 协议的控制平面。通常置于消息队列头部，注入全局规则与人设，其优先级在上下文窗口内最高，用于约束模型的行为边界。
• user --- 外部事件源。每一次用户输入都是触发推理的信号，驱动对话状态机向前推进。
• assistant --- 历史状态锚点。记录模型之前生成的每一轮回复，为后续推理提供完整的上下文结晶。

本质上，这是一套对话编排协议 ------调用方从单纯的"输入者"升级为"编排者"，在 messages 数组中精确构造对话历史，模型则在此确定性舞台上完成生成。角色的显式化一举解决了多轮对话的三个结构性问题：角色边界模糊 、上下文污染 、行为不可控。随着 ChatGPT 的爆炸式扩散，这套消息格式迅速溢出 OpenAI，被第三方模型和平台广泛兼容，成为当前整个行业最通用的对话接口规范。它不再是 OpenAI 一家的私有实现，而已是事实上的协议标准。

阶段三：智能体交互协议（2023 年-至今）

对话标准化之后，下一个问题几乎必然冒出来：模型能不能不只是"说"，而是"做"？

2023 年下半年起，OpenAI API 协议栈再次升维。这次迭代的核心不再是优化文本交互的体验，而是将模型从一个被动生成文本的函数，重构为一个可感知、可决策、可行动的智能体运行时。协议本身开始承载"行动"语义。

🛠️ Function Calling（2023.6）--- 工具调用原语

请求体中新增 tools 字段，用于声明可用的函数签名；响应中新增 tool_calls，模型不再只返回自然语言，而是输出一个结构化的函数调用请求------函数名 + 参数 JSON。调用方执行该函数后，将结果以 role: "tool" 的消息形式回填进 messages，模型再基于此继续推理。这一步的本质，是把外部工具纳入了模型的上下文循环，模型从"语言生成器"转型为"决策与编排节点"。

🧱 JSON Mode（2023.11）--- 输出确定性约束

通过设置 response_format: { type: "json_object" }，强制模型输出合法的 JSON。这看似只是一个参数开关，实则改变了输出端的契约------模型的回复不再是自由文本，而是一个可被下游系统直接消费的结构化数据。它把 AI 输出从"需要人工解析"的半结构化形态，推进到了"机器可无歧义读取"的确定性协议层。

👁️ 多模态输入（2023.11）--- 感知通道扩展

messages 中 content 的类型从单一字符串扩展为 text 与 image_url 的数组。协议开始承载视觉 token，模型的感知域从纯文本跨越到图文混合。这是协议在输入端的根本性扩充------推理的前置条件不再只是文字序列，而是任意的多模态信号组合。

⚙️ 更细粒度的控制原语

一系列新参数被引入，让模型的运行时行为变得可预测、可调试：

• seed --- 固定随机种子，确保输出可复现，满足审计与测试需求。
• logprobs --- 返回每个输出 token 的概率对数，提供推理过程的 token 级可观测性。
• parallel_tool_calls --- 允许模型在单轮中并发发起多个工具调用，提升 agent 的执行效率。

这套新的原语集合，共同构成了一套智能体交互协议 。协议不再只是文本进出的信道，而是一张覆盖感知（多模态）、决策（Function Calling）、行动（工具结果回填）和确定性输出（JSON Mode）的完整控制平面。模型通过 messages 维持状态，通过 tools 感知能力边界，通过 tool_calls 发起对外操作------一个最小闭环的 agent loop 已经在协议层原生化。

总结

回看这条演化路径，驱动每一次协议重构的，其实是同一个底层追问：人机交互的边界到底划在哪里，谁来承担推理，谁来触发行动？

• 第一阶段的答案：你给前缀，我补后缀。边界画在文本补全原语上，模型是纯粹的条件概率生成器，上下文状态全部外挂。
• 第二阶段的答案：你编排角色，我执行对话。边界外移到结构化消息与角色类型，模型从"补全函数"升级为"有状态对话引擎"。
• 第三阶段的答案：你声明目标与工具，我决策并调用。边界直接闯入外部信息系统，模型成为可感知、可行动、可审计的智能体运行时。

更精确地看，这三个阶段并非互相替代，而是一次"协议栈的层积过程"。我们如今所说的 OpenAI API 协议 ，正是这三层逐级叠加后形成的完整接口规范：底层是 1.0 的 token 流与补全能力，中间层是 2.0 的角色体系与会话管理，上层是 3.0 的工具调用、多模态感知与确定性输出控制。协议中的每一个字段------messages、tools、response_format、seed、logprobs------都是某一次边界重划时落下的刻痕，标志着人与模型之间的责任划分被重新修订。

因此，OpenAI API 协议的本质，不是一份静态的接口文档，而是一套动态演进的契约：**它持续定义"一个智能体以何种粒度、何种角色、何种自主权限参与到人类的目标系统中"。**每一次新的字段写入请求体，都是在协议层对 "机器能做什么" 做出一次新的承诺，同时在人机之间完成一次责任边界的再分配。

下一篇：这套协议的关键设计

理解了 OpenAI API 协议是一套动态划界的"能力契约"之后，一个更底层的架构问题自然浮现：这套契约的关键条款是怎么设计的？这些设计是不可或缺的，还是是锦上添花？

下一篇，我们将放下演进史，直接切入协议栈的静态结构------把 messages 的关键设计、tools 的绑定语义、response_format 的确定性约束逐一拆开，看清那些看似平淡的 JSON 键名背后，究竟隐藏着怎样的设计意图与取舍权衡。

不想错过？现在就关注、点赞、转发 吧~