Pereiti prie turinio
Struktūruoti išėjimai

Struktūruoti išėjimai

Prašykite atsakymo kaip JSON: bet kokio JSON objekto arba JSON, atitinkančio jūsų siunčiamą schemą. Naudokite, kai atsakymą skaito programa, o ne žmogus.

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 yra atsakymo tekstas, 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 režimai

response_format yra /v1/chat/completions laukas. Be jo atsakymas yra įprastas tekstas.

Režimas Reikšmė Ką gaunate
JSON objektas {"type": "json_object"} Atsakymas yra JSON be nustatytos formos. Užklausoje nurodykite, kokių raktų norite.
JSON schema {"type": "json_schema", "json_schema": {"name": "…", "schema": {…}}} Atsakymas atitinka jūsų siunčiamą schemą: jos raktus, tipus ir privalomus laukus.
Griežtas "strict": true json_schema laukas, o ne trečias režimas. Jis yra true, nebent siunčiate false.
Laukas Tipas Numatytoji Aprašymas Taiko
type string json_object arba json_schema. Privaloma response_format viduje. text priimamas ir duoda įprastą tekstinį atsakymą. Kiekvienas modelis, priimantis režimą
json_schema.schema object JSON Schema, kurią atsakymas atitinka. Siųskite ją, kai tik type yra json_schema. Kiekvienas modelis, priimantis režimą
json_schema.name string Schemos žymė, kaip OpenAI formate. Talpinami atvirų svorių modeliai
json_schema.strict boolean true Ar atsakymas turi tiksliai atitikti schemą. Shannon modeliai kiekvieną schemą taiko kaip griežtą. Talpinami atvirų svorių modeliai

JSON objekto režimui schemos nereikia. Raktus įvardykite užklausoje:

Užklausos turinys
{
  "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"}
}

Palaikymas pagal modelį

Modelis json_object json_schema
Kiekvienas Shannon modelis (shannon-*) Taip Taip
Talpinami atvirų svorių modeliai, išskyrus toliau įvardytus Taip Taip
Laguna-S-2.1-W4A16-AUTOROUND-REAP — —
inkling-W4A16-AUTOROUND-REAP Taip —

GET /v1/models tą patį nurodo kiekvienam id: capabilities.json_schema kiekvienam modeliui ir capabilities.response_format talpinamiems atvirų svorių modeliams. Modeliai ir kainos

Palaikomi schemos raktažodžiai

Ką modelis gauna iš jūsų schemos, priklauso nuo modelio ir nuo galinio taško:

Modeliai /v1/chat/completions /v1/responses
Shannon modeliai Toliau pateiktas raktažodžių poaibis, taikomas kaip griežtas. Schema tokia, kokią siunčiate, taikoma kaip griežta.
Talpinami atvirų svorių modeliai Schema tokia, kokią siunčiate. strict yra true, nebent jį išsiųstumėte. Schema tokia, kokią siunčiate. strict yra true, nebent jį išsiųstumėte.

Shannon modelių raktažodžių poaibis kelyje /v1/chat/completions:

Raktažodis Kaip skaitoma
Skaitomi raktažodžiai type, format, title, description, nullable, enum, items, properties, required, minItems, maxItems, minimum, maximum, minLength, maxLength, pattern, anyOf, default
$ref Išsprendžiama pagal $defs arba definitions aukščiausiame schemos lygyje. Šalia $ref parašyti raktažodžiai, pavyzdžiui, description, išlaikomi. Nuoroda be atitinkamo apibrėžimo skaitoma kaip {"type": "object"}.
allOf Nariai sujungiami į vieną schemą. Kur du nariai nustato tą patį raktažodį, galioja vėlesnis.
oneOf Skaitoma kaip anyOf.
Schemos, kurios nurodo pačios save Išskleidžiama iki 24 lygių. Gilesnis lygis skaitomas kaip {"type": "object"}.
Už poaibio ribų Kiekvienas kitas raktažodis, pavyzdžiui, additionalProperties, const, multipleOf, uniqueItems, exclusiveMinimum, exclusiveMaximum, patternProperties, prefixItems, minProperties, maxProperties, not ir if / then / else. Jie nėra schemos, kurią gauna modelis, dalis.

Kelyje /v1/responses: text.format

/v1/responses tą pačią užklausą užrašo kaip text.format. Schema yra tiesiai format, šalia name ir strict, o ne po raktu json_schema. JSON objekto režimui siųskite {"format": {"type": "json_object"}}.

Užklausos turinys
{
  "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 yra message elemento output_text dalies 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": []
        }
      ]
    }
  ]
}

Palaikymas pagal modelį ir klaidos tokios pačios kaip /v1/chat/completions. Responses API

Kelyje /v1/messages: įrankis kaip schema

Messages formatas struktūruotos išvesties lauko neturi. Norėdami gauti JSON iš tų pačių modelių, su tuo pačiu raktu kvieskite /v1/chat/completions arba /v1/responses.

Norėdami likti kelyje /v1/messages, objektą apibūdinkite kaip įrankį: schemą dėkite į input_schema, o įrankį įvardykite tool_choice. Tada tool_use bloko input yra jūsų objektas, jau išanalizuotas. Įvardytą tool_choice taiko talpinami atvirų svorių modeliai.

Užklausos turinys
{
  "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"}
    }
  ]
}

Prieš skaitydami bloką, patikrinkite, ar stop_reason yra tool_use. Funkcijų kvietimas

Kaip ateina JSON

  • JSON yra eilutė. Šalia jos atsakyme išanalizuoto objekto nėra: paleiskite savo JSON analizatorių ant message.content.
  • Su stream: true JSON ateina delta.content dalimis. Sujunkite jas ir išanalizuokite, kai srautas pasibaigs; atskira dalis nėra tinkamas JSON.
  • Talpinamas atvirų svorių modelis į užklausą su response_format atsako be mąstymo teksto: reasoning_content yra null.

Patikrinkite, ką gaunate

Schema nukreipia, kaip modelis rašo. API baigto atsakymo su jūsų schema nepalygina, todėl galutinę patikrą atlieka jūsų kodas:

  • Analizuokite klaidų tvarkyklės viduje, kaip daroma viršuje esančiame pavyzdyje.
  • Patikrinkite išanalizuotą objektą pagal tą pačią schemą savo kode, pavyzdžiui, su JSON Schema biblioteka, Pydantic ar Zod.
  • Ilgas atsakymas gali pasibaigti, kol JSON dar neužbaigtas. Ne srautinis atsakymas finish_reason nurodo tik kaip stop arba tool_calls, todėl signalas yra analizės klaida. Paklauskite iš naujo arba prašykite mažesnio objekto.

Klaidos

Būsena Tipas Pranešimas Kada
400 invalid_request_error <id> does not accept response_format Modelis nepriima nė vieno režimo.
400 invalid_request_error <id> does not accept response_format json_schema; use json_object Modelis priima json_object, o jūs išsiuntėte json_schema.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … response_format neturi type arba nėra JSON objektas.

Abu 400 atsakymai siunčiami prieš nuskaičiuojant ką nors iš jūsų balanso. Klaidų tvarkymas