はじめに

この記事では、Google製生成AI「Gemini」の新機能「response_schema」を使って、JSONデータを直接取得し、Pydanticで型安全に扱う方法を紹介します。

環境準備

本記事のコードはGoogle Colabで実行することを想定しています。まず必要なライブラリをインストールしましょう。

!pip install -q google-generativeai pydantic

実装の流れ

APIキーの設定とクライアント初期化
Pydanticによるスキーマ定義
プロンプト作成と構造化出力の指定
レスポンス取得と構造化データの利用

コード全体

まずは全体のコードを見てみましょう：

from google import genai
from pydantic import BaseModel
from typing import List
from google.colab import userdata

# Geminiクライアント初期化
client = genai.Client(api_key=userdata.get('GEMINI_API_KEY'))

# スキーマ定義：スパイス調合
class Spice(BaseModel):
    name: str
    amount: str
    purpose: str

class CurrySpiceMix(BaseModel):
    recipe_name: str
    spices: List[Spice]


# プロンプト
prompt = (
    "インド風カレーのスパイス調合を提案してください。"
    "スパイスの名前、量、目的を含め、レシピ名とともにJSONで返してください。"
)

# コンテンツ生成リクエスト
response = client.models.generate_content(
    model="gemini-2.0-flash",
    contents=prompt,
    config={
        "response_mime_type": "application/json",
        "response_schema": CurrySpiceMix,
    },
)

# 生テキスト表示（JSON文字列）
print("=== JSON出力 ===")
print(response.text)

# オブジェクトとして利用可能（Pydanticモデル化）
parsed: CurrySpiceMix = response.parsed
print("\n=== 構造化出力 ===")
print(f"レシピ名: {parsed.recipe_name}")
for spice in parsed.spices:
    print(f"- {spice.name}: {spice.amount}（{spice.purpose}）")

コードの詳細解説

1. APIキーとクライアント初期化

from google import genai
from google.colab import userdata

# Geminiクライアント初期化
client = genai.Client(api_key=userdata.get('GEMINI_API_KEY'))

Colabの環境変数に保存されたAPIキーを使ってGeminiのクライアントを初期化しています。

2. Pydanticによるスキーマ定義

from pydantic import BaseModel
from typing import List

# スキーマ定義：スパイス調合
class Spice(BaseModel):
    name: str
    amount: str
    purpose: str

class CurrySpiceMix(BaseModel):
    recipe_name: str
    spices: List[Spice]

Pydanticを使って、APIから取得したいデータの型定義を行っています。この定義によって：

Spiceクラス：各スパイスの「名前」「量」「目的」の3つのプロパティを持つ
CurrySpiceMixクラス：「レシピ名」と「スパイスのリスト」の2つのプロパティを持つ

この型定義により、取得するデータに対して静的型チェックが可能になります。

3. プロンプトと構造化出力の指定

# プロンプト
prompt = (
    "インド風カレーのスパイス調合を提案してください。"
    "スパイスの名前、量、目的を含め、レシピ名とともにJSONで返してください。"
)

# コンテンツ生成リクエスト
response = client.models.generate_content(
    model="gemini-2.0-flash",
    contents=prompt,
    config={
        "response_mime_type": "application/json",
        "response_schema": CurrySpiceMix,
    },
)

ここがこの実装の最も重要なポイントです：

response_mime_type: レスポンスの形式をJSONに指定
response_schema: 先ほど定義したPydanticクラスを指定

これにより、Gemini APIは指定されたスキーマに従ったJSONを生成してくれます。

4. レスポンスの利用

# 生テキスト表示（JSON文字列）
print("=== JSON出力 ===")
print(response.text)

# オブジェクトとして利用可能（Pydanticモデル化）
parsed: CurrySpiceMix = response.parsed
print("\n=== 構造化出力 ===")
print(f"レシピ名: {parsed.recipe_name}")
for spice in parsed.spices:
    print(f"- {spice.name}: {spice.amount}（{spice.purpose}）")

レスポンスは2つの形式で利用できます：

response.text：生のJSON文字列
response.parsed：Pydanticモデルにパース済みのオブジェクト

.parsedプロパティを使うことで、すでにPydanticモデルとしてパースされたオブジェクトにアクセスできるため、追加のパース処理は不要です。

実行結果例

=== JSON出力 ===
{
  "recipe_name": "本格インド風チキンカレー",
  "spices": [
    {
      "name": "ターメリック",
      "amount": "大さじ2",
      "purpose": "色付け、抗炎症作用"
    },
    {
      "name": "コリアンダー",
      "amount": "大さじ3",
      "purpose": "香り、とろみ"
    },
    {
      "name": "クミン",
      "amount": "大さじ2",
      "purpose": "香り、消化促進"
    },
    {
      "name": "レッドチリパウダー",
      "amount": "小さじ1-2 (お好みで調整)",
      "purpose": "辛味"
    },
    {
      "name": "ガラムマサラ",
      "amount": "小さじ2",
      "purpose": "仕上げの香り"
    },
    {
      "name": "ジンジャーパウダー",
      "amount": "小さじ1",
      "purpose": "風味、消化促進"
    },
    {
      "name": "ガーリックパウダー",
      "amount": "小さじ1",
      "purpose": "風味"
    }
  ]
}

=== 構造化出力 ===
レシピ名: 本格インド風チキンカレー
- ターメリック: 大さじ2（色付け、抗炎症作用）
- コリアンダー: 大さじ3（香り、とろみ）
- クミン: 大さじ2（香り、消化促進）
- レッドチリパウダー: 小さじ1-2 (お好みで調整)（辛味）
- ガラムマサラ: 小さじ2（仕上げの香り）
- ジンジャーパウダー: 小さじ1（風味、消化促進）
- ガーリックパウダー: 小さじ1（風味）

この実装のメリット

Pydanticを使うことで、データの型安全性が確保され、手動でJSONを解析する必要がなくなります。スキーマに合わないデータがあった場合には、明確なエラーメッセージが表示されるため、エラー処理も容易です。また、構造化されたオブジェクトに対してIDEの補完が効くため、開発効率が向上します。さらに、Pydanticの自動バリデーション機能により、入力データの整合性を確実に保つことができます。

活用例

この実装パターンは以下のようなケースで特に有効です：

チャットボットから構造化データを取得したい場合
生成AIによるデータエントリーの自動化
既存のデータモデルとの連携
複雑なJSON構造のハンドリング

注意点

モデルによってはスキーマ通りの出力を生成できない場合があります
複雑すぎるスキーマは失敗しやすいため、シンプルな構造を心がけましょう
APIキーの管理には十分注意してください

まとめ

Google GeminiのAPI + Pydanticによる構造化データ取得は、生成AIを実践的なアプリケーション開発に組み込む際の強力なパターンです。特に、生成AIの出力を他のシステムと連携させる場合に非常に有効です。

是非、みなさんも自分のユースケースに合わせて試してみてください！

参考リンク