構造化出力

指定された JSON スキーマに準拠したレスポンスを生成するように Gemini モデルを構成できます。この機能により、予測可能で解析可能な結果が保証され、形式と型の安全性が確保され、拒否のプログラムによる検出が可能になり、プロンプトが簡素化されます。

構造化出力の使用は、次のような幅広いアプリケーションに最適です。

  • データ抽出: 請求書から名前、日付、金額を抽出するなど、非構造化テキストから特定の情報を取得します。
  • 構造化された分類: テキストを事前定義されたカテゴリに分類し、構造化されたラベルを割り当てます。たとえば、顧客のフィードバックを感情やトピックで分類します。
  • エージェント ワークフロー: ゲームのキャラクター シートの作成やフォームの入力など、他のツールや API の呼び出しに使用できる構造化データを生成します。

REST API での JSON スキーマのサポートに加えて、Python と JavaScript 用の Google GenAI SDK を使用すると、それぞれ PydanticZod を使用してオブジェクト スキーマを簡単に定義できます。次の例は、コードで定義されたスキーマに準拠する非構造化テキストから情報を抽出する方法を示しています。

この例では、objectarraystringinteger などの基本的な JSON スキーマ型を使用して、テキストから構造化データを抽出する方法を示します。

Python

from google import genai
from pydantic import BaseModel, Field
from typing import List, Optional

class Ingredient(BaseModel):
    name: str = Field(description="Name of the ingredient.")
    quantity: str = Field(description="Quantity of the ingredient, including units.")

class Recipe(BaseModel):
    recipe_name: str = Field(description="The name of the recipe.")
    prep_time_minutes: Optional[int] = Field(description="Optional time in minutes to prepare the recipe.")
    ingredients: List[Ingredient]
    instructions: List[str]

client = genai.Client()

prompt = """
Please extract the recipe from the following text.
The user wants to make delicious chocolate chip cookies.
They need 2 and 1/4 cups of all-purpose flour, 1 teaspoon of baking soda,
1 teaspoon of salt, 1 cup of unsalted butter (softened), 3/4 cup of granulated sugar,
3/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs.
For the best part, they'll need 2 cups of semisweet chocolate chips.
First, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour,
baking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar
until light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry
ingredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons
onto ungreased baking sheets and bake for 9 to 11 minutes.
"""

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents=prompt,
    config={
        "response_mime_type": "application/json",
        "response_json_schema": Recipe.model_json_schema(),
    },
)

recipe = Recipe.model_validate_json(response.text)
print(recipe)

JavaScript

import { GoogleGenAI } from "@google/genai";
import { z } from "zod";
import { zodToJsonSchema } from "zod-to-json-schema";

const ingredientSchema = z.object({
  name: z.string().describe("Name of the ingredient."),
  quantity: z.string().describe("Quantity of the ingredient, including units."),
});

const recipeSchema = z.object({
  recipe_name: z.string().describe("The name of the recipe."),
  prep_time_minutes: z.number().optional().describe("Optional time in minutes to prepare the recipe."),
  ingredients: z.array(ingredientSchema),
  instructions: z.array(z.string()),
});

const ai = new GoogleGenAI({});

const prompt = `
Please extract the recipe from the following text.
The user wants to make delicious chocolate chip cookies.
They need 2 and 1/4 cups of all-purpose flour, 1 teaspoon of baking soda,
1 teaspoon of salt, 1 cup of unsalted butter (softened), 3/4 cup of granulated sugar,
3/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs.
For the best part, they'll need 2 cups of semisweet chocolate chips.
First, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour,
baking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar
until light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry
ingredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons
onto ungreased baking sheets and bake for 9 to 11 minutes.
`;

const response = await ai.models.generateContent({
  model: "gemini-2.5-flash",
  contents: prompt,
  config: {
    responseMimeType: "application/json",
    responseJsonSchema: zodToJsonSchema(recipeSchema),
  },
});

const recipe = recipeSchema.parse(JSON.parse(response.text));
console.log(recipe);

