• メッセージ API 層: messages=[{"role": ..., "content": ...}] や tools=[...]、enable_thinking=True/False といった、Python コード上で指定するデータ構造の層です。
• チャットテンプレート層: processor.apply_chat_template(..., tokenize=False) によって変換された生のテキストプロトコルの層です。ここでは <|turn> や <|tool_call> のような制御トークンが文字列として可視化されます。
• プロセッサ展開層: Gemma4Processor が、画像・音声・動画などの高レベルなプレースホルダーを、Tokenizer に渡すための長い特殊トークン列へと内部的に展開する層です。

<bos>
<|turn>system
[任意: <|think|>][任意: system/developer 内容][任意: <|tool>...<tool|> ...]
<turn|>
<|turn>user
...
<turn|>
<|turn>model
[過去 assistant content / tool_calls / tool_responses]
<turn|>
...
<|turn>model
[生成開始位置]

• Role の変換: 入力時の assistant ロールは、テンプレートを経由すると自動的に model に変換されます。つまり、API 層では assistant として定義したものが、生テキスト層では <|turn>model として出力されます。
• Reasoning のトリガー: モデルの推論プロセスを有効化するスイッチは <|think|> トークンです。これは最初の System Turn の冒頭に挿入されます。
• Tool の定義と呼び出し: Tool の定義は、System Turn 内に <|tool>declaration:...<tool|> の形で列挙されます。一方、実際の Tool Call と Response は、Assistant の Turn 内に <|tool_call>...<tool_call|> および <|tool_response>...<tool_response|> として配置されます。
• 履歴における思考プロセスの除外: 過去の Assistant の出力を履歴として再入力する際、Thinking Channel の内容は自動的に除去されます。マルチターンの会話履歴に、過去の思考プロセス自体は残さない仕様です。
• 非 JSON 形式の採用: apply_chat_template(..., tokenize=False) が出力する形式は JSON ではありません。疑似 JSON 風の構造をしていますが、キーはクォーテーションで囲まれず、文字列値は <|"|> で囲まれます。また、型名も STRING や OBJECT のように大文字で表記される独自仕様です。

• enable_thinking=True が設定されている場合。
• tools が定義されている場合。
• 最初のメッセージの Role が system または developer の場合。

• assistant は model に変換されます。
• user は user のまま維持されます。
• system は system のまま維持されます。
• developer は、先頭メッセージの場合は System ブロックに吸収され、それ以外は developer のまま出力される実装です。

<|turn>{role}
{シリアライズされた本文}<turn|>

<|turn>system
You are a helpful assistant.<|tool>declaration:get_current_weather{...}<tool|><turn|>

• user、system、developer の文字列は trim 処理されてそのまま出力されます。
• assistant の文字列は、strip_thinking() を通して処理された後に出力されます。これにより、履歴に生の出力をそのまま戻したとしても、Thinking ブロックは自動的に削除される設計になっています。

• text
• image
• audio
• video

<bos><|turn>system
<|think|>You are a helpful assistant.<turn|>
<|turn>user
What is 2 + 2?<turn|>
<|turn>model

<|turn>model
<|channel>thought
<channel|>

<|tool>declaration:{function_name}{...}<tool|>

• キー名はクォーテーションなしのベア表記。
• 文字列の値は <|"|> で囲む。
• 真偽値は小文字の true / false。
• 型名は STRING、OBJECT、ARRAY のようにすべて大文字。
• 配列は [ ... ]、オブジェクトは { ... } で表現。

• 関数の name と description
• パラメータの type、properties、required
• 各プロパティの description、type、nullable
• String 型のプロパティにおける enum
• 配列アイテムの構造や、任意の response 宣言

<|tool_call>call:{function_name}{arg1:value1,arg2:value2,...}<tool_call|>

• オブジェクトのレスポンス: {temperature:15,weather:<|"|>sunny<|"|>} のような形で出力されます。
• スカラー値のレスポンス: マッピング形式ではない場合、テンプレートが自動的に {value:<|"|>結果<|"|>} のように value: というキーで包んでフォーマットします。

1. tool_calls
2. tool_responses
3. content

<|tool_call>call:f1{...}<tool_call|><|tool_call>call:f2{...}<tool_call|>

• role: 常に assistant
• thinking: 任意の文字列としての思考プロセス
• content: 任意の文字列としての回答テキスト
• tool_calls: 任意の配列としてのツール呼び出しリスト

1. 任意の thought ブロック
2. 任意の content
3. 任意の tool_calls ブロック
4. 任意の末尾 <turn|>

• 生のプロトコルを確認したい場合: skip_special_tokens=False を指定してデコードします。これにより、内部的な特殊トークンの配置を直接確認できます。
• 思考プロセス、回答、ツール呼び出しを構造化して扱いたい場合: processor.parse_response() を活用します。

• 画像: \n\n<|image|>\n\n
• 音声: <|audio|>
• 動画: \n\n<|video|>\n\n

• 画像: 各 <|image|> は、画像ごとの Soft Token 数に応じて、前後の境界トークンに挟まれた複数の <|image|> に置換されます。
• 音声: 各 <|audio|> も同様に、音声の長さに応じて計算された Token 数分の <|audio|> に展開され、境界トークンで挟まれます。現在の Gemma4Processor では音声波形の長さから動的に計算され、基本的には 40ms あたり 1 トークン、上限 750 トークンとして扱われます。
• 動画: 動画はフレームごとのタイムスタンプが付与された形式に展開されます。特徴的なのは、動画であっても境界トークンには画像と同じ <|image> / <image|> が再利用される点です。各フレームのトークン列の前に mm:ss 形式のタイムスタンプが挿入される形になります。

