結構化輸出內容

您可以設定 Gemini 模型,生成符合所提供 JSON 結構定義的回覆。這項功能可確保結果可預測且可剖析、確保格式和型別安全、以程式輔助偵測拒絕回應,並簡化提示。

使用結構化輸出內容非常適合多種應用程式:

  • 資料擷取:從非結構化文字中擷取特定資訊,例如從應付憑據中擷取姓名、日期和金額。
  • 結構化分類:將文字分類到預先定義的類別,並指派結構化標籤,例如依據情緒和主題分類顧客意見。
  • 代理工作流程:產生可用於呼叫其他工具或 API 的結構化資料,例如建立遊戲的角色表單或填寫表單。

除了在 REST API 中支援 JSON 結構定義,Python 和 JavaScript 適用的 Google GenAI SDK 也分別使用 PydanticZod,讓您輕鬆定義物件結構定義。以下範例說明如何從非結構化文字中擷取資訊,並符合程式碼中定義的結構定義。

這個範例說明如何使用基本 JSON 結構定義型別 (例如 objectarraystringinteger),從文字中擷取結構化資料。

Python

from google import genai from pydantic import BaseModel, Field from typing import List, Optional  class Ingredient(BaseModel):     name: str = Field(description="Name of the ingredient.")     quantity: str = Field(description="Quantity of the ingredient, including units.")  class Recipe(BaseModel):     recipe_name: str = Field(description="The name of the recipe.")     prep_time_minutes: Optional[int] = Field(description="Optional time in minutes to prepare the recipe.")     ingredients: List[Ingredient]     instructions: List[str]  client = genai.Client()  prompt = """ Please extract the recipe from the following text. The user wants to make delicious chocolate chip cookies. They need 2 and 1/4 cups of all-purpose flour, 1 teaspoon of baking soda, 1 teaspoon of salt, 1 cup of unsalted butter (softened), 3/4 cup of granulated sugar, 3/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs. For the best part, they'll need 2 cups of semisweet chocolate chips. First, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour, baking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar until light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry ingredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons onto ungreased baking sheets and bake for 9 to 11 minutes. """  response = client.models.generate_content(     model="gemini-2.5-flash",     contents=prompt,     config={         "response_mime_type": "application/json",         "response_json_schema": Recipe.model_json_schema(),     }, )  recipe = Recipe.model_validate_json(response.text) print(recipe) 

JavaScript

import { GoogleGenAI } from "@google/genai"; import { z } from "zod"; import { zodToJsonSchema } from "zod-to-json-schema";  const ingredientSchema = z.object({   name: z.string().describe("Name of the ingredient."),   quantity: z.string().describe("Quantity of the ingredient, including units."), });  const recipeSchema = z.object({   recipe_name: z.string().describe("The name of the recipe."),   prep_time_minutes: z.number().optional().describe("Optional time in minutes to prepare the recipe."),   ingredients: z.array(ingredientSchema),   instructions: z.array(z.string()), });  const ai = new GoogleGenAI({});  const prompt = ` Please extract the recipe from the following text. The user wants to make delicious chocolate chip cookies. They need 2 and 1/4 cups of all-purpose flour, 1 teaspoon of baking soda, 1 teaspoon of salt, 1 cup of unsalted butter (softened), 3/4 cup of granulated sugar, 3/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs. For the best part, they'll need 2 cups of semisweet chocolate chips. First, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour, baking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar until light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry ingredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons onto ungreased baking sheets and bake for 9 to 11 minutes. `;  const response = await ai.models.generateContent({   model: "gemini-2.5-flash",   contents: prompt,   config: {     responseMimeType: "application/json",     responseJsonSchema: zodToJsonSchema(recipeSchema),   }, });  const recipe = recipeSchema.parse(JSON.parse(response.text)); console.log(recipe); 

Go

