guidance ライブラリ徹底解説：LLMの挙動を自在に操る新時代のプロンプトエンジニアリング 🚀

近年、ChatGPTをはじめとする大規模言語モデル（LLM）の進化は目覚ましく、様々な分野での応用が期待されています。しかし、LLMはその性質上、常に期待通りの出力をするとは限りません。プロンプトエンジニアリングによってある程度の制御は可能ですが、より複雑なタスクや厳密な出力形式が求められる場合、限界が生じることがありました。

そこで登場したのが、Microsoft Researchが開発したPythonライブラリ guidance です。guidanceは、LLMのプロンプトと制御ロジックをシームレスに統合し、まるでプログラミング言語のようにLLMの挙動を細かく制御できる画期的なフレームワークです。従来のプロンプトやチェイニング（複数のプロンプトを連鎖させる手法）よりも効率的かつ効果的にLLMを制御できると注目を集めています。

この記事では、guidanceライブラリの基本的な考え方から主要な機能、具体的な使い方、そしてその利点と注意点まで、網羅的に解説します。guidanceを使いこなすことで、あなたのLLMアプリケーション開発は新たな次元へと進化するでしょう！ ✨

インストール

guidanceのインストールは非常に簡単です。pipコマンドを使ってインストールできます。

pip install guidance

依存関係によっては追加のライブラリが必要になる場合がありますが、基本的な利用はこのコマンドで開始できます。

基本的な考え方：Guidanceプログラム

guidanceの中核となるのは「Guidanceプログラム」という概念です。これは、PythonのコードとLLMへの指示（プロンプトテキストや生成コマンド）を組み合わせたものです。F-stringのような構文を使い、テキスト生成、選択、条件分岐、ループなどをプログラム内に記述できます。

従来のプロンプトエンジニアリングでは、プロンプトは単なるテキスト文字列でしたが、guidanceではプロンプト自体が実行可能なプログラムとなります。これにより、LLMの生成プロセス中にPythonのロジックを介入させ、より動的で精密な制御が可能になります。

Guidanceプログラムは、モデルオブジェクト（LLMへのインターフェース）に対してテキストやguidanceの関数を追加していく形で構築されます。実行すると、guidanceがLLMとのやり取りを管理し、指定された制御に従ってテキストを生成します。

簡単なコード例：Hello, guidance!

まずは、guidanceを使って簡単なテキスト生成を行ってみましょう。ここではOpenAIのモデルを使う例を示します（他のモデルも利用可能です）。

import guidance

# OpenAIモデルをロード（APIキーの設定が必要）
# guidance.llm = guidance.llms.OpenAI("text-davinci-003")
# または、ローカルモデルを使う場合 (例: LlamaCpp)
# guidance.llm = guidance.models.LlamaCpp("/path/to/your/model.gguf")

# Guidanceプログラムを定義
program = guidance(
'''こんにちは！ guidanceライブラリを使って、{{topic}} について短い説明文を生成してください。
{{gen 'explanation' max_tokens=50}}'''
)

# プログラムを実行し、変数を渡す
executed_program = program(topic="プロンプトエンジニアリング")

# 生成されたテキストを表示
print(executed_program['explanation'])

この例では、guidance(...) でプログラムテンプレートを作成し、{{topic}} という変数と {{gen 'explanation' max_tokens=50}} という生成コマンドを含めています。program(topic="...") で変数を渡し、プログラムを実行します。{{gen ...}} の部分でLLMによるテキスト生成が行われ、その結果が executed_program['explanation'] に格納されます。

実行結果は、guidance がテンプレートの {{gen ...}} 部分をLLMの生成結果で置き換えた形になります。Jupyter Notebookなどで実行すると、生成された部分が色付きで表示され、どの部分が生成されたか分かりやすくなっています。

guidanceの真価は、その豊富な制御構文にあります。これらを組み合わせることで、複雑なLLMの振る舞いをデザインできます。

program = guidance(
'''Q: 宇宙について面白い事実を教えてください。
A: {{gen 'fact' temperature=0.7 max_tokens=100}}'''
            )
executed_program = program()
print(executed_program['fact'])

program = guidance(
'''この文章の感情はポジティブですか、ネガティブですか、それともニュートラルですか？
文章: {{text}}
感情: {{select 'sentiment' options=['ポジティブ', 'ネガティブ', 'ニュートラル']}}'''
            )
executed_program = program(text="今日は素晴らしい天気だ！")
print(executed_program['sentiment']) # 出力例: ポジティブ

