ናብ ትሕዝቶ ዝለል
የተዋቀረ ውጤት

የተዋቀረ ውጤት

መልሲ ከም JSON ሕተት፦ ዝኾነ JSON object፣ ወይ 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}
  }
}

እቶም ዓይነታት mode ኣብ response_format ዘለዉ

response_format field ናይ /v1/chat/completions እዩ። ብዘይኡ እቲ መልሲ ተራ ጽሑፍ እዩ።

Mode ዋጋ እትረኽቦ
JSON object {"type": "json_object"} እቲ መልሲ JSON እዩ ብዘይ ዝተወሰነ ቅርጺ። ኣየኖት keys ከም እትደሊ ኣብ prompt ንገር።
JSON schema {"type": "json_schema", "json_schema": {"name": "…", "schema": {…}}} እቲ መልሲ schema እትልእኾ ይስዕብ፦ keys ኡ፣ ዓይነታቱን ዘድልዩ field ታትን።
Strict "strict": true field ናይ json_schema፣ ሳልሳይ mode ኣይኮነን። false እንተ ዘይለኣኽካ true እዩ።
Field ዓይነት ነባሪ መግለጺ ዝተጠቐመሉ
type string json_object ወይ json_schema። ኣብ response_format ዘድሊ። text ይቅበል ከምኡውን ተራ ጽሑፍ መልሲ ይህብ። ነፍሲ ወከፍ ሞዴል እቲ mode ዝቕበል
json_schema.schema object እቲ JSON Schema እቲ መልሲ ዝስዕቦ። type json_schema ምስ ዝኸውን ኩሉ ግዜ ልኣኾ። ነፍሲ ወከፍ ሞዴል እቲ mode ዝቕበል
json_schema.name string ስም ን schema፣ ከም ኣብ ቅርጺ OpenAI። ዝተሃንደሱ open-weight ሞዴላት
json_schema.strict boolean true እቲ መልሲ ነቲ schema ልክዕ ክስዕቦ ኣለዎ ወይ ኣይኮነን። እቶም Shannon ሞዴላት ነፍሲ ወከፍ schema ከም strict ይትግብሩ። ዝተሃንደሱ open-weight ሞዴላት

mode JSON object schema ኣየድልዮን። Keys ኣብ 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 ሞዴላት። ሞዴላትን ዋጋን

Keywords ናይ schema ዝድገፉ

ሞዴል ካብ schema ናትካ እንታይ ከም ዝቕበል ብሞዴልን endpoint ን ይውስን፦

ሞዴላት /v1/chat/completions /v1/responses
ሞዴላት Shannon እቲ ንኡስ ኣታዊ keywords ኣብ ታሕቲ፣ ከም strict ዝተተግበረ። እቲ schema ከም እትልእኾ፣ ከም strict ዝተተግበረ።
ዝተሃንደሱ open-weight ሞዴላት እቲ schema ከም እትልእኾ። strict እትልእኾ እንተ ዘይኮንካ true እዩ። እቲ schema ከም እትልእኾ። strict እትልእኾ እንተ ዘይኮንካ true እዩ።

እቲ ንኡስ ኣታዊ keywords ናይ ሞዴላት Shannon ኣብ /v1/chat/completions፦

Keyword ከመይ ይንበብ
Keywords ዝንበቡ type, format, title, description, nullable, enum, items, properties, required, minItems, maxItems, minimum, maximum, minLength, maxLength, pattern, anyOf, default
$ref ካብ $defs ወይ definitions ኣብ ላዕለዋይ ደረጃ ናይ schema ይፍታሕ። Keywords ጎኒ $ref ዝተጻሕፉ፣ ከም description፣ ይተርፉ። ምስ ዝምልከት ትርጉም ዘይብሉ ጠቐስታ ከም {"type": "object"} ይንበብ።
allOf እቶም ኣባላት ናብ ሓደ schema ይሓወሱ። ክልተ ኣባላት ተመሳሳሊ keyword ኣብ ዘዘጋጁሉ፣ እቲ ድሕሪ ዝመጽእ ይቑጸር።
oneOf ከም anyOf ይንበብ።
Schemas ባዕሎም ዝጠቅሱ ናብ 24 ደረጃታት ይዝርጋሕ። ዝዕምቕ ደረጃ ከም {"type": "object"} ይንበብ።
ካብ ንኡስ ኣታዊ ወጻኢ ኩሉ ካልእ keyword፣ ንኣብነት 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፣ ኣብ ትሕቲ key json_schema ኣይኮነን። ን mode 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 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፦ ሓደ tool ከም እቲ schema

ቅርጺ Messages field ናይ structured-output የብሉን። ን JSON ካብ ተመሳሳሊ ሞዴላት፣ ምስ ተመሳሳሊ ቁልፊ /v1/chat/completions ወይ /v1/responses ጸውዕ።

ኣብ /v1/messages ንምጽናሕ፣ እቲ object ከም tool ግለጾ፦ schema ኣብ input_schema ኣእቱ ከምኡውን ነቲ tool ኣብ tool_choice ሰምዮ። input ናይ block tool_use ሽዑ object ናትካ እዩ፣ ድሮ parsed። ዝተሰምየ 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 እዩ። እቲ ምላሽ ጎኑ parsed 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 ግበር፣ ከም ኣብነት ኣብ ላዕሊ።
  • እቲ parsed object ምስ ተመሳሳሊ schema ኣብ ኮድ ናትካ ኣረጋግጽ፣ ንኣብነት ብ JSON Schema library፣ Pydantic ወይ Zod።
  • ነዊሕ መልሲ ቅድሚ እቲ JSON ምሉእ ምዃኑ ክውድእ ይኽእል። ዘይውሕዝ ምላሽ finish_reason stop ወይ tool_calls ጥራይ ይሕብር፣ ስለዚ ጌጋ parse እቲ ምልክት እዩ። ደጊምካ ሕተት፣ ወይ ንእሽተይ object ሕተት።

ጌጋታት

ኩነታት ዓይነት መልእኽቲ መዓስ
400 invalid_request_error <id> does not accept response_format እቲ ሞዴል ክልቲኡ mode ኣይቅበልን።
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 ምላሻት ቅድሚ ካብ ሚዛንካ ዝኾነ ዝውሰድ ይለኣኻ። ሓጋይ ኣስተዳደር