Gemini API を使用して構造化された出力を生成する


Gemini はデフォルトで非構造化テキストを生成しますが、一部のアプリケーションでは構造化テキストが必要です。このようなユースケースでは、自動処理に適した構造化データ形式である JSON で応答するように Gemini を制約できます。列挙型で指定されたいずれかのオプションで応答するようにモデルを制約することもできます。

モデルからの構造化出力が必要なユースケースをいくつか示します。

  • 新聞記事から企業情報を抽出して、企業のデータベースを構築します。
  • 履歴書から標準化された情報を抽出します。
  • レシピから材料を抽出し、各材料の食料品ウェブサイトへのリンクを表示します。

プロンプトで、Gemini に JSON 形式の出力を生成するよう指示できますが、モデルが JSON のみを出力することは保証されません。より確定的なレスポンスを取得するには、responseSchema フィールドに特定の JSON スキーマを渡して、Gemini が常に想定される構造で応答するようにします。スキーマの操作の詳細については、JSON スキーマの詳細をご覧ください。

このガイドでは、任意の SDK または REST API を直接使用して generateContent メソッドを使用して JSON を生成する方法について説明します。これらの例ではテキストのみの入力を示していますが、Gemini は画像、動画、音声を含むマルチモーダル リクエストに対して JSON レスポンスを生成することもできます。

始める前に: プロジェクトと API キーを設定する

Gemini API を呼び出す前に、プロジェクトを設定して API キーを構成する必要があります。

API キーを取得して保護する

Gemini API を呼び出すには、API キーが必要です。キーがない場合は、Google AI Studio でキーを作成します。

API キーを取得する

API キーをバージョン管理システムにチェックインしないことを強くおすすめします。

API キーは、Google Cloud Secret Manager などのシークレット ストアに保存する必要があります。

このチュートリアルでは、API キーに環境変数としてアクセスすることを前提としています。

SDK パッケージをインストールして API キーを構成する

Gemini API 用の Python SDK は google-generativeai パッケージに含まれています。

  1. pip を使用して依存関係をインストールします。

    pip install -U google-generativeai

  2. パッケージをインポートし、API キーを使用してサービスを構成します。

    import os
import google.generativeai as genai

genai.configure(api_key=os.environ['API_KEY'])

JSONを生成

モデルが JSON を出力するように構成されている場合、モデルは JSON 形式の出力でプロンプトに応答します。

スキーマを指定することで、JSON レスポンスを制御できます。モデルにスキーマを提供する方法は 2 つあります。

  • プロンプトのテキストとして
  • モデル構成で指定された構造化スキーマとして

プロンプトでスキーマをテキストとして指定する

次の例では、特定の JSON 形式でクッキーのレシピを返すようにモデルに指示します。

モデルはプロンプトのテキストから形式仕様を取得するため、仕様の表現方法に柔軟性を持たせることができます。JSON スキーマを表すための適切な形式であれば、どのような形式でも使用できます。

from google import genai

prompt = """List a few popular cookie recipes in JSON format.

Use this JSON schema:

Recipe = {'recipe_name': str, 'ingredients': list[str]}
Return: list[Recipe]"""

client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model='gemini-2.0-flash',
    contents=prompt,
)

# Use the response as a JSON string.
print(response.text)

出力は次のようになります。

[
  {
    "recipe_name": "Chocolate Chip Cookies",
    "ingredients": [
      "2 1/4 cups all-purpose flour",
      "1 teaspoon baking soda",
      "1 teaspoon salt",
      "1 cup (2 sticks) unsalted butter, softened",
      "3/4 cup granulated sugar",
      "3/4 cup packed brown sugar",
      "1 teaspoon vanilla extract",
      "2 large eggs",
      "2 cups chocolate chips"
    ]
  },
  ...
]

モデル構成でスキーマを指定する

次の例では、次のことを行います。

  1. JSON でレスポンスを返すようにスキーマで構成されたモデルをインスタンス化します。
  2. クッキーのレシピを返すようにモデルに指示します。

JSON スキーマを宣言するこのより正式な方法では、プロンプトのテキストに頼るよりも正確に制御できます。

from google import genai
from pydantic import BaseModel


class Recipe(BaseModel):
  recipe_name: str
  ingredients: list[str]


client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model='gemini-2.0-flash',
    contents='List a few popular cookie recipes. Be sure to include the amounts of ingredients.',
    config={
        'response_mime_type': 'application/json',
        'response_schema': list[Recipe],
    },
)
# Use the response as a JSON string.
print(response.text)

# Use instantiated objects.
my_recipes: list[Recipe] = response.parsed

出力は次のようになります。

[
  {
    "recipe_name": "Chocolate Chip Cookies",
    "ingredients": [
      "1 cup (2 sticks) unsalted butter, softened",
      "3/4 cup granulated sugar",
      "3/4 cup packed brown sugar",
      "1 teaspoon vanilla extract",
      "2 large eggs",
      "2 1/4 cups all-purpose flour",
      "1 teaspoon baking soda",
      "1 teaspoon salt",
      "2 cups chocolate chips"
    ]
  },
  ...
]

スキーマ定義の構文

モデル構成の response_schema プロパティで JSON レスポンスのスキーマを指定します。response_schema の値は次のいずれかである必要があります。

型を使用してスキーマを定義する

スキーマを定義する最も簡単な方法は、直接型を使用する方法です。上記の例で使用したアプローチは次のとおりです。

config={'response_mime_type': 'application/json',
        'response_schema': list[Recipe]}

