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 キーにグローバル定数としてアクセスすることを前提としています。

JSONを生成

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

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

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

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

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

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

// Make sure to include these imports:
// import { GoogleGenerativeAI } from "@google/generative-ai";
const genAI = new GoogleGenerativeAI(process.env.API_KEY);

const model = genAI.getGenerativeModel({
  model: "gemini-1.5-flash",
});

const prompt = `List a few popular cookie recipes using this JSON schema:

Recipe = {'recipeName': string}
Return: Array<Recipe>`;

const result = await model.generateContent(prompt);
console.log(result.response.text());
controlled_generation.js

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

[{"recipeName": "Chocolate Chip Cookies"}, {"recipeName": "Oatmeal Raisin Cookies"}, {"recipeName": "Snickerdoodles"}, {"recipeName": "Sugar Cookies"}, {"recipeName": "Peanut Butter Cookies"}]

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

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

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

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

// Make sure to include these imports:
// import { GoogleGenerativeAI, SchemaType } from "@google/generative-ai";
const genAI = new GoogleGenerativeAI(process.env.API_KEY);

const schema = {
  description: "List of recipes",
  type: SchemaType.ARRAY,
  items: {
    type: SchemaType.OBJECT,
    properties: {
      recipeName: {
        type: SchemaType.STRING,
        description: "Name of the recipe",
        nullable: false,
      },
    },
    required: ["recipeName"],
  },
};

const model = genAI.getGenerativeModel({
  model: "gemini-1.5-pro",
  generationConfig: {
    responseMimeType: "application/json",
    responseSchema: schema,
  },
});

const result = await model.generateContent(
  "List a few popular cookie recipes.",
);
console.log(result.response.text());
controlled_generation.js

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

[{"recipeName": "Chocolate Chip Cookies"}, {"recipeName": "Oatmeal Raisin Cookies"}, {"recipeName": "Snickerdoodles"}, {"recipeName": "Sugar Cookies"}, {"recipeName": "Peanut Butter 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 -> 形式
  • boolean
  • 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": "boolean" }

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