package main  import (     "context"     "fmt"     "log"      "google.golang.org/genai" )  func main() {     ctx := context.Background()     client, err := genai.NewClient(ctx, nil)     if err != nil {         log.Fatal(err)     }      prompt := `   Please extract the recipe from the following text.   The user wants to make delicious chocolate chip cookies.   They need 2 and 1/4 cups of all-purpose flour, 1 teaspoon of baking soda,   1 teaspoon of salt, 1 cup of unsalted butter (softened), 3/4 cup of granulated sugar,   3/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs.   For the best part, they'll need 2 cups of semisweet chocolate chips.   First, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour,   baking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar   until light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry   ingredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons   onto ungreased baking sheets and bake for 9 to 11 minutes.   `     config := &genai.GenerateContentConfig{         ResponseMIMEType: "application/json",         ResponseJsonSchema: map[string]any{             "type": "object",             "properties": map[string]any{                 "recipe_name": map[string]any{                     "type":        "string",                     "description": "The name of the recipe.",                 },                 "prep_time_minutes": map[string]any{                     "type":        "integer",                     "description": "Optional time in minutes to prepare the recipe.",                 },                 "ingredients": map[string]any{                     "type": "array",                     "items": map[string]any{                         "type": "object",                         "properties": map[string]any{                             "name": map[string]any{                                 "type":        "string",                                 "description": "Name of the ingredient.",                             },                             "quantity": map[string]any{                                 "type":        "string",                                 "description": "Quantity of the ingredient, including units.",                             },                         },                         "required": []string{"name", "quantity"},                     },                 },                 "instructions": map[string]any{                     "type":  "array",                     "items": map[string]any{"type": "string"},                 },             },             "required": []string{"recipe_name", "ingredients", "instructions"},         },     }      result, err := client.Models.GenerateContent(         ctx,         "gemini-2.5-flash",         genai.Text(prompt),         config,     )     if err != nil {         log.Fatal(err)     }     fmt.Println(result.Text()) } 

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \     -H "x-goog-api-key: $GEMINI_API_KEY" \     -H 'Content-Type: application/json' \     -X POST \     -d '{       "contents": [{         "parts":[           { "text": "Please extract the recipe from the following text.\nThe user wants to make delicious chocolate chip cookies.\nThey need 2 and 1/4 cups of all-purpose flour, 1 teaspoon of baking soda,\n1 teaspoon of salt, 1 cup of unsalted butter (softened), 3/4 cup of granulated sugar,\n3/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs.\nFor the best part, they will need 2 cups of semisweet chocolate chips.\nFirst, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour,\nbaking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar\nuntil light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry\ningredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons\nonto ungreased baking sheets and bake for 9 to 11 minutes." }         ]       }],       "generationConfig": {         "responseMimeType": "application/json",         "responseJsonSchema": {           "type": "object",           "properties": {             "recipe_name": {               "type": "string",               "description": "The name of the recipe."             },             "prep_time_minutes": {                 "type": "integer",                 "description": "Optional time in minutes to prepare the recipe."             },             "ingredients": {               "type": "array",               "items": {                 "type": "object",                 "properties": {                   "name": { "type": "string", "description": "Name of the ingredient."},                   "quantity": { "type": "string", "description": "Quantity of the ingredient, including units."}                 },                 "required": ["name", "quantity"]               }             },             "instructions": {               "type": "array",               "items": { "type": "string" }             }           },           "required": ["recipe_name", "ingredients", "instructions"]         }       }     }' 

回覆範例:

{   "recipe_name": "Delicious Chocolate Chip Cookies",   "ingredients": [     {       "name": "all-purpose flour",       "quantity": "2 and 1/4 cups"     },     {       "name": "baking soda",       "quantity": "1 teaspoon"     },     {       "name": "salt",       "quantity": "1 teaspoon"     },     {       "name": "unsalted butter (softened)",       "quantity": "1 cup"     },     {       "name": "granulated sugar",       "quantity": "3/4 cup"     },     {       "name": "packed brown sugar",       "quantity": "3/4 cup"     },     {       "name": "vanilla extract",       "quantity": "1 teaspoon"     },     {       "name": "large eggs",       "quantity": "2"     },     {       "name": "semisweet chocolate chips",       "quantity": "2 cups"     }   ],   "instructions": [     "Preheat the oven to 375°F (190°C).",     "In a small bowl, whisk together the flour, baking soda, and salt.",     "In a large bowl, cream together the butter, granulated sugar, and brown sugar until light and fluffy.",     "Beat in the vanilla and eggs, one at a time.",     "Gradually beat in the dry ingredients until just combined.",     "Stir in the chocolate chips.",     "Drop by rounded tablespoons onto ungreased baking sheets and bake for 9 to 11 minutes."   ] } 

串流

您可以串流結構化輸出內容,不必等待整個輸出內容完成,即可開始處理回覆。這有助於提升應用程式的感知效能。

串流區塊會是有效的 JSON 字串片段,可串連成最終的完整 JSON 物件。

Python

from google import genai from pydantic import BaseModel, Field from typing import Literal  class Feedback(BaseModel):     sentiment: Literal["positive", "neutral", "negative"]     summary: str  client = genai.Client() prompt = "The new UI is incredibly intuitive and visually appealing. Great job. Add a very long summary to test streaming!"  response_stream = client.models.generate_content_stream(     model="gemini-2.5-flash",     contents=prompt,     config={         "response_mime_type": "application/json",         "response_json_schema": Feedback.model_json_schema(),     }, )  for chunk in response_stream:     print(chunk.candidates[0].content.parts[0].text) 

JavaScript

import { GoogleGenAI } from "@google/genai"; import { z } from "zod"; import { zodToJsonSchema } from "zod-to-json-schema";  const ai = new GoogleGenAI({}); const prompt = "The new UI is incredibly intuitive and visually appealing. Great job! Add a very long summary to test streaming!";  const feedbackSchema = z.object({   sentiment: z.enum(["positive", "neutral", "negative"]),   summary: z.string(), });  const stream = await ai.models.generateContentStream({   model: "gemini-2.5-flash",   contents: prompt,   config: {     responseMimeType: "application/json",     responseJsonSchema: zodToJsonSchema(feedbackSchema),   }, });  for await (const chunk of stream) {   console.log(chunk.candidates[0].content.parts[0].text) } 

支援 JSON 結構定義

如要產生 JSON 物件,請將生成設定中的 response_mime_type 設為 application/json,並提供 response_json_schema。結構定義必須是有效的 JSON 結構定義,用於說明所需的輸出格式。

模型接著會生成符合所提供結構定義的語法有效 JSON 字串。使用結構化輸出時,模型會按照結構定義中的鍵順序產生輸出內容。

Gemini 的結構化輸出模式支援部分 JSON 結構定義規格。

支援的 type 值如下:

  • string:文字。
  • number:適用於浮點數。
  • integer:適用於整數。
  • boolean:適用於 true/false 值。
  • object:適用於含有鍵/值組合的結構化資料。
  • array:適用於項目清單。
  • null:如要允許屬性為空值,請在型別陣列中加入 "null" (例如 {"type": ["string", "null"]})。

這些描述性屬性有助於引導模型:

  • title:屬性的簡短說明。
  • description:房源的詳細說明。

類型專屬屬性

適用於 object 值:

  • properties:物件,其中每個鍵都是屬性名稱,每個值都是該屬性的結構定義。
  • required:字串陣列,列出哪些屬性為必要屬性。
  • additionalProperties:控制是否允許未列於 properties 中的屬性。可以是布林值或結構定義。

適用於 string 值:

  • enum:列出分類工作的一組特定可能字串。
  • format:指定字串的語法,例如 date-timedatetime

numberinteger 值:

  • enum:列出特定的一組可能數值。
  • minimum:最小值 (含)。
  • maximum:最大值 (含)。

適用於 array 值:

  • items:定義陣列中所有項目的結構定義。
  • prefixItems:定義前 N 個項目的結構定義清單,允許類似元組的結構。
  • minItems:陣列中的項目數量下限。
  • maxItems:陣列中的項目數量上限。

模型支援

下列模型支援結構化輸出內容:

模型 結構化輸出內容
Gemini 2.5 Pro ✔️
Gemini 2.5 Flash ✔️
Gemini 2.5 Flash-Lite ✔️
Gemini 2.0 Flash ✔️*
Gemini 2.0 Flash-Lite ✔️*

* 請注意,Gemini 2.0 需要在 JSON 輸入內容中明確列出 propertyOrdering,才能定義偏好的結構。如需範例,請參閱這份教戰手冊

結構化輸出內容與函式呼叫

結構化輸出和函式呼叫都會使用 JSON 結構定義,但用途不同:

功能 主要用途
結構化輸出內容 將最終回應格式化,然後傳送給使用者。如果您希望模型回答時採用特定格式 (例如從文件擷取資料並儲存至資料庫),請使用這項功能。
函式呼叫 在對話期間採取行動。如果模型需要要求您執行工作 (例如 「get current weather」) 才能提供最終答案。

最佳做法

  • 清楚的說明:在結構定義中使用 description 欄位,清楚說明每個屬性代表的意義。這對引導模型輸出內容至關重要。
  • 嚴格型別:盡可能使用特定型別 (integerstringenum)。如果參數的有效值有限,請使用 enum
  • 提示工程:在提示中清楚說明您希望模型執行的動作。例如:「從這段文字中擷取下列資訊...」或「根據提供的結構定義,將這則意見回饋分類...」。
  • 驗證:結構化輸出內容可確保 JSON 語法正確,但無法保證值在語意上正確。請務必先驗證應用程式程式碼中的最終輸出內容,再使用該內容。
  • 錯誤處理:在應用程式中導入健全的錯誤處理機制,妥善管理模型輸出內容符合結構定義,但可能不符合業務邏輯要求的情況。

限制

  • 結構定義子集:系統不支援 JSON 結構定義規格的所有功能。模型會忽略不支援的屬性。
  • 結構定義複雜度:API 可能會拒絕過大或深度巢狀結構的結構定義。如果發生錯誤,請嘗試縮短屬性名稱、減少巢狀結構或限制條件數量,簡化結構定義。