OpenAI Harmony

OpenAI面向其开源权重模型系列 gpt-oss 的响应格式
试用 gpt-oss | 了解更多 | 模型卡片

gpt-oss 模型 是基于 harmony 响应格式 训练的，该格式用于定义对话结构、生成推理输出以及组织函数调用。如果您不是直接使用 gpt-oss，而是通过 API 或 HuggingFace、Ollama、vLLM 等提供商来使用，则无需担心此格式问题，因为您的推理解决方案会自动处理格式化。但如果您正在构建自己的推理系统，本指南将指导您如何使用该提示格式。此格式的设计旨在模仿 OpenAI 的 Responses API，因此如果您之前使用过该 API，应该会觉得非常熟悉。请注意，gpt-oss 必须配合 harmony 格式使用，否则将无法正常工作。

该格式允许模型在思维链、工具调用前言以及常规回复等不同通道中输出内容。同时，它还支持指定多种工具命名空间、结构化输出，并提供清晰的指令层级。查看指南 以深入了解该格式的具体细节。

<|start|>system<|message|>你是 ChatGPT，一个由 OpenAI 训练的大语言模型。
知识截止日期：2024年6月
当前日期：2025年6月28日

推理能力：高

# 有效通道：分析、评论、最终。每条消息都必须包含通道信息。
对这些工具的调用必须发送到“functions”评论通道。<|end|>

<|start|>developer<|message|># 指令

始终以谜语形式回应

# 工具

## functions

namespace functions {

// 获取用户所在位置。
type get_location = () => any;

// 获取指定地点的当前天气。
type get_current_weather = (_: {
// 城市和州，例如旧金山，加州
location: string,
format?: "摄氏度" 或 "华氏度", // 默认为摄氏度
}) => any;

} // namespace functions<|end|><|start|>user<|message|>旧金山的天气怎么样？<|end|><|start|>assistant

我们建议在使用采用 harmony 响应格式 的模型时，使用此库：

• 格式一致 – 共享的渲染与解析实现确保标记序列无损。
• 极速高效 – 大量计算工作由 Rust 完成。
• 一流的 Python 支持 – 可通过 pip 安装，附带类型注解存根，测试覆盖率与 Rust 版本完全一致。

使用 Harmony

Python

查看完整文档

安装

从 PyPI 安装该包，运行以下命令：

pip install openai-harmony
# 或者如果你使用 uv
uv pip install openai-harmony

示例

from openai_harmony import (
    load_harmony_encoding,
    HarmonyEncodingName,
    Role,
    Message,
    Conversation,
    DeveloperContent,
    SystemContent,
)
enc = load_harmony_encoding(HarmonyEncodingName.HARMONY_GPT_OSS)
convo = Conversation.from_messages([
    Message.from_role_and_content(
        Role.SYSTEM,
        SystemContent.new(),
    ),
    Message.from_role_and_content(
        Role.DEVELOPER,
        DeveloperContent.new().with_instructions("像海盗一样说话！")
    ),
    Message.from_role_and_content(Role.USER, "啊哈，你好吗？"),
])
tokens = enc.render_conversation_for_completion(convo, Role.ASSISTANT)
print(tokens)
# 稍后，当模型做出回应后……
parsed = enc.parse_messages_from_completion_tokens(tokens, role=Role.ASSISTANT)
print(parsed)

Rust

查看完整文档

安装

将依赖项添加到你的 Cargo.toml 文件中：

[dependencies]
openai-harmony = { git = "https://github.com/openai/harmony" }

示例

use openai_harmony::chat::{Message, Role, Conversation};
use openai_harmony::{HarmonyEncodingName, load_harmony_encoding};

fn main() -> anyhow::Result<()> {
    let enc = load_harmony_encoding(HarmonyEncodingName::HarmonyGptOss)?;
    let convo =
        Conversation::from_messages([Message::from_role_and_content(Role::User, "你好呀！")]);
    let tokens = enc.render_conversation_for_completion(&convo, Role::Assistant, None)?;
    println!("{:?}", tokens);
    Ok(())
}

贡献

大部分渲染和解析逻辑由 Rust 实现，以保证性能，并通过轻量级的 pyo3 绑定暴露给 Python。

┌──────────────────┐      ┌───────────────────────────┐
│  Python代码     │      │  Rust核心（本仓库）    │
│  （数据类、   │────► │  • 对话/编码逻辑       │
│   便利功能）   │      │  • 分词器（tiktoken）   │
└──────────────────┘  FFI └───────────────────────────┘

仓库布局

.
├── src/                  # Rust crate
│   ├── chat.rs           # 高层次数据结构（Role、Message等）
│   ├── encoding.rs       # 渲染与解析实现
│   ├── registry.rs       # 内置编码
│   ├── tests.rs          # 正式的 Rust 测试套件
│   └── py_module.rs      # PyO3 绑定 ⇒ 编译为 openai_harmony.*.so
│
├── python/openai_harmony/ # 纯 Python 封装层，围绕绑定模块
│   └── __init__.py       # 数据类 + 辅助 API，镜像 chat.rs
│
├── tests/                # Python 测试套件（与 tests.rs 一一对应）
├── Cargo.toml            # Rust 包清单文件
├── pyproject.toml        # Python 构建配置，用于 maturin
└── README.md             # 你现在就在这里 🖖