program = guidance(
'''ユーザーのリクエスト: {{request}}
{{#if use_expert_mode}}
専門家モードで回答します: {{gen 'expert_answer'}}
{{else}}
通常モードで回答します: {{gen 'normal_answer'}}
{{/if}}'''
            )
# 専門家モードを有効にして実行
executed_program_expert = program(request="量子力学について", use_expert_mode=True)
# 通常モードで実行
executed_program_normal = program(request="今日の天気", use_expert_mode=False)

program = guidance(
'''以下の各項目について短い説明を生成してください:
{{#each items}}- {{this}}: {{gen 'description' max_tokens=30}}
{{/each}}'''
            )
executed_program = program(items=["リンゴ", "バナナ", "オレンジ"])
# 出力例:
# - リンゴ: 赤または緑色の果物で、シャキシャキとした食感が特徴です。
# - バナナ: 黄色い皮を持つ細長い果物で、甘くて柔らかいです。
# - オレンジ: 丸い柑橘系の果物で、ビタミンCが豊富です。

program = guidance(
'''まず、物語の主人公の名前を生成します。
主人公の名前: {{gen 'character_name' stop='\\n'}}
{{set 'name_length' value=len(character_name)}}
生成された名前「{{character_name}}」は {{name_length}} 文字です。
この主人公が登場する短い物語を書いてください:
{{gen 'story' max_tokens=100}}'''
            )
executed_program = program()
print(f"主人公: {executed_program['character_name']}")
print(f"名前の長さ: {executed_program['name_length']}")
print(f"物語: {executed_program['story']}")

import datetime

# 非同期で現在時刻を取得する関数 (例)
async def get_current_time():
    return datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S")

program = guidance(
'''現在の時刻を調べます。
{{await 'current_time' get_current_time()}}
現在時刻は {{current_time}} です。
この時刻に基づいて、ユーザーへの挨拶を生成してください:
{{gen 'greeting'}}'''
)

# guidanceプログラムは非同期実行に対応
import asyncio
executed_program = asyncio.run(program())
print(executed_program['greeting'])

program = guidance(
'''{{#system}}あなたは親切なAIアシスタントです。{{/system}}

{{#user}}日本の首都はどこですか？{{/user}}

{{#assistant}}{{gen 'answer'}}{{/assistant}}

{{#user}}そこでおすすめの観光地を3つ教えてください。{{/user}}

{{#assistant}}{{gen 'recommendations' max_tokens=100}}{{/assistant}}'''
            )
executed_program = program()
print(f"回答1: {executed_program['answer']}")
print(f"おすすめ: {executed_program['recommendations']}")

高度な制約：正規表現とJSONスキーマ

guidanceの強力な機能の一つが、生成されるテキストの形式を厳密に制約できる点です。

• 正規表現 (Regex): gen コマンドに regex=r"..." パラメータを指定することで、生成されるテキストが特定の正規表現パターンに一致するように強制できます。これは、電話番号、メールアドレス、特定のIDフォーマットなどを生成させたい場合に役立ちます。
• JSONスキーマ: gen コマンドで json_schema=... を指定すると、生成されるテキストが指定されたJSONスキーマに準拠した有効なJSONオブジェクトであることを保証します。これは、構造化データをLLMに生成させる際に非常に強力です。

# JSONスキーマを使った例
import json

character_schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string"},
        "class": {"type": "string", "enum": ["Warrior", "Mage", "Rogue"]},
        "level": {"type": "integer", "minimum": 1, "maximum": 99},
        "hp": {"type": "integer"}
    },
    "required": ["name", "class", "level", "hp"]
}

program = guidance(
'''RPGキャラクターのプロフィールをJSON形式で生成してください。
```json
{{gen 'character_json' json_schema=character_schema temperature=0}}
```'''
)

executed_program = program()
try:
    # 生成されたJSONをパース
    character_data = json.loads(executed_program['character_json'])
    print(json.dumps(character_data, indent=2, ensure_ascii=False))
except json.JSONDecodeError:
    print("生成された出力は有効なJSONではありませんでした。")
    print(executed_program['character_json'])

guidanceは、トークンレベルでの制御（マスキングやバイアス調整）を行うことで、これらの制約を効率的に実現します。これにより、無効な形式の出力を生成してしまい、後処理で修正したり再生成したりするコストを削減できます。

