कंटेंट पर जाएँ
संरचित आउटपुट

संरचित आउटपुट

उत्तर JSON में माँगें: कोई भी JSON ऑब्जेक्ट, या ऐसा JSON जो आपके भेजे स्कीमा का पालन करे। इसका उपयोग तब करें जब उत्तर कोई व्यक्ति नहीं, कोई प्रोग्राम पढ़ता हो।

POST https://api.shannon-ai.com/v1/chat/completions

import json
from openai import OpenAI

client = OpenAI(api_key="YOUR_API_KEY", base_url="https://api.shannon-ai.com/v1")

response = client.chat.completions.create(
    model="Kimi-K3-3BIT-REAP",
    messages=[
        {"role": "user", "content": "Extract the person: John Doe, 30 years old, engineer."}
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "person",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "age": {"type": "integer"},
                    "occupation": {"type": "string"},
                },
                "required": ["name", "age", "occupation"],
            },
        },
    },
)

# The JSON arrives as text in message.content: parse it, then check it.
try:
    person = json.loads(response.choices[0].message.content)
except json.JSONDecodeError:
    person = None  # ask again, or report the failure

print(person)

JSON उत्तर का टेक्स्ट है, choices[0].message.content में:

200 JSON
{
  "id": "chatcmpl-0c4e7a1b9d2f4e6a8b3c5d7e9f1a2b3c",
  "object": "chat.completion",
  "created": 1791590400,
  "model": "Kimi-K3-3BIT-REAP",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "{\"name\":\"John Doe\",\"age\":30,\"occupation\":\"engineer\"}",
        "reasoning_content": null
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 96,
    "completion_tokens": 19,
    "total_tokens": 115,
    "prompt_tokens_details": {"cached_tokens": 0},
    "completion_tokens_details": {"reasoning_tokens": 0}
  }
}

response_format के उपलब्ध मोड

response_format /v1/chat/completions का एक फ़ील्ड है। इसके बिना उत्तर सामान्य टेक्स्ट होता है।

मोड मान आपको क्या मिलता है
JSON ऑब्जेक्ट {"type": "json_object"} उत्तर बिना तय आकार का JSON है। प्रॉम्प्ट में बताएँ कि आपको कौन सी कुंजियाँ चाहिए।
JSON स्कीमा {"type": "json_schema", "json_schema": {"name": "…", "schema": {…}}} उत्तर आपके भेजे स्कीमा का पालन करता है: उसकी कुंजियाँ, प्रकार और ज़रूरी फ़ील्ड।
Strict "strict": true json_schema का एक फ़ील्ड, तीसरा मोड नहीं। आप false न भेजें तो यह true है।
फ़ील्ड प्रकार डिफ़ॉल्ट विवरण लागू करने वाले
type string json_object या json_schema। response_format के भीतर ज़रूरी। text स्वीकार है और सामान्य टेक्स्ट उत्तर देता है। हर मॉडल जो यह मोड लेता है
json_schema.schema object वह JSON Schema जिसका उत्तर पालन करता है। जब भी type json_schema हो, इसे भेजें। हर मॉडल जो यह मोड लेता है
json_schema.name string स्कीमा के लिए एक लेबल, जैसा OpenAI फ़ॉर्मेट में है। होस्टेड ओपन-वेट मॉडल
json_schema.strict boolean true क्या उत्तर को स्कीमा का ठीक-ठीक पालन करना है। Shannon मॉडल हर स्कीमा को strict के रूप में लागू करते हैं। होस्टेड ओपन-वेट मॉडल

JSON ऑब्जेक्ट मोड को स्कीमा नहीं चाहिए। प्रॉम्प्ट में कुंजियों के नाम बताएँ:

अनुरोध की बॉडी
{
  "model": "shannon-3",
  "messages": [
    {
      "role": "user",
      "content": "Name the capital of France. Answer as JSON with the keys city and country."
    }
  ],
  "response_format": {"type": "json_object"}
}

हर मॉडल के लिए समर्थन

