मजकुराकडे जा
संरचित आउटपुट्स

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

उत्तर 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 फॉरमॅटप्रमाणे स्कीमाचे लेबल. होस्ट केलेली open-weight मॉडेल्स
json_schema.strict boolean true उत्तराने स्कीमाचे तंतोतंत पालन केले पाहिजे का. Shannon मॉडेल्स प्रत्येक स्कीमा strict म्हणून लागू करतात. होस्ट केलेली open-weight मॉडेल्स

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-*) होय होय
खाली नाव दिलेल्यांखेरीज होस्ट केलेली open-weight मॉडेल्स होय होय
Laguna-S-2.1-W4A16-AUTOROUND-REAP — —
inkling-W4A16-AUTOROUND-REAP होय —

GET /v1/models प्रत्येक id साठी हेच कळवते: प्रत्येक मॉडेलवर capabilities.json_schema, आणि होस्ट केलेल्या open-weight मॉडेल्सवर capabilities.response_format. मॉडेल्स आणि किंमत

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

मॉडेलला तुमच्या स्कीमाचे काय मिळते ते मॉडेल आणि एंडपॉइंटवर अवलंबून असते:

मॉडेल्स /v1/chat/completions /v1/responses
Shannon मॉडेल्स खालील कीवर्ड उपसंच, strict म्हणून लागू. तुम्ही पाठवता तसा स्कीमा, strict म्हणून लागू.
होस्ट केलेली open-weight मॉडेल्स तुम्ही पाठवता तसा स्कीमा. तुम्ही न पाठवल्यास 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 हवा असल्यास त्याच कीसह /v1/chat/completions किंवा /v1/responses कॉल करा.

/v1/messages वरच राहायचे असल्यास ऑब्जेक्ट टूल म्हणून वर्णन करा: तुमचा स्कीमा input_schema मध्ये ठेवा आणि टूलचे नाव tool_choice मध्ये द्या. मग tool_use ब्लॉकचा input हा तुमचा ऑब्जेक्ट असतो, आधीच पार्स केलेला. नाव दिलेले tool_choice होस्ट केलेली open-weight मॉडेल्स लागू करतात.

रिक्वेस्ट बॉडी
{
  "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 नसतो.
  • होस्ट केलेले open-weight मॉडेल 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 उत्तरे तुमच्या बॅलन्समधून काहीही वजा होण्यापूर्वी दिली जातात. त्रुटी हाताळणी