Məzmuna keç
Strukturlaşdırılmış çıxışlar

Strukturlaşdırılmış çıxışlar

Cavabı JSON kimi istəyin: istənilən JSON obyekti və ya göndərdiyiniz sxemə uyğun JSON. Cavabı insan yox, proqram oxuyursa istifadə edin.

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 cavabın mətnidir, choices[0].message.content-də:

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 rejimləri

response_format /v1/chat/completions sahəsidir. Onsuz cavab adi mətndir.

Rejim Dəyər Nə alırsınız
JSON obyekti {"type": "json_object"} Cavab əvvəlcədən müəyyən formasız JSON-dur. Hansı açarları istədiyinizi prompt-da deyin.
JSON sxemi {"type": "json_schema", "json_schema": {"name": "…", "schema": {…}}} Cavab göndərdiyiniz sxemə uyğundur: onun açarlarına, tiplərinə və məcburi sahələrinə.
Strict "strict": true json_schema-nın sahəsidir, üçüncü rejim deyil. false göndərməsəniz true-dur.
Sahə Tip Defolt Təsvir Tətbiq edən
type string json_object və ya json_schema. response_format içində məcburidir. text qəbul edilir və adi mətn cavabı verir. Rejimi qəbul edən hər model
json_schema.schema object Cavabın uyğun olduğu JSON Schema. type json_schema olduqda həmişə göndərin. Rejimi qəbul edən hər model
json_schema.name string Sxem üçün etiket, OpenAI formatında olduğu kimi. Host edilən açıq çəkili modellər
json_schema.strict boolean true Cavabın sxemə dəqiq uyğun olub-olmaması. Shannon modelləri hər sxemi strict kimi tətbiq edir. Host edilən açıq çəkili modellər

JSON obyekti rejimi sxem tələb etmir. Açarları prompt-da adlandırın:

Sorğu gövdəsi
{
  "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"}
}

Model üzrə dəstək

Model json_object json_schema
Hər Shannon modeli (shannon-*) Bəli Bəli
Host edilən açıq çəkili modellər, aşağıda adı çəkilənlər istisna olmaqla Bəli Bəli
Laguna-S-2.1-W4A16-AUTOROUND-REAP — —
inkling-W4A16-AUTOROUND-REAP Bəli —

GET /v1/models eyni şeyi hər id üçün bildirir: hər modeldə capabilities.json_schema, host edilən açıq çəkili modellərdə isə capabilities.response_format. Modellər və qiymətlər

Dəstəklənən sxem açar sözləri

Modelin sxeminizdən nəyi aldığı modeldən və endpoint-dən asılıdır:

Modellər /v1/chat/completions /v1/responses
Shannon modelləri Aşağıdakı açar söz alt çoxluğu, strict kimi tətbiq olunur. Sxem göndərdiyiniz kimi, strict kimi tətbiq olunur.
Host edilən açıq çəkili modellər Sxem göndərdiyiniz kimi. Göndərmədikdə strict true-dur. Sxem göndərdiyiniz kimi. Göndərmədikdə strict true-dur.

Shannon modellərinin /v1/chat/completions-da açar söz alt çoxluğu:

Açar söz Necə oxunur
Oxunan açar sözlər type, format, title, description, nullable, enum, items, properties, required, minItems, maxItems, minimum, maximum, minLength, maxLength, pattern, anyOf, default
$ref Sxemin yuxarı səviyyəsindəki $defs və ya definitions-dan həll edilir. $ref-in yanında yazılan description kimi açar sözlər saxlanılır. Uyğun tərifi olmayan istinad {"type": "object"} kimi oxunur.
allOf Üzvlər bir sxemdə birləşdirilir. İki üzv eyni açar sözü təyin etdikdə sonrakı nəzərə alınır.
oneOf anyOf kimi oxunur.
Özünə istinad edən sxemlər 24 səviyyəyə qədər açılır. Daha dərin səviyyə {"type": "object"} kimi oxunur.
Alt çoxluqdan kənar Hər digər açar söz, məsələn additionalProperties, const, multipleOf, uniqueItems, exclusiveMinimum, exclusiveMaximum, patternProperties, prefixItems, minProperties, maxProperties, not və if / then / else. Bunlar modelin aldığı sxemin tərkibinə daxil deyil.

/v1/responses-da: text.format

/v1/responses eyni sorğunu text.format kimi yazır. Sxem json_schema açarının altında deyil, birbaşa format-da, name və strict-in yanında durur. JSON obyekti rejimi üçün {"format": {"type": "json_object"}} göndərin.

Sorğu gövdəsi
{
  "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 elementinin output_text hissəsinin text-idir:

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": []
        }
      ]
    }
  ]
}

Model üzrə dəstək və xətalar /v1/chat/completions-dakı kimidir. Responses API

/v1/messages-də: sxem kimi alət

Messages formatında strukturlu çıxış sahəsi yoxdur. Eyni modellərdən JSON üçün eyni açarla /v1/chat/completions və ya /v1/responses çağırın.

/v1/messages-də qalmaq üçün obyekti alət kimi təsvir edin: sxeminizi input_schema-ya qoyun və aləti tool_choice-da adlandırın. Onda tool_use blokunun input-u artıq parse edilmiş obyektiniz olur. Adlı tool_choice-u host edilən açıq çəkili modellər tətbiq edir.

Sorğu gövdəsi
{
  "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"}
    }
  ]
}

Bloku oxumazdan əvvəl stop_reason-un tool_use olduğunu yoxlayın. Funksiya çağırışı

JSON necə gəlir

  • JSON sətirdir. Cavabda yanında parse edilmiş obyekt yoxdur: JSON parser-inizi message.content-də işlədin.
  • stream: true ilə JSON delta.content hissələri kimi gəlir. Onları birləşdirin və axın bitdikdən sonra bir dəfə parse edin; tək hissə etibarlı JSON deyil.
  • Host edilən açıq çəkili model response_format sorğusuna reasoning mətni olmadan cavab verir: reasoning_content null-dır.

Aldığınızı yoxlayın

Sxem modelin necə yazdığına yön verir. API bitmiş cavabı sxeminizlə müqayisə etmir, ona görə son yoxlamanı kodunuz aparır:

  • Yuxarıdakı nümunədə olduğu kimi parse-i xəta emaledicisinin içində aparın.
  • Parse edilmiş obyekti öz kodunuzda eyni sxemlə, məsələn JSON Schema kitabxanası, Pydantic və ya Zod ilə yoxlayın.
  • Uzun cavab JSON tamamlanmamış bitə bilər. Axınsız cavab finish_reason-u yalnız stop və ya tool_calls kimi bildirir, ona görə parse xətası siqnaldır. Yenidən soruşun və ya daha kiçik obyekt istəyin.

Xətalar

Status Tip Mesaj Nə vaxt
400 invalid_request_error <id> does not accept response_format Model hər iki rejimi qəbul etmir.
400 invalid_request_error <id> does not accept response_format json_schema; use json_object Model json_object qəbul edir, siz isə json_schema göndərdiniz.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … response_format-da type yoxdur və ya JSON obyekti deyil.

İki 400 cavabı balansınızdan heç nə çıxılmazdan əvvəl göndərilir. Xəta idarəetməsi