आपके कोड को डेटा चाहिए, और मॉडल टेक्स्ट लिखते हैं। स्ट्रक्चर्ड आउटपुट यह दूरी पाटता है, लेकिन “मॉडल 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 के रूप में सूचीबद्ध होनी चाहिए।
आपका प्रोवाइडर कौन-सा मोड सपोर्ट करता है?
किसी मॉडल पर कुछ बनाने से पहले यह टेस्ट एक बार चलाएँ:
json_schemaके साथ ऐसा प्रॉम्प्ट भेजें जो एक अतिरिक्त फ़ील्ड माँगे (“साथ में एक छोटी टिप्पणी भी जोड़ें”)।- अगर अनुरोध एरर देता है, तो प्रोवाइडर
json_schemaस्वीकार नहीं करता।json_objectआज़माएँ। - अगर जवाब में अतिरिक्त फ़ील्ड है, तो स्कीमा लागू नहीं हो रहा। इसे JSON mode मानें।
- अगर
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” मॉडल को ठीक करने के लिए कुछ ठोस देता है।
- बिज़नेस नियम कोड में जाँचें। स्कीमा यह नहीं कह सकता कि टोटल उसके लाइन आइटम के बराबर होना चाहिए। ऊपर की जाँच कह सकती है।
- कोशिशें सीमित रखें। हर कोशिश पूरा प्रॉम्प्ट इनपुट टोकन के रूप में दोबारा भेजती है।
स्कीमा के कौन-से फ़ीचर दिक़्क़त देते हैं?
स्कीमा सीधे-सादे रखें:
- नेस्टेड से फ़्लैट बेहतर। ज़्यादातर एक्सट्रैक्शन के लिए दो स्तर काफ़ी हैं।
- कैटेगरी के लिए खुले स्ट्रिंग की जगह enum।
- कोई खुले-अंत वाले ऑब्जेक्ट नहीं। फ़्री-फ़ॉर्म
dictफ़ील्ड पूरा मक़सद ही ख़त्म कर देते हैं। - विवरण के साथ छोटे फ़ील्ड नाम। स्कीमा में दिए विवरण मॉडल को राह दिखाते हैं।
- वैकल्पिक फ़ील्ड 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 के लिए स्ट्रक्चर्ड आउटपुट नहीं बताता, इसलिए वहाँ वैलिडेशन के साथ सिर्फ़ प्रॉम्प्ट वाला तरीक़ा इस्तेमाल करें। प्रति टोकन कीमतों की तुलना प्राइसिंग पेज पर करें।
