स्ट्रक्चर्ड आउटपुट

Gemini मॉडल को कॉन्फ़िगर करके, दिए गए JSON स्कीमा के मुताबिक जवाब जनरेट किए जा सकते हैं. इस सुविधा से, अनुमान के मुताबिक और पार्स किए जा सकने वाले नतीजे मिलते हैं. साथ ही, यह फ़ॉर्मैट और टाइप-सेफ़्टी को पक्का करती है. इससे प्रोग्राम के ज़रिए अनुरोध अस्वीकार किए जाने का पता लगाया जा सकता है और प्रॉम्प्ट को आसान बनाया जा सकता है.

स्ट्रक्चर्ड आउटपुट का इस्तेमाल कई तरह के ऐप्लिकेशन के लिए सबसे सही होता है:

  • डेटा निकालना: बिना किसी स्ट्रक्चर वाले टेक्स्ट से खास जानकारी निकालना. जैसे, किसी इनवॉइस से नाम, तारीखें, और रकम निकालना.
  • स्ट्रक्चर्ड क्लासिफ़िकेशन: टेक्स्ट को पहले से तय की गई कैटगरी में बांटें और स्ट्रक्चर्ड लेबल असाइन करें. जैसे, ग्राहक से मिली प्रतिक्रिया को भावना और विषय के हिसाब से कैटगरी में बांटना.
  • एजेंटिक वर्कफ़्लो: ऐसा स्ट्रक्चर्ड डेटा जनरेट करें जिसका इस्तेमाल अन्य टूल या एपीआई को कॉल करने के लिए किया जा सकता है. जैसे, किसी गेम के लिए कैरेक्टर शीट बनाना या कोई फ़ॉर्म भरना.

REST API में JSON स्कीमा के साथ-साथ, Python और JavaScript के लिए Google के GenAI SDK टूल भी उपलब्ध हैं. इनकी मदद से, Pydantic और Zod का इस्तेमाल करके, ऑब्जेक्ट स्कीमा को आसानी से तय किया जा सकता है. यहां दिए गए उदाहरण में, कोड में तय किए गए स्कीमा के मुताबिक, बिना स्ट्रक्चर वाले टेक्स्ट से जानकारी निकालने का तरीका दिखाया गया है.

इस उदाहरण में, object, array, string, और integer जैसे बुनियादी JSON स्कीमा टाइप का इस्तेमाल करके, टेक्स्ट से स्ट्रक्चर्ड डेटा निकालने का तरीका दिखाया गया है.

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

ऐप पर जाएं

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: सही/गलत वैल्यू के लिए.
  • 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 स्कीमा स्पेसिफ़िकेशन की सभी सुविधाएँ काम नहीं करती हैं. मॉडल, इस्तेमाल नहीं की जा सकने वाली प्रॉपर्टी को अनदेखा करता है.
  • स्कीमा की जटिलता: एपीआई, बहुत बड़े या डीपली नेस्ट किए गए स्कीमा को अस्वीकार कर सकता है. अगर आपको गड़बड़ियां मिलती हैं, तो प्रॉपर्टी के नाम छोटे करके, नेस्टिंग कम करके या शर्तों की संख्या सीमित करके, अपने स्कीमा को आसान बनाएं.