بازدان بۆ ناوەڕۆک
Derketinên strukturkirî

Derketinên strukturkirî

وەڵامەکە وەک 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 {"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 پێویستی بە schema نییە. کلیلەکان لە prompt دا ناو ببە:

body ی داواکاری 
{
  "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 لەسەر هەموو مۆدێلێک، و capabilities.response_format لەسەر مۆدێلە open-weight ـە میوانداریکراوەکان. مۆدێل و نرخ

وشە کلیلییە پشتگیریکراوەکانی schema

ئەوەی مۆدێلێک لە schema ـکەت وەریدەگرێت بەندە بە مۆدێلەکە و endpoint ـەکەوە:

مۆدێلەکان /v1/chat/completions /v1/responses
مۆدێلەکانی Shannon بەشی وشە کلیلییەکانی خوارەوە، وەک strict جێبەجێ دەکرێت. schema وەک دەینێریت، وەک strict جێبەجێ دەکرێت.
مۆدێلە open-weight ـە میوانداریکراوەکان schema وەک دەینێریت. strict true ە مەگەر بینێریت. schema وەک دەینێریت. strict true ە مەگەر بینێریت.

بەشی وشە کلیلییەکانی مۆدێلەکانی Shannon لەسەر /v1/chat/completions:

وشەی کلیلی چۆن دەخوێنرێتەوە
وشە کلیلییە خوێندراوەکان type, format, title, description, nullable, enum, items, properties, required, minItems, maxItems, minimum, maximum, minLength, maxLength, pattern, anyOf, default
$ref لە $defs یان definitions ی ئاستی سەرەوەی schema چارەسەر دەکرێت. وشە کلیلییەکانی لەتەنیشت $ref نووسراون، وەک description، دەمێننەوە. ئاماژەیەک بەبێ پێناسەی گونجاو وەک {"type": "object"} دەخوێنرێتەوە.
allOf ئەندامەکان دەکرێنە یەک schema. لەو شوێنەی دوو ئەندام هەمان وشەی کلیلی دادەنێن، دواییان دەژمێردرێت.
oneOf وەک anyOf دەخوێنرێتەوە.
Schema ـکان کە ئاماژە بە خۆیان دەکەن تا 24 ئاست فراوان دەکرێن. ئاستێکی قووڵتر وەک {"type": "object"} دەخوێنرێتەوە.
دەرەوەی ئەو بەشە هەموو وشە کلیلییەکی دیکە، بۆ نموونە additionalProperties، const، multipleOf، uniqueItems، exclusiveMinimum، exclusiveMaximum، patternProperties، prefixItems، minProperties، maxProperties، not و if / then / else. ئەمانە بەشێک نین لەو schema ـەی مۆدێلەکە وەریدەگرێت.

بواری text.format لەسەر /v1/responses

/v1/responses هەمان داواکاری وەک text.format دەنووسێت. schema ڕاستەوخۆ لە format دایە، لەتەنیشت name و strict، نەک لەژێر کلیلی json_schema. بۆ شێوازی ئۆبجێکتی JSON بنێرە {"format": {"type": "json_object"}}.

body ی داواکاری 
{
  "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 text ی بەشی output_text ی ئایتمی message ە:

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: ئامرازێک وەک schema

فۆرماتی Messages بوارێکی structured-output ی نییە. بۆ JSON لە هەمان مۆدێلەکان، /v1/chat/completions یان /v1/responses بانگ بکە بە هەمان کلیل.

بۆ مانەوە لەسەر /v1/messages، ئۆبجێکتەکە وەک ئامرازێک وەسف بکە: schema ـکەت لە input_schema دابنێ و ئامرازەکە لە tool_choice ناو ببە. input ی بلۆکی tool_use ئەو کات ئۆبجێکتەکەتە، پێشتر parse کراوە. tool_choice ی ناونراو لەلایەن مۆدێلە open-weight ـە میوانداریکراوەکانەوە جێبەجێ دەکرێت.

body ی داواکاری 
{
  "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 ە پێش ئەوەی بلۆکەکە بخوێنیتەوە. Bangkirina fonksiyonê

JSON چۆن دەگات

  • JSON string ە. وەڵامەکە ئۆبجێکتێکی parse کراوی لەتەنیشت نییە: JSON parser ـەکەت لەسەر message.content جێبەجێ بکە.
  • لەگەڵ stream: true JSON لە پارچەکانی delta.content دا دەگات. یەکیان بخەرەوە و کاتێک stream کۆتایی هات parse ی بکە؛ پارچەیەک بە تەنها JSON ی دروست نییە.
  • مۆدێلێکی open-weight ی میوانداریکراو داواکاری response_format بەبێ دەقی بیرکردنەوە وەڵام دەداتەوە: reasoning_content null ە.

ئەوەی وەریدەگریت بپشکنە

schema ڕێنمایی دەکات مۆدێلەکە چۆن دەنووسێت. API وەڵامی تەواوبوو لەگەڵ schema ـکەت بەراورد ناکات، بۆیە کۆدەکەی تۆ پشکنینی کۆتایی دەکات:

  • لەناو مامەڵەکەری هەڵە parse بکە، وەک نموونەی سەرەوە.
  • ئۆبجێکتی parse کراو بە هەمان schema لە کۆدی خۆتدا validate بکە، بۆ نموونە بە کتێبخانەی JSON Schema، 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 ـەکە پێش ئەوە دەنێردرێن کە هیچ شتێک لە باڵانسەکەت بگیرێت. Çewtî