• Harmonyフォーマットが解決する技術的課題
• system / developer / user / assistant / tool 各ロールの役割定義
• analysis / commentary / final の3チャンネルによる出力の分離
• 推論（reasoning / CoT）、ツール呼び出し、および構造化出力の表現方式
• 全公開特殊トークン（special token） の一覧と使用基準
• トークナイザ設定上は未公開であるが、openai/harmony 実装内に存在する追加トークン候補の扱い
• Hugging Faceの chat_template.jinja における実際の処理ロジック
• 具体的な対話例、ツール利用例、および実装例の提示

• 会話の階層構造（system / developer / user / assistant / tool）
• モデルの内部推論（analysis）
• ユーザー向けの中間通知（commentary）および最終回答（final）
• ユーザー定義関数（function tools）の呼び出し
• 組み込みツール（browser / python）の実行
• 構造化出力（JSON Schema等に基づく出力）

• assistantの出力を analysis / commentary / final の独立したチャンネルに分割可能。
• ツール呼び出し（tool call）の終端を <|call|> トークンで制御。
• 最終回答（final answer）の終端を <|return|> トークンで制御。
• 次ターンの会話履歴を構築する際、終端の <|return|> を完了状態を示す <|end|> に正規化可能。
• ツール呼び出しのシーケンス内に、推論プロセス（reasoning）を介在させることが可能。
• developerメッセージ内に、スキーマ定義を伴うレスポンスフォーマット（response format）を組み込み可能。

1. OpenAI Cookbook: OpenAI Harmony Response Format https://developers.openai.com/cookbook/articles/openai-harmony
2. GitHub: openai/harmony https://github.com/openai/harmony
3. openai/harmony Python API docs
   https://github.com/openai/harmony/blob/main/docs/python.md
4. openai/harmony 実装コード (src/encoding.rs)
   https://github.com/openai/harmony/blob/main/src/encoding.rs
5. GitHub: openai/gpt-oss https://github.com/openai/gpt-oss
6. OpenAI Cookbook: How to run gpt-oss with Hugging Face Transformers https://github.com/openai/openai-cookbook/blob/main/articles/gpt-oss/run-transformers.md

1. Hugging Face openai/gpt-oss-20b chat_template.jinja
   https://huggingface.co/openai/gpt-oss-20b/blob/main/chat_template.jinja
2. Hugging Face openai/gpt-oss-20b tokenizer_config.json
   https://huggingface.co/openai/gpt-oss-20b/blob/main/tokenizer_config.json
3. vLLM Recipe: GPT OSS https://docs.vllm.ai/projects/recipes/en/latest/OpenAI/GPT-OSS.html
4. Ollama gpt-oss テンプレート blob
   https://ollama.com/library/gpt-oss%3A20b/blobs/51468a0fd901

• 公式ドキュメント（2.1）を一次情報 として扱う。
• ただし、実際のシステムの振る舞いはチャットテンプレート、トークナイザ設定、およびライブラリの実装に依存するため、これらの二次情報（2.2）も仕様の一部として包括的に評価する。
• 公式ドキュメントの記述と、実際の実装・テンプレート間で乖離が確認された場合は、その差異を明記する。
• 用途が公開されていない特殊トークンについては「未定義」または「不明」として扱い、推測による意味付けは行わない。

1. analysis チャンネルによる内部推論（CoT）の実行
2. commentary チャンネルによるユーザー向けの中間通知（例: 「検索を開始します」などの宣言）
3. commentary または analysis チャンネルを経由した関数・ツール呼び出し（Tool Call）
4. ツール実行結果の読み込み
5. final チャンネルによる最終回答の出力

• 優先順位: system > developer > user > assistant > tool

• 固定的なアイデンティティ（例: You are ChatGPT, a large language model trained by OpenAI.）
• 知識のカットオフ時期（Knowledge cutoff: ...）
• 現在日時（Current date: ...）
• 推論レベル（Reasoning: low | medium | high）
• 組み込みツール（built-in tools）の定義
• 有効なチャンネル（valid channels）の宣言

messages = [
    {"role": "system", "content": "必ず日本語で答えてください"},
    {"role": "user", "content": "こんにちは"},
]

<|start|>system<|message|>You are ChatGPT, a large language model trained by OpenAI.
Knowledge cutoff: 2024-06
Current date: 2026-04-04

Reasoning: medium

