شما میتوانید مدلهای Gemini را طوری پیکربندی کنید که پاسخهایی تولید کنند که به یک JSON Schema ارائه شده پایبند باشند. این امر نتایج قابل پیشبینی و ایمن از نظر نوع داده را تضمین میکند و استخراج دادههای ساختاریافته از متن بدون ساختار را ساده میکند.
استفاده از خروجیهای ساختاریافته برای موارد زیر ایدهآل است:
- استخراج دادهها: اطلاعات خاص مانند نامها و تاریخها را از متن استخراج کنید.
- طبقهبندی ساختاریافته: متن را در دستههای از پیش تعریفشده طبقهبندی میکند.
- گردشهای کاری عاملمحور: ورودیهای ساختاریافته برای ابزارها یا APIها تولید کنید.
علاوه بر پشتیبانی از JSON Schema در REST API، SDK های Google GenAI تعریف طرحوارهها را با استفاده از Pydantic (پایتون) و Zod (جاوااسکریپت) آسان میکنند.
این مثال نحوه استخراج دادههای ساختاریافته از متن را با استفاده از انواع اولیه JSON Schema مانند object ، array ، string و integer نشان میدهد.
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-3-flash-preview",
contents=prompt,
config={
"response_mime_type": "application/json",
"response_json_schema": Recipe.model_json_schema(),
},
)
recipe = Recipe.model_validate_json(response.text)
print(recipe)
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-3-flash-preview",
contents: prompt,
config: {
responseMimeType: "application/json",
responseJsonSchema: zodToJsonSchema(recipeSchema),
},
});
const recipe = recipeSchema.parse(JSON.parse(response.text));
console.log(recipe);
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-3-flash-preview",
genai.Text(prompt),
config,
)
if err != nil {
log.Fatal(err)
}
fmt.Println(result.Text())
}
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-flash-preview: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."
]
}
شما میتوانید خروجیهای ساختاریافته را به صورت استریم (stream) دریافت کنید، که به شما امکان میدهد پردازش پاسخ را همزمان با تولید آن شروع کنید، بدون اینکه مجبور باشید منتظر بمانید تا کل خروجی کامل شود. این میتواند عملکرد درک شده از برنامه شما را بهبود بخشد.
بخشهای استریمشده، رشتههای JSON ناقص معتبری خواهند بود که میتوانند برای تشکیل شیء JSON نهایی و کامل، به هم متصل شوند.
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-3-flash-preview",
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)
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-3-flash-preview",
contents: prompt,
config: {
responseMimeType: "application/json",
responseJsonSchema: zodToJsonSchema(feedbackSchema),
},
});
for await (const chunk of stream) {
console.log(chunk.candidates[0].content.parts[0].text)
}
Gemini 3 به شما امکان میدهد خروجیهای ساختاریافته را با ابزارهای داخلی، از جمله Grounding with Google Search ، URL Context ، Code Execution و File Search، ترکیب کنید.
from google import genai
from pydantic import BaseModel, Field
from typing import List
class MatchResult(BaseModel):
winner: str = Field(description="The name of the winner.")
final_match_score: str = Field(description="The final match score.")
scorers: List[str] = Field(description="The name of the scorer.")
client = genai.Client()
response = client.models.generate_content(
model="gemini-3-pro-preview",
contents="Search for all details for the latest Euro.",
config={
"tools": [
{"google_search": {}},
{"url_context": {}}
],
"response_mime_type": "application/json",
"response_json_schema": MatchResult.model_json_schema(),
},
)
result = MatchResult.model_validate_json(response.text)
print(result)
import { GoogleGenAI } from "@google/genai";
import { z } from "zod";
import { zodToJsonSchema } from "zod-to-json-schema";
const ai = new GoogleGenAI({});
const matchSchema = z.object({
winner: z.string().describe("The name of the winner."),
final_match_score: z.string().describe("The final score."),
scorers: z.array(z.string()).describe("The name of the scorer.")
});
async function run() {
const response = await ai.models.generateContent({
model: "gemini-3-pro-preview",
contents: "Search for all details for the latest Euro.",
config: {
tools: [
{ googleSearch: {} },
{ urlContext: {} }
],
responseMimeType: "application/json",
responseJsonSchema: zodToJsonSchema(matchSchema),
},
});
const match = matchSchema.parse(JSON.parse(response.text));
console.log(match);
}
run();
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro-preview:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [{
"parts": [{"text": "Search for all details for the latest Euro."}]
}],
"tools": [
{"googleSearch": {}},
{"urlContext": {}}
],
"generationConfig": {
"responseMimeType": "application/json",
"responseJsonSchema": {
"type": "object",
"properties": {
"winner": {"type": "string", "description": "The name of the winner."},
"final_match_score": {"type": "string", "description": "The final score."},
"scorers": {
"type": "array",
"items": {"type": "string"},
"description": "The name of the scorer."
}
},
"required": ["winner", "final_match_score", "scorers"]
}
}
}'
برای تولید یک شیء JSON، response_mime_type در پیکربندی generation روی application/json تنظیم کنید و یک response_json_schema ارائه دهید. این طرحواره باید یک JSON Schema معتبر باشد که فرمت خروجی مورد نظر را توصیف کند.
سپس مدل پاسخی تولید میکند که یک رشته JSON معتبر از نظر نحوی است که با طرحواره ارائه شده مطابقت دارد. هنگام استفاده از خروجیهای ساختاریافته، مدل خروجیها را به همان ترتیب کلیدهای موجود در طرحواره تولید میکند.
حالت خروجی ساختاریافتهی Gemini از زیرمجموعهای از مشخصات JSON Schema پشتیبانی میکند.
مقادیر type زیر پشتیبانی میشوند:
-
string: برای متن. -
number: برای اعداد اعشاری. -
integer: برای اعداد صحیح. -
boolean: برای مقادیر درست/نادرست. -
object: برای دادههای ساختاریافته با جفتهای کلید-مقدار. -
array: برای لیست آیتمها. -
null: برای اینکه یک ویژگی بتواند null باشد،"null"را در آرایه نوع قرار دهید (مثلاً{"type": ["string", "null"]}).
این ویژگیهای توصیفی به هدایت مدل کمک میکنند:
-
title: شرح مختصری از یک ملک. -
description: شرح طولانیتر و مفصلتر یک ملک.
برای مقادیر object :
-
properties: شیءای که در آن هر کلید، نام یک ویژگی و هر مقدار، طرحوارهای برای آن ویژگی است. -
required: آرایهای از رشتهها که ویژگیهای اجباری را فهرست میکند. -
additionalProperties: کنترل میکند که آیا ویژگیهایی که درpropertiesفهرست نشدهاند، مجاز هستند یا خیر. میتواند یک مقدار بولی یا یک schema باشد.
برای مقادیر string :
-
enum: مجموعهای خاص از رشتههای ممکن برای وظایف طبقهبندی را فهرست میکند. -
format: یک سینتکس برای رشته مشخص میکند، مانندdate-time،date،time.
برای مقادیر number و integer :
-
enum: مجموعهای خاص از مقادیر عددی ممکن را فهرست میکند. -
minimum: حداقل مقدار شامل. -
maximum: حداکثر مقدار شامل.
برای مقادیر array :
-
items: طرحواره (schema) را برای همه آیتمهای موجود در آرایه تعریف میکند. -
prefixItems: فهرستی از طرحوارهها را برای N مورد اول تعریف میکند و امکان ساختارهای تاپلمانند را فراهم میکند. -
minItems: حداقل تعداد آیتمها در آرایه. -
maxItems: حداکثر تعداد آیتمها در آرایه.
مدلهای زیر از خروجی ساختاریافته پشتیبانی میکنند:
| مدل | خروجیهای ساختاریافته |
|---|---|
| پیشنمایش جمینی ۳ پرو | ✔️ |
| پیشنمایش فلش جمینی ۳ | ✔️ |
| جمینی ۲.۵ پرو | ✔️ |
| فلش جمینی ۲.۵ | ✔️ |
| جمینی ۲.۵ فلش-لایت | ✔️ |
| فلش جمینی ۲.۰ | ✔️* |
| جمینی ۲.۰ فلش-لایت | ✔️* |
* توجه داشته باشید که Gemini 2.0 برای تعریف ساختار ترجیحی، به یک لیست propertyOrdering صریح در ورودی JSON نیاز دارد. میتوانید مثالی از آن را در این کتاب آشپزی بیابید.
هم خروجیهای ساختاریافته و هم فراخوانی تابع از طرحوارههای JSON استفاده میکنند، اما اهداف متفاوتی را دنبال میکنند:
| ویژگی | مورد استفاده اصلی |
|---|---|
| خروجیهای ساختاریافته | قالببندی پاسخ نهایی به کاربر. از این مورد زمانی استفاده کنید که میخواهید پاسخ مدل در قالب خاصی باشد (مثلاً استخراج دادهها از یک سند برای ذخیره در پایگاه داده). |
| فراخوانی تابع | اقدام کردن در طول مکالمه. از این مورد زمانی استفاده کنید که مدل قبل از ارائه پاسخ نهایی، نیاز به انجام کاری (مثلاً «دریافت آب و هوای فعلی») از شما داشته باشد . |
- توضیحات واضح: از فیلد
descriptionدر طرحواره خود برای ارائه دستورالعملهای واضح به مدل در مورد آنچه هر ویژگی نشان میدهد، استفاده کنید. این برای هدایت خروجی مدل بسیار مهم است. - تایپ قوی: هر زمان که ممکن است از انواع خاص (
integer،string،enum) استفاده کنید. اگر یک پارامتر مجموعه محدودی از مقادیر معتبر دارد، ازenumاستفاده کنید. - مهندسی سریع: در دستور خود به طور واضح بیان کنید که از مدل میخواهید چه کاری انجام دهد. برای مثال، «اطلاعات زیر را از متن استخراج کنید...» یا «این بازخورد را طبق طرحواره ارائه شده طبقهبندی کنید...».
- اعتبارسنجی: اگرچه خروجی ساختاریافته، درستی نحو JSON را تضمین میکند، اما تضمین نمیکند که مقادیر از نظر معنایی نیز صحیح باشند. همیشه قبل از استفاده از خروجی نهایی در کد برنامه خود، آن را اعتبارسنجی کنید.
- مدیریت خطا: مدیریت خطای قوی را در برنامه خود پیادهسازی کنید تا مواردی را که خروجی مدل، اگرچه مطابق با طرحواره است، اما ممکن است الزامات منطق کسبوکار شما را برآورده نکند، به طرز شایستهای مدیریت کنید.
- زیرمجموعهی Schema: همه ویژگیهای مشخصات JSON Schema پشتیبانی نمیشوند. این مدل، ویژگیهای پشتیبانی نشده را نادیده میگیرد.
- پیچیدگی طرحواره: API ممکن است طرحوارههای بسیار بزرگ یا عمیقاً تودرتو را رد کند. اگر با خطایی مواجه شدید، سعی کنید طرحواره خود را با کوتاه کردن نام ویژگیها، کاهش تودرتو بودن یا محدود کردن تعداد محدودیتها ساده کنید.