Preskočiť na obsah
Štruktúrované výstupy

Štruktúrované výstupy

Požiadajte o odpoveď vo forme JSON: ľubovoľný objekt JSON, alebo JSON zodpovedajúci schéme, ktorú pošlete. Použite to, keď odpoveď číta program, nie človek.

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 je text odpovede, v 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}
  }
}

Režimy response_format

response_format je pole /v1/chat/completions. Bez neho je odpoveď bežný text.

Režim Hodnota Čo dostanete
Objekt JSON {"type": "json_object"} Odpoveď je JSON bez predpísaného tvaru. V prompte uveďte, aké kľúče chcete.
Schéma JSON {"type": "json_schema", "json_schema": {"name": "…", "schema": {…}}} Odpoveď dodržiava schému, ktorú pošlete: jej kľúče, typy a povinné polia.
Strict "strict": true Pole json_schema, nie tretí režim. Je true, pokiaľ nepošlete false.
Pole Typ Predvolené Popis Uplatňuje
type string json_object alebo json_schema. Povinné vo vnútri response_format. text sa prijíma a dáva bežnú textovú odpoveď. Každý model, ktorý berie tento režim
json_schema.schema object Schéma JSON Schema, ktorú odpoveď dodržiava. Pošlite ju vždy, keď je type json_schema. Každý model, ktorý berie tento režim
json_schema.name string Označenie schémy, ako vo formáte OpenAI. Hostované open-weight modely
json_schema.strict boolean true Či musí odpoveď schému dodržať presne. Modely Shannon uplatňujú každú schému ako striktnú. Hostované open-weight modely

Režim objektu JSON nepotrebuje schému. Kľúče pomenujte v prompte:

Telo requestu
{
  "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"}
}

Podpora podľa modelu

Model json_object json_schema
Každý model Shannon (shannon-*) Áno Áno
Hostované open-weight modely okrem nižšie uvedených Áno Áno
Laguna-S-2.1-W4A16-AUTOROUND-REAP — —
inkling-W4A16-AUTOROUND-REAP Áno —

GET /v1/models hlási to isté pri každom id: capabilities.json_schema na každom modeli a capabilities.response_format na hostovaných open-weight modeloch. Modely a ceny

Podporované kľúčové slová schémy

Čo model zo vašej schémy dostane, závisí od modelu a od endpointu:

Modely /v1/chat/completions /v1/responses
Modely Shannon Podmnožina kľúčových slov nižšie, uplatnená ako striktná. Schéma tak, ako ju pošlete, uplatnená ako striktná.
Hostované open-weight modely Schéma tak, ako ju pošlete. strict je true, pokiaľ ho neposlíte. Schéma tak, ako ju pošlete. strict je true, pokiaľ ho neposlíte.

Podmnožina kľúčových slov modelov Shannon na /v1/chat/completions:

Kľúčové slovo Ako sa číta
Čítané kľúčové slová type, format, title, description, nullable, enum, items, properties, required, minItems, maxItems, minimum, maximum, minLength, maxLength, pattern, anyOf, default
$ref Rieši sa z $defs alebo definitions na najvyššej úrovni schémy. Kľúčové slová zapísané vedľa $ref, napríklad description, sa zachovajú. Odkaz bez zodpovedajúcej definície sa číta ako {"type": "object"}.
allOf Členy sa zlúčia do jednej schémy. Kde dva členy nastavujú rovnaké kľúčové slovo, platí neskorší.
oneOf Číta sa ako anyOf.
Schémy, ktoré odkazujú samy na seba Rozvinuté do 24 úrovní. Hlbšia úroveň sa číta ako {"type": "object"}.
Mimo podmnožiny Každé iné kľúčové slovo, napríklad additionalProperties, const, multipleOf, uniqueItems, exclusiveMinimum, exclusiveMaximum, patternProperties, prefixItems, minProperties, maxProperties, not a if / then / else. Nie sú súčasťou schémy, ktorú model dostane.

Na /v1/responses: text.format

/v1/responses zapisuje ten istý request ako text.format. Schéma je priamo vo format, vedľa name a strict, nie pod kľúčom json_schema. Pre režim objektu JSON pošlite {"format": {"type": "json_object"}}.

Telo requestu
{
  "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 je text časti output_text položky message:

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

Podpora podľa modelu a chyby sú rovnaké ako na /v1/chat/completions. Responses API

Na /v1/messages: nástroj ako schéma

Formát Messages nemá pole pre štruktúrovaný výstup. Na JSON z tých istých modelov volajte /v1/chat/completions alebo /v1/responses s rovnakým kľúčom.

Aby ste zostali na /v1/messages, opíšte objekt ako nástroj: schému dajte do input_schema a nástroj pomenujte v tool_choice. input bloku tool_use je potom váš objekt, už spracovaný. Pomenované tool_choice uplatňujú hostované open-weight modely.

Telo requestu
{
  "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"}
    }
  ]
}

Skôr než blok prečítate, skontrolujte, že stop_reason je tool_use. Volanie funkcií

Ako JSON prichádza

  • JSON je reťazec. Odpoveď vedľa neho nemá spracovaný objekt: spustite svoj parser JSON na message.content.
  • So stream: true prichádza JSON v kúskoch delta.content. Spojte ich a spracujte, až keď stream skončil; samotný kúsok nie je platný JSON.
  • Hostovaný open-weight model odpovedá na request s response_format bez textu uvažovania: reasoning_content je null.

Skontrolujte, čo dostanete

Schéma usmerňuje, ako model píše. API hotovú odpoveď so schémou neporovnáva, takže poslednú kontrolu robí váš kód:

  • Spracovanie robte vo vnútri obsluhy chýb, ako to robí ukážka hore.
  • Spracovaný objekt overte rovnakou schémou vo vlastnom kóde, napríklad knižnicou JSON Schema, Pydantic alebo Zod.
  • Dlhá odpoveď môže skončiť skôr, než je JSON úplný. Odpoveď bez streamovania hlási finish_reason len ako stop alebo tool_calls, takže signálom je chyba pri spracovaní. Požiadajte znova alebo požiadajte o menší objekt.

Chyby

Stav Typ Správa Kedy
400 invalid_request_error <id> does not accept response_format Model neberie ani jeden režim.
400 invalid_request_error <id> does not accept response_format json_schema; use json_object Model berie json_object a vy ste poslali json_schema.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … response_format nemá type, alebo nie je objekt JSON.

Obe odpovede 400 sa posielajú skôr, než sa zo zostatku čokoľvek odpočíta. Spracovanie chýb