# Valid channels: analysis, commentary, final. Channel must be included for every message.<|end|>
<|start|>developer<|message|># Instructions

必ず日本語で答えてください

<|end|>
<|start|>user<|message|>こんにちは<|end|>
<|start|>assistant

<|start|>assistant<|channel|>analysis<|message|>Need to verify the date before answering.<|end|>

<|start|>assistant<|channel|>commentary<|message|>最新情報を確認してから答えます。<|end|>

<|start|>assistant<|channel|>final<|message|>結論は 42 です。<|return|>

<|start|>{header}<|message|>{content}<|end|>

• 通常の完結メッセージ: <|end|>
• 最終回答の生成完了（デコード停止）: <|return|>
• ツール呼び出しの生成完了（デコード停止）: <|call|>

message      := "<|start|>" header "<|message|>" content terminator
header       := author [recipient] [channel] [content_type]
author       := role | role ":" name | tool_name
recipient    := " to=" recipient_name
channel      := "<|channel|>" channel_name
content_type := " " plain_type | " <|constrain|>" constrained_type
terminator   := "<|end|>" | "<|return|>" | "<|call|>"

<|start|>assistant to=functions.get_current_weather<|channel|>commentary <|constrain|>json<|message|>{"location":"Tokyo"}<|call|>

• <|start|>: メッセージの開始を示すトークン。
• assistant: 発信者のロール。
• to=functions.get_current_weather: 呼び出し先の関数指定。
• <|channel|>commentary: 使用するチャンネル。
• <|constrain|>json: ペイロードのデータ型。
• <|message|>: ヘッダ部と本文（コンテンツ）の境界トークン。
• {"location":"Tokyo"}: 本文（JSON形式の引数）。
• <|call|>: ツール呼び出し用の終端トークン。ここで推論を停止し、ツールの実行プロセスへ移行する。

<|start|>user<|message|>What is 2 + 2?<|end|>
<|start|>assistant

<|channel|>analysis<|message|>...

• 固定のアイデンティティ: 例として「You are ChatGPT, a large language model trained by OpenAI.」などを指定する。
• Knowledge cutoff: 知識のカットオフ日を指定する。
• Current date: 現在の日付を指定する。
• Reasoning: 推論の度合いを low、medium、high のいずれかで指定する。
• built-in tools: 必要に応じて組み込みツールを定義する。
• valid channels: 有効なチャンネル（analysis, commentary, final）を宣言する。
• function toolsの指定: function toolsを使用する場合は、該当ツールをcommentaryチャンネルで呼び出すよう指定する記述を追加する。

<|start|>system<|message|>You are ChatGPT, a large language model trained by OpenAI.
Knowledge cutoff: 2024-06
Current date: 2026-04-04

Reasoning: high

# Valid channels: analysis, commentary, final. Channel must be included for every message.<|end|>

<|start|>system<|message|>You are ChatGPT, a large language model trained by OpenAI.
Knowledge cutoff: 2024-06
Current date: 2026-04-04

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|>

<|start|>system<|message|>You are ChatGPT, a large language model trained by OpenAI.
Knowledge cutoff: 2024-06
Current date: 2026-04-04

Reasoning: medium

# Tools

## browser

// Tool for browsing.
// The `cursor` appears in brackets before each browsing display: `[{cursor}]`.
// Cite information from the tool using the following format:
// `〖{cursor}†L{line_start}(-L{line_end})?〗`, for example: `〖6†L9-L11〗` or `〖8†L3〗`.
// Do not quote more than 10 words directly from the tool output.
// sources=web (default: web)
namespace browser {

type search = (_: {
query: string,
topn?: number, // default: 10
source?: string,
}) => any;

type open = (_: {
id?: number | string, // default: -1
cursor?: number, // default: -1
loc?: number, // default: -1
num_lines?: number, // default: -1
view_source?: boolean, // default: false
source?: string,
}) => any;

type find = (_: {
pattern: string,
cursor?: number, // default: -1
}) => any;

} // namespace browser

## python

Use this tool to execute Python code in your chain of thought. The code will not be shown to the user.
When you send a message containing Python code to python, it will be executed in a stateful Jupyter notebook environment...

# Valid channels: analysis, commentary, final. Channel must be included for every message.<|end|>

• # Instructions
• # Tools
• # Response Formats

<|start|>developer<|message|># Instructions

必ず日本語で、箇条書きは最小限にして答えてください。<|end|>

<|start|>developer<|message|># Instructions

フレンドリーな口調で答えてください。

# Tools

## functions

namespace functions {

// 現在地を返す
type get_location = () => any;

// 指定都市の現在天気を返す
type get_current_weather = (_: {
// 市名。例: "Tokyo"
location: string,
// 単位
format?: "celsius" | "fahrenheit", // default: celsius
}) => any;

} // namespace functions<|end|>

<|start|>developer<|message|># Instructions

あなたは買い物リスト作成アシスタントです。

# Response Formats

## shopping_list

{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"},"description":"買い物項目"}},"required":["items"]}<|end|>

<|start|>user<|message|>東京の今日の気温を教えて<|end|>

<|start|>user:alice<|message|>こんにちは<|end|>

1. analysis: 内部推論
2. commentary: ユーザー向けの中間説明およびプリアンブル
3. final: 最終回答
4. to=... 属性を持つツール呼び出し（tool call）

<|start|>assistant<|channel|>final<|message|>2 + 2 = 4 です。<|return|>

<|start|>assistant<|channel|>analysis<|message|>ユーザーは単純な算数を聞いている。直接答える。<|end|>

<|start|>assistant<|channel|>commentary<|message|>まず公式情報を確認します。<|end|>

<|start|>assistant<|channel|>analysis<|message|>Need to use function get_current_weather.<|end|>
<|start|>assistant<|channel|>commentary to=functions.get_current_weather <|constrain|>json<|message|>{"location":"San Francisco"}<|call|>

<|start|>assistant to=functions.get_current_weather<|channel|>commentary json<|message|>{"location":"San Francisco"}<|call|>

• プレーンテキストの "json"
• 特殊トークンを用いた "<|constrain|>json"

<|start|>functions.get_current_weather to=assistant<|channel|>commentary<|message|>{"sunny":true,"temperature":20}<|end|>

<|start|>python to=assistant<|channel|>analysis<|message|>55<|end|>

<|start|>browser.search to=assistant<|channel|>analysis<|message|>[12] Bank of Japan - Policy Interest Rate<|end|>

• gpt-oss は推論モデル（reasoning model）として機能する。
• 推論の強度（reasoning effort）は low、medium、high のいずれかで指定される。
• 生の推論過程（CoT: Chain of Thought）は analysis チャンネルに出力される。
• analysis チャンネルの内容は、エンドユーザーに対しては非表示とする仕様である。
• ユーザーに対する最終的な回答は final チャンネルを介して出力される。

<|start|>user<|message|>What is 2 + 2?<|end|>
<|start|>assistant

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

• 生成停止時点の最終回答: <|return|>
• 会話履歴としての保存時: <|end|>

<|start|>assistant<|channel|>final<|message|>2 + 2 = 4.<|return|>

<|start|>assistant<|channel|>final<|message|>2 + 2 = 4.<|end|>

1. analysis の出力
2. ツール呼び出しの出力
3. ツール実行結果の受領
4. 推論の継続、または final の出力

<|start|>assistant<|channel|>analysis<|message|>Need to use function get_current_weather.<|end|>
<|start|>assistant<|channel|>commentary to=functions.get_current_weather <|constrain|>json<|message|>{"location":"San Francisco"}<|call|>
<|start|>functions.get_current_weather to=assistant<|channel|>commentary<|message|>{"sunny": true, "temperature": 20}<|end|>
<|start|>assistant

• openai-harmony には、RenderConversationConfig(auto_drop_analysis=True) が実装されている。
• Hugging Faceの chat_template.jinja は、後続に final が存在する場合、それ以前の tool-CoT および analysis を破棄するロジックを内包している。

• assistant の1メッセージにつき、最大1回のツール呼び出しが行われるものと想定する。
• tool ロールのメッセージにおけるツール名は、直前の assistant によるツール呼び出し名から推定される。
• content と thinking を同時に内包する assistant のツール呼び出しメッセージは、例外として処理される。

• 名前空間は namespace functions { ... } の形式で宣言する。
• 引数を持たない関数は type foo = () => any; と定義する。
• 引数を持つ関数は type foo = (_: { ... }) => any; と定義する。
• 各フィールドの上部には // を用いて説明（コメント）を記述する。
• 戻り値の型（return type）は常に any を指定する。

# Tools

## functions

namespace functions {

// ユーザーの位置情報を返す
type get_location = () => any;

// 指定都市の現在天気を返す
type get_current_weather = (_: {
// 都市名。例: "Tokyo"
location: string,
// 温度単位
format?: "celsius" | "fahrenheit", // default: celsius
}) => any;

// 複数都市の天気を一括取得
type get_multiple_weathers = (_: {
// 都市一覧
locations: string[],
format?: "celsius" | "fahrenheit", // default: celsius
}) => any;

} // namespace functions

• 配列型は string[]、number[]、boolean[] 等へ変換される。
• Enum型は "a" | "b" | "c" のようなユニオン型へ変換される。
• 必須（required）でないプロパティには ? が付与される。
• デフォルト値は // default: ... の形式でコメントとして明記される。
• 複雑なユニオン型やオブジェクト型は、any 型へフォールバックされる場合がある。

• browser
• python

• Web検索
• Webページの展開（開く）
• ページ内検索
• 行番号を伴う情報引用

## browser

// Tool for browsing.
// The `cursor` appears in brackets before each browsing display: `[{cursor}]`.
// Cite information from the tool using the following format:
// `〖{cursor}†L{line_start}(-L{line_end})?〗`
// Do not quote more than 10 words directly from the tool output.
// sources=web (default: web)
namespace browser {

type search = (_: {
query: string,
topn?: number, // default: 10
source?: string,
}) => any;

type open = (_: {
id?: number | string, // default: -1
cursor?: number, // default: -1
loc?: number, // default: -1
num_lines?: number, // default: -1
view_source?: boolean, // default: false
source?: string,
}) => any;

type find = (_: {
pattern: string,
cursor?: number, // default: -1
}) => any;

} // namespace browser

<|start|>assistant<|channel|>analysis<|message|>Need to verify the latest policy rate from an official source.<|end|>
<|start|>assistant to=browser.search<|channel|>analysis <|constrain|>json<|message|>{"query":"site:boj.or.jp policy rate","topn":5,"source":"web"}<|call|>
<|start|>browser.search to=assistant<|channel|>analysis<|message|>[12] Bank of Japan - Monetary Policy<|end|>
<|start|>assistant to=browser.open<|channel|>analysis <|constrain|>json<|message|>{"cursor":12,"id":0,"loc":120,"num_lines":20,"source":"web"}<|call|>
<|start|>browser.open to=assistant<|channel|>analysis<|message|>[13]
L120: ...
L121: ...
L122: ...<|end|>
<|start|>assistant<|channel|>final<|message|>公式資料では政策金利は 0.5% と記載されています。〖13†L120-L122〗<|return|>

• 内部推論過程における計算処理
• データの整形処理
• 小規模なコードの実行
• 最終生成物（表、図、ファイル等）の出力準備作業

• Chain-of-Thought（CoT）の過程として Python コードの実行が可能である。
• 実行されるコードはエンドユーザーには非表示とする前提である。
• ステートフルな Jupyter ノートブック風の環境が提供される。
• 実行にはタイムアウト制約が存在する。
• /mnt/data ディレクトリへのアクセスが許可されている。
• インターネットアクセスの可否は、ホストされるクラスターの環境設定に依存し、一律ではない。

<|start|>assistant<|channel|>analysis<|message|>Need exact computation for the sum of squares from 1 to 5.<|end|>
<|start|>assistant to=python<|channel|>analysis<|message|>sum(i*i for i in range(1, 6))<|call|>
<|start|>python to=assistant<|channel|>analysis<|message|>55<|end|>
<|start|>assistant<|channel|>final<|message|>1^2 から 5^2 までの和は 55 です。<|return|>

# Response Formats

## {format_name}

// 任意の説明
{json_schema}

<|start|>developer<|message|># Instructions

あなたは買い物アシスタントです。

# Response Formats

## shopping_list

{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"},"description":"entries on the shopping list"}},"required":["items"]}<|end|>
<|start|>user<|message|>コーヒー、卵、牛乳を買いたい<|end|>
<|start|>assistant

<|start|>assistant<|channel|>final<|message|>{"items":["コーヒー","卵","牛乳"]}<|return|>

• <|reserved_200000|>
• <|reserved_200001|>
• <|reserved_200004|>
• <|reserved_200009|>
• <|reserved_200010|>
• <|reserved_200011|>
• <|reserved_200013|>
• <|reserved_200014|>
• <|reserved_200015|>
• <|reserved_200016|>
• <|reserved_200017|>

• bos_token = "<|startoftext|>"
• eos_token = "<|return|>"
• pad_token = "<|endoftext|>"

<|start|>user<|message|>Hello<|reserved_200015|><|end|>

• <|refusal|>
• <|untrusted|>
• <|end_untrusted|>
• <|meta_end|>

<|start|>assistant<|channel|>final<|refusal|><|message|>...

<|start|>functions.search_docs to=assistant<|channel|>commentary<|message|>{"results":[...]}<|end|>

• 出力例:

<|start|>assistant<|channel|>commentary<|message|>作業計画:
1. 公式サイトを検索
2. PDF を開く
3. 要点を要約
順番に進めます。<|end|>

• 入力メッセージ:

<|start|>system<|message|>You are ChatGPT, a large language model trained by OpenAI.
Knowledge cutoff: 2024-06
Current date: 2026-04-04

Reasoning: high

# Valid channels: analysis, commentary, final. Channel must be included for every message.<|end|>
<|start|>user<|message|>2 + 2 は？<|end|>
<|start|>assistant

• モデル出力:

<|channel|>analysis<|message|>ユーザーは単純な加算を尋ねている。直接答えればよい。<|end|>
<|start|>assistant<|channel|>final<|message|>2 + 2 = 4 です。<|return|>

• 次ターン用履歴データの正規化:

<|start|>assistant<|channel|>final<|message|>2 + 2 = 4 です。<|end|>

• ツール定義（developer ロールに配置）:

<|start|>developer<|message|># Instructions

天気は簡潔に答えてください。

# Tools

## functions

namespace functions {

// 指定都市の現在天気を返す
type get_current_weather = (_: {
// 都市名
location: string,
}) => any;

} // namespace functions<|end|>

• ユーザー入力:

<|start|>user<|message|>サンフランシスコの天気は？<|end|>
<|start|>assistant

• 初回モデル出力（ツール呼び出し）:

<|channel|>analysis<|message|>Need to use function get_current_weather.<|end|>
<|start|>assistant<|channel|>commentary to=functions.get_current_weather <|constrain|>json<|message|>{"location":"San Francisco"}<|call|>

• ツール実行結果の返却:

<|start|>functions.get_current_weather to=assistant<|channel|>commentary<|message|>{"sunny":true,"temperature":20,"unit":"celsius"}<|end|>
<|start|>assistant

• 2回目モデル出力（最終回答）:

<|channel|>analysis<|message|>Tool says sunny and 20C. Provide concise final answer in Japanese.<|end|>
<|start|>assistant<|channel|>final<|message|>サンフランシスコは晴れ、20℃です。<|return|>

• 仕様上の留意点:
  • analysis チャンネルの出力はユーザーに対して非表示とする。
  • ツールの呼び出しは <|call|> トークンで停止する。
  • 実行結果を返却したのち、末尾に <|start|>assistant を付与して生成処理を再開する。

• 実行シーケンス例:

<|start|>assistant<|channel|>analysis<|message|>Need an official and recent source from the Bank of Japan website.<|end|>
<|start|>assistant to=browser.search<|channel|>analysis <|constrain|>json<|message|>{"query":"site:boj.or.jp policy interest rate","topn":5,"source":"web"}<|call|>
<|start|>browser.search to=assistant<|channel|>analysis<|message|>[12] Bank of Japan - Monetary Policy Meetings<|end|>
<|start|>assistant to=browser.open<|channel|>analysis <|constrain|>json<|message|>{"cursor":12,"id":0,"loc":120,"num_lines":10,"source":"web"}<|call|>
<|start|>browser.open to=assistant<|channel|>analysis<|message|>[13]
L120: ...
L121: The uncollateralized overnight call rate ...
L122: ...
<|end|>
<|start|>assistant<|channel|>final<|message|>日銀の公式資料では、無担保コール翌日物金利の誘導目標は 0.5% とされています。〖13†L121-L122〗<|return|>

• 仕様上の留意点:
  • browser ツールは原則として analysis チャンネル上で実行される。
  • 最終回答時の引用には行番号指定フォーマット（〖cursor†Lx-Ly〗）を使用する。
  • ツール出力からの直接的な文字列引用は、テンプレートの制約により10語以内とされる。

• 実行シーケンス例:

<|start|>assistant<|channel|>analysis<|message|>Need exact calculation; using python is simplest.<|end|>
<|start|>assistant to=python<|channel|>analysis<|message|>sum(i*i for i in range(1, 6))<|call|>
<|start|>python to=assistant<|channel|>analysis<|message|>55<|end|>
<|start|>assistant<|channel|>final<|message|>1^2 から 5^2 までの和は 55 です。<|return|>

• 仕様上の留意点:
  • Pythonコードの実行自体はフォーマット上可視化されるが、analysis チャンネルを使用するためユーザーUIには表示させない設計が原則となる。

• 実行シーケンス例:

<|start|>assistant<|channel|>analysis<|message|>Need a multi-step plan involving file generation and server startup.<|end|>
<|start|>assistant<|channel|>commentary<|message|>作業計画:
1. HTML ファイルを生成
2. Node.js サーバーコードを生成
3. 起動確認
---
順番に実行します。<|end|>
<|start|>assistant to=functions.generate_file<|channel|>commentary <|constrain|>json<|message|>{"template":"basic_html","path":"index.html"}<|call|>

• 仕様上の留意点:
  • commentary は直近の処理に関するユーザー向けの中間報告として機能する。
  • final はすべての処理が完了した後の最終成果物として位置づけられる。

• developer 設定例:

<|start|>developer<|message|># Instructions

買い物リストだけを返してください。

# Response Formats

## shopping_list

{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"}}},"required":["items"]}<|end|>

• ユーザー入力:

<|start|>user<|message|>コーヒー、炭酸水、卵が必要<|end|>
<|start|>assistant

• 出力例:

<|start|>assistant<|channel|>final<|message|>{"items":["コーヒー","炭酸水","卵"]}<|return|>

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

encoding = 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, "2 + 2 は？"),
])