Go

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    prompt := `
  Please extract the recipe from the following text.
  The user wants to make delicious chocolate chip cookies.
  They need 2 and 1/4 cups of all-purpose flour, 1 teaspoon of baking soda,
  1 teaspoon of salt, 1 cup of unsalted butter (softened), 3/4 cup of granulated sugar,
  3/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs.
  For the best part, they'll need 2 cups of semisweet chocolate chips.
  First, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour,
  baking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar
  until light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry
  ingredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons
  onto ungreased baking sheets and bake for 9 to 11 minutes.
  `
    config := &genai.GenerateContentConfig{
        ResponseMIMEType: "application/json",
        ResponseJsonSchema: map[string]any{
            "type": "object",
            "properties": map[string]any{
                "recipe_name": map[string]any{
                    "type":        "string",
                    "description": "The name of the recipe.",
                },
                "prep_time_minutes": map[string]any{
                    "type":        "integer",
                    "description": "Optional time in minutes to prepare the recipe.",
                },
                "ingredients": map[string]any{
                    "type": "array",
                    "items": map[string]any{
                        "type": "object",
                        "properties": map[string]any{
                            "name": map[string]any{
                                "type":        "string",
                                "description": "Name of the ingredient.",
                            },
                            "quantity": map[string]any{
                                "type":        "string",
                                "description": "Quantity of the ingredient, including units.",
                            },
                        },
                        "required": []string{"name", "quantity"},
                    },
                },
                "instructions": map[string]any{
                    "type":  "array",
                    "items": map[string]any{"type": "string"},
                },
            },
            "required": []string{"recipe_name", "ingredients", "instructions"},
        },
    }

    result, err := client.Models.GenerateContent(
        ctx,
        "gemini-2.5-flash",
        genai.Text(prompt),
        config,
    )
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(result.Text())
}

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
          { "text": "Please extract the recipe from the following text.\nThe user wants to make delicious chocolate chip cookies.\nThey need 2 and 1/4 cups of all-purpose flour, 1 teaspoon of baking soda,\n1 teaspoon of salt, 1 cup of unsalted butter (softened), 3/4 cup of granulated sugar,\n3/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs.\nFor the best part, they will need 2 cups of semisweet chocolate chips.\nFirst, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour,\nbaking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar\nuntil light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry\ningredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons\nonto ungreased baking sheets and bake for 9 to 11 minutes." }
        ]
      }],
      "generationConfig": {
        "responseMimeType": "application/json",
        "responseJsonSchema": {
          "type": "object",
          "properties": {
            "recipe_name": {
              "type": "string",
              "description": "The name of the recipe."
            },
            "prep_time_minutes": {
                "type": "integer",
                "description": "Optional time in minutes to prepare the recipe."
            },
            "ingredients": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "name": { "type": "string", "description": "Name of the ingredient."},
                  "quantity": { "type": "string", "description": "Quantity of the ingredient, including units."}
                },
                "required": ["name", "quantity"]
              }
            },
            "instructions": {
              "type": "array",
              "items": { "type": "string" }
            }
          },
          "required": ["recipe_name", "ingredients", "instructions"]
        }
      }
    }'

レスポンスの例:

{
  "recipe_name": "Delicious Chocolate Chip Cookies",
  "ingredients": [
    {
      "name": "all-purpose flour",
      "quantity": "2 and 1/4 cups"
    },
    {
      "name": "baking soda",
      "quantity": "1 teaspoon"
    },
    {
      "name": "salt",
      "quantity": "1 teaspoon"
    },
    {
      "name": "unsalted butter (softened)",
      "quantity": "1 cup"
    },
    {
      "name": "granulated sugar",
      "quantity": "3/4 cup"
    },
    {
      "name": "packed brown sugar",
      "quantity": "3/4 cup"
    },
    {
      "name": "vanilla extract",
      "quantity": "1 teaspoon"
    },
    {
      "name": "large eggs",
      "quantity": "2"
    },
    {
      "name": "semisweet chocolate chips",
      "quantity": "2 cups"
    }
  ],
  "instructions": [
    "Preheat the oven to 375°F (190°C).",
    "In a small bowl, whisk together the flour, baking soda, and salt.",
    "In a large bowl, cream together the butter, granulated sugar, and brown sugar until light and fluffy.",
    "Beat in the vanilla and eggs, one at a time.",
    "Gradually beat in the dry ingredients until just combined.",
    "Stir in the chocolate chips.",
    "Drop by rounded tablespoons onto ungreased baking sheets and bake for 9 to 11 minutes."
  ]
}

ストリーミング

構造化された出力をストリーミングできます。これにより、出力全体が完了するのを待つことなく、レスポンスの生成と同時に処理を開始できます。これにより、アプリケーションのパフォーマンスが向上します。

ストリーミングされたチャンクは有効な部分 JSON 文字列であり、連結して最終的な完全な JSON オブジェクトを形成できます。

Python

from google import genai
from pydantic import BaseModel, Field
from typing import Literal

class Feedback(BaseModel):
    sentiment: Literal["positive", "neutral", "negative"]
    summary: str

client = genai.Client()
prompt = "The new UI is incredibly intuitive and visually appealing. Great job. Add a very long summary to test streaming!"

response_stream = client.models.generate_content_stream(
    model="gemini-2.5-flash",
    contents=prompt,
    config={
        "response_mime_type": "application/json",
        "response_json_schema": Feedback.model_json_schema(),
    },
)

for chunk in response_stream:
    print(chunk.candidates[0].content.parts[0].text)

JavaScript

import { GoogleGenAI } from "@google/genai";
import { z } from "zod";
import { zodToJsonSchema } from "zod-to-json-schema";

const ai = new GoogleGenAI({});
const prompt = "The new UI is incredibly intuitive and visually appealing. Great job! Add a very long summary to test streaming!";

