JSON Schema एक्सट्रैक्शन में OpenAI API की समस्याओं का निदान
स्ट्रक्चर्ड एक्सट्रैक्शन पाइपलाइन में OpenAI प्रमाणीकरण, रेट लिमिट, टाइमआउट और अमान्य JSON की समस्याओं को हल करने के लिए व्यावहारिक वर्कफ़्लो।
सारांश · TL;DR
स्ट्रक्चर्ड एक्सट्रैक्शन विफल होने पर, ट्रांसपोर्ट और API त्रुटियों को आउटपुट-वैलिडेशन की विफलताओं से अलग पहचानें। पहले क्रेडेंशियल और प्रोजेक्ट ऐक्सेस जांचें, केवल अस्थायी त्रुटियों पर दोबारा कोशिश करें, और प्राप्त JSON का उपयोग करने से पहले उसे अपने स्कीमा के विरुद्ध वैलिडेट करें।
मुख्य बातें
- 401 का संबंध क्रेडेंशियल, संगठन की सदस्यता या IP allowlisting से होता है—यह आउटपुट-स्कीमा की समस्या नहीं है।
- 429 प्रतिक्रिया के लिए त्रुटि कोड देखें: रेट लिमिट होने पर अंतराल देकर दोबारा कोशिश की जा सकती है, जबकि क्रेडिट खत्म होने या खर्च की सीमा पूरी होने पर खाते में बदलाव करना होगा।
- API प्रतिक्रिया सफल होने पर भी एक्सट्रैक्शन आउटपुट अनुपयोगी हो सकता है; उसका JSON पार्स करें और अपने JSON Schema के विरुद्ध वैलिडेट करें।
- दोबारा कोशिशों की अधिकतम सीमा तय करें और बार-बार होने वाली विफलताओं का निदान करने लायक अनुरोध मेटाडेटा सुरक्षित रखें—लेकिन सीक्रेट या संवेदनशील स्रोत-पाठ लॉग न करें।
इस पृष्ठ पर (7)
पहले API विफलताओं और एक्सट्रैक्शन विफलताओं को अलग-अलग पहचानें
स्ट्रक्चर्ड एक्सट्रैक्शन पाइपलाइन में विफलता के दो अलग-अलग चरण होते हैं: मॉडल से उपयोगी प्रतिक्रिया मिलने से पहले अनुरोध विफल हो सकता है, या प्रतिक्रिया मिलने के बाद वह पार्सिंग अथवा स्कीमा जांच में विफल हो सकती है। दोनों स्थितियों को अलग-अलग संभालें। स्कीमा या प्रतिक्रिया की जांच किए बिना गलत फ़ॉर्मैट वाले आउटपुट पर बार-बार कोशिश करने से अनुरोध व्यर्थ हो सकते हैं; क्रेडिट बैलेंस खत्म होने पर बार-बार कोशिश करने से ऐक्सेस वापस नहीं मिलेगा।
OpenAI की त्रुटि-कोड गाइड में API स्टेटस कोड और उनसे जुड़े Python लाइब्रेरी अपवादों की जानकारी है। एक्सट्रैक्शन वर्कफ़्लो के लिए इसमें दिया व्यावहारिक अंतर खास तौर पर उपयोगी है: प्रमाणीकरण और अनुरोध संबंधी त्रुटियों के लिए कॉन्फ़िगरेशन ठीक करना होगा, अस्थायी थ्रॉटलिंग या सेवा-त्रुटियों पर सीमित संख्या में दोबारा कोशिश करना उपयोगी हो सकता है, और प्रतिक्रिया मिलने के बाद स्कीमा वैलिडेशन आपके ऐप्लिकेशन में होना चाहिए। OpenAI API त्रुटि कोड
एक्सट्रैक्शन कोड बदलने से पहले प्रमाणीकरण जांचें
401 के लिए जांचें कि ऐप्लिकेशन सही सक्रिय API key और सही organization context का उपयोग कर रहा है। त्रुटि-गाइड में संगठन की सदस्यता और IP allowlisting को भी संभावित कारण बताया गया है। अगर एक environment से अनुरोध सफल होते हैं लेकिन दूसरे से विफल, तो एक्सट्रैक्शन प्रॉम्प्ट बदलने से पहले दोनों environments के outbound IP और उपलब्ध क्रेडेंशियल की तुलना करें।
403 के लिए जांचें कि अनुरोध किसी समर्थित देश, क्षेत्र या इलाके से आ रहा है या नहीं। JSON Schema फ़ील्ड बदलने से अनुमति या ऐक्सेस पर लगी पाबंदी दूर नहीं होगी।
क्रेडेंशियल को source control और लॉग से बाहर रखें। डीबगिंग के दौरान environment का नाम और key का ऐसा पहचानकर्ता दर्ज करें जिसमें संवेदनशील हिस्सा छिपा हो—सीक्रेट स्वयं नहीं।
दोबारा कोशिश करने से पहले 429 प्रतिक्रियाओं का वर्गीकरण करें
429 का मतलब हमेशा यह नहीं होता कि “वही अनुरोध कुछ देर बाद फिर भेजें।” त्रुटि कोड और संदेश पढ़ें:
- अनुरोध-दर की सीमा: समवर्ती अनुरोधों की संख्या घटाएं या अनुरोधों के बीच अंतराल रखें।
Retry-Afterदिया हो तो उसका पालन करें, और ट्रैफ़िक को धीरे-धीरे बढ़ाएं—तुरंत पुरानी दर पर न लौटें। - क्रेडिट बैलेंस खत्म: अनुरोध फिर शुरू करने से पहले क्रेडिट जोड़ें।
- संगठन या प्रोजेक्ट की खर्च सीमा: लागू खर्च सीमा की समीक्षा करें।
- संगठन की उपयोग सीमा: स्वीकृत सीमा बढ़ाने का अनुरोध करें या सहायता से संपर्क करें।
गाइड के अनुसार, बिलिंग या उपयोग-सीमा से जुड़ी ये त्रुटियां दोबारा कोशिश करने से ठीक नहीं होतीं। अपने हैंडलर को व्यापक त्रुटि प्रकार के बजाय विशिष्ट त्रुटि कोड के आधार पर बनाएं: कुछ बिलिंग त्रुटियों का व्यापक कोटा-संबंधी प्रकार अन्य विफलताओं जैसा हो सकता है।
एक्सट्रैक्शन बैच के लिए, सभी दस्तावेज़ एक साथ भेजने के बजाय समवर्ती अनुरोधों की एक सरल सीमा तय करना अक्सर अधिक सुरक्षित होता है। केवल उन अनुरोधों पर दोबारा कोशिश करें जिनके अस्थायी होने की संभावना हो; प्रयासों की अधिकतम संख्या तय करें और backoff का इस्तेमाल करें। वैलिडेशन विफलताओं को रेट लिमिट समझकर दोबारा न भेजें।
टाइमआउट और अस्थायी सेवा-त्रुटियों को सुरक्षित तरीके से संभालें
क्लाइंट टाइमआउट का अर्थ है कि क्लाइंट को समय पर प्रतिक्रिया नहीं मिली; इससे यह साबित नहीं होता कि अनुरोध प्रोसेस ही नहीं हुआ। एक्सट्रैक्शन जॉब में प्रत्येक स्रोत दस्तावेज़ के लिए एक स्थिर job identifier रखें और नतीजे ऐसे सहेजें कि एक ही नतीजे को दोबारा दर्ज करने से डुप्लिकेट न बने। दोबारा कोशिश करते समय downstream रिकॉर्ड डुप्लिकेट होने से बचें।
OpenAI की गाइड में 500 सर्वर त्रुटियों और 503 मॉडल ओवरलोड के लिए बताया गया है कि थोड़ी देर बाद दोबारा कोशिश करने से मदद मिल सकती है; Retry-After दिया हो तो उसका पालन करें। गाइड में Python लाइब्रेरी के APITimeoutError, InternalServerError और RateLimitError जैसे अपवाद भी दिए गए हैं। कनेक्शन विफलता की वजह नेटवर्क, proxy, certificate या firewall कॉन्फ़िगरेशन भी हो सकती है। इन सभी स्थितियों में एक जैसा retry व्यवहार नहीं अपनाना चाहिए।
उदाहरण के तौर पर Python पैटर्न: पार्स करें, वैलिडेट करें, फिर उपयोग करें
नीचे दिया उदाहरण स्ट्रक्चर्ड प्रतिक्रिया के आसपास की जांचें दिखाता है। यह केवल उदाहरण है, जांचा हुआ कॉन्फ़िगरेशन नहीं। पुष्टि करें कि आपके मॉडल, SDK संस्करण, endpoint और structured-output पैरामीटर इस अनुरोध फ़ॉर्मैट का समर्थन करते हैं। OpenAI की त्रुटि-कोड गाइड JSON Schema पैरामीटर की अनुकूलता के बारे में जानकारी नहीं देती।
import json
from jsonschema import validate, ValidationError
from openai import OpenAI, APIConnectionError, APITimeoutError
from openai import APIStatusError, RateLimitError
client = OpenAI()
schema = {
"type": "object",
"properties": {
"invoice_number": {"type": "string"},
"total": {"type": "number"},
"currency": {"type": "string"}
},
"required": ["invoice_number", "total", "currency"],
"additionalProperties": False
}
try:
response = client.responses.create(
model="YOUR_SUPPORTED_MODEL",
input="Extract the invoice number, total, and currency from: ...",
text={
"format": {
"type": "json_schema",
"name": "invoice",
"strict": True,
"schema": schema
}
}
)
data = json.loads(response.output_text)
validate(instance=data, schema=schema)
except (RateLimitError, APITimeoutError, APIConnectionError) as exc:
# Apply a bounded, error-aware retry policy in the job runner.
print(f"Transient or connection failure: {exc}")
except APIStatusError as exc:
# Inspect status and the API error code before deciding what to do.
print(f"API failure: status={exc.status_code}, message={exc}")
except (json.JSONDecodeError, ValidationError) as exc:
# Quarantine the result; do not pass invalid data downstream.
print(f"Response failed JSON parsing or schema validation: {exc}")
अगर चुना गया endpoint या मॉडल इस schema-format पैरामीटर का समर्थन नहीं करता, तो अनुरोध गलत फ़ॉर्मैट वाला या असमर्थित होने के कारण विफल हो सकता है। वैलिडेशन को चुपचाप हटाने के बजाय endpoint के मौजूदा दस्तावेज़ देखें। सीमित आउटपुट उपलब्ध होने पर भी, डेटा को डेटाबेस या व्यावसायिक प्रक्रिया तक पहुंचाने से पहले ऐप्लिकेशन स्तर पर पार्सिंग और वैलिडेशन करना एक उपयोगी सुरक्षा चरण है।
संक्षिप्त निदान चेकलिस्ट
- प्रतिक्रिया नहीं मिली या क्लाइंट अपवाद आया? कनेक्टिविटी, टाइमआउट सेटिंग, proxy और TLS कॉन्फ़िगरेशन जांचें।
- 401 या 403? key, संगठन का ऐक्सेस, IP allowlist और क्षेत्रीय उपलब्धता जांचें।
- 429? सटीक कोड देखें। अस्थायी रेट-लिमिट विफलताओं में अनुरोधों के बीच अंतराल रखें; खाते से जुड़ी पाबंदियों के लिए क्रेडिट या सीमा संबंधी समस्या हल करें।
- 500 या 503? सीमित नीति के तहत दोबारा कोशिश करें और
Retry-Afterदिया गया हो तो उसका पालन करें। - प्रतिक्रिया मिली, लेकिन उपयोगी नहीं? प्रतिक्रिया को सुरक्षित तरीके से दर्ज करें, पता लगाएं कि JSON पार्सिंग या स्कीमा वैलिडेशन में से क्या विफल हुआ, और अमान्य रिकॉर्ड को आगे की प्रोसेसिंग से बाहर रखें।
- समस्या लगातार बनी हुई है? मॉडल का नाम, त्रुटि कोड और संदेश, टाइमस्टैम्प और टाइमज़ोन, तथा अनुरोध से जुड़ी प्रासंगिक जानकारी और headers सुरक्षित रखें। निदान की जानकारी साझा करने से पहले API keys और संवेदनशील स्रोत सामग्री छिपाएं।
निष्कर्ष
विश्वसनीय JSON एक्सट्रैक्शन के लिए पहले HTTP या SDK त्रुटि का निदान करें, फिर सफल प्रतिक्रियाओं को अलग से वैलिडेट करें। केवल उन्हीं त्रुटियों पर दोबारा कोशिश करें जिनके ठीक होने की संभावना हो, और थ्रॉटलिंग को क्रेडिट, खर्च सीमा तथा ऐक्सेस से जुड़ी अन्य पाबंदियों से अलग पहचानने के लिए विशिष्ट त्रुटि कोड देखें।
सामान्य प्रश्न
क्या हर OpenAI 429 प्रतिक्रिया पर दोबारा कोशिश करनी चाहिए?
नहीं। अनुरोध-दर की सीमा वाली विफलताओं में सीमा के भीतर अंतराल रखकर दोबारा कोशिश करें और `Retry-After` दिया हो तो उसका पालन करें। क्रेडिट खत्म होने, खर्च सीमा या उपयोग सीमा से जुड़ी त्रुटियों के लिए संबंधित खाता या सीमा बदलनी होगी; केवल दोबारा कोशिश करने से ऐक्सेस वापस नहीं मिलेगा।
एक्सट्रैक्शन के दौरान OpenAI 401 आने पर क्या जांचना चाहिए?
पुष्टि करें कि API key सही और सक्रिय है, अनुरोध में इच्छित organization का उपयोग हो रहा है और खाता उस संगठन का सदस्य है। IP allowlist कॉन्फ़िगर हो तो जांचें कि अनुरोध अधिकृत IP से आ रहा है।
क्या सफल API प्रतिक्रिया इस बात की गारंटी देती है कि JSON स्कीमा के मुताबिक सही है?
नहीं। लौटाए गए टेक्स्ट को पार्स करें और परिणामी ऑब्जेक्ट का उपयोग करने से पहले उसे अपने ऐप्लिकेशन के JSON Schema के विरुद्ध वैलिडेट करें। यह भी पुष्टि करें कि चुना गया endpoint, मॉडल और SDK आपके अनुरोध के structured-output पैरामीटर का समर्थन करते हैं।
त्रुटि लगातार बनी रहने पर कौन-सी जानकारी सुरक्षित रखनी चाहिए?
मॉडल, त्रुटि कोड और संदेश, टाइमस्टैम्प और टाइमज़ोन, तथा अनुरोध से जुड़ी प्रासंगिक जानकारी और headers दर्ज करें। लॉग करने या निदान की जानकारी साझा करने से पहले क्रेडेंशियल और संवेदनशील इनपुट छिपाएं।
संबंधित लेख
Guides
JSON Extraction वर्कफ़्लो के लिए Grok Imagine Image API की लागत का अनुमान
Grok Imagine Image से इमेज जनरेट करने का शुल्क अनुमानित करें, extraction की अज्ञात लागतों को पहचानें और JSON schema के आधार पर structured records को validate करें।
Guides
Structured extraction के लिए GPT 6.2 Sol API की लागत: दोहराया जा सकने वाला अनुमान
Token, retry, cache और context-tier से जुड़ी स्पष्ट मान्यताओं के आधार पर GPT 6.2 Sol से structured extraction की लागत का अनुमान लगाएं।
Guides
स्ट्रक्चर्ड एक्सट्रैक्शन के लिए GPT Image 2.6 Sunburst API की लागत: योजना बनाने की गाइड
टोकन संबंधी स्पष्ट मान्यताओं, स्कीमा वैलिडेशन, रीट्राई और मूल्य निर्धारण की सीमाओं के साथ image-to-JSON वर्कलोड का अनुमान लगाएं।
Guides
Schema से सत्यापित extraction के लिए GPT Image 2.6 Flare API की लागत का अनुमान
Structured extraction के लिए दोबारा जाँचा जा सकने वाला API बजट बनाएँ और दस्तावेज़ों में दी गई image-token दरों को extraction और OneMux की अज्ञात कीमतों से अलग रखें।