BroadRouter

JSON mode बनाम json_schema: भरोसेमंद स्ट्रक्चर्ड आउटपुट

BroadNet Inference टीम · 4 मिनट में पढ़ें · प्रकाशित

JSON mode (response_format json_object) सिर्फ़ वैध JSON का वादा करता है। स्ट्रक्चर्ड आउटपुट (response_format json_schema) आपके फ़ील्ड और टाइप का भी वादा करता है, जहाँ प्रोवाइडर इसे लागू करता है। दोनों में finish_reason जाँचें, पार्स करें, और Pydantic मॉडल जैसे स्कीमा से वैलिडेट करें। वैलिडेशन फ़ेल हो, तो एरर वापस भेजकर फिर माँगें, कोशिशों की पक्की सीमा के साथ।

आपके कोड को डेटा चाहिए, और मॉडल टेक्स्ट लिखते हैं। स्ट्रक्चर्ड आउटपुट यह दूरी पाटता है, लेकिन “मॉडल JSON लौटाता है” के तीन अलग मतलब हैं, इस पर निर्भर करते हुए कि आप कैसे माँगते हैं। यह पोस्ट OpenAI-कम्पैटिबल ओपन मॉडल पर इन विकल्पों की तुलना करती है, हर एक को माँगने का तरीक़ा दिखाती है, और एक वैलिडेट-और-रिपेयर लूप देती है जिसे आप सीधे प्रोडक्शन में लगा सकते हैं।

JSON mode और json_schema में क्या फ़र्क़ है?

तरीक़ा अनुरोध आपको किस बात का वादा मिलता है
सिर्फ़ प्रॉम्प्ट “इन फ़ील्ड के साथ JSON में जवाब दें…” किसी बात का नहीं; आम तौर पर JSON, कभी-कभी अतिरिक्त टेक्स्ट के साथ
JSON mode response_format: {"type": "json_object"} वैध JSON, कोई भी ढाँचा
स्ट्रक्चर्ड आउटपुट response_format: {"type": "json_schema", ...} आपके स्कीमा से मेल खाता JSON, जहाँ लागू किया गया हो

OpenAI की Structured Outputs गाइड यह सीधे कहती है: “While both ensure valid JSON is produced, only Structured Outputs ensure schema adherence.” (अनुवाद: दोनों वैध JSON बनना पक्का करते हैं, लेकिन स्कीमा का पालन सिर्फ़ Structured Outputs पक्का करते हैं।) वह जहाँ भी संभव हो, JSON mode की जगह स्ट्रक्चर्ड आउटपुट की सलाह देती है।

ओपन मॉडल के प्रोवाइडर पर यह गारंटी इस पर निर्भर करती है कि सर्वर इसे कैसे लागू करता है। कई constrained decoding इस्तेमाल करते हैं, जो उन टोकन को रोक देता है जो स्कीमा तोड़ते। कुछ फ़ील्ड स्वीकार तो करते हैं लेकिन उसे लागू नहीं करते। इसीलिए नीचे का कोड हर हाल में वैलिडेट करता है।

json_schema कैसे माँगें?

import os
from openai import OpenAI
from pydantic import BaseModel, Field

client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])

class Invoice(BaseModel):
    vendor: str
    currency: str = Field(pattern="^[A-Z]{3}$")
    total: float
    line_items: list[float]

schema = Invoice.model_json_schema()
schema["additionalProperties"] = False

response_format = {"type": "json_schema",
                   "json_schema": {"name": "invoice", "strict": True, "schema": schema}}

Pydantic आपकी क्लास से JSON Schema बनाता है, इसलिए स्कीमा और वैलिडेटर कभी अलग नहीं होते। अगर आप Pydantic इस्तेमाल नहीं करते, तो JSON schema जेनरेटर एक सैंपल ऑब्जेक्ट से strict mode वाला स्कीमा बना देता है। strict mode के लिए OpenAI को additionalProperties: false चाहिए और हर प्रॉपर्टी required के रूप में सूचीबद्ध होनी चाहिए।

आपका प्रोवाइडर कौन-सा मोड सपोर्ट करता है?

किसी मॉडल पर कुछ बनाने से पहले यह टेस्ट एक बार चलाएँ:

  1. json_schema के साथ ऐसा प्रॉम्प्ट भेजें जो एक अतिरिक्त फ़ील्ड माँगे (“साथ में एक छोटी टिप्पणी भी जोड़ें”)।
  2. अगर अनुरोध एरर देता है, तो प्रोवाइडर json_schema स्वीकार नहीं करता। json_object आज़माएँ।
  3. अगर जवाब में अतिरिक्त फ़ील्ड है, तो स्कीमा लागू नहीं हो रहा। इसे JSON mode मानें।
  4. अगर json_object भी एरर देता है, तो वैलिडेशन के साथ सिर्फ़ प्रॉम्प्ट वाला तरीक़ा इस्तेमाल करें।