const feedbackSchema = z.object({
  sentiment: z.enum(["positive", "neutral", "negative"]),
  summary: z.string(),
});

const stream = await ai.models.generateContentStream({
  model: "gemini-2.5-flash",
  contents: prompt,
  config: {
    responseMimeType: "application/json",
    responseJsonSchema: zodToJsonSchema(feedbackSchema),
  },
});

for await (const chunk of stream) {
  console.log(chunk.candidates[0].content.parts[0].text)
}

JSON スキーマのサポート

JSON オブジェクトを生成するには、生成構成の response_mime_typeapplication/json に設定し、response_json_schema を指定します。スキーマは、目的の出力形式を記述する有効な JSON スキーマである必要があります。

モデルは、指定されたスキーマに一致する構文的に有効な JSON 文字列であるレスポンスを生成します。構造化された出力を使用する場合、モデルはスキーマ内のキーと同じ順序で出力を生成します。

Gemini の構造化出力モードは、JSON Schema 仕様のサブセットをサポートしています。

次の type 値がサポートされています。

  • string: テキストの場合。
  • number: 浮動小数点数。
  • integer: 整数の場合。
  • boolean: true/false の値。
  • object: Key-Value ペアを含む構造化データの場合。
  • array: 項目のリストの場合。
  • null: プロパティを null にするには、型配列に "null" を含めます(例: {"type": ["string", "null"]})。

これらの説明プロパティは、モデルのガイドに役立ちます。

  • title: プロパティの簡単な説明。
  • description: プロパティの詳細な説明。

型固有のプロパティ

object 値の場合:

  • properties: 各キーがプロパティ名で、各値がそのプロパティのスキーマであるオブジェクト。
  • required: 必須のプロパティを列挙した文字列の配列。
  • additionalProperties: properties にリストされていないプロパティを許可するかどうかを制御します。ブール値またはスキーマを指定できます。

string 値の場合:

  • enum: 分類タスクで使用できる文字列の特定のセットを一覧表示します。
  • format: 文字列の構文(date-timedatetime など)を指定します。

numberinteger の値の場合:

  • enum: 可能性のある数値の特定のセットを一覧表示します。
  • minimum: 最小値(包括的)。
  • maximum: 最大値(包括的)。

array 値の場合:

  • items: 配列内のすべての項目のスキーマを定義します。
  • prefixItems: 最初の N 個の項目のスキーマのリストを定義し、タプルのような構造を許可します。
  • minItems: 配列内のアイテムの最小数。
  • maxItems: 配列内のアイテムの最大数。

モデルサポート

次のモデルは構造化された出力をサポートしています。

モデル 構造化出力
Gemini 2.5 Pro ✔️
Gemini 2.5 Flash ✔️
Gemini 2.5 Flash-Lite ✔️
Gemini 2.0 Flash ✔️*
Gemini 2.0 Flash-Lite ✔️*

* Gemini 2.0 では、JSON 入力内に優先構造を定義するための明示的な propertyOrdering リストが必要です。例については、こちらのクックブックをご覧ください。

構造化出力と関数呼び出し

構造化出力と関数呼び出しはどちらも JSON スキーマを使用しますが、目的は異なります。

機能 主なユースケース
構造化出力 ユーザーへの最終的な回答の書式設定。モデルの回答を特定の形式にする場合(ドキュメントからデータを抽出してデータベースに保存するなど)に使用します。
関数呼び出し 会話中にアクションを実行する。モデルがタスクの実行をユーザーに依頼する必要がある場合(たとえば、「現在の天気を取得」)を呼び出す必要があります。

ベスト プラクティス

  • 明確な説明: スキーマの description フィールドを使用して、各プロパティが何を表しているかについて、モデルに明確な指示を提供します。これは、モデルの出力を導くために重要です。
  • 強い型付け: 可能な限り、特定の型(integerstringenum)を使用します。パラメータの有効な値のセットが限られている場合は、enum を使用します。
  • プロンプト エンジニアリング: モデルに何をしてほしいかをプロンプトで明確に指定します。たとえば、「テキストから次の情報を抽出してください」や「提供されたスキーマに従ってこのフィードバックを分類してください」などです。
  • 検証: 構造化された出力では、構文的に正しい JSON が保証されますが、値が意味的に正しいことは保証されません。最終的な出力は、使用する前に必ずアプリケーション コードで検証してください。
  • エラー処理: アプリケーションに堅牢なエラー処理を実装して、モデルの出力がスキーマに準拠していてもビジネス ロジックの要件を満たしていない場合を適切に処理します。

制限事項

  • スキーマのサブセット: JSON スキーマ仕様のすべての機能がサポートされているわけではありません。モデルはサポートされていないプロパティを無視します。
  • スキーマの複雑さ: API は、非常に大きいスキーマや深くネストされたスキーマを拒否することがあります。エラーが発生した場合は、プロパティ名を短くしたり、ネストを減らしたり、制約の数を制限したりして、スキーマを簡素化してみてください。