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

iOS 以上版本 Android 網頁版 Flutter

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

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

例如：

• 確保模型回應產生有效的 JSON，並且符合提供的結構定義。
  舉例來說，模型可以為食譜產生結構化項目，這些項目一律包含食譜名稱、食材清單和步驟。接著，您可以更輕鬆地在應用程式 UI 中剖析及顯示這項資訊。

• 限制模型在分類工作期間的回應方式。
  例如，您可以讓模型使用一組特定的標籤 (例如 positive 和 negative 等特定列舉組合) 為文字加上註解，而不是模型產生的標籤 (可能的變異程度可能為 good、positive、negative 或 bad)。

注意：使用回應結構定義產生結構化輸出內容，有時稱為「JSON 模式」或「受控產生」。

本指南說明如何在呼叫 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 的入門指南。請確認您已完成下列所有步驟：

1. 設定新的或現有的 Firebase 專案，包括使用 Blaze 定價方案，並啟用必要的 API。

2. 將應用程式連結至 Firebase，包括註冊應用程式以及將 Firebase 設定新增至應用程式。

3. 新增 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 1.5 Pro 和 Gemini 1.5 Flash 支援使用 responseSchema。

iOS+ Android 網頁版 Flutter

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

其他範例

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

產生列舉值做為輸出內容

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

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

iOS 以上版本 Android 網頁版 Flutter

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

控管內容生成功能的其他選項

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

提供有關 Vertex AI in Firebase 使用體驗的意見回饋