BroadNet Inference पर डॉक्यूमेंटेशन GLM 5.3 और Qwen3.8 27B (आमने-सामने तुलना) के लिए स्ट्रक्चर्ड आउटपुट दिखाता है, लेकिन अनुरोध का पैरामीटर नहीं बताता। जिस मॉडल को आप प्रोडक्शन में ले जाते हैं, उस पर ऊपर का टेस्ट चलाएँ।

ग़लत आउटपुट को वैलिडेट और रिपेयर कैसे करें?

import json
from pydantic import ValidationError

def extract(text: str, model="broadnet/glm-5.3", attempts=3) -> Invoice:
    messages = [
        {"role": "system", "content": "Extract the invoice. Reply with JSON only."},
        {"role": "user", "content": text},
    ]
    for attempt in range(attempts):
        r = client.chat.completions.create(model=model, messages=messages,
                                           response_format=response_format,
                                           max_tokens=4000)
        choice = r.choices[0]
        if choice.finish_reason == "length":
            raise RuntimeError("Cut off: raise max_tokens")  # retrying won't help
        if getattr(choice.message, "refusal", None):
            raise RuntimeError(f"Refused: {choice.message.refusal}")
        raw = choice.message.content or ""
        try:
            inv = Invoice.model_validate_json(raw)
            if abs(sum(inv.line_items) - inv.total) > 0.01:
                raise ValueError("total must equal the sum of line_items")
            return inv
        except (ValidationError, ValueError) as e:
            messages += [
                {"role": "assistant", "content": raw},
                {"role": "user", "content": f"That JSON is invalid: {e}. Return corrected JSON only."},
            ]
    raise RuntimeError(f"No valid JSON after {attempts} attempts")

यह लूप क्यों काम करता है:

  • पहले finish_reason जाँचें। जो जवाब max_tokens तक पहुँच गया, वह कटा हुआ JSON है। उसी सीमा के साथ रीट्राई उसी तरह फ़ेल होगा। ऊपर के दोनों मॉडल जवाब देने से पहले रीज़निंग करते हैं, और रीज़निंग सीमा में गिनी जाती है, इसलिए जगह छोड़ें।
  • इनकार को अलग से सँभालें। OpenAI की गाइड बताती है कि इनकार “does not necessarily follow the schema you have supplied” (अनुवाद: ज़रूरी नहीं कि आपके दिए स्कीमा का पालन करे)।
  • सटीक एरर वापस भेजें। बिना जानकारी का रीट्राई अक्सर वही ग़लती लौटाता है। “line_items: field required” मॉडल को ठीक करने के लिए कुछ ठोस देता है।
  • बिज़नेस नियम कोड में जाँचें। स्कीमा यह नहीं कह सकता कि टोटल उसके लाइन आइटम के बराबर होना चाहिए। ऊपर की जाँच कह सकती है।
  • कोशिशें सीमित रखें। हर कोशिश पूरा प्रॉम्प्ट इनपुट टोकन के रूप में दोबारा भेजती है।

स्कीमा के कौन-से फ़ीचर दिक़्क़त देते हैं?

स्कीमा सीधे-सादे रखें:

  1. नेस्टेड से फ़्लैट बेहतर। ज़्यादातर एक्सट्रैक्शन के लिए दो स्तर काफ़ी हैं।
  2. कैटेगरी के लिए खुले स्ट्रिंग की जगह enum।
  3. कोई खुले-अंत वाले ऑब्जेक्ट नहीं। फ़्री-फ़ॉर्म dict फ़ील्ड पूरा मक़सद ही ख़त्म कर देते हैं।
  4. विवरण के साथ छोटे फ़ील्ड नाम। स्कीमा में दिए विवरण मॉडल को राह दिखाते हैं।
  5. वैकल्पिक फ़ील्ड nullable के रूप में। strict mode में हर फ़ील्ड को required सूचीबद्ध करें और null की अनुमति दें।

OpenAI की गाइड बताती है कि JSON Schema के कुछ फ़ीचर strict mode में सपोर्ट नहीं होते। ओपन मॉडल सर्वर की अपनी सीमाएँ होती हैं। अगर कोई स्कीमा अस्वीकार हो जाए, तो मोड बदलने से पहले उसे सरल करें।

प्रोडक्शन में स्ट्रक्चर्ड आउटपुट की निगरानी कैसे करें?

चुपचाप रिपेयर करने वाला लूप ऐसी समस्या छिपा सकता है जो आपसे रोज़ टोकन ख़र्च करवाती है। हर कॉल साइट पर तीन संख्याएँ लॉग करें:

