ウェブアプリのハイブリッド エクスペリエンスの構造化出力を生成する

Gemini モデルは、デフォルトでレスポンスを非構造化テキストとして返します。ただし、一部のユースケースでは、JSON などの構造化テキストが必要です。たとえば、確立したデータ スキーマを必要とする他のダウンストリーム タスクでレスポンスを使用している場合があります。

モデルの生成済み出力が常に特定のスキーマに準拠するようにするには、スキーマを定義します。これは、モデルのレスポンスのブループリントのように機能します。これにより、後処理をあまり行わずにモデルの出力からデータを直接抽出できます。

次に例を示します。

  • モデルのレスポンスが有効な JSON を生成し、指定されたスキーマに準拠していることを確認します。
    たとえば、モデルはレシピ名、材料リスト、手順を常に含むレシピの構造化されたエントリを生成できます。これにより、アプリの UI でこの情報をより簡単に解析して表示できます。

  • 分類タスク中にモデルが応答する方法を制限します。
    たとえば、モデルが生成するラベル（good、positive、negative、bad など、ある程度のばらつきがある可能性がある）ではなく、特定のラベルセット（positive や negative などの特定の列挙型セットなど）でテキストにアノテーションを付けるようにモデルを設定できます。

このページでは、ウェブアプリのハイブリッド エクスペリエンスで構造化された出力（JSON や列挙型など）を生成する方法について説明します。

始める前に

ハイブリッド エクスペリエンスの構築に関するスタートガイドを完了していることを確認します。

構造化出力の構成を設定する

クラウドホスト型モデルとオンデバイス モデルの両方を使用した推論で、構造化出力（JSON や列挙型など）の生成がサポートされています。

ハイブリッド推論では、inCloudParams と onDeviceParams の両方を使用して、構造化された出力を返すようにモデルを構成します。他のモードでは、該当する構成のみを使用します。

  • inCloudParams の場合: 適切な responseMimeType（application/json など）と、モデルで使用する responseSchema を指定します。

  • onDeviceParams の場合: モデルで使用する responseConstraint を指定します。

JSON 出力

次の例では、ハイブリッド推論（この例では PREFER_ON_DEVICE）に対応するように一般的な JSON 出力の例を調整しています。

例 1: Firebase Schema ヘルパー メソッドを使用する

この例では、Firebase AI Logic SDK で提供されるヘルパー メソッドを使用して、スキーマ定義をよりコンパクトにしています。

import {
  getAI,
  getGenerativeModel,
  Schema
} from "firebase/ai";

// This schema can also be defined as a plain JSON object.
// See next snippet for an example of a plain JSON schema.
const jsonSchema = Schema.object({
 properties: {
    characters: Schema.array({
      items: Schema.object({
        properties: {
          name: Schema.string(),
          accessory: Schema.string(),
          age: Schema.number(),
          species: Schema.string(),
        },
        optionalProperties: ["accessory"],
      }),
    }),
  }
});

const model = getGenerativeModel(ai, {
  mode: InferenceMode.PREFER_ON_DEVICE,
  inCloudParams: {
    generationConfig: {
      model: "gemini-3.1-flash-lite",
      responseMimeType: "application/json",
      responseSchema: jsonSchema
    },
  }
  onDeviceParams: {
    promptOptions: {
      responseConstraint: jsonSchema
    }
  }
});

const result = await model
  .generateContent(
    "Create profiles for some characters for a fantasy story.");

console.log(result.response.text());
console.log(JSON.parse(result.response.text()));

// ...

例 2: プレーンな JSON スキーマを使用する

この例では、JSON のみを使用してスキーマを定義し、同じ結果を返します。

import {
  getAI,
  getGenerativeModel,
  Schema
} from "firebase/ai";

// The JSON schema defined as a plain JSON object.
const jsonSchema = {
    "type": "object",
    "properties": {
        "characters": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "name": {
                        "type": "string",
                        "nullable": false
                    },
                    "accessory": {
                        "type": "string",
                        "nullable": false
                    },
                    "age": {
                        "type": "number",
                        "nullable": false
                    },
                    "species": {
                        "type": "string",
                        "nullable": false
                    }
                },
                "nullable": false,
                "required": [
                    "name",
                    "age",
                    "species"
                ]
            },
            "nullable": false
        }
    },
    "nullable": false,
    "required": [
        "characters"
    ]
};

const model = getGenerativeModel(ai, {
  mode: InferenceMode.PREFER_ON_DEVICE,
  inCloudParams: {
    generationConfig: {
      model: "gemini-3.1-flash-lite",
      responseMimeType: "application/json",
      responseSchema: jsonSchema
    },
  }
  onDeviceParams: {
    promptOptions: {
      responseConstraint: jsonSchema
    }
  }
});

const result = await model
  .generateContent(
    "Create profiles for some characters for a fantasy story.");

console.log(result.response.text());
console.log(JSON.parse(result.response.text()));

列挙型の出力

次の例では、一般的な列挙型出力の例をハイブリッド推論（この例では PREFER_ON_DEVICE）に対応するように変更します。

import {
  getAI,
  getGenerativeModel,
  Schema
} from "firebase/ai";

// enumSchema can also be defined as a plain JSON schema instead of
// using the `Schema` helper methods, just as in the JSON output example.
const enumSchema = Schema.enumString({
  enum: ["drama", "comedy", "documentary"],
});

const model = getGenerativeModel(ai, {
  mode: InferenceMode.PREFER_ON_DEVICE,
  inCloudParams: {
    generationConfig: {
      responseMimeType: "text/x.enum",
      responseSchema: enumSchema
    },
  }
  onDeviceParams: {
    promptOptions: {
      responseConstraint: enumSchema
    }
  }
});

// ...