prefill_ids = encoding.render_conversation_for_completion(convo, Role.ASSISTANT)
stop_ids = encoding.stop_tokens_for_assistant_actions()

• 主要API:
  • render_conversation_for_completion(...)
  • render_conversation_for_training(...)
  • render_conversation(...)
  • parse_messages_from_completion_tokens(...)
  • stop_tokens()
  • stop_tokens_for_assistant_actions()
  • StreamableParser(...)
• RenderConversationConfig の設定:
  • auto_drop_analysis=True パラメータを設定することで、履歴レンダリング時に不要な analysis データを自動的に除外可能である。
  • この機能により、会話履歴への不要な推論プロセスの蓄積を防止できる。

• 実装例:

from transformers import AutoTokenizer, AutoModelForCausalLM

model_name = "openai/gpt-oss-20b"
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForCausalLM.from_pretrained(model_name, torch_dtype="auto", device_map="auto")

messages = [
    {"role": "system", "content": "必ず日本語で答えてください"},
    {"role": "user", "content": "MXFP4 とは何ですか？"},
]

inputs = tokenizer.apply_chat_template(
    messages,
    add_generation_prompt=True,
    return_tensors="pt",
    return_dict=True,
).to(model.device)

• 実装時の留意事項:
  • 先頭に定義された system ロールは、自動的にHarmonyの developer ロールとして扱われる。
  • Harmonyの本来の system メッセージは、テンプレート側で自動生成される。
  • add_generation_prompt=True を指定することで、末尾に生成開始トリガーとなる <|start|>assistant が追加される。
  • テンプレートには builtin_tools, model_identity, reasoning_effort などの引数が用意されており、reasoning_effort の初期値は medium となっている。