मेट्रिक यह क्या बताता है
पहली कोशिश में सफलता की दर मॉडल और स्कीमा कितने मेल खाते हैं; गिरावट अक्सर प्रॉम्प्ट या मॉडल बदलने के बाद आती है
हर सफलता पर औसत कोशिशें रिपेयर की टोकन लागत
आख़िरी विफलताएँ वे इनपुट जिन्हें आपकी पाइपलाइन नहीं सँभाल पाती; इन्हें हाथ से देखें

अगर पहली कोशिश की सफलता आपकी सामान्य दर से नीचे गिरे, तो और रीट्राई जोड़ने से पहले स्कीमा सरल करें या कोई दूसरा मॉडल आज़माएँ। फ़ेल हुए कच्चे जवाबों का एक सैंपल रखें, ताकि आप सुधारों को असली मामलों पर टेस्ट कर सकें।

इसकी जगह टूल कब इस्तेमाल करें?

आख़िरी जवाब के लिए स्ट्रक्चर्ड आउटपुट इस्तेमाल करें: एक्सट्रैक्शन, वर्गीकरण, योजना। टूल कॉलिंग तब इस्तेमाल करें जब मॉडल को आपके कोड से कुछ करवाना हो और फिर आगे बढ़ना हो। कई एजेंट दोनों इस्तेमाल करते हैं: लूप के दौरान टूल, और आख़िरी कदम के लिए स्कीमा। इमेज से JSON के उदाहरण के लिए विज़न मॉडल से अरबी इनवॉइस पढ़ना देखें।

BroadNet Inference कहाँ फ़िट होता है

BroadNet Inference, GLM 5.3 और Qwen3.8 27B के लिए स्ट्रक्चर्ड आउटपुट दिखाता है, मानक chat-completions फ़ॉर्मैट के पीछे, इसलिए ऊपर का कोड OpenAI Python SDK के साथ बिना बदलाव चलता है। Qwen3.8 27B इमेज भी लेता है, जो डॉक्यूमेंट एक्सट्रैक्शन के लिए ठीक है। BroadNet का डॉक्यूमेंटेशन DeepSeek V4.1 Flash या Gemma 4 VL 26B के लिए स्ट्रक्चर्ड आउटपुट नहीं बताता, इसलिए वहाँ वैलिडेशन के साथ सिर्फ़ प्रॉम्प्ट वाला तरीक़ा इस्तेमाल करें। प्रति टोकन कीमतों की तुलना प्राइसिंग पेज पर करें।

अक्सर पूछे जाने वाले सवाल

JSON mode और स्ट्रक्चर्ड आउटपुट में क्या फ़र्क़ है?

JSON mode, यानी response_format का type json_object, सिर्फ़ यह वादा करता है कि जवाब JSON के रूप में पार्स होगा। स्ट्रक्चर्ड आउटपुट, यानी type json_schema, आपके तय किए फ़ील्ड और टाइप का भी वादा करता है, जहाँ प्रोवाइडर इसे लागू करता है। OpenAI जहाँ संभव हो, JSON mode की जगह स्ट्रक्चर्ड आउटपुट की सलाह देता है।

क्या ओपन मॉडल json_schema वाला response_format सपोर्ट करते हैं?

यह प्रोवाइडर पर निर्भर है। कुछ json_schema स्वीकार करते हैं, कुछ सिर्फ़ json_object, और कुछ इस फ़ील्ड को अनदेखा कर देते हैं। एक स्कीमा और ऐसे प्रॉम्प्ट के साथ टेस्ट अनुरोध भेजें जो मॉडल को एक अतिरिक्त फ़ील्ड जोड़ने के लिए उकसाए, फिर जवाब जाँचें।

क्या स्ट्रक्चर्ड आउटपुट को फिर भी वैलिडेट करना ज़रूरी है?

हाँ। जवाब max_tokens से कट सकते हैं, इनकार हो सकते हैं, और ऐसे बिज़नेस नियम तोड़ सकते हैं जिन्हें स्कीमा व्यक्त नहीं कर सकता, जैसे ऐसे टोटल जिनका जोड़ मिलना चाहिए।

अमान्य JSON को कितनी बार रीट्राई करें?

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

स्ट्रक्चर्ड आउटपुट इस्तेमाल करूँ या टूल कॉलिंग?

जब आपको आख़िरी जवाब एक तय ढाँचे में चाहिए, तो स्ट्रक्चर्ड आउटपुट। जब मॉडल को आपके कोड से कुछ करवाकर आगे बढ़ना है, तो टूल कॉलिंग।

Markdown में पढ़ेंChatGPT से पूछेंClaude से पूछेंPerplexity से पूछें