使用 Gemini API 產生結構化輸出內容 (例如 JSON)

Gemini API 預設會以非結構化文字格式傳回回應。不過，某些用途需要結構化文字，例如 JSON。例如，您可能會將回應用於其他需要已建立資料結構定義的下游工作。

為確保模型產生的輸出內容一律遵循特定結構定義，您可以定義回覆結構定義，這類似於模型回覆的藍圖。接著，您可以直接從模型輸出內容中擷取資料，減少後置處理作業。

例如：

確保模型回應會產生有效的 JSON，並符合您提供的結構定義。
舉例來說，模型可以為食譜產生結構化項目，這些項目一律包含食譜名稱、食材清單和步驟。這樣一來，您就能更輕鬆地在應用程式的 UI 中剖析及顯示這項資訊。
限制模型在分類工作期間的回應方式。
舉例來說，您可以讓模型使用特定一組標籤 (例如 positive 和 negative 等特定一組列舉) 為文字加上註解，而非模型產生的標籤 (可能會像 good、positive、negative 或 bad 一樣具有一定程度的變化)。

本指南說明如何在對 generateContent 的呼叫中提供 responseSchema，產生 JSON 輸出內容。雖然 Gemini 主要處理純文字輸入內容，但也可以針對多模態要求產生結構化回應，這些要求的輸入內容包括圖片、影片和音訊。

本頁底部提供更多範例，例如如何產生列舉值做為輸出內容。如要查看如何產生結構化輸出的其他範例，請參閱 Google Cloud 說明文件中的範例結構定義和模型回應清單。

其他與 Gemini API 相關的選項

您可以選擇嘗試 Gemini API
的「Google AI」替代版本，使用 Google AI Studio 和 Google AI 用戶端 SDK 取得免付費存取權 (在限制範圍內，且適用於可用版本)。這些 SDK 應僅用於行動應用程式和網頁應用程式的原型設計。

熟悉 Gemini API 的運作方式後，請遷移至我們的 Vertex AI in Firebase SDK (本說明文件)，其中提供許多對行動和網頁應用程式重要的額外功能，例如使用 Firebase App Check 保護 API 免遭濫用，以及支援要求中的大型媒體檔案。

視需要呼叫 Vertex AI Gemini API 伺服器端 (例如使用 Python、Node.js 或 Go)
使用伺服器端 Vertex AI SDK、Firebase Genkit 或 Firebase Extensions 來處理 Gemini API。

事前準備

如果您尚未完成，請完成Vertex AI in Firebase SDK 的入門指南。請確認您已完成下列所有操作：

設定新的或現有的 Firebase 專案，包括使用 Blaze 定價方案和啟用必要的 API。
將應用程式連結至 Firebase，包括註冊應用程式，以及將 Firebase 設定新增至應用程式。
新增 SDK，並在應用程式中初始化 Vertex AI 服務和生成式模型。

將應用程式連結至 Firebase、新增 SDK 並初始化 Vertex AI 服務和生成模型後，您就可以呼叫 Gemini API。

步驟 1：定義回應結構定義

定義回應結構定義，以指定模型輸出的結構、欄位名稱和每個欄位的預期資料類型。

模型產生回覆時，會使用提示中的欄位名稱和脈絡。為清楚表達您的意圖，建議您使用明確的結構、不含歧義的欄位名稱，甚至視需要使用說明。

回應結構定義的注意事項

編寫回應結構定義時，請注意下列事項：

回應結構定義的大小會計入輸入符記限制。
回應結構定義功能支援下列回應 MIME 類型：
- application/json：輸出回應結構定義的 JSON (適用於結構化輸出要求)
- text/x.enum：輸出回應結構定義的列舉值 (適用於分類工作)
回應結構定義功能支援下列結構定義欄位：

enum
items
maxItems
nullable
properties
required

