ወደ ይዘቱ እለፍ
የተዋቀሩ ውጤቶች

የተዋቀሩ ውጤቶች

መልሱን እንደ JSON ይጠይቁ፦ ማንኛውም JSON object፣ ወይም የሚልኩትን schema የሚከተል 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 object {"type": "json_object"} መልሱ የተወሰነ ቅርጽ የሌለው JSON ነው። የትኞቹን ቁልፎች እንደሚፈልጉ በprompt ውስጥ ይናገሩ።
JSON schema {"type": "json_schema", "json_schema": {"name": "…", "schema": {…}}} መልሱ የሚልኩትን 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 ለschema መለያ፣ እንደ OpenAI ፎርማት። የተስተናገዱ open-weight ሞዴሎች
json_schema.strict boolean true መልሱ schema ን በትክክል መከተል አለበት ወይስ አይደለም። የShannon ሞዴሎች እያንዳንዱን schema እንደ strict ይተገብራሉ። የተስተናገዱ open-weight ሞዴሎች

የJSON object ሁነታ 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፣ እና በተስተናገዱ 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"}} ይላኩ።

የጥያቄ 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 የ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 ፎርማት የstructured-output መስክ የለውም። ከተመሳሳይ ሞዴሎች JSON ለማግኘት በተመሳሳይ ቁልፍ /v1/chat/completions ወይም /v1/responses ይጥሩ።

በ/v1/messages ላይ ለመቆየት object ን እንደ tool ይግለጹ፦ schema ዎን በinput_schema ውስጥ ያስቀምጡ እና tool ን በtool_choice ይሰይሙ። ከዚያ የtool_use block input ቀድሞ የተተነተነ object ዎ ነው። ስም የተሰጠው 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"}
    }
  ]
}

block ን ከማንበብዎ በፊት stop_reason tool_use መሆኑን ያረጋግጡ። ፋንክሽን ጥራት

JSON እንዴት ይደርሳል

  • JSON string ነው። ምላሹ ከጎኑ የተተነተነ object የለውም፦ የJSON parser ዎን በmessage.content ላይ ያስኪዱ።
  • በstream: true JSON በdelta.content ቁርጥራጮች ይደርሳል። ያጣምሯቸው እና stream ካበቃ በኋላ አንድ ጊዜ parse ያድርጉ፤ አንድ ቁራጭ ብቻውን ትክክለኛ JSON አይደለም።
  • የተስተናገደ open-weight ሞዴል ለresponse_format ጥያቄ ያለ reasoning ጽሑፍ ይመልሳል፦ reasoning_content null ነው።

የሚቀበሉትን ያረጋግጡ

schema ሞዴሉ እንዴት እንደሚጽፍ ይመራል። API የተጠናቀቀውን መልስ ከschema ዎ ጋር አያወዳድርም፣ ስለዚህ የመጨረሻውን ፍተሻ ኮድዎ ያደርጋል፦

  • ከላይ ያለው ናሙና እንደሚያደርገው በስህተት አያያዥ ውስጥ parse ያድርጉ።
  • የተተነተነውን object በራስዎ ኮድ በተመሳሳይ schema ያረጋግጡ፣ ለምሳሌ በJSON Schema library፣ በPydantic ወይም በZod።
  • ረጅም መልስ JSON ሳይሟላ ሊያበቃ ይችላል። stream ያልሆነ ምላሽ finish_reason ን stop ወይም tool_calls ብቻ ያሳውቃል፣ ስለዚህ የparse ስህተት ምልክቱ ነው። እንደገና ይጠይቁ፣ ወይም ያነሰ object ይጠይቁ።

ስህተቶች

ሁኔታ ዓይነት መልእክት መቼ
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 object አይደለም።

ሁለቱ 400 ምላሾች ከቀሪ ሂሳብዎ ምንም ከመወሰዱ በፊት ይላካሉ። ስህተት አስተዳደር