[
  {"type": "image", "url": "..."},
  {"type": "audio", "url": "..."},
  {"type": "text", "text": "What is shown in this image?"}
]

messages = [
  {"role": "user", "content": "Write a haiku about memory."}
]

<bos><|turn>user
Write a haiku about memory.<turn|>
<|turn>model
<|channel>thought
<channel|>

messages = [
  {"role": "system", "content": "You are a concise assistant."},
  {"role": "user", "content": "What is 2 + 2?"},
]

<bos><|turn>system
<|think|>You are a concise assistant.<turn|>
<|turn>user
What is 2 + 2?<turn|>
<|turn>model

<|channel>thought
2+2 を短く計算する。<channel|>4<turn|>

tools = [WEATHER_TOOL]
messages = [
  {"role": "system", "content": "You are a helpful assistant."},
  {"role": "user", "content": "Hey, what's the weather in Tokyo right now?"},
]

<bos><|turn>system
You are a helpful assistant.<|tool>declaration:get_current_weather{description:<|"|>Gets the current weather in a given location.<|"|>,parameters:{properties:{location:{description:<|"|>The city and state, e.g. "San Francisco, CA" or "Tokyo, JP"<|"|>,type:<|"|>STRING<|"|>},unit:{description:<|"|>The unit to return the temperature in.<|"|>,enum:[<|"|>celsius<|"|>,<|"|>fahrenheit<|"|>],type:<|"|>STRING<|"|>} },required:[<|"|>location<|"|>],type:<|"|>OBJECT<|"|>} }<tool|><turn|>
<|turn>user
Hey, what's the weather in Tokyo right now?<turn|>
<|turn>model
<|tool_call>call:get_current_weather{location:<|"|>Tokyo, JP<|"|>}<tool_call|>

{
  "role": "assistant",
  "tool_calls": [
    {"function": {"name": "get_current_weather", "arguments": {"location": "Tokyo, JP"}}}
  ],
  "tool_responses": [
    {"name": "get_current_weather", "response": {"temperature": 15, "weather": "sunny"}}
  ]
}

<|turn>model
<|tool_call>call:get_current_weather{location:<|"|>Tokyo, JP<|"|>}<tool_call|><|tool_response>response:get_current_weather{temperature:15,weather:<|"|>sunny<|"|>}<tool_response|>

<|turn>model
<|tool_call>call:get_current_weather{location:<|"|>Tokyo, JP<|"|>}<tool_call|><|tool_response>response:get_current_weather{temperature:15,weather:<|"|>sunny<|"|>}<tool_response|>The current weather in Tokyo is 15 degrees and sunny.<turn|>

messages = [
  {
    "role": "user",
    "content": [
      {"type": "image", "url": "https://.../cat.jpg"},
      {"type": "text", "text": "What is shown in this image?"},
    ],
  }
]

<bos><|turn>user

<|image|>

What is shown in this image?<turn|>
<|turn>model
<|channel>thought
<channel|>

<bos><|turn>user

<|image><|image|><|image|>...<image|>

What is shown in this image?<turn|>
<|turn>model
<|channel>thought
<channel|>

• プロンプトやデバッグ時は生文字列を確認する: 開発時には、必ず一度 apply_chat_template(..., tokenize=False) の出力を確認してください。モデルに実際にどのような文字列が渡されているかを把握することが、トラブルシューティングの第一歩になります。
• 生の出力を確認する際は特殊トークンをスキップしない: プロトコルレベルのトークンの挙動を確認したい場合は、デコード時に skip_special_tokens=False を指定してください。
• 本番環境での解析には専用メソッドを利用する: 実際のアプリケーションでは、生の出力を自前でパースするのではなく、processor.parse_response() を活用してください。
• ツールの実行はホワイトリスト方式で管理する: モデルが返すツール呼び出しは、あくまで文字列によるリクエストです。関数名や引数のバリデーションを実施してから実行してください。
• 複雑なツールスキーマは手動で定義する: ネストされたオブジェクトやカスタムクラスを含む複雑な関数の場合、自動スキーマ生成に頼るよりも、手動でスキーマを定義する方が安全です。
• マルチモーダル入力の内部展開を意識する: テンプレート上では <|image|> のようなプレースホルダーが 1 つだけ見えている場合でも、内部では多数の Soft Token へと展開されます。このプレースホルダー層と内部展開層の違いを区別して設計してください。

1. [S1] Hugging Face chat_template.jinja: google/gemma-4-31B-it のチャットテンプレート実装です。 https://huggingface.co/google/gemma-4-31B-it/blob/main/chat_template.jinja
2. [S2] Hugging Face tokenizer_config.json: トークナイザ設定およびレスポンススキーマが定義されています。 https://huggingface.co/google/gemma-4-31B-it/blob/main/tokenizer_config.json
3. [S3] Hugging Face Model Card: Gemma 4 (google/gemma-4-31B) の公式モデルカードです。 https://huggingface.co/google/gemma-4-31B
4. [S4] Google AI for Developers: Function calling with Gemma 4 に関する公式ガイドラインです。 https://ai.google.dev/gemma/docs/capabilities/text/function-calling-gemma4
5. [S5] Hugging Face Transformers Docs: Transformers ライブラリにおける gemma4.md ドキュメントです。 https://github.com/huggingface/transformers/blob/main/docs/source/en/model_doc/gemma4.md
6. [S6] Hugging Face Transformers Source: プロセッサの実装ファイルである processing_gemma4.py です。 https://github.com/huggingface/transformers/blob/main/src/transformers/models/gemma4/processing_gemma4.py