一个 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_KEYBearer是 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或assistantcontent即消息正文。此例仅一条{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 Calling2023.6— 工具调用原语请求体中新增tools字段用于声明可用的函数签名响应中新增tool_calls模型不再只返回自然语言而是输出一个结构化的函数调用请求——函数名 参数 JSON。调用方执行该函数后将结果以role: tool的消息形式回填进messages模型再基于此继续推理。这一步的本质是把外部工具纳入了模型的上下文循环模型从“语言生成器”转型为“决策与编排节点”。 JSON Mode2023.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 已经在协议层原生化。总结