• /v1/responses:
  • 推論（Chain-of-Thought）途中におけるツールの実行をサポートする。
  • 最終応答までの全工程を処理可能である。
  • 入力のレンダリングおよび出力のパースには openai-harmony ライブラリが使用される。
  • 状態保持（stateful operation）や完全なストリーミング処理については現在開発中（WIP）である。
• /v1/chat/completions:
  • 標準的なチャット補完インターフェースを提供するが、ツールの実行は行われない。
  • 推論データと最終テキストを構造化して返却することが可能である。
  • include_reasoning: false を指定することで、推論プロセスをレスポンスから除外できる。
• /v1/completions:
  • プレーンな入出力のみをサポートし、Harmonyの高度な機能についてはクライアント側で処理を実装する必要がある。
• Function Calling 有効化のための起動引数:

vllm serve ... --tool-call-parser openai --enable-auto-tool-choice

1. アプリケーション固有の指示は developer ロールに記述する
   system ロールにすべての指示を含めないこと。
2. final チャネルの末尾 <|return|> を履歴に保持しない
   次ターンの履歴として保持する際は、終端トークンを <|end|> に正規化すること。
3. analysis チャネルの出力をエンドユーザーに表示しない
   Harmonyフォーマットの設計上、analysis は明示的に分離された内部推論として扱う。
