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

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

Gemini, स्ट्रक्चर्ड आउटपुट के तौर पर JSON या enum वैल्यू जनरेट कर सकता है.

JSON जनरेट किया जा रहा है

Gemini API का इस्तेमाल करके JSON जनरेट करने के दो तरीके हैं:

  • मॉडल पर स्कीमा कॉन्फ़िगर करना
  • टेक्स्ट प्रॉम्प्ट में स्कीमा देना

मॉडल पर स्कीमा कॉन्फ़िगर करना, JSON जनरेट करने का सुझाया गया तरीका है, क्योंकि इससे मॉडल को JSON आउटपुट करने के लिए मजबूर किया जाता है.

स्कीमा कॉन्फ़िगर करना (सुझाया गया)

मॉडल को JSON जनरेट करने के लिए सीमित करने के लिए, responseSchema कॉन्फ़िगर करें. इसके बाद, मॉडल किसी भी प्रॉम्प्ट का जवाब JSON फ़ॉर्मैट में देगा.

Python

from google import genai
from pydantic import BaseModel

class Recipe(BaseModel):
    recipe_name: str
    ingredients: list[str]

client = genai.Client()
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="List a few popular cookie recipes, and include the amounts of ingredients.",
    config={
        "response_mime_type": "application/json",
        "response_schema": list[Recipe],
    },
)
# Use the response as a JSON string.
print(response.text)

# Use instantiated objects.
my_recipes: list[Recipe] = response.parsed

JavaScript

import { GoogleGenAI, Type } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents:
      "List a few popular cookie recipes, and include the amounts of ingredients.",
    config: {
      responseMimeType: "application/json",
      responseSchema: {
        type: Type.ARRAY,
        items: {
          type: Type.OBJECT,
          properties: {
            recipeName: {
              type: Type.STRING,
            },
            ingredients: {
              type: Type.ARRAY,
              items: {
                type: Type.STRING,
              },
            },
          },
          propertyOrdering: ["recipeName", "ingredients"],
        },
      },
    },
  });

  console.log(response.text);
}

main();

शुरू करें

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

    config := &genai.GenerateContentConfig{
        ResponseMIMEType: "application/json",
        ResponseSchema: &genai.Schema{
            Type: genai.TypeArray,
            Items: &genai.Schema{
                Type: genai.TypeObject,
                Properties: map[string]*genai.Schema{
                    "recipeName": {Type: genai.TypeString},
                    "ingredients": {
                        Type:  genai.TypeArray,
                        Items: &genai.Schema{Type: genai.TypeString},
                    },
                },
                PropertyOrdering: []string{"recipeName", "ingredients"},
            },
        },
    }

    result, err := client.Models.GenerateContent(
        ctx,
        "gemini-2.5-flash",
        genai.Text("List a few popular cookie recipes, and include the amounts of ingredients."),
        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' \
-d '{
      "contents": [{
        "parts":[
          { "text": "List a few popular cookie recipes, and include the amounts of ingredients." }
        ]
      }],
      "generationConfig": {
        "responseMimeType": "application/json",
        "responseSchema": {
          "type": "ARRAY",
          "items": {
            "type": "OBJECT",
            "properties": {
              "recipeName": { "type": "STRING" },
              "ingredients": {
                "type": "ARRAY",
                "items": { "type": "STRING" }
              }
            },
            "propertyOrdering": ["recipeName", "ingredients"]
          }
        }
      }
}' 2> /dev/null | head

आउटपुट ऐसा दिख सकता है:

[
  {
    "recipeName": "Chocolate Chip Cookies",
    "ingredients": [
      "1 cup (2 sticks) unsalted butter, softened",
      "3/4 cup granulated sugar",
      "3/4 cup packed brown sugar",
      "1 teaspoon vanilla extract",
      "2 large eggs",
      "2 1/4 cups all-purpose flour",
      "1 teaspoon baking soda",
      "1 teaspoon salt",
      "2 cups chocolate chips"
    ]
  },
  ...
]

टेक्स्ट प्रॉम्प्ट में स्कीमा देना

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

यहां टेक्स्ट प्रॉम्प्ट में दिए गए स्कीमा का सामान्य उदाहरण दिया गया है:

List a few popular cookie recipes, and include the amounts of ingredients.

Produce JSON matching this specification:

Recipe = { "recipeName": string, "ingredients": array<string> }
Return: array<Recipe>

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

ईनम वैल्यू जनरेट करना

कुछ मामलों में, आपको मॉडल से विकल्पों की सूची में से सिर्फ़ एक विकल्प चुनने के लिए कहना पड़ सकता है. इस व्यवहार को लागू करने के लिए, अपने स्कीमा में enum पास करें. responseSchema में string का इस्तेमाल करने की जगह, किसी भी Enum विकल्प का इस्तेमाल किया जा सकता है. ऐसा इसलिए, क्योंकि Enum, स्ट्रिंग का एक कलेक्शन होता है. JSON स्कीमा की तरह, enum की मदद से मॉडल के आउटपुट को सीमित किया जा सकता है, ताकि वह आपके ऐप्लिकेशन की ज़रूरी शर्तों को पूरा कर सके.

उदाहरण के लिए, मान लें कि आपको एक ऐसा ऐप्लिकेशन बनाना है जो संगीत वाद्ययंत्रों को पांच कैटगरी में बांटता है: "Percussion", "String", "Woodwind", "Brass" या ""Keyboard"". इस काम में मदद पाने के लिए, एक enum बनाया जा सकता है.

यहां दिए गए उदाहरण में, आपने responseSchema के तौर पर एक enum पास किया है. इससे मॉडल को सबसे सही विकल्प चुनने में मदद मिलती है.

Python

from google import genai
import enum

class Instrument(enum.Enum):
  PERCUSSION = "Percussion"
  STRING = "String"
  WOODWIND = "Woodwind"
  BRASS = "Brass"
  KEYBOARD = "Keyboard"

client = genai.Client()
response = client.models.generate_content(
    model='gemini-2.5-flash',
    contents='What type of instrument is an oboe?',
    config={
        'response_mime_type': 'text/x.enum',
        'response_schema': Instrument,
    },
)

print(response.text)
# Woodwind

JavaScript

import { GoogleGenAI, Type } from "@google/genai";

const ai = new GoogleGenAI({});

const response = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: "What type of instrument is an oboe?",
    config: {
      responseMimeType: "text/x.enum",
      responseSchema: {
        type: Type.STRING,
        enum: ["Percussion", "String", "Woodwind", "Brass", "Keyboard"],
      },
    },
  });