मॉडल json_object json_schema
हर Shannon मॉडल (shannon-*) हाँ हाँ
होस्टेड ओपन-वेट मॉडल, नीचे नामित मॉडल को छोड़कर हाँ हाँ
Laguna-S-2.1-W4A16-AUTOROUND-REAP — —
inkling-W4A16-AUTOROUND-REAP हाँ —

GET /v1/models हर id के लिए यही बताता है: हर मॉडल पर capabilities.json_schema, और होस्टेड ओपन-वेट मॉडल पर capabilities.response_format। मॉडल और कीमतें

समर्थित स्कीमा कीवर्ड

आपके स्कीमा का कितना हिस्सा मॉडल को मिलता है, यह मॉडल और endpoint पर निर्भर करता है:

मॉडल /v1/chat/completions /v1/responses
Shannon मॉडल नीचे का कीवर्ड उपसमुच्चय, strict के रूप में लागू। स्कीमा जैसा आप भेजते हैं, strict के रूप में लागू।
होस्टेड ओपन-वेट मॉडल स्कीमा जैसा आप भेजते हैं। आप न भेजें तो strict true है। स्कीमा जैसा आप भेजते हैं। आप न भेजें तो strict true है।

/v1/chat/completions पर Shannon मॉडल का कीवर्ड उपसमुच्चय:

कीवर्ड इसे कैसे पढ़ा जाता है
पढ़े जाने वाले कीवर्ड type, format, title, description, nullable, enum, items, properties, required, minItems, maxItems, minimum, maximum, minLength, maxLength, pattern, anyOf, default
$ref स्कीमा के शीर्ष स्तर पर $defs या definitions से हल किया जाता है। $ref के बगल में लिखे कीवर्ड, जैसे description, रखे जाते हैं। जिस संदर्भ की कोई मेल खाती परिभाषा न हो, उसे {"type": "object"} की तरह पढ़ा जाता है।
allOf सदस्य एक स्कीमा में मिला दिए जाते हैं। जहाँ दो सदस्य एक ही कीवर्ड सेट करते हैं, वहाँ बाद वाला गिना जाता है।
oneOf anyOf की तरह पढ़ा जाता है।
वे स्कीमा जो खुद का संदर्भ देते हैं 24 स्तर तक फैलाए जाते हैं। उससे गहरा स्तर {"type": "object"} की तरह पढ़ा जाता है।
उपसमुच्चय से बाहर बाकी हर कीवर्ड, उदाहरण के लिए additionalProperties, const, multipleOf, uniqueItems, exclusiveMinimum, exclusiveMaximum, patternProperties, prefixItems, minProperties, maxProperties, not और if / then / else। ये उस स्कीमा का हिस्सा नहीं हैं जो मॉडल को मिलता है।

/v1/responses पर text.format के ज़रिए स्ट्रक्चर्ड आउटपुट

/v1/responses यही अनुरोध text.format के रूप में लिखता है। स्कीमा सीधे format में, name और strict के बगल में रहता है, json_schema कुंजी के नीचे नहीं। JSON ऑब्जेक्ट मोड के लिए {"format": {"type": "json_object"}} भेजें।

अनुरोध की बॉडी
{
  "model": "Kimi-K3-3BIT-REAP",
  "input": "Extract the person: John Doe, 30 years old, engineer.",
  "text": {
    "format": {
      "type": "json_schema",
      "name": "person",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "name": {"type": "string"},
          "age": {"type": "integer"},
          "occupation": {"type": "string"}
        },
        "required": ["name", "age", "occupation"]
      }
    }
  }
}

JSON message आइटम के output_text भाग का text है:

200 JSON
{
  "output": [
    {
      "id": "msg_7e1d3c5b9a2f4d6e8c0b1a3f5e7d9c2b",
      "type": "message",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "{\"name\":\"John Doe\",\"age\":30,\"occupation\":\"engineer\"}",
          "annotations": []
        }
      ]
    }
  ]
}

हर मॉडल के लिए समर्थन और एरर वही हैं जो /v1/chat/completions पर हैं। Responses API

