منځپانګې ته ټوپ ووهئ
جوړښت شوي محصولات

جوړښت شوي محصولات

ځواب د JSON په توګه وغواړئ: هر JSON څیز، یا JSON چې هغه schema تعقیبوي چې تاسو یې لیږئ. دا هغه وخت وکاروئ کله چې پروګرام، نه کس، ځواب لولي.

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 object {"type": "json_object"} ځواب JSON دی پرته له ټاکل شوې بڼې. په prompt کې ووایئ چې کوم کلیدونه غواړئ.
JSON schema {"type": "json_schema", "json_schema": {"name": "…", "schema": {…}}} ځواب هغه 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 د schema لپاره لیبل، لکه په OpenAI بڼه کې. کوربه شوي open-weight ماډلونه
json_schema.strict boolean true ایا ځواب باید schema دقیقاً تعقیب کړي. د Shannon ماډلونه هره schema د strict په توګه پلي کوي. کوربه شوي open-weight ماډلونه

د JSON object حالت schema ته اړتیا نه لري. کلیدونه په prompt کې ونوموئ:

د غوښتنې بدنه
{
  "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. ماډلونه او بیې

ملاتړ شوې د schema کلیدي کلمې

ماډل ستاسو د schema څه ترلاسه کوي د ماډل او د endpoint پورې اړه لري:

ماډلونه /v1/chat/completions /v1/responses
د Shannon ماډلونه لاندې د کلیدي کلمو فرعي سیټ، د strict په توګه پلي شوی. Schema هماغسې لکه تاسو چې لیږئ، د strict په توګه پلي شوې.
کوربه شوي open-weight ماډلونه Schema هماغسې لکه تاسو چې لیږئ. strict true دی مګر دا چې تاسو یې ولیږئ. Schema هماغسې لکه تاسو چې لیږئ. 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 د schema په پورتنۍ کچه له $defs یا definitions څخه حل کیږي. هغه کلیدي کلمې چې د $ref تر څنګ لیکل شوې، لکه description، ساتل کیږي. اشاره چې سمه تعریف نه لري د {"type": "object"} په توګه لوستل کیږي.
allOf غړي په یوه schema کې یوځای کیږي. هلته چې دوه غړي همدا کلیدي کلمه ټاکي، وروستی شمیرل کیږي.
oneOf د anyOf په توګه لوستل کیږي.
Schemas چې پخپله ته اشاره کوي تر 24 کچو پورې پراخیږي. ژور کچه د {"type": "object"} په توګه لوستل کیږي.
له فرعي سیټ بهر هره بله کلیدي کلمه، د مثال په توګه additionalProperties، const، multipleOf، uniqueItems، exclusiveMinimum، exclusiveMaximum، patternProperties، prefixItems، minProperties، maxProperties، not او if / then / else. دا د هغه schema برخه نه دي چې ماډل یې ترلاسه کوي.

په /v1/responses کې د ځواب بڼه: text.format

/v1/responses همدا غوښتنه د text.format په توګه لیکي. Schema مستقیماً په format کې ده، د name او strict تر څنګ، نه د json_schema کیلي لاندې. د JSON object حالت لپاره {"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 کې: tool د schema په توګه

د Messages بڼه د جوړښت لرونکي output ساحه نه لري. له همدغو ماډلونو څخه د JSON لپاره، /v1/chat/completions یا /v1/responses د همدې کیلي سره وغواړئ.

د /v1/messages کې پاتې کیدو لپاره، څیز د tool په توګه بیان کړئ: خپله schema په input_schema کې ږدئ او tool په tool_choice کې ونوموئ. د tool_use block input بیا ستاسو څیز دی، لا دمخه parse شوی. نومول شوی 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"}
    }
  ]
}

مخکې له block لوستلو وګورئ چې stop_reason tool_use دی. فنکشن زنګ وهل

JSON څنګه رارسیږي

  • JSON یو string دی. ځواب د هغه تر څنګ parse شوی څیز نه لري: خپل JSON parser په message.content چلوئ.
  • د stream: true سره JSON د delta.content په ټوټو کې رارسیږي. ټوټې یوځای کړئ او وروسته له stream پای parse کړئ؛ یوه ټوټه پخپله معتبره JSON نه ده.
  • کوربه شوی open-weight ماډل response_format غوښتنې ته پرته له reasoning متن ځواب ورکوي: reasoning_content null دی.

هغه څه وګورئ چې ترلاسه کوئ

Schema ماډل ته لارښوونه کوي چې څنګه ولیکي. API بشپړ ځواب ستاسو له schema سره نه پرتله کوي، نو ستاسو کوډ وروستی چک کوي:

  • د تېروتنې handler دننه parse کړئ، لکه څنګه چې پورتنۍ نمونه کوي.
  • parse شوی څیز په خپل کوډ کې د همدې schema سره تایید کړئ، د مثال په توګه د JSON Schema library، Pydantic یا Zod سره.
  • اوږد ځواب کولی شي مخکې له دې پای ته ورسیږي چې JSON بشپړ شي. هغه ځواب چې stream نه وي finish_reason یوازې د stop یا tool_calls په توګه راپور کوي، نو د parse تېروتنه نښه ده. بیا وغواړئ، یا کوچنی څیز وغواړئ.

تېروتنې

حالت ډول پیغام کله
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 ځوابونه مخکې له دې لیږل کیږي چې ستاسو له بیلانس څه کم شي. د تېروتنې اداره کول