Gemini API Python クライアント ライブラリは、次の型で定義されたスキーマをサポートしています（AllowedType は許可される任意の型です）。

  • int
  • float
  • bool
  • str
  • list[AllowedType]
  • 構造化型の場合:
    • dict[str, AllowedType]。このアノテーションは、すべての辞書値が同じ型であることを宣言しますが、どのキーを含めるかを指定しません。
    • ユーザー定義の Pydantic モデル。この方法では、キー名を指定し、ネストされた構造など、各キーに関連付けられた値の異なる型を定義できます。

列挙型を使用して出力を制限する

場合によっては、モデルにオプションのリストから 1 つのオプションを選択させる必要があります。この動作を実装するには、スキーマで列挙型を渡します。列挙型は文字列のリストであるため、response_schema で str を使用できる場所であれば、列挙型オプションを使用できます。JSON スキーマと同様に、列挙型を使用すると、アプリケーションの要件を満たすようにモデル出力を制限できます。

たとえば、楽器を "Percussion"、"String"、"Woodwind"、"Brass"、"Keyboard" の 5 つのカテゴリのいずれかに分類するアプリを開発しているとします。このタスクを支援するために列挙型を作成できます。

次の例では、列挙型クラス Instrument を response_schema として渡します。モデルは、最も適切な列挙型オプションを選択します。

from google import genai
import enum

class Instrument(enum.Enum):
  PERCUSSION = "Percussion"
  STRING = "String"
  WOODWIND = "Woodwind"
  BRASS = "Brass"
  KEYBOARD = "Keyboard"

client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model='gemini-2.0-flash',
    contents='What type of instrument is an oboe?',
    config={
        'response_mime_type': 'text/x.enum',
        'response_schema': Instrument,
    },
)

print(response.text)
# Woodwind

Python SDK は、API の型宣言を変換します。ただし、API は OpenAPI 3.0 スキーマのサブセット（スキーマ）を受け入れます。スキーマを JSON として渡すこともできます。

from google import genai

client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model='gemini-2.0-flash',
    contents='What type of instrument is an oboe?',
    config={
        'response_mime_type': 'text/x.enum',
        'response_schema': {
            "type": "STRING",
            "enum": ["Percussion", "String", "Woodwind", "Brass", "Keyboard"],
        },
    },
)

print(response.text)
# Woodwind

基本的な多肢選択式の問題以外にも、JSON や関数呼び出しのスキーマの任意の場所で列挙型を使用できます。たとえば、モデルにレシピのタイトルのリストをリクエストし、Grade 列挙型を使用して各タイトルに人気度を割り当てることができます。

from google import genai

import enum
from pydantic import BaseModel

class Grade(enum.Enum):
    A_PLUS = "a+"
    A = "a"
    B = "b"
    C = "c"
    D = "d"
    F = "f"

class Recipe(BaseModel):
  recipe_name: str
  rating: Grade

client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model='gemini-2.0-flash',
    contents='List 10 home-baked cookies and give them grades based on tastiness.',
    config={
        'response_mime_type': 'application/json',
        'response_schema': list[Recipe],
    },
)

print(response.text)
# [{"rating": "a+", "recipe_name": "Classic Chocolate Chip Cookies"}, ...]

JSON スキーマの詳細

JSON レスポンスを返すようにモデルを構成する場合は、Schema オブジェクトを使用して JSON データの形式を定義できます。Schema は、OpenAPI 3.0 スキーマ オブジェクトの一部のサブセットを表します。

すべての Schema フィールドの疑似 JSON 表現を次に示します。

{
  "type": enum (Type),
  "format": string,
  "description": string,
  "nullable": boolean,
  "enum": [
    string
  ],
  "maxItems": string,
  "minItems": string,
  "properties": {
    string: {
      object (Schema)
    },
    ...
  },
  "required": [
    string
  ],
  "propertyOrdering": [
    string
  ],
  "items": {
    object (Schema)
  }
}

スキーマの Type は、OpenAPI のデータ型のいずれかである必要があります。各 Type で有効なのはフィールドのサブセットのみです。次のリストは、各 Type をそのタイプの有効なフィールドにマッピングしています。

  • string -> 列挙型、形式
  • integer -> 形式
  • number -> 形式
  • bool
  • array -> minItems、maxItems、items
  • object -> properties、required、propertyOrdering、nullable

有効な型とフィールドの組み合わせを示すスキーマの例を次に示します。

{ "type": "string", "enum": ["a", "b", "c"] }

{ "type": "string", "format": "date-time" }

{ "type": "integer", "format": "int64" }

{ "type": "number", "format": "double" }

{ "type": "bool" }

{ "type": "array", "minItems": 3, "maxItems": 3, "items": { "type": ... } }

{ "type": "object",
  "properties": {
    "a": { "type": ... },
    "b": { "type": ... },
    "c": { "type": ... }
  },
  "nullable": true,
  "required": ["c"],
  "propertyOrdering": ["c", "b", "a"]
}

Gemini API で使用されるスキーマ フィールドの詳細については、スキーマ リファレンスをご覧ください。

宿泊施設の並べ替え

Gemini API で JSON スキーマを操作する場合、プロパティの順序が重要になります。デフォルトでは、API はプロパティをアルファベット順に並べ替え、プロパティが定義された順序を保持しません（ただし、Google Gen AI SDK ではこの順序が保持される場合があります）。スキーマが構成されたモデルにサンプルを提供するときに、サンプルのプロパティの順序がスキーマのプロパティの順序と一致しない場合、出力が冗長または予期しないものになる可能性があります。

プロパティの順序を一定にして予測できるようにするには、省略可能な propertyOrdering[] フィールドを使用します。

"propertyOrdering": ["recipe_name", "ingredients"]

propertyOrdering[] - OpenAPI 仕様の標準フィールドではありません。レスポンス内のプロパティの順序を決定するために使用される文字列の配列です。プロパティの順序を指定し、その順序でプロパティを含む例を指定すると、結果の品質が向上する可能性があります。