• 🤖 高度なチャットボット開発:

  role タグを使って対話の流れを管理し、if や await を使ってユーザーの発言内容に応じた条件分岐や外部API連携（天気情報取得、データベース検索など）を組み込むことで、単なる応答生成を超えたインテリジェントなチャットボットを構築できます。会話履歴もguidanceプログラム内で自然に扱えます。

• 📄 構造化データの抽出:

  非構造化テキスト（メール、レポート、記事など）から特定の情報を抽出し、JSON形式で出力させることが容易になります。JSONスキーマ制約を使えば、抽出結果が必ず定義したフォーマットに従うことを保証できます。これにより、後続のシステムでのデータ処理が格段に楽になります。

  # 請求書テキストから情報を抽出しJSONにする例
  invoice_text = """
  請求書番号: INV-00123
  発行日: 2025年4月1日
  支払期日: 2025年4月30日
  請求元: 株式会社サンプルテック
  請求先: ABC株式会社 御中
  商品: 製品X, 数量: 2, 単価: 10000
  商品: 製品Y, 数量: 1, 単価: 5000
  合計金額: 25000円 (税抜)
  """
  
  extraction_schema = {
      "type": "object",
      "properties": {
          "invoice_number": {"type": "string"},
          "issue_date": {"type": "string", "format": "date"},
          "due_date": {"type": "string", "format": "date"},
          "biller_name": {"type": "string"},
          "client_name": {"type": "string"},
          "total_amount": {"type": "integer"}
      },
      "required": ["invoice_number", "issue_date", "due_date", "biller_name", "client_name", "total_amount"]
  }
  
  program = guidance(
  '''以下の請求書テキストから指定された情報を抽出し、JSON形式で出力してください。
  テキスト:
  {{invoice_text}}
  
  抽出結果:
  ```json
  {{gen 'extracted_data' json_schema=extraction_schema temperature=0}}
  ```'''
  )
  
  executed_program = program(invoice_text=invoice_text)
  print(executed_program['extracted_data'])
  

• 📝 多様な出力形式の生成:

  select や正規表現制約、ループ構文 (each) などを組み合わせることで、箇条書きリスト、表形式のテキスト、特定のフォーマットに従ったコードスニペットなど、様々な形式のテキストを確実に生成させることができます。

• 🤔 思考連鎖 (Chain-of-Thought) の実装:

  複雑な問題解決プロセスをLLMに段階的に実行させ、その思考プロセス（中間的な推論）も出力させることができます。gen や set を使って中間結果を保持し、if で条件分岐させることで、より信頼性の高い推論を実現できます。

• 🔧 外部ツールとの連携 (エージェント):

  await を活用して、LLMが判断したタイミングで外部の計算ツール（電卓、コード実行環境）、情報検索API、データベースなどを呼び出すエージェントを構築できます。LLMは思考や計画を行い、実際の計算や情報取得は外部ツールに任せる、といった分業が可能になります。

LLMアプリケーション開発フレームワークとしては、LangChain も非常に有名です。guidanceとLangChainは目的が一部重なりますが、アプローチに違いがあります。

また、構造化出力に特化した Outlines や、OpenAIのFunction Callingを使いやすくする Instructor といったライブラリも存在します。guidanceはこれらの機能を取り込みつつ、より汎用的な制御フレームワークを目指していると言えるでしょう。

Microsoftが開発した guidance ライブラリは、LLMの制御を新たなレベルに引き上げる可能性を秘めた、非常に強力で革新的なツールです。プロンプトと制御ロジックをシームレスに統合し、PythonコードのようにLLMの挙動を記述できるため、開発者はより意図した通りにLLMを動作させることができます。

特に、出力形式の厳密な制御、条件に応じた動的なプロンプト生成、外部ツールとの連携といった点で、従来のプロンプトエンジニアリングや単純なAPIコールでは難しかった高度なタスクを実現可能にします。

学習コストや一部モデルでの機能制限といった注意点もありますが、そのメリットは非常に大きく、LLMアプリケーション開発の効率と品質を大幅に向上させることが期待できます。今後のLLM開発において、guidanceのような制御フレームワークはますます重要な役割を担っていくでしょう。

ぜひ、guidanceを試してみて、そのパワーを体験してください！ 🚀

学習リソース

さらに詳しく学びたい方は、以下の公式リソースを参照することをお勧めします。

• GitHubリポジトリ: https://github.com/guidance-ai/guidance (最新情報、Issue、コントリビューション)
• 公式ドキュメント: https://guidance.readthedocs.io/en/latest/ (チュートリアル、APIリファレンス、使用例)