OpenAI Harmony：为 gpt-oss 统一对话、推理与工具调用的响应格式

1. 项目定位

OpenAI Harmony 是为 gpt-oss 开放权重模型设计的响应格式和渲染库。它定义了对话消息、指令层级、推理频道、工具调用与结构化输出如何编码成模型所需的 token 序列。[S1] OpenAI 在发布 gpt-oss 时同时开源了 Harmony 渲染器。[S2]

2. 核心结构

Harmony 将消息按 system、developer、user、assistant 等角色组织，并使用频道区分推理、工具调用前的说明和面向用户的最终响应。[S1] 它还规定消息边界和停止 token，使推理引擎能在模型要调用工具或完成回答时停下并做正确的后续处理。

3. 与 gpt-oss 的关系

gpt-oss-120b 和 gpt-oss-20b 在后训练中使用 Harmony 提示格式，官方说明对自行运行权重的实现者，正确渲染该格式是模型正常工作的前提。[S1][S2] 若通过 Ollama 或其他已集成提供者使用模型，格式处理通常由推理方完成；自建引擎时才需直接集成库。[S1]

4. 渲染与解析

官方仓库提供 Rust 核心实现和 Python 绑定。调用者可以构造 Conversation 和不同角色的 Message，将其渲染为完成所需 token，再把模型输出解析回消息。[S1] 共用实现的价值是降低手写字符串模板在转义、停止位置和 token 边界上的不一致。

5. 集成路径

自建推理服务可先用官方库处理纯对话，对固定用例保存渲染后 token 和解析结果。通过后再加入 developer 指令、一个只读工具和一个 JSON Schema 输出，逐层比对回归。不建议一开始就同时自定义模板、停止规则和工具调度，否则很难判断错误来自哪一层。

6. 适用场景

Harmony 适合自行托管 gpt-oss、开发新推理后端、编写模型运行时适配器，或需要精确控制工具调用和频道解析的团队。普通业务应用若已通过托管 API 使用 gpt-oss，通常无需直接操作 Harmony，否则只是重复提供者已完成的工作。

7. 成本与开放程度

Harmony 提供公开开源仓库，同时包含 Python 包和 Rust 实现。[S1] 库本身只解决格式问题，自建推理仍需承担 GPU、调度、监控、模型下载、安全更新和兼容性维护。如果只是为了获得格式控制而自建完整服务，这些成本可能超过实际收益。

8. 主要风险

格式实现错误可能导致指令层级错位、工具参数被当成普通文本，或推理内容泄露到面向用户的频道。结构化输出的提示也不能单独保证符合 schema；官方指南提醒自建方还需语法约束或独立验证。[S1] 升级库和模型时若没有成对回归，也可能出现隐蔽不兼容。

9. 验收方法

应为每个角色、频道、停止类型、工具调用和结构化输出建立黄金样本。检查渲染后 token 可被官方解析器无损还原，工具调用能在正确停止点触发，最终频道不含推理文本。再针对截断输出、非法 token、超长工具参数和多次工具循环做异常测试，才能进入生产压测。

10. 来源与更新时间

• [S1] OpenAI Harmony 官方仓库，说明格式、角色、频道、渲染解析与开源实现｜链接
• [S2] OpenAI Cookbook 的 Harmony 官方指南，说明 gpt-oss 对该格式的使用与实现要求｜链接

更新于 2026-08-12。对调整 tokenizer、模型版本或运行时的部署，应重跑 token 级兼容性回归。