console.log(response.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' \
    -d '{
          "contents": [{
            "parts":[
              { "text": "What type of instrument is an oboe?" }
            ]
          }],
          "generationConfig": {
            "responseMimeType": "text/x.enum",
            "responseSchema": {
              "type": "STRING",
              "enum": ["Percussion", "String", "Woodwind", "Brass", "Keyboard"]
            }
          }
    }'

Python लाइब्रेरी, एपीआई के लिए टाइप डिक्लेरेशन का अनुवाद करेगी. हालांकि, एपीआई, OpenAPI 3.0 स्कीमा के सबसेट (स्कीमा) को स्वीकार करता है.

गिनती बताने के दो अन्य तरीके भी हैं. इसके लिए, Literal का इस्तेमाल किया जा सकता है: ```

Python

Literal["Percussion", "String", "Woodwind", "Brass", "Keyboard"]

इसके अलावा, स्कीमा को JSON के तौर पर भी पास किया जा सकता है:

Python

from google import genai

client = genai.Client()
response = client.models.generate_content(
    model='gemini-2.5-flash',
    contents='What type of instrument is an oboe?',
    config={
        'response_mime_type': 'text/x.enum',
        'response_schema': {
            "type": "STRING",
            "enum": ["Percussion", "String", "Woodwind", "Brass", "Keyboard"],
        },
    },
)

print(response.text)
# Woodwind

एक से ज़्यादा विकल्पों वाले सवालों के अलावा, JSON स्कीमा में किसी भी जगह पर enum का इस्तेमाल किया जा सकता है. उदाहरण के लिए, मॉडल से रेसिपी के टाइटल की सूची मांगी जा सकती है. साथ ही, हर टाइटल को लोकप्रियता के हिसाब से ग्रेड देने के लिए, Grade enum का इस्तेमाल किया जा सकता है:

Python

from google import genai

import enum
from pydantic import BaseModel

class Grade(enum.Enum):
    A_PLUS = "a+"
    A = "a"
    B = "b"
    C = "c"
    D = "d"
    F = "f"

class Recipe(BaseModel):
  recipe_name: str
  rating: Grade

client = genai.Client()
response = client.models.generate_content(
    model='gemini-2.5-flash',
    contents='List 10 home-baked cookie recipes and give them grades based on tastiness.',
    config={
        'response_mime_type': 'application/json',
        'response_schema': list[Recipe],
    },
)

print(response.text)

जवाब कुछ इस तरह दिख सकता है:

[
  {
    "recipe_name": "Chocolate Chip Cookies",
    "rating": "a+"
  },
  {
    "recipe_name": "Peanut Butter Cookies",
    "rating": "a"
  },
  {
    "recipe_name": "Oatmeal Raisin Cookies",
    "rating": "b"
  },
  ...
]

JSON स्कीमा के बारे में जानकारी

responseSchema पैरामीटर का इस्तेमाल करके, JSON आउटपुट के लिए मॉडल को कॉन्फ़िगर करना, Schema ऑब्जेक्ट पर निर्भर करता है. यह ऑब्जेक्ट, OpenAPI 3.0 Schema ऑब्जेक्ट के चुने गए सबसेट को दिखाता है. साथ ही, इसमें propertyOrdering फ़ील्ड भी जोड़ा जाता है.

यहां सभी Schema फ़ील्ड का सूडो-JSON फ़ॉर्मैट दिया गया है:

{
  "type": enum (Type),
  "format": string,
  "description": string,
  "nullable": boolean,
  "enum": [
    string
  ],
  "maxItems": integer,
  "minItems": integer,
  "properties": {
    string: {
      object (Schema)
    },
    ...
  },
  "required": [
    string
  ],
  "propertyOrdering": [
    string
  ],
  "items": {
    object (Schema)
  }
}

स्कीमा का Type, OpenAPI के डेटा टाइप में से एक होना चाहिए. इसके अलावा, यह उन टाइप का यूनियन (anyOf का इस्तेमाल करके) भी हो सकता है. हर Type के लिए, फ़ील्ड का सिर्फ़ एक सबसेट मान्य होता है. यहां दी गई सूची में, हर Type को उन फ़ील्ड के सबसेट से मैप किया गया है जो उस टाइप के लिए मान्य हैं:

  • string -> enum, format, nullable
  • integer -> format, minimum, maximum, enum, nullable
  • number -> format, minimum, maximum, enum, nullable
  • boolean -> nullable
  • array -> minItems, maxItems, items, nullable
  • object -> properties, required, propertyOrdering, nullable

यहां कुछ उदाहरण स्कीमा दिए गए हैं. इनमें टाइप और फ़ील्ड के मान्य कॉम्बिनेशन दिखाए गए हैं:

{ "type": "string", "enum": ["a", "b", "c"] }

{ "type": "string", "format": "date-time" }

{ "type": "integer", "format": "int64" }

{ "type": "number", "format": "double" }

{ "type": "boolean" }

{ "type": "array", "minItems": 3, "maxItems": 3, "items": { "type": ... } }

{ "type": "object",
  "properties": {
    "a": { "type": ... },
    "b": { "type": ... },
    "c": { "type": ... }
  },
  "nullable": true,
  "required": ["c"],
  "propertyOrdering": ["c", "b", "a"]
}

Gemini API में इस्तेमाल किए गए स्कीमा फ़ील्ड के पूरे दस्तावेज़ के लिए, स्कीमा रेफ़रंस देखें.

प्रॉपर्टी ऑर्डर करना

Gemini API में JSON स्कीमा के साथ काम करते समय, प्रॉपर्टी का क्रम मायने रखता है. डिफ़ॉल्ट रूप से, एपीआई प्रॉपर्टी को वर्णमाला के क्रम में लगाता है. साथ ही, प्रॉपर्टी को जिस क्रम में तय किया जाता है उस क्रम को बनाए नहीं रखता. हालांकि, Google Gen AI SDK इस क्रम को बनाए रख सकते हैं. अगर आपने स्कीमा कॉन्फ़िगर करके मॉडल को उदाहरण दिए हैं और उदाहरणों में प्रॉपर्टी का क्रम, स्कीमा में प्रॉपर्टी के क्रम से मेल नहीं खाता है, तो आउटपुट में गड़बड़ी हो सकती है या वह आपकी उम्मीद के मुताबिक नहीं हो सकता.

प्रॉपर्टी को एक ही क्रम में दिखाने के लिए, propertyOrdering[] फ़ील्ड का इस्तेमाल किया जा सकता है. यह फ़ील्ड ज़रूरी नहीं है.

"propertyOrdering": ["recipeName", "ingredients"]

propertyOrdering[] – OpenAPI स्पेसिफ़िकेशन में यह स्टैंडर्ड फ़ील्ड नहीं है – यह स्ट्रिंग का एक कलेक्शन है. इसका इस्तेमाल, रिस्पॉन्स में प्रॉपर्टी के क्रम का पता लगाने के लिए किया जाता है. प्रॉपर्टी का क्रम तय करके और उसी क्रम में प्रॉपर्टी के उदाहरण देकर, नतीजों की क्वालिटी को बेहतर बनाया जा सकता है. propertyOrdering का इस्तेमाल सिर्फ़ तब किया जा सकता है, जब आपने मैन्युअल तरीके से types.Schema बनाया हो.

Python में स्कीमा

Python लाइब्रेरी का इस्तेमाल करते समय, response_schema की वैल्यू इनमें से कोई एक होनी चाहिए:

  • टाइप एनोटेशन में इस्तेमाल किया जाने वाला टाइप (Python typing मॉड्यूल देखें)
  • genai.types.Schema का एक उदाहरण
  • genai.types.Schema के बराबर dict

किसी स्कीमा को तय करने का सबसे आसान तरीका, Pydantic टाइप का इस्तेमाल करना है. जैसा कि पिछले उदाहरण में दिखाया गया है:

Python

config={'response_mime_type': 'application/json',
        'response_schema': list[Recipe]}

Pydantic टाइप का इस्तेमाल करने पर, Python लाइब्रेरी आपके लिए JSON स्कीमा बनाती है और उसे एपीआई को भेजती है. ज़्यादा उदाहरणों के लिए, Python लाइब्रेरी के दस्तावेज़ देखें.

Python लाइब्रेरी, इन टाइप के साथ तय किए गए स्कीमा के साथ काम करती है. यहां AllowedType कोई भी मान्य टाइप है:

  • int
  • float
  • bool
  • str
  • list[AllowedType]
  • AllowedType|AllowedType|...
  • स्ट्रक्चर्ड टाइप के लिए:
    • dict[str, AllowedType]. इस एनोटेशन से, डिक्शनरी की सभी वैल्यू को एक ही टाइप का बताया जाता है. हालांकि, इसमें यह नहीं बताया जाता कि कौनसी कुंजियां शामिल की जानी चाहिए.
    • उपयोगकर्ता के तय किए गए Pydantic मॉडल. इस तरीके से, कुंजियों के नाम तय किए जा सकते हैं. साथ ही, हर कुंजी से जुड़ी वैल्यू के लिए अलग-अलग टाइप तय किए जा सकते हैं. इनमें नेस्ट किए गए स्ट्रक्चर भी शामिल हैं.

JSON स्कीमा के साथ काम करता है

JSON स्कीमा, OpenAPI 3.0 से ज़्यादा नया स्पेसिफ़िकेशन है. स्कीमा ऑब्जेक्ट, इसी पर आधारित है. JSON स्कीमा के साथ काम करने की सुविधा, फ़ील्ड responseJsonSchema का इस्तेमाल करके झलक के तौर पर उपलब्ध है. यह फ़ील्ड, इन सीमाओं के साथ किसी भी JSON स्कीमा को स्वीकार करता है:

  • यह सुविधा सिर्फ़ Gemini 2.5 के साथ काम करती है.
  • सभी JSON स्कीमा प्रॉपर्टी पास की जा सकती हैं. हालांकि, सभी प्रॉपर्टी काम नहीं करती हैं. ज़्यादा जानकारी के लिए, फ़ील्ड से जुड़ा दस्तावेज़ देखें.
  • रिकर्सिव रेफ़रंस का इस्तेमाल सिर्फ़ किसी ऐसे ऑब्जेक्ट की वैल्यू के तौर पर किया जा सकता है जिसकी प्रॉपर्टी ज़रूरी नहीं है.
  • स्कीमा के साइज़ के आधार पर, रेफ़रंस को सीमित तौर पर अनरोल किया जाता है.
  • $ref वाले स्कीमा में, $ से शुरू होने वाली प्रॉपर्टी के अलावा कोई और प्रॉपर्टी नहीं हो सकती.

यहां Pydantic की मदद से JSON स्कीमा जनरेट करने और उसे मॉडल को सबमिट करने का एक उदाहरण दिया गया है:

curl "https://generativelanguage.googleapis.com/v1alpha/models/\
gemini-2.5-flash:generateContent" \
    -H "x-goog-api-key: $GEMINI_API_KEY"\
    -H 'Content-Type: application/json' \
    -d @- <<EOF
{
  "contents": [{
    "parts":[{
      "text": "Please give a random example following this schema"
    }]
  }],
  "generationConfig": {
    "response_mime_type": "application/json",
    "response_json_schema": $(python3 - << PYEOF
    from enum import Enum
    from typing import List, Optional, Union, Set
    from pydantic import BaseModel, Field, ConfigDict
    import json

    class UserRole(str, Enum):
        ADMIN = "admin"
        VIEWER = "viewer"

    class Address(BaseModel):
        street: str
        city: str

    class UserProfile(BaseModel):
        username: str = Field(description="User's unique name")
        age: Optional[int] = Field(ge=0, le=120)
        roles: Set[UserRole] = Field(min_items=1)
        contact: Union[Address, str]
        model_config = ConfigDict(title="User Schema")

    # Generate and print the JSON Schema
    print(json.dumps(UserProfile.model_json_schema(), indent=2))
    PYEOF
    )
  }
}
EOF

एसडीके का इस्तेमाल करते समय, JSON स्कीमा को सीधे तौर पर पास करने की सुविधा फ़िलहाल उपलब्ध नहीं है.

सबसे सही तरीके

जवाब के स्कीमा का इस्तेमाल करते समय, इन बातों का ध्यान रखें और सबसे सही तरीके अपनाएं:

  • आपके जवाब के स्कीमा का साइज़, इनपुट टोकन की सीमा में शामिल होता है.
  • डिफ़ॉल्ट रूप से, फ़ील्ड ज़रूरी नहीं होते. इसका मतलब है कि मॉडल, फ़ील्ड में जानकारी भर सकता है या उन्हें छोड़ सकता है. मॉडल को वैल्यू देने के लिए मजबूर करने के लिए, फ़ील्ड को 'ज़रूरी' के तौर पर सेट किया जा सकता है. अगर इनपुट प्रॉम्प्ट में ज़रूरी कॉन्टेक्स्ट नहीं दिया गया है, तो मॉडल मुख्य रूप से उस डेटा के आधार पर जवाब जनरेट करता है जिस पर उसे ट्रेन किया गया है.

  • कॉम्प्लेक्स स्कीमा की वजह से, InvalidArgument: 400 गड़बड़ी हो सकती है. जटिलता, प्रॉपर्टी के लंबे नामों, ऐरे की लंबाई की सीमाएं, कई वैल्यू वाले एनम, कई वैकल्पिक प्रॉपर्टी वाले ऑब्जेक्ट या इन फ़ैक्टर के कॉम्बिनेशन की वजह से हो सकती है.

    अगर आपको मान्य स्कीमा के साथ यह गड़बड़ी दिखती है, तो इसे ठीक करने के लिए इनमें से एक या एक से ज़्यादा बदलाव करें:

    • प्रॉपर्टी के नाम या enum के नाम छोटे करें.
    • नेस्ट किए गए ऐरे को फ़्लैट करता है.
    • सीमाओं वाली प्रॉपर्टी की संख्या कम करें. जैसे, कम से कम और ज़्यादा से ज़्यादा सीमा वाली संख्याएं.
    • जटिल शर्तों वाली प्रॉपर्टी की संख्या कम करें. जैसे, date-time जैसे जटिल फ़ॉर्मैट वाली प्रॉपर्टी.
    • ज़रूरी नहीं वाली प्रॉपर्टी की संख्या कम करें.
    • एनम के लिए मान्य वैल्यू की संख्या कम करें.

  • अगर आपको मनमुताबिक नतीजे नहीं मिल रहे हैं, तो अपने इनपुट प्रॉम्प्ट में ज़्यादा कॉन्टेक्स्ट जोड़ें या अपने जवाब के स्कीमा में बदलाव करें. उदाहरण के लिए, मॉडल के रिस्पॉन्स की समीक्षा करें. इसमें स्ट्रक्चर्ड आउटपुट शामिल नहीं होना चाहिए, ताकि यह देखा जा सके कि मॉडल किस तरह से जवाब देता है. इसके बाद, जवाब के स्कीमा को अपडेट किया जा सकता है, ताकि वह मॉडल के आउटपुट के हिसाब से बेहतर हो. स्ट्रक्चर्ड आउटपुट से जुड़ी समस्या हल करने के बारे में ज़्यादा जानकारी के लिए, समस्या हल करने की गाइड देखें.

आगे क्या करना है

अब जब आपको स्ट्रक्चर्ड आउटपुट जनरेट करने का तरीका पता चल गया है, तो हो सकता है कि आपको Gemini API के टूल इस्तेमाल करने हों: