გადასვლა შინაარსზე
სტრუქტურირებული შედეგები

სტრუქტურირებული შედეგები

მოითხოვეთ პასუხი 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-ის ველია და არა მესამე რეჟიმი. ის არის true, თუ false არ გაგიგზავნიათ.
ველი ტიპი ნაგულისხმევი აღწერა მოქმედებს
type string json_object ან json_schema. response_format-ის შიგნით აუცილებელია. text მიიღება და ჩვეულებრივ ტექსტურ პასუხს იძლევა. ყველა მოდელი, რომელიც რეჟიმს იღებს
json_schema.schema object JSON Schema, რომელსაც პასუხი მისდევს. გაგზავნეთ ყოველთვის, როცა type არის json_schema. ყველა მოდელი, რომელიც რეჟიმს იღებს
json_schema.name string სქემის ეტიკეტი, როგორც OpenAI-ის ფორმატში. Hosted open-weight მოდელები
json_schema.strict boolean true უნდა მისდიოს თუ არა პასუხი სქემას ზუსტად. Shannon მოდელები ყველა სქემას strict-ად იყენებენ. Hosted open-weight მოდელები

JSON object რეჟიმს სქემა არ სჭირდება. გასაღებები დაასახელეთ პრომპტში:

მოთხოვნის სხეული
{
  "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 ყველა მოდელზე და capabilities.response_format hosted open-weight მოდელებზე. მოდელები და ფასები

მხარდაჭერილი სქემის საკვანძო სიტყვები

თქვენი სქემიდან მოდელი იღებს იმას, რაც მოდელსა და endpoint-ზეა დამოკიდებული:

მოდელები /v1/chat/completions /v1/responses
Shannon მოდელები ქვემოთ მოცემული საკვანძო სიტყვების ქვესიმრავლე, strict-ად გამოყენებული. სქემა ისე, როგორც გაგზავნეთ, strict-ად გამოყენებული.
Hosted open-weight მოდელები სქემა ისე, როგორც გაგზავნეთ. strict არის true, თუ არ გაგიგზავნიათ. სქემა ისე, როგორც გაგზავნეთ. strict არის true, თუ არ გაგიგზავნიათ.

Shannon მოდელების საკვანძო სიტყვების ქვესიმრავლე /v1/chat/completions-ზე:

საკვანძო სიტყვა როგორ იკითხება
წაკითხული საკვანძო სიტყვები 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. სქემა პირდაპირ format-შია, name-ისა და strict-ის გვერდით და არა json_schema გასაღების ქვეშ. JSON object რეჟიმისთვის გაგზავნეთ {"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-ს hosted open-weight მოდელები იყენებენ.

მოთხოვნის სხეული
{
  "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 არის სტრიქონი. პასუხში მის გვერდით დაპარსული ობიექტი არ არის: გაუშვით თქვენი JSON პარსერი message.content-ზე.
  • stream: true-ს შემთხვევაში JSON delta.content ნაწილებად მოდის. გააერთიანეთ ისინი და პარსინგი სტრიმის დასრულების შემდეგ ერთხელ გააკეთეთ; ცალკე ნაწილი ვალიდური JSON არ არის.
  • hosted open-weight მოდელი response_format მოთხოვნას მსჯელობის ტექსტის გარეშე პასუხობს: 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 პასუხი იგზავნება მანამ, სანამ თქვენი ბალანსიდან რამე ჩამოიჭრება. შეცდომების დამუშავება