Мазмунга өтүү
Түзүмдүү чыгыштар

Түзүмдүү чыгыштар

Жоопту 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 талаасы, үчүнчү режим эмес. false жөнөтпөсөңүз ал true.
Талаа Түрү Демейки Сүрөттөмө Колдонгон
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 деп жазат. Схема json_schema ачкычынын астында эмес, format ичинде name жана strict жанында түз турат. 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 бүткөн жоопту схемаңыз менен салыштырбайт, ошондуктан акыркы текшерүүнү коддуңуз жасайт:

  • Үстүндөгү мисалдагыдай ката иштеткичтин ичинде талдаңыз.
  • Талданган объектти өз кодуңузда ошол эле схема менен текшериңиз, мисалы 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 жообу балансыңыздан эч нерсе алынганга чейин жөнөтүлөт. Ката иштетүү