Phase 13: Tools & Protocols

संरचित आउटपुट JSON योजना, पायदान्टिक, Zod, प्रतिबंधित डिकोडिंग

"मोडेल को JSON वापस करने के लिए अच्छी तरह से पूछें" 5 से 15 प्रतिशत समय में विफल रहता है, यहां तक कि सीमा मॉडल पर भी। संरचित आउटपुट प्रतिबंधित डिकोडिंग के साथ उस अंतर को बंद करते हैंः मॉडल को शाब्दिक रूप से एक टोकन जारी करने से रोका जाता है जो योजना का उल्लंघन करेगा। ओपनएआई का सख्त मोड, एंथ्रोपिक का स्कीमा-टाइप किए गए उपकरण का उपयोग, मिथुन का responseSchema, पाइडान्टिक एआई output_type, और Zod के .parseइस पाठ में स्कीमा वैधता का निर्माण किया गया है और सख्त मोड अनुबंध सीखने वाले प्रत्येक उत्पादन निष्कर्षण पाइपलाइन के लिए उपयोग करेंगे।

Type: Build

Languages: Python (stdlib, JSON Schema 2020-12 subset)

Prerequisites: Phase 13 · 02 (function calling deep dive)

Time: ~75 minutes

सीखने के लक्ष्य

सही प्रतिबंधों (enum, min/max, आवश्यक, पैटर्न) का उपयोग करके निष्कर्षण लक्ष्य के लिए JSON Schema 2020-12 लिखें।
स्पष्ट करें कि क्यों सख्त मोड और सीमित डिकोडिंग "जनरेशन के बाद वैधता" से अलग गारंटी देती है।
तीन विफलता मोडों में अंतर करेंः विश्लेषण त्रुटि, योजना उल्लंघन, मॉडल अस्वीकरण।
टाइप की गई मरम्मत और टाइप की गई अस्वीकार प्रसंस्करण के साथ एक निष्कर्षण पाइपलाइन भेजें।

समस्या

एक एजेंट खरीद आदेश ईमेल पढ़ने के लिए मुक्त पाठ में बदलना चाहिए {customer, line_items, total_usd}तीन दृष्टिकोण।

Approach one: prompt for JSON."ग्राहक, लाइन_इटम, कुल_यूएसडी के साथ JSON में फ़ील्ड का जवाब दें।" सीमा मॉडल पर 85 से 95 प्रतिशत समय पर काम करता है। छह तरीकों से विफल होता हैः गायब ब्रैस, पीछे वाला अल्पविराम, गलत प्रकार, भ्रमग्रस्त फ़ील्ड, टोकन सीमा पर ट्रंक, लीक प्रोसा जैसे "यहां आपका JSON हैः।"

Approach two: validate after generation.स्वतंत्र रूप से उत्पन्न करें, विश्लेषण करें, स्कीम के खिलाफ मान्य करें, विफलता पर पुनः प्रयास करें। विश्वसनीय लेकिन महंगी आप प्रत्येक पुनः प्रयास के लिए भुगतान करते हैं, और ट्रंकिंग बग प्रति घटना एक अतिरिक्त वक्र लागत है।

Approach three: constrained decoding.प्रदाता स्कीमा को डिकोड करने के समय लागू करता है। अमान्य टोकन नमूना वितरण से बाहर छिपे जाते हैं। आउटपुट को विश्लेषण करने और सत्यापित करने की गारंटी है। विफलता एक मोड में गिर जाती हैः अस्वीकार (मॉडल निर्णय लेता है कि इनपुट स्कीमा के अनुरूप नहीं है) ।

2026 तक हर सीमा प्रदाता किसी न किसी तरह का दृष्टिकोण 3 भेजता है।

OpenAI. response_format: {type: "json_schema", strict: true}और refusalयदि मॉडल घटता है तो प्रतिक्रिया में।
Anthropic.योजना के कार्यान्वयन परtool_useइनपुट; stop_reason: "refusal"यह एक बात नहीं है, लेकिन end_turnबिना उपकरण कॉल संकेत है।
Gemini. responseSchemaअनुरोध स्तर पर; 2026 में मिथुन चयनित प्रकारों के लिए टोकन स्तर के व्याकरण प्रतिबंध भेजता है।
Pydantic AI. output_type=InvoiceModelएक संरचित प्रक्षेपण करता है RunResultInvoiceModel. .
Zod (TypeScript).रनटाइम पार्सर जो एक Zod योजना के खिलाफ प्रदाता आउटपुट को मान्य करता है; OpenAI के साथ जोड़े beta.chat.completions.parse. .

सामान्य मुद्दा: योजना को एक बार घोषित करें, इसे अंत से अंत तक लागू करें।

अवधारणा

JSON योजना 2020-12 भाषा

प्रत्येक प्रदाता JSON Schema 2020-12 को स्वीकार करता है। आप सबसे अधिक उपयोग करने वाले निर्माणः

typeobject,array,string,number,integer,boolean,null. .
properties: उप-अनुसूची के लिए फ़ील्ड नाम का नक्शा।
required: क्षेत्र के नामों की सूची जो दिखाई देनी चाहिए।
enum: अनुमत मानों का बंद सेट।
minimum/maximum(संख्याएँ), minLength/maxLength/pattern(कणों) ।
items: प्रत्येक सरणी तत्व पर लागू उप-अनुसूची।
additionalPropertiesfalseअतिरिक्त फ़ील्ड को प्रतिबंधित करता है (पूर्वनिर्धारित मोड के अनुसार भिन्न होता है) ।

OpenAI सख्त मोड में तीन आवश्यकताएं शामिल हैंः प्रत्येक संपत्ति को सूचीबद्ध किया जाना चाहिए required,additionalProperties: falseहर जगह, और कोई भी अनसुलझा $refयदि आप इन तोड़ते हैं, एपीआई अनुरोध समय पर 400 वापस आ जाएगा.

पायदान्टिक, पायथन बंधन

Pydantic v2 डेटा क्लास के आकार के मॉडल से JSON योजना उत्पन्न करता है model_json_schema()पायदान्टिक एआई इस को लिपटे तो आप लिखते हैंः

pythonclass Invoice(BaseModel):
    customer: str
    line_items: list[LineItem]
    total_usd: Decimal

और एजेंट फ्रेमवर्क स्कीम को ओपनएआई सख्त मोड में अनुवाद करता है, मानव input_schema, या जुड़वां responseSchemaमॉडल के आउटपुट टाइप किया गया है के रूप में वापस आता हैInvoiceउदाहरण. सत्यापन त्रुटियों बढ़ते हैं ValidationErrorटाइप त्रुटि पथ के साथ।

Zod, टाइपस्क्रिप्ट बंधन

ज़ोड (z.object({customer: z.string(), ...})) TS समकक्ष है। OpenAI के नोड SDK उजागर करता है zodResponseFormat(Invoice)जो एपीआई के JSON योजना के उपयोगिता लोड में अनुवाद करता है।

अस्वीकरण

यदि इनपुट स्कीमा में फिट नहीं हो सकता है ("ईमेल एक कविता थी, एक चालान नहीं"), तो मॉडल एक refusalआपके कोड को इसे एक प्रथम श्रेणी के परिणाम के रूप में संभालना चाहिए, एक विफलता नहीं। अस्वीकृति सुरक्षा संकेत के रूप में भी उपयोगी हैः एक मॉडल से संरक्षित सामग्री वाले ईमेल से क्रेडिट कार्ड नंबर निकालने के लिए कहा गया एक अस्वीकृति सुरक्षा कारण के साथ वापस आता है।

खुले में प्रतिबंधित डिकोडिंग

खुले वजन के कार्यान्वयन में तीन तकनीकें प्रयोग की जाती हैं।

Grammar-based decoding(outlines,guidance,lm-format-enforcer): स्कीम से एक निर्धारात्मक परिमित ऑटोमैटोन का निर्माण करें; प्रत्येक चरण में, FSM का उल्लंघन करने वाले टोकन के लॉजिट को छिपाएं।
Logit masking with a JSON parser: मॉडल के साथ लॉकस्टेप में स्ट्रीमिंग JSON पार्सर चलाएं; प्रत्येक चरण में, मान्य-अगले टोकन सेट की गणना करें।
Speculative decoding with a verifier: सस्ते ड्राफ्ट मॉडल टोकन का प्रस्ताव देता है, सत्यापनकर्ता योजना को लागू करता है।

2026 में, लघु संरचनात्मक आउटपुट के लिए सामान्य पीढ़ी से तेज और लंबे आउटपुट के लिए लगभग समान गति है।

तीन विफलता मोड

Parse error.आउटपुट मान्य नहीं है JSON. यह सख्त मोड में नहीं हो सकता है. यह अभी भी गैर-सख्त प्रदाताओं पर हो सकता है.
Schema violation.आउटपुट विश्लेषण करता है, लेकिन योजना का उल्लंघन करता है. यह सख्त मोड में नहीं हो सकता. यह बाहर आम है.
Refusal.मॉडल गिरावट है. एक टाइप परिणाम के रूप में संभाला जाना चाहिए.

पुनः प्रयास की रणनीति

जब आप सख्त मोड के बाहर हैं (मानव उपकरण उपयोग, गैर-सख्त ओपनएआई, पुराने जुड़वां), पुनर्प्राप्ति पैटर्न हैः

generate -> parse -> validate -> if fail, inject error and retry, max 3x

एक पुनः प्रयास आमतौर पर पर्याप्त होता है। तीन पुनः प्रयास कमजोर मॉडल फ्लेक्स को पकड़ते हैं। तीन से आगे एक खराब योजना का संकेत हैः मॉडल कुछ इनपुट के लिए इसे संतुष्ट नहीं कर सकता है, और प्रॉम्प्ट या योजना को ठीक करने की आवश्यकता है।

छोटे मॉडल के लिए सहायता

सीमित डिकोडिंग छोटे मॉडल पर काम करता है। व्याकरण प्रवर्तन के साथ 3 बी-पैरामीटर खुला मॉडल संरचित कार्यों पर कच्चे संकेत के साथ 70 बी-पैरामीटर मॉडल से बेहतर प्रदर्शन करता है। यह संरचनात्मक आउटपुट उत्पादन के लिए मायने रखता है: यह मॉडल आकार से विश्वसनीयता को अलग करता है।

इसका प्रयोग करें

code/main.pystdlib में न्यूनतम JSON Schema 2020-12 सत्यापनकर्ता (प्रकार, आवश्यक, enum, min/max, पैटर्न, आइटम, अतिरिक्त गुण) भेजता है। यह एक Invoiceस्कीमा और सत्यापनकर्ता के माध्यम से एक नकली एलएलएम आउटपुट चलाता है, विश्लेषण त्रुटि, स्कीमा उल्लंघन, और अस्वीकार पथ प्रदर्शित करता है। उत्पादन में किसी भी प्रदाता की वास्तविक प्रतिक्रिया के लिए नकली आउटपुट को बदलें।

क्या देखना हैः

सत्यापनकर्ता टाइप की गई एक लौटाता है [ValidationError]पथ और संदेश के साथ सूची. यह आकार आप पुनः प्रयास प्रलोभन में दिखाई देना चाहते हैं.
अस्वीकार शाखा पुनः प्रयास नहीं करती है। यह लॉग करती है और टाइप किए गए अस्वीकार को लौटा देती है। चरण 14 · 09 सुरक्षा संकेत के रूप में अस्वीकार का उपयोग करता है।
additionalProperties: falseप्रतिकूल परीक्षण इनपुट पर आग की जांच करें, यह दिखाने के लिए कि कठोर मोड का कारण है कि पग्लाने वाले क्षेत्रों पर दरवाजा बंद हो जाता है।

इसे भेजें

यह सबक हमें फल देता हैoutputs/skill-structured-output-designer.md. मुक्त पाठ निष्कर्षण लक्ष्य (इंफॉक्स, समर्थन टिकट, जीवन शैली, आदि) को देखते हुए, कौशल एक JSON योजना 2020-12 का उत्पादन करता है जो कि कठोर मोड-संगत है और एक पायदान्टिक मॉडल जो इसे दर्पण करता है, जिसमें टाइप किए गए अस्वीकार और पुनः प्रयास हैंडलिंग स्टब किया गया है।

व्यायाम

दौड़ेंcode/main.py. एक चौथा परीक्षण मामला जोड़ा total_usdपुष्टि करें कि सत्यापितकर्ता इसे खारिज करता हैminimumप्रतिबंध पथ।

समर्थन करने के लिए वैधकर्ता का विस्तार करें oneOfएक भेदभावकर्ता के साथ।line_item द्वारा चिह्नित एक उत्पाद या सेवा हैkind. सख्त मोड में यहां सूक्ष्म नियम हैं; OpenAI के संरचित आउटपुट गाइड की जाँच करें।

एक Pydantic BaseModel के रूप में एक ही चालान योजना लिखें और तुलना model_json_schema()अपने हाथ से रोल किए गए स्कीमा में आउटपुट. डिफ़ॉल्ट रूप से एक क्षेत्र Pydantic सेट की पहचान करें कि हाथ से रोल किए गए संस्करण छोड़ देता है.

अस्वीकार दरों को मापें। दस इनपुट बनाएं जिन्हें निकाला नहीं जाना चाहिए (एक गीत गीत, एक गणित प्रमाण, एक खाली ईमेल) और उन्हें एक वास्तविक प्रदाता के माध्यम से सख्त मोड के साथ चलाएं। अस्वीकारों की गणना करें बनाम भ्रमग्रस्त आउटपुट। यह अस्वीकार-जागरूक पुनः प्रयासों के लिए आपका मूल सत्य है।

OpenAI के संरचित आउटपुट गाइड को ऊपर से नीचे तक पढ़ें। स्पष्ट JSON योजना द्वारा अनुमति देने वाले सख्त मोड में स्पष्ट रूप से प्रतिबंधित एक निर्माण की पहचान करें। फिर एक योजना बनाएं जो प्रतिबंधित निर्माण का उपयोग गैर-असली रूप से करता है और इसे सख्त संगत बनाने के लिए रीफैक्टर करता है।

प्रमुख शर्तें

Term	What people say	What it actually means
JSON Schema 2020-12	"The schema spec"	IETF-draft schema dialect every modern provider speaks
Strict mode	"Guaranteed schema"	OpenAI flag that enforces schema via constrained decoding
Constrained decoding	"Logit masking"	Decode-time enforcement that masks invalid next-tokens
Refusal	"Model declines"	Typed outcome when input cannot fit the schema
Parse error	"Invalid JSON"	Output did not parse as JSON; impossible under strict
Schema violation	"Wrong shape"	Parsed but violated types / required / enum / range
`additionalProperties: false`	"No extras allowed"	Forbids unknown fields; required in OpenAI strict
Pydantic BaseModel	"Typed output"	Python class that emits and validates JSON Schema
Zod schema	"TypeScript output type"	TS runtime schema for provider output validation
Grammar enforcement	"Open-weights constrained decode"	FSM-based logit masking, as in outlines / guidance

आगे पढ़ना

OpenAI — Structured outputs सख्त मोड, अस्वीकृति और योजना आवश्यकताएं
OpenAI — Introducing structured outputs अगस्त 2024 लॉन्च पोस्ट जिसमें डिकोडिंग गारंटी की व्याख्या की गई है
Pydantic AI — Output टाइप output_type बंधन जो प्रत्येक प्रदाता के लिए क्रमबद्ध
JSON Schema — 2020-12 release notes कैनोनिक विनिर्देश
Microsoft — Structured outputs in Azure OpenAI उद्यम तैनाती नोट्स और सख्त मोड चेतावनी

This free lesson is part of the AI Engineering from Scratch curriculum. Read the full explanation, run the lesson code, and verify the result in the interactive reader or from the repository source.

Browse the complete course catalog or open this lesson on GitHub.