如果您使用不支援的欄位，模型仍可處理您的要求，但會忽略該欄位。請注意，上述清單是 OpenAPI 3.0 結構定義物件的子集 (請參閱 Vertex AI 結構定義參考資料)。
根據預設，對於 Vertex AI in Firebase SDK，除非您在 optionalProperties 陣列中將所有欄位指定為選用欄位，否則系統會將所有欄位視為必要欄位。對於這些選填欄位，模型可以填入欄位或略過欄位。

請注意，這與 Vertex AI Gemini API 的預設行為相反。

步驟 2：傳送含有回應結構定義的提示，以產生 JSON

以下範例說明如何產生結構化 JSON 輸出內容。

如要產生結構化輸出內容，您必須在模型初始化期間指定適當的 responseMimeType (在本例中為 application/json)，以及要讓模型使用的 responseSchema。

所有 Gemini 模型 (Gemini 1.0 模型除外) 都支援使用 responseSchema。

import FirebaseVertexAI

// Provide a JSON schema object using a standard format.
// Later, pass this schema object into `responseSchema` in the generation config.
let jsonSchema = Schema.object(
  properties: [
    "characters": Schema.array(
      items: .object(
        properties: [
          "name": .string(),
          "age": .integer(),
          "species": .string(),
          "accessory": .enumeration(values: ["hat", "belt", "shoes"]),
        ],
        optionalProperties: ["accessory"]
      )
    ),
  ]
)

// Initialize the Vertex AI service and the generative model.
let model = VertexAI.vertexAI().generativeModel(
  modelName: "gemini-2.0-flash",
  // In the generation config, set the `responseMimeType` to `application/json`
  // and pass the JSON schema object into `responseSchema`.
  generationConfig: GenerationConfig(
    responseMIMEType: "application/json",
    responseSchema: jsonSchema
  )
)

let prompt = "For use in a children's card game, generate 10 animal-based characters."

let response = try await model.generateContent(prompt)
print(response.text ?? "No text in response.")

瞭解如何選擇適合您用途和應用程式的 Gemini 模型，以及選用的位置。

其他範例

如要查看如何使用及產生結構化輸出的其他範例，請參閱 Google Cloud 說明文件中的範例結構定義和模型回應清單。

產生列舉值做為輸出內容

以下範例說明如何為分類工作使用回應結構定義。請模型根據電影說明，識別電影類型。輸出內容是模型從提供的回應結構定義中定義的值清單中選取的一個純文字列舉值。

如要執行這項結構化分類工作，您必須在模型初始化期間指定適當的 responseMimeType (本例為 text/x.enum)，以及要讓模型使用的 responseSchema。

import FirebaseVertexAI

// Provide an enum schema object using a standard format.
// Later, pass this schema object into `responseSchema` in the generation config.
let enumSchema = Schema.enumeration(values: ["drama", "comedy", "documentary"])

// Initialize the Vertex AI service and the generative model.
let model = VertexAI.vertexAI().generativeModel(
  modelName: "gemini-2.0-flash",
  // In the generation config, set the `responseMimeType` to `text/x.enum`
  // and pass the enum schema object into `responseSchema`.
  generationConfig: GenerationConfig(
    responseMIMEType: "text/x.enum",
    responseSchema: enumSchema
  )
)

let prompt = """
The film aims to educate and inform viewers about real-life subjects, events, or people.
It offers a factual record of a particular topic by combining interviews, historical footage,
and narration. The primary purpose of a film is to present information and provide insights
into various aspects of reality.
"""

let response = try await model.generateContent(prompt)
print(response.text ?? "No text in response.")

瞭解如何選擇適合您用途和應用程式的 Gemini 模型，以及選用的位置。

其他控管內容產生作業的選項

進一步瞭解提示設計，以便您影響模型，讓模型產生符合您需求的輸出內容。
設定模型參數，控管模型產生回覆的方式。這些參數包括輸出符記數量上限、溫度、topK 和 topP。
您可以使用安全性設定調整可能會產生有害回應內容的機率，包括仇恨言論和煽情露骨內容。
設定系統指示，引導模型的行為。這項功能就像是「前言」，可在模型向使用者提供任何進一步指示之前新增。

針對 Vertex AI in Firebase 的使用體驗提供意見回饋