Guidance（ガイダンス）
MicrosoftリサーチチームがLLMの生成フローをプログラム的に制御するために開発したPythonライブラリ。テンプレート構文でLLM呼び出しと条件分岐・ループを混在させた「制御可能生成」を実現。
Guidance — Microsoft製LLM制御可能生成ライブラリ
GuidanceはMicrosoft Researchが開発し、2023年にオープンソース公開したPythonライブラリ。従来の「プロンプトを投げてレスポンスを受け取る」モデルを超えて、LLMの生成プロセスそのものをプログラムから細かく制御するアプローチを採用している。
設計哲学: インターリーブ制御
Guidanceの最大の特徴は「テキスト生成とプログラムロジックのインターリーブ（交互実行）」。生成の途中で条件分岐・ループ・外部関数呼び出しを挟み込むことで、複雑な構造化タスクを確実かつ効率的にこなせる:
import guidance
from guidance import models, gen, select
# ローカルLLM使用例
lm = models.LlamaCpp("./llama-3.2-3b.gguf")
# テンプレートによる制御フロー
with lm:
lm += "自作PCのCPU選択:
"
lm += "用途: " + select(["ゲーミング", "クリエイター", "一般事務"]) + "
"
lm += "予算: " + select(["5万円以下", "5〜10万円", "10万円以上"]) + "
"
lm += "推奨CPU: " + gen("cpu_recommendation", max_tokens=50, stop="
")
lm += "
理由: " + gen("reason", max_tokens=200)
print(lm["cpu_recommendation"])
デコレータスタイルAPI
Guidanceは関数デコレータ形式でLLMプログラムを定義できる:
@guidance
def product_analyzer(lm, product_name: str):
lm += f"製品: {product_name}
"
lm += "カテゴリ: " + select(["CPU", "GPU", "メモリ", "SSD", "その他"]) + "
"
lm += "価格帯評価: " + select(["コスパ優秀", "標準", "プレミアム"]) + "
"
lm += "総評: " + gen("review", max_tokens=300) + "
"
return lm
result = product_analyzer(lm, "Ryzen 9 9900X")
select()による制約生成
select()は指定した選択肢から確率的に最適なものをLLMに選ばせる。選択肢以外の出力は物理的に不可能になるため、分類タスクのハルシネーションを完全に排除できる:
# 評価スコア（1〜5）の確実な生成
lm += "評価スコア: " + select(["1", "2", "3", "4", "5"]) + "点
"
# 製品カテゴリの分類
category = select(["電源ユニット", "PCケース", "CPUクーラー", "ケースファン"])
トークンヒーリング
Guidanceは「トークンヒーリング」機能を持つ。通常のLLM生成ではプロンプトの末尾文字がトークン境界と一致しないと性能が落ちることがある。Guidanceはこれを自動補正して正確な継続生成を保証する。
対応モデルバックエンド
models.LlamaCpp: ローカルGGUFモデル（Gemma/Qwen等）models.Transformers: HuggingFaceモデルmodels.OpenAI: OpenAI API（制限付き）models.VertexAI: Google Vertex AI
JSONスキーマ生成
from guidance import json as guidance_json
schema = {
"type": "object",
"properties": {
"name": {"type": "string"},
"score": {"type": "number", "minimum": 0, "maximum": 100}
}
}
with lm:
lm += "評価結果:
" + guidance_json(schema=schema)
result = json.loads(lm["result"])
パフォーマンス最適化
GuidanceはKVキャッシュを最大限活用する設計。select()の候補評価時に共通プレフィックスのKVキャッシュを再利用することで、n個の候補に対するトークン生成コストをO(n)からO(1)+差分に削減できる。
InstructorやXGrammarとの違い
- Guidance: 生成フローそのものを制御。条件分岐・ループが書ける。プログラミング的アプローチ。
- Instructor: Pydantic+リトライ。プロンプトとスキーマの結合が目的。
- XGrammar: 高速トークンマスキング。推論サーバー組み込み向け。
Guidanceは「LLMをサブルーチンとして呼び出す高度な制御フロー」が必要なケース、例えば複数ステップの推論チェーンや動的な質問生成・回答評価ループに特に適している。