近日，OpenAI在发布其开源模型gpt-oss-120b和gpt-oss-20b的同时，也推出了一种专为这些模型设计的全新消息格式——Harmony。对于希望在自有解决方案中充分利用这些开源模型的开发者而言，理解Harmony至关重要。本文将以客观的第三方视角，详细解析Harmony格式的设计理念与技术细节。

什么是Harmony格式？

Harmony是OpenAI为其gpt-oss系列模型量身打造的一种响应格式，其核心目标是定义对话结构、生成推理输出以及结构化函数调用。 gpt-oss模型在训练时已深度整合此格式，因此，任何直接与模型进行交互的推理解决方案都必须遵循Harmony规范，否则模型将无法正确工作。 不过，如果通过Ollama等第三方服务或API使用这些模型，则无需直接处理该格式，因为服务提供商会完成底层的格式转换。

Harmony的设计理念借鉴了OpenAI的Responses API，因此熟悉该API的开发者会感到亲切。 它通过引入特定的角色、通道和特殊令牌，为模型交互提供了前所未有的结构性和控制力。

核心概念：角色 (Roles) 与通道 (Channels)

角色 (Roles)

Harmony为每一次交互的消息都定义了角色，模型能够识别以下五种角色：

这些角色还构成了一个清晰的指令层级，当出现指令冲突时，模型会遵循 system > developer > user > assistant > tool 的优先级顺序。

通道 (Channels)

assistant（助手）角色的消息可以被分发到三个不同的“通道”，用以区分面向用户的回复和模型内部的思考过程：

消息格式与特殊令牌

Harmony的底层格式由一系列特殊令牌和结构化的消息组成。

特殊令牌

模型使用一套以 <|...|> 格式包裹的特殊令牌来识别输入结构：

• <|start|>: 标志一条消息的开始。
• <|end|>: 标志一条消息的结束。
• <|message|>: 分隔消息的“头部”元信息和实际内容。
• <|channel|>: 在头部信息中，用于引出通道信息。
• <|constrain|>: 在工具调用中，用于指示数据类型定义。
• <|return|>: 一个停止令牌，表示模型已完成响应生成。
• <|call|>: 一个停止令牌，表示模型希望调用一个工具。

消息结构

一条基础的Harmony消息遵循以下结构：
<|start|>{header}<|message|>{content}<|end|>

其中，{header} 包含角色等元信息，{content} 则是消息的具体内容。

不同消息类型的详细格式

系统消息 (System Message)

系统消息用于提供模型的通用配置，不同于其他格式中的“系统提示”。 它主要定义：

• 模型身份: 例如，“你是由OpenAI训练的大型语言模型ChatGPT。”
• 元数据: 如知识截止日期和当前日期。
• 推理强度: 可设为 high、medium 或 low。
• 可用通道: 通常为 analysis, commentary, final。
• 内置工具: 如浏览器或Python解释器。

示例：

<|start|>system<|message|>You are ChatGPT, a large language model trained by OpenAI.
Knowledge cutoff: 2024-06
Current date: 2025-06-28
Reasoning: high
# Valid channels: analysis, commentary, final. Channel must be included for every message.
Calls to these tools must go to the commentary channel: 'functions'.<|end|>

开发者消息 (Developer Message)

开发者消息才是通常意义上的“系统提示”，包含对模型的具体指令和可用工具的定义。

示例 (不含函数调用):

<|start|>developer<|message|># Instructions
Always respond in riddles<|end|>

推理、函数调用与结构化输出

思维链 (CoT) 推理

gpt-oss是推理模型，开发者可以在系统消息中通过 Reasoning: high 来启用高强度推理。 模型会将其原始的思维链（CoT）作为助手消息输出到 analysis 通道，而最终答案则输出到 final 通道。

示例：
对于问题“2 + 2等于几？”，模型输出可能如下：

<|channel|>analysis<|message|>User asks: "What is 2 + 2?" Simple arithmetic. Provide answer.<|end|>
<|start|>assistant<|channel|>final<|message|>2 + 2 = 4.<|return|>

这里的CoT是 “User asks: “What is 2 + 2?” Simple arithmetic. Provide answer.”，而最终答案是 “2 + 2 = 4.”。

处理后续采样：通常情况下，如果一次交互以 final 通道的消息结束，那么在下一次请求中，应丢弃之前的 analysis 内容。但函数调用是一个例外，因为模型需要保留完整的上下文以继续其思考过程。

函数调用

• 定义工具: 所有可用函数都应在开发者消息的 Tools 部分使用类似TypeScript的语法进行定义，并包裹在 namespace 中。
• 接收调用: 当模型决定调用工具时，它会在消息头中指定接收方（如 to=functions.get_current_weather），并将消息发往 commentary 通道，最后以 <|call|> 令牌结束。
• 处理并响应: 在处理完工具调用后，需要以 tool 角色的新消息将结果返回给模型。

示例 (完整的函数调用流程):

# 1. 用户提问
<|start|>user<|message|>What is the weather like in SF?<|end|><|start|>assistant

# 2. 模型推理并决定调用工具
<|channel|>analysis<|message|>Need to use function get_weather.<|end|>
<|start|>assistant<|channel|>commentary to=functions.get_weather <|constrain|>json<|message|>{"location":"San Francisco"}<|call|>

# 3. 开发者处理调用后，将结果返回给模型
<|start|>functions.get_weather to=assistant<|channel|>commentary<|message|>{"sunny": true, "temperature": 20}<|end|><|start|>assistant

在此之后，模型将基于收到的工具输出继续推理，并给出最终答案。

结构化输出

开发者可以在 developer 消息的末尾定义一个 Response Formats 部分，通过提供JSON Schema来影响模型的输出格式。但这仅能“影响”模型，要严格保证格式合规，仍需在采样阶段自行构建并实施语法约束。

内置工具与辅助库

内置工具

gpt-oss模型经过了browser（浏览器）和python（代码执行器）两种内置工具的训练。 这些工具应在system消息中定义，而非developer消息。调用格式与普通函数调用类似，但请求会被发往analysis通道。

openai_harmony 辅助库

为了简化开发流程，OpenAI提供了 openai_harmony 库（支持Python和Rust）。 该库能自动处理消息的渲染、令牌化和解析，包括流式解析，极大地降低了直接操作Harmony格式的复杂性。 官方强烈推荐使用此库来构建推理解决方案。

结论

Harmony格式是OpenAI为其新一代开源模型设计的精密通信协议。 它通过对角色、通道和消息结构的精细定义，实现了对模型行为（尤其是推理和工具使用）前所未有的控制力。虽然其细节繁多，但这种结构化的设计为构建更强大、更可靠的智能体应用奠定了坚实的基础。对于希望深度挖掘gpt-oss模型潜力的开发者来说，掌握Harmony将是必不可少的一步。