خروجی‌های ساختاریافته

شما می‌توانید مدل‌های 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-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)

جاوا اسکریپت

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);

برو

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())
}

استراحت

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."
  ]
}

پخش جریانی

شما می‌توانید خروجی‌های ساختاریافته را به صورت استریم (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-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)

جاوا اسکریپت

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 در پیکربندی 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 ممکن است طرحواره‌های بسیار بزرگ یا عمیقاً تودرتو را رد کند. اگر با خطایی مواجه شدید، سعی کنید طرحواره خود را با کوتاه کردن نام ویژگی‌ها، کاهش تودرتو بودن یا محدود کردن تعداد محدودیت‌ها ساده کنید.