Агуулга руу алгасах
Бүтэцтэй гаралт

Бүтэцтэй гаралт

Хариултыг JSON хэлбэрээр хүснэ үү: дурын JSON объект, эсвэл таны илгээсэн 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 объект {"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 OpenAI форматын адил schema-ийн шошго. Hosted open-weight загварууд
json_schema.strict boolean true Хариулт schema-г яг дагах ёстой эсэх. Shannon загварууд schema бүрийг strict гэж хэрэгжүүлнэ. Hosted 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-*) Тийм Тийм
Доор нэрлэснээс бусад hosted open-weight загварууд Тийм Тийм
Laguna-S-2.1-W4A16-AUTOROUND-REAP — —
inkling-W4A16-AUTOROUND-REAP Тийм —

GET /v1/models ижил зүйлийг id бүрт мэдээлнэ: бүх загварт capabilities.json_schema, hosted open-weight загваруудад capabilities.response_format. Загвар ба үнэ

Дэмжигддэг schema түлхүүр үгс

Загвар таны schema-аас юуг хүлээн авах нь загвар ба endpoint-оос хамаарна:

Загварууд /v1/chat/completions /v1/responses
Shannon загварууд Доорх түлхүүр үгийн дэд олонлог, strict гэж хэрэгжүүлнэ. Таны илгээсэн schema хэвээрээ, strict гэж хэрэгжүүлнэ.
Hosted 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 гэж уншина.
Өөрийгөө заасан schema 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 нь json_schema түлхүүрийн дор биш, name ба strict-ийн хажууд format дотор шууд байрлана. 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 нь 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 дээр: schema болох tool

Messages формат бүтэцтэй гаралтын талбаргүй. Ижил загваруудаас JSON авахын тулд ижил түлхүүрээр /v1/chat/completions эсвэл /v1/responses-ийг дуудна уу.

/v1/messages дээр үлдэхийн тулд объектыг tool болгон тайлбарлана: schema-гаа input_schema-д оруулж, tool-ийг tool_choice-д нэрлэнэ. Дараа нь tool_use block-ийн input нь таны parse хийгдсэн объект болно. Нэрлэсэн tool_choice-ийг hosted 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. Хариуны хажууд parse хийсэн объект байхгүй: message.content дээр өөрийн JSON parser-ээ ажиллуулна уу.
  • stream: true-тэй үед JSON нь delta.content хэсгүүдээр ирнэ. Тэдгээрийг залгаад stream дууссаны дараа нэг удаа parse хийнэ үү; дан хэсэг хүчинтэй JSON биш.
  • Hosted open-weight загвар response_format хүсэлтэд reasoning текстгүйгээр хариулна: reasoning_content нь null.

Хүлээн авсан зүйлээ шалгах

Schema нь загвар хэрхэн бичихийг чиглүүлнэ. API дууссан хариултыг таны schema-тай харьцуулдаггүй тул эцсийн шалгалтыг таны код хийнэ:

  • Дээд талын жишээн дээрх шиг алдаа боловсруулагч дотор parse хийнэ үү.
  • Parse хийсэн объектыг ижил schema-аар өөрийн кодод баталгаажуулна уу, жишээлбэл 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 хариуг таны үлдэгдлээс юу ч хасахаас өмнө илгээнэ. Алдаа боловсруулах