4. ツール呼び出しは <|call|> で停止する
   その後、ツールの実行結果を tool メッセージとしてモデルに返却すること。
5. 予約済みトークンを手動で挿入しない
   トークナイザに定義が存在する場合でも、公開仕様として意味は保証されない。
6. 独自実装よりも標準のテンプレートまたはレンダラを使用する
   軽微な構文の差異によりパーサーがエラーとなるリスクを回避するため。
7. Hugging Face (HF) テンプレートの挙動に準拠する
   • system メッセージはHarmonyの developer メッセージに自動変換される。
   • 1つの assistant メッセージにつき、1つのツール呼び出しを前提とする。
   • final 応答生成後は、先行するCoT（Chain of Thought）履歴を破棄する。
8. <|constrain|>json と plain text の json の差異に留意する
   公式CookbookとHFテンプレートで構文例に差異があるが、ライブラリ実装上は双方の形式を許容する仕様となっている。

• Transformers を利用する場合
  tokenizer.apply_chat_template(...) を利用すること。
• カスタム生成処理を実装する場合
  openai-harmony ライブラリのレンダラおよびパーサーを適用すること。
• 推論サーバーを構築する場合
  vLLM、Ollama、または公式互換レイヤーなど、Harmonyフォーマットをネイティブサポートするミドルウェアを選定すること。

• パーサーおよびレンダラの動作検証
• 学術的または技術的な研究用途
• 互換実装の開発
• トークナイザやプロトコルレベルのデバッグ作業

• Harmonyは、gpt-oss モデル向けに設計された「会話」「推論（reasoning）」「ツール利用」「構造化出力」を統合的に扱うためのフォーマットである。
• system ロールはメタ情報の定義に使用し、アプリケーション固有の指示は developer ロールに定義する。
• assistant ロールの出力は、analysis、commentary、final の3つのチャネルに分離される。
• ツール呼び出しの終端トークンは <|call|>、最終回答の終端トークンは <|return|> を使用する。
• 次ターンの履歴として保持する際は、終端トークンを <|return|> から <|end|> に置換（正規化）する必要がある。
• ユーザー定義の関数ツールは通常 commentary チャネルから呼び出し、組み込みのブラウザ・Pythonツールは通常 analysis チャネルから呼び出す。
• HFチャットテンプレートは、入力の先頭にある system メッセージをHarmonyの developer ロールとして再解釈する。
• トークナイザには21個の追加特殊トークンが定義されているが、大半は予約済みトークンとして扱われる。
• openai/harmony 実装内には公開トークナイザに存在しない追加フォーマットトークンが含まれるが、これらを gpt-oss 向けに手動で入力することは避ける。
• 実装にあたっては、openai-harmony ライブラリまたは公式チャットテンプレートの利用を標準とする。

• OpenAI Cookbook / OpenAI Harmony Response Format
  https://developers.openai.com/cookbook/articles/openai-harmony
• openai/harmony
  https://github.com/openai/harmony
• openai/harmony Python API docs
  https://github.com/openai/harmony/blob/main/docs/python.md
• openai/harmony src/encoding.rs
  https://github.com/openai/harmony/blob/main/src/encoding.rs
• openai/gpt-oss
  https://github.com/openai/gpt-oss
• OpenAI Cookbook / How to run gpt-oss with Hugging Face Transformers
  https://github.com/openai/openai-cookbook/blob/main/articles/gpt-oss/run-transformers.md
• Hugging Face openai/gpt-oss-20b chat_template.jinja
  https://huggingface.co/openai/gpt-oss-20b/blob/main/chat_template.jinja
• Hugging Face openai/gpt-oss-20b tokenizer_config.json
  https://huggingface.co/openai/gpt-oss-20b/blob/main/tokenizer_config.json
• vLLM Recipes / GPT OSS
  https://docs.vllm.ai/projects/recipes/en/latest/OpenAI/GPT-OSS.html
• Ollama gpt-oss template blob
  https://ollama.com/library/gpt-oss%3A20b/blobs/51468a0fd901