本地开发

前提条件

• Rust 工具链（稳定版）– https://rustup.rs
• Python ≥ 3.8 + virtualenv/venv
• maturin – 用于 PyO3 项目的构建工具

1. 克隆并初始化

git clone https://github.com/openai/harmony.git
cd harmony
# 创建并激活虚拟环境
python -m venv .venv
source .venv/bin/activate
# 安装 maturin 和测试依赖
pip install maturin pytest mypy ruff  # 根据你的工作流程调整

# 编译 Rust crate 并以可编辑模式安装 Python 包
maturin develop --release

maturin develop 使用 Cargo 构建 harmony，生成一个原生扩展模块（openai_harmony.<abi>.so），并将其放置在你的虚拟环境中，与纯 Python 封装器相邻——这类似于纯 Python 项目的 pip install -e .。

2. 运行测试套件

Rust:

cargo test          # 运行 src/tests.rs

Python:

pytest              # 执行 tests/ 目录中的测试（与 Rust 测试套件一致）

为了确保两者的一致性，可以同时运行：

pytest && cargo test

3. 类型检查与代码格式化（可选）

mypy harmony        # 静态类型分析
ruff check .        # 代码 lint 检查
cargo fmt --all     # Rust 代码格式化工具

OpenAI Harmony 快速上手指南

OpenAI Harmony 是专为 gpt-oss 系列开源模型设计的响应格式库。它支持定义对话结构、生成推理过程（Chain of Thought）以及结构化函数调用。如果你直接使用 API 或托管服务（如 HuggingFace、Ollama），通常无需关心此格式；但如果你构建自己的推理后端，则必须使用此库来确保模型正常工作。

环境准备

在开始之前，请确保你的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows (WSL 推荐)
• Python: 版本 ≥ 3.8
• 包管理工具: pip 或 uv (推荐 uv 以获得更快的安装速度)
• 可选 (仅针对贡献者或需要本地编译 Rust 核心时):
  • Rust 工具链 (stable): rustup
  • maturin: 用于构建 PyO3 项目 (pip install maturin)

注意：普通用户直接通过 pip/uv 安装预编译包即可，无需安装 Rust 环境。

安装步骤

你可以选择使用标准的 pip 或更现代的 uv 进行安装。

方式一：使用 pip (通用)

pip install openai-harmony

方式二：使用 uv (推荐，速度更快)

uv pip install openai-harmony

国内加速提示：如果下载速度较慢，可指定国内镜像源（如清华源或阿里源）：

pip install openai-harmony -i https://pypi.tuna.tsinghua.edu.cn/simple
# 或
uv pip install openai-harmony --index-url https://mirrors.aliyun.com/pypi/simple/

基本使用

Harmony 的核心功能是将会话消息渲染为模型所需的 Token 序列，并在模型输出后解析回结构化消息。以下是基于 Python 的最简使用示例。

Python 示例

此示例展示了如何构建一个包含系统指令、开发者指令和用户输入的对话，并将其渲染为 Token。

from openai_harmony import (
    load_harmony_encoding,
    HarmonyEncodingName,
    Role,
    Message,
    Conversation,
    DeveloperContent,
    SystemContent,
)

# 1. 加载 gpt-oss 专用的编码格式
enc = load_harmony_encoding(HarmonyEncodingName.HARMONY_GPT_OSS)

# 2. 构建对话历史
convo = Conversation.from_messages([
    # 系统消息：定义模型身份和知识截止
    Message.from_role_and_content(
        Role.SYSTEM,
        SystemContent.new(),
    ),
    # 开发者消息：设定行为指令 (例如：像海盗一样说话)
    Message.from_role_and_content(
        Role.DEVELOPER,
        DeveloperContent.new().with_instructions("Talk like a pirate!")
    ),
    # 用户消息
    Message.from_role_and_content(Role.USER, "Arrr, how be you?"),
])

# 3. 渲染对话以发送给模型 (生成 Token 序列)
tokens = enc.render_conversation_for_completion(convo, Role.ASSISTANT)
print("Tokens sent to model:", tokens)

# ---------------------------------------------------------
# [此处模拟模型返回了 tokens...]
# 假设模型回复后的 tokens 存储在变量 response_tokens 中
# ---------------------------------------------------------

# 4. 解析模型返回的 Token 为结构化消息
# parsed = enc.parse_messages_from_completion_tokens(response_tokens, role=Role.ASSISTANT)
# print("Parsed response:", parsed)

核心概念说明

• Role (角色): 支持 SYSTEM, DEVELOPER, USER, ASSISTANT。其中 DEVELOPER 角色用于传递高阶指令和工具定义。
• Channels (通道): Harmony 格式允许模型输出到不同通道（如 analysis 用于推理，commentary 用于工具调用前缀，final 用于最终回复），这在解析阶段会自动处理。
• 一致性: 该库保证了渲染（Render）和解析（Parse）过程中的 Token 序列无损，确保与 gpt-oss 模型的训练格式完全一致。

如需更高级的功能（如自定义工具命名空间或复杂的思维链控制），请参考官方完整文档。