プロンプト変数（プロンプトヘンスウ）
プロンプトテンプレート内に定義されるプレースホルダー。実行時に具体的な値（ユーザー入力・検索結果・設定値等）に置換され、動的なプロンプト生成を可能にする。
プロンプト変数とは
プロンプト変数（Prompt Variable）とは、プロンプトテンプレート内に配置されるプレースホルダー（占位子）です。{variable_name} や {{variable_name}} の形式で記述され、プロンプトの実行時に具体的な値に置換されます。プログラミング言語における変数と同じ概念をプロンプトエンジニアリングに適用したものです。
変数の種類
プロンプト変数は用途によって以下のカテゴリに分類されます。
| 種類 | 説明 | 例 |
|---|---|---|
| 入力変数 | ユーザーからの直接入力 | {user_query}, {question} |
| コンテキスト変数 | RAG検索結果や外部データ | {context}, {search_results} |
| 設定変数 | 出力言語やフォーマット指定 | {language}, {output_format} |
| メタ変数 | 日時・セッションID等のシステム値 | {current_date}, {session_id} |
| 例示変数 | Few-shotの入出力ペア | {example_input}, {example_output} |
変数記法の比較
フレームワークやテンプレートエンジンによって変数の記法が異なります。
| 記法 | フレームワーク | 例 |
|---|---|---|
{var} | LangChain PromptTemplate | {user_query} |
{{var}} | Jinja2, Mustache | {{user_query}} |
${var} | シェル風、一部カスタム実装 | ${user_query} |
{{{var}}} | Handlebars (HTMLエスケープなし) | {{{raw_html}}} |
<<var>> | Semantic Kernel | <<user_query>> |
LangChain では Python の f-string と衝突するため、テンプレート内の波括弧リテラルは {{ でエスケープします（例：JSON出力指定時の {{"key": "value"}} ）。
変数のバリデーション
必須変数チェック
テンプレート展開前に全必須変数が提供されているか検証します。未定義変数があればテンプレートエンジンがエラーを発生させ、不完全なプロンプトがLLMに送信されることを防ぎます。
型バリデーション
変数の値が期待する型・フォーマットに合致しているか検証します。日付変数が日付形式か、数値変数が数値範囲内か、文字列変数が最大長を超えていないか等をチェックします。
サニタイズ
ユーザー入力を含む変数は、プロンプトインジェクション対策としてサニタイズ処理を適用します。特殊文字のエスケープ、HTMLタグの除去、文字数制限の適用などが含まれます。
変数の高度な利用パターン
条件分岐
Jinja2 テンプレートでは変数の値に応じて条件分岐が可能です。ユーザーの言語設定に応じてプロンプトの言語を切り替える、データの有無によってセクションを表示/非表示にするなどのロジックをテンプレート内に記述できます。
ループ展開
複数の検索結果やFew-shot例をループで展開する場合に使用します。RAGパイプラインでは取得したドキュメントチャンクを {% for doc in documents %} で反復展開し、コンテキストウィンドウに収まる分だけ挿入します。
デフォルト値
変数が未定義の場合のフォールバック値を設定します。{language|日本語} や Jinja2 の {{ var | default("fallback") }} 構文で実現します。オプショナルなパラメータの柔軟な管理に有効です。
パイプライン変数
前段のLLM呼び出し結果を後段のテンプレート変数として渡すパターンです。プロンプトチェーンでは、ステップ1の出力 {step1_result} がステップ2のテンプレートに自動注入されます。
変数管理のベストプラクティス
変数のドキュメント化は必須です。各変数の名前・型・説明・必須/任意・デフォルト値・サンプル値を一覧化し、テンプレートファイルと同じリポジトリで管理します。
変数名は一貫した命名規則（snake_case 推奨）で統一し、省略形を避けます。q ではなく user_query、ctx ではなく retrieved_context のように意図が明確な名前を使用します。
FAQ
Q1: プロンプト変数の数に上限はありますか？
A1: 技術的な上限はありませんが、10個以上の変数を持つテンプレートは複雑すぎるサインです。変数が多い場合はテンプレートを分割するか、構造化データ（JSON）を1つの変数で渡すことを検討してください。
Q2: 変数名に日本語は使えますか？
A2: 技術的には可能ですが、非推奨です。エンコーディング問題や開発ツールとの互換性の観点から、変数名は ASCII 英数字と _ のみで構成する snake_case が安全です。
Q3: 変数の値が長すぎてトークン制限を超える場合は？
A3: コンテキストウィンドウの上限を考慮して、変数値のトランケーション（切り詰め）処理を実装します。RAGのコンテキスト変数なら、挿入するチャンク数を動的に調整してトークン予算内に収めるのが標準的なアプローチです。