مواد پر جائیں
ساختی آؤٹ پٹس

ساختی آؤٹ پٹس

جواب 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 کا فیلڈ، تیسرا موڈ نہیں۔ یہ true ہے جب تک آپ false نہ بھیجیں۔
فیلڈ قسم ڈیفالٹ تفصیل لاگو کرنے والے
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 کے لیے اسی کلید کے ساتھ /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 متن کے بغیر دیتا ہے: reasoning_content کی قدر null ہوتی ہے۔

جو ملے اسے جانچیں

اسکیما ماڈل کے لکھنے کی رہنمائی کرتی ہے۔ API تیار جواب کا آپ کی اسکیما سے موازنہ نہیں کرتی، اس لیے آخری جانچ آپ کا کوڈ کرتا ہے:

  • ایرر ہینڈلر کے اندر پارس کریں، جیسا اوپر کا نمونہ کرتا ہے۔
  • پارس شدہ آبجیکٹ کو اپنے کوڈ میں اسی اسکیما سے validate کریں، مثلاً 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 جوابات آپ کے بیلنس سے کچھ نکالے جانے سے پہلے بھیجے جاتے ہیں۔ غلطیاں