संरचित आउटपुट
उत्तर 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) import OpenAI from "openai";
const client = new OpenAI({ apiKey: "YOUR_API_KEY", baseURL: "https://api.shannon-ai.com/v1" });
const response = await 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.
let person = null;
try {
person = JSON.parse(response.choices[0].message.content);
} catch {
// ask again, or report the failure
}
console.log(person); curl https://api.shannon-ai.com/v1/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"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"]
}
}
}
}' JSON उत्तर का टेक्स्ट है, choices[0].message.content में:
{
"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 है:
{
"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"}
} {
"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के साथ JSONdelta.contentके टुकड़ों में आता है। उन्हें जोड़ें और स्ट्रीम खत्म होने पर एक बार पार्स करें; अकेला टुकड़ा वैध JSON नहीं है।- होस्टेड ओपन-वेट मॉडल
response_formatअनुरोध का उत्तर रीज़निंग टेक्स्ट के बिना देता है:reasoning_contentnullहोता है।
जो मिले उसे जाँचें
स्कीमा मॉडल के लिखने का मार्गदर्शन करता है। 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 उत्तर आपके बैलेंस से कुछ लिए जाने से पहले भेजे जाते हैं। त्रुटि प्रबंधन