Gemini API की मदद से स्ट्रक्चर्ड आउटपुट जनरेट करें

Python Node.js Go Dart (Flutter) Android Swift वेब REST

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

यहां कुछ ऐसे इस्तेमाल के उदाहरण दिए गए हैं जिनमें मॉडल से स्ट्रक्चर्ड आउटपुट की ज़रूरत पड़ सकती है:

• अखबार के लेखों से कंपनी की जानकारी इकट्ठा करके, कंपनियों का डेटाबेस बनाएं.
• रीज़्यूमे से स्टैंडर्ड जानकारी निकालना.
• रेसिपी से सामग्री निकालें और हर सामग्री के लिए, किराने की सामान बेचने वाली वेबसाइट का लिंक दिखाएं.

अपने प्रॉम्प्ट में, Gemini से JSON फ़ॉर्मैट में आउटपुट देने के लिए कहा जा सकता है. हालांकि, ध्यान रखें कि यह ज़रूरी नहीं है कि मॉडल सिर्फ़ JSON फ़ॉर्मैट में आउटपुट दे. ज़्यादा सटीक जवाब पाने के लिए, responseSchema फ़ील्ड में कोई खास JSON स्कीमा पास किया जा सकता है, ताकि Gemini हमेशा उम्मीद के मुताबिक स्ट्रक्चर में जवाब दे. स्कीमा के साथ काम करने के बारे में ज़्यादा जानने के लिए, JSON स्कीमा के बारे में ज़्यादा जानकारी देखें.

इस गाइड में, अपनी पसंद के SDK टूल के ज़रिए generateContent तरीके का इस्तेमाल करके या सीधे REST API का इस्तेमाल करके, JSON जनरेट करने का तरीका बताया गया है. उदाहरणों में सिर्फ़ टेक्स्ट वाला इनपुट दिखाया गया है. हालांकि, Gemini मल्टीमोडल अनुरोधों के लिए JSON रिस्पॉन्स भी जनरेट कर सकता है. इनमें इमेज, वीडियो, और ऑडियो शामिल हैं.

शुरू करने से पहले: अपना प्रोजेक्ट और एपीआई पासकोड सेट अप करना

Gemini API को कॉल करने से पहले, आपको अपना प्रोजेक्ट सेट अप करना होगा और अपनी एपीआई पासकोड को कॉन्फ़िगर करना होगा.

JSON जेनरेट करें

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

स्कीमा की मदद से, JSON रिस्पॉन्स के स्ट्रक्चर को कंट्रोल किया जा सकता है. मॉडल में स्कीमा डालने के दो तरीके हैं:

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

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

नीचे दिए गए उदाहरण में, मॉडल को किसी खास JSON फ़ॉर्मैट में कुकी रेसिपी दिखाने के लिए कहा गया है.

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

from google import genai

prompt = """List a few popular cookie recipes in JSON format.

Use this JSON schema:

Recipe = {'recipe_name': str, 'ingredients': list[str]}
Return: list[Recipe]"""

client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model='gemini-2.0-flash',
    contents=prompt,
)

# Use the response as a JSON string.
print(response.text)

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

[
  {
    "recipe_name": "Chocolate Chip Cookies",
    "ingredients": [
      "2 1/4 cups all-purpose flour",
      "1 teaspoon baking soda",
      "1 teaspoon salt",
      "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 cups chocolate chips"
    ]
  },
  ...
]

मॉडल कॉन्फ़िगरेशन की मदद से स्कीमा देना

यहां दिए गए उदाहरण में ये काम किए गए हैं:

1. JSON के साथ जवाब देने के लिए, स्कीमा के ज़रिए कॉन्फ़िगर किए गए मॉडल को इंस्टैंशिएट करता है.
2. मॉडल को कुकी की रेसिपी दिखाने के लिए कहता है.

JSON स्कीमा को बताने का यह तरीका ज़्यादा औपचारिक है. इससे आपको प्रॉम्प्ट में सिर्फ़ टेक्स्ट पर भरोसा करने के बजाय, ज़्यादा सटीक कंट्रोल मिलता है.

from google import genai
from pydantic import BaseModel


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


client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model='gemini-2.0-flash',
    contents='List a few popular cookie recipes. Be sure to 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

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

[
  {
    "recipe_name": "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"
    ]
  },
  ...
]

स्कीमा डेफ़िनिशन सिंटैक्स

अपने मॉडल कॉन्फ़िगरेशन की response_schema प्रॉपर्टी में, JSON रिस्पॉन्स के लिए स्कीमा तय करें. response_schema की वैल्यू इनमें से कोई एक होनी चाहिए:

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

टाइप के साथ स्कीमा तय करना

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

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

Gemini API की Python क्लाइंट लाइब्रेरी, इन टाइप के स्कीमा के साथ काम करती है (AllowedType, अनुमति वाले किसी भी टाइप का हो सकता है):

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

आउटपुट को सीमित करने के लिए, एनम का इस्तेमाल करना

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

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

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

from google import genai
import enum

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

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

print(response.text)
# Woodwind

Python SDK, एपीआई के लिए टाइप के एलान का अनुवाद करेगा. हालांकि, एपीआई, OpenAPI 3.0 स्कीमा (स्कीमा) के सबसेट को स्वीकार करता है. स्कीमा को JSON के तौर पर भी पास किया जा सकता है:

from google import genai

client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model='gemini-2.0-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 या फ़ंक्शन कॉल करने के लिए, स्कीमा में कहीं भी एनम का इस्तेमाल किया जा सकता है. उदाहरण के लिए, मॉडल से रेसिपी के टाइटल की सूची मांगी जा सकती है. साथ ही, हर टाइटल को लोकप्रियता का ग्रेड देने के लिए, Grade एनम का इस्तेमाल किया जा सकता है:

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(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model='gemini-2.0-flash',
    contents='List 10 home-baked cookies and give them grades based on tastiness.',
    config={
        'response_mime_type': 'application/json',
        'response_schema': list[Recipe],
    },
)

print(response.text)
# [{"rating": "a+", "recipe_name": "Classic Chocolate Chip Cookies"}, ...]

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

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

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

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

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

• string -> enum, format
• integer -> फ़ॉर्मैट
• number -> फ़ॉर्मैट
• bool
• array -> minItems, maxItems, items
• 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": "bool" }

{ "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 जनरेटिव एआई SDK टूल इस क्रम को सेव कर सकते हैं. अगर कॉन्फ़िगर किए गए स्कीमा के साथ मॉडल को उदाहरण दिए जा रहे हैं और उदाहरणों की प्रॉपर्टी का क्रम, स्कीमा की प्रॉपर्टी के क्रम से मेल नहीं खाता है, तो आउटपुट गलत या अनचाहा हो सकता है.

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

"propertyOrdering": ["recipe_name", "ingredients"]

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