/v1/messages पर: स्कीमा के रूप में टूल

Messages फ़ॉर्मेट में स्ट्रक्चर्ड आउटपुट का कोई फ़ील्ड नहीं है। उन्हीं मॉडल से JSON पाने के लिए उसी key के साथ /v1/chat/completions या /v1/responses कॉल करें।

/v1/messages पर रहने के लिए ऑब्जेक्ट को टूल के रूप में बताएँ: अपना स्कीमा input_schema में रखें और tool_choice में टूल का नाम दें। तब tool_use ब्लॉक का input आपका ऑब्जेक्ट है, पहले से पार्स किया हुआ। नाम वाला tool_choice होस्टेड ओपन-वेट मॉडल लागू करते हैं।

अनुरोध की बॉडी
{
  "model": "Kimi-K3-3BIT-REAP",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "Extract the person: John Doe, 30 years old, engineer."
    }
  ],
  "tools": [
    {
      "name": "record_person",
      "description": "Record the extracted person.",
      "input_schema": {
        "type": "object",
        "properties": {
          "name": {"type": "string"},
          "age": {"type": "integer"},
          "occupation": {"type": "string"}
        },
        "required": ["name", "age", "occupation"]
      }
    }
  ],
  "tool_choice": {"type": "tool", "name": "record_person"}
}
200 JSON
{
  "stop_reason": "tool_use",
  "content": [
    {
      "type": "tool_use",
      "id": "toolu_4b8d2f6a1c3e4a5b9d7f0e2c4a6b8d1f",
      "name": "record_person",
      "input": {"name": "John Doe", "age": 30, "occupation": "engineer"}
    }
  ]
}

ब्लॉक पढ़ने से पहले जाँचें कि stop_reason tool_use है। फ़ंक्शन कॉलिंग

JSON कैसे आता है

  • JSON एक स्ट्रिंग है। उत्तर में उसके साथ कोई पार्स किया हुआ ऑब्जेक्ट नहीं होता: message.content पर अपना JSON पार्सर चलाएँ।
  • stream: true के साथ JSON delta.content के टुकड़ों में आता है। उन्हें जोड़ें और स्ट्रीम खत्म होने पर एक बार पार्स करें; अकेला टुकड़ा वैध JSON नहीं है।
  • होस्टेड ओपन-वेट मॉडल response_format अनुरोध का उत्तर रीज़निंग टेक्स्ट के बिना देता है: reasoning_content null होता है।

जो मिले उसे जाँचें

स्कीमा मॉडल के लिखने का मार्गदर्शन करता है। API तैयार उत्तर की तुलना आपके स्कीमा से नहीं करती, इसलिए अंतिम जाँच आपका कोड करता है:

  • एरर हैंडलर के भीतर पार्स करें, जैसा सबसे ऊपर का नमूना करता है।
  • पार्स किए ऑब्जेक्ट को अपने कोड में उसी स्कीमा से वैलिडेट करें, उदाहरण के लिए JSON Schema लाइब्रेरी, Pydantic या Zod से।
  • लंबा उत्तर JSON पूरा होने से पहले खत्म हो सकता है। स्ट्रीम न किया गया उत्तर finish_reason को केवल stop या tool_calls बताता है, इसलिए पार्स एरर ही संकेत है। फिर से पूछें, या छोटा ऑब्जेक्ट माँगें।

एरर

स्टेटस प्रकार संदेश कब
400 invalid_request_error <id> does not accept response_format मॉडल दोनों में से कोई मोड नहीं लेता।
400 invalid_request_error <id> does not accept response_format json_schema; use json_object मॉडल json_object लेता है और आपने json_schema भेजा।
422 invalid_request_error Failed to deserialize the JSON body into the target type: … response_format में type नहीं है, या वह JSON ऑब्जेक्ट नहीं है।

दोनों 400 उत्तर आपके बैलेंस से कुछ लिए जाने से पहले भेजे जाते हैं। त्रुटि प्रबंधन