您可以設定 Gemini 模型,生成符合所提供 JSON 結構定義的回覆。這項功能可確保結果可預測且可剖析、確保格式和型別安全、以程式輔助偵測拒絕回應,並簡化提示。
使用結構化輸出內容非常適合多種應用程式:
- 資料擷取:從非結構化文字中擷取特定資訊,例如從應付憑據中擷取姓名、日期和金額。
- 結構化分類:將文字分類到預先定義的類別,並指派結構化標籤,例如依據情緒和主題分類顧客意見。
- 代理工作流程:產生可用於呼叫其他工具或 API 的結構化資料,例如建立遊戲的角色表單或填寫表單。
除了在 REST API 中支援 JSON 結構定義,Python 和 JavaScript 適用的 Google GenAI SDK 也分別使用 Pydantic 和 Zod,讓您輕鬆定義物件結構定義。以下範例說明如何從非結構化文字中擷取資訊,並符合程式碼中定義的結構定義。
這個範例說明如何使用基本 JSON 結構定義型別 (例如 object、array、string 和 integer),從文字中擷取結構化資料。
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-time、date、time。
number 和 integer 值:
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欄位,清楚說明每個屬性代表的意義。這對引導模型輸出內容至關重要。 - 嚴格型別:盡可能使用特定型別 (
integer、string、enum)。如果參數的有效值有限,請使用enum。 - 提示工程:在提示中清楚說明您希望模型執行的動作。例如:「從這段文字中擷取下列資訊...」或「根據提供的結構定義,將這則意見回饋分類...」。
- 驗證:結構化輸出內容可確保 JSON 語法正確,但無法保證值在語意上正確。請務必先驗證應用程式程式碼中的最終輸出內容,再使用該內容。
- 錯誤處理:在應用程式中導入健全的錯誤處理機制,妥善管理模型輸出內容符合結構定義,但可能不符合業務邏輯要求的情況。
限制
- 結構定義子集:系統不支援 JSON 結構定義規格的所有功能。模型會忽略不支援的屬性。
- 結構定義複雜度:API 可能會拒絕過大或深度巢狀結構的結構定義。如果發生錯誤,請嘗試縮短屬性名稱、減少巢狀結構或限制條件數量,簡化結構定義。