カスタムチャットテンプレートを使用する場面
次のような場合は、Chat Completions API の代わりに、カスタムチャットテンプレートと Completions API を使用してください。- プロンプト構造を完全に制御する必要がある場合。 ワークフローによっては、Chat Completions API のパラメータでは指定できないカスタム変数、特殊トークン、指示を挿入する必要があります。カスタマイズを行わない SambaCloud の標準モデルには、組み込みの Function calling (関数呼び出し) を備えた Chat Completions API の使用を推奨します。詳細は Function calling と JSON モード をご参照ください。
- BYOC (Bring Your Own Checkpoint) モデルを使用している場合。 SambaStack にデプロイされたファインチューニング済みのチェックポイントは、ベースモデルとは異なるチャットテンプレートを使用していることがあります。サーバー側でベースモデルのデフォルトテンプレートを適用させると、これらのチェックポイントに対して不正なプロンプトが生成されます。
- モデルが非標準のツール呼び出し出力形式を使用している場合。 ファインチューニングされたモデルは、デフォルトのパーサーでは処理できない形式 (たとえば JSON ではなく XML マーカー) でツール呼び出しを出力することがあります。
仕組み
/v1/chat/completions を呼び出す代わりに、プロンプト文字列を自身でレンダリングし、/v1/completions に直接送信します。サーバーは生の文字列を受け取り、テンプレートを一切適用せずに、そこから続きを生成します。
このワークフローは次の 4 つのステップで構成されます。
- チャットテンプレートの読み込み。 Hugging Face のトークナイザーから Jinja テンプレートを取得するか、カスタムテンプレートを作成します。
- プロンプトのレンダリング。 テンプレートをメッセージとツール定義に適用し、生のプロンプト文字列を生成します。
- Completions API の呼び出し。 レンダリングした文字列を
/v1/completionsに送信します。 - 出力のパース。 生のテキスト応答を、ツール呼び出しを含む構造化された assistant メッセージに変換します。
チャットテンプレートの読み込み
Hugging Face モデルからの読み込み
transformers ライブラリを使用してベースモデルのトークナイザーを読み込み、組み込みのチャットテンプレートを抽出します。
カスタム Jinja テンプレートの定義
チェックポイントがベースモデルと異なるテンプレートを使用している場合は、Jinja2 テンプレートを直接記述します。テンプレートは、少なくともmessages、tools、add_generation_prompt の各変数を処理できる必要があります。
プロンプトのレンダリング
Jinja2 を使用して、テンプレートをメッセージとツール定義に適用します。トークナイザーから読み込んだテンプレートを使用する場合は、bos_token や eos_token などのトークナイザー属性をコンテキスト変数として渡します。カスタムテンプレートの場合は、これらの値を明示的に指定してください。
Completions API の呼び出し
レンダリングしたプロンプト文字列を/v1/completions エンドポイントに送信します。このエンドポイントは生の文字列を受け取り、生の文字列を返します。サーバー側でテンプレートは適用されません。
モデル出力のパース
生のテキスト応答は、構造化された assistant メッセージにパースする必要があります。適切なパーサーは、モデルが出力するツール呼び出しの形式によって異なります。JSON 形式 (Llama 系)
Llama の instruction チューニング済みモデルは、応答テキスト内に JSON オブジェクトとしてツール呼び出しを出力します。XML 形式 (DeepSeek 系)
DeepSeek モデルは、XML マーカーでツール呼び出しを区切ります。assistant メッセージの構築
ツール呼び出しを抽出したら、OpenAI 互換形式で最終的な assistant メッセージを組み立てます。カスタムパーサー
モデルがデフォルト以外の形式でツール呼び出しを出力する場合は、カスタムパーサーを実装してください。パーサーは、生の応答文字列を受け取り、OpenAI 互換形式のツール呼び出し dict のリストを返す必要があります。注: カスタムパーサーはユーザーが用意したコードを実行します。信頼できるコードのみを実行してください。これはサンドボックス化された実行環境ではありません。
次のステップ
- エンドツーエンドの完全なワークフロー、インタラクティブな Streamlit アプリ、Jupyter ノートブックについては、Custom Chat Templates AI スターターキット をご覧ください。
- カスタムテンプレートを使用しない標準的な Function calling については、Function calling と JSON モード をご参照ください。

