使用 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 的入門指南。請確認您已完成下列所有步驟：

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。

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

其他範例

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

以輸出內容產生列舉值

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

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

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

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

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

提供使用 Vertex AI in Firebase 的意見回饋