Mine sisu juurde
Struktureeritud väljundid

Struktureeritud väljundid

Küsi vastust JSON-ina: mis tahes JSON-objekti või JSON-i, mis järgib sinu saadetud skeemi. Kasuta seda, kui vastust loeb programm, mitte inimene.

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 on vastuse tekst, väljas 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žiimid

response_format on lõpp-punkti /v1/chat/completions väli. Ilma selleta on vastus tavaline tekst.

Režiim Väärtus Mida saad
JSON-objekt {"type": "json_object"} Vastus on JSON ilma ettekirjutatud kujuta. Ütle promptis, milliseid võtmeid soovid.
JSON schema {"type": "json_schema", "json_schema": {"name": "…", "schema": {…}}} Vastus järgib sinu saadetud skeemi: selle võtmeid, tüüpe ja kohustuslikke välju.
Strict "strict": true Välja json_schema väli, mitte kolmas režiim. See on true, kui sa ei saada false.
Väli Tüüp Vaikeväärtus Kirjeldus Rakendavad
type string json_object või json_schema. Nõutav sees response_format. text võetakse vastu ja annab tavalise tekstivastuse. Iga mudel, mis režiimi võtab
json_schema.schema object JSON Schema, mida vastus järgib. Saada see alati, kui type on json_schema. Iga mudel, mis režiimi võtab
json_schema.name string Skeemi silt, nagu OpenAI formaadis. Hostitud avatud kaaludega mudelid
json_schema.strict boolean true Kas vastus peab skeemi täpselt järgima. Shannoni mudelid rakendavad iga skeemi range (strict) kujul. Hostitud avatud kaaludega mudelid

JSON-objekti režiim ei vaja skeemi. Nimeta võtmed promptis:

Päringu sisu
{
  "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"}
}

Tugi mudeli kaupa

Mudel json_object json_schema
Iga Shannoni mudel (shannon-*) Jah Jah
Hostitud avatud kaaludega mudelid, välja arvatud allpool nimetatud Jah Jah
Laguna-S-2.1-W4A16-AUTOROUND-REAP — —
inkling-W4A16-AUTOROUND-REAP Jah —

GET /v1/models teatab sama id kaupa: capabilities.json_schema igal mudelil ja capabilities.response_format hostitud avatud kaaludega mudelitel. Mudelid ja hinnad

Toetatud skeemi märksõnad

Mida mudel sinu skeemist saab, sõltub mudelist ja lõpp-punktist:

Mudelid /v1/chat/completions /v1/responses
Shannoni mudelid Allolev märksõnade alamhulk, rakendatud range (strict) kujul. Skeem nii, nagu sa selle saadad, rakendatud range (strict) kujul.
Hostitud avatud kaaludega mudelid Skeem nii, nagu sa selle saadad. strict on true, kui sa seda ei saada. Skeem nii, nagu sa selle saadad. strict on true, kui sa seda ei saada.

Shannoni mudelite märksõnade alamhulk lõpp-punktis /v1/chat/completions:

Märksõna Kuidas seda loetakse
Loetavad märksõnad type, format, title, description, nullable, enum, items, properties, required, minItems, maxItems, minimum, maximum, minLength, maxLength, pattern, anyOf, default
$ref Lahendatakse skeemi ülataseme $defs või definitions põhjal. $ref kõrvale kirjutatud märksõnad, näiteks description, säilitatakse. Viidet, millel sobivat definitsiooni ei ole, loetakse kui {"type": "object"}.
allOf Liikmed ühendatakse üheks skeemiks. Kus kaks liiget määravad sama märksõna, loeb hilisem.
oneOf Loetakse kui anyOf.
Iseendale viitavad skeemid Laiendatakse 24 tasemeni. Sügavamat taset loetakse kui {"type": "object"}.
Alamhulgast väljas Iga teine märksõna, näiteks additionalProperties, const, multipleOf, uniqueItems, exclusiveMinimum, exclusiveMaximum, patternProperties, prefixItems, minProperties, maxProperties, not ja if / then / else. Need ei kuulu skeemi, mille mudel saab.

Lõpp-punktis /v1/responses: text.format

/v1/responses kirjutab sama päringu kujul text.format. Skeem asub otse väljas format, välja name ja strict kõrval, mitte võtme json_schema all. JSON-objekti režiimi jaoks saada {"format": {"type": "json_object"}}.

Päringu sisu
{
  "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 on message üksuse output_text osa 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": []
        }
      ]
    }
  ]
}

Tugi mudeli kaupa ja vead on samad mis lõpp-punktis /v1/chat/completions. Responses API

Lõpp-punktis /v1/messages: tööriist skeemina

Messages formaadil ei ole struktureeritud väljundi välja. JSON-i saamiseks samadelt mudelitelt kutsu /v1/chat/completions või /v1/responses sama võtmega.

Et jääda lõpp-punkti /v1/messages, kirjelda objekt tööriistana: pane oma skeem väljale input_schema ja nimeta tööriist väljas tool_choice. tool_use ploki input on siis sinu objekt, juba parsitud. Nimetatud tool_choice rakendavad hostitud avatud kaaludega mudelid.

Päringu sisu
{
  "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"}
    }
  ]
}

Kontrolli, et stop_reason on tool_use, enne kui plokki loed. Funktsioonikutse

Kuidas JSON saabub

  • JSON on string. Vastuses ei ole selle kõrval parsitud objekti: käivita oma JSON parser väljal message.content.
  • Väärtusega stream: true saabub JSON delta.content tükkidena. Ühenda need ja parsi üks kord pärast voo lõppu; üksik tükk ei ole kehtiv JSON.
  • Hostitud avatud kaaludega mudel vastab response_format päringule ilma arutlusteksti: reasoning_content on null.

Kontrolli, mida saad

Skeem juhib, kuidas mudel kirjutab. API ei võrdle valmis vastust sinu skeemiga, seega teeb lõppkontrolli sinu kood:

  • Parsi veakäsitleja sees, nagu ülaosas olev näide teeb.
  • Valideeri parsitud objekt sama skeemiga oma koodis, näiteks JSON Schema teegi, Pydantic'u või Zodiga.
  • Pikk vastus võib lõppeda enne, kui JSON on täielik. Voogedastamata vastus teatab finish_reason ainult kui stop või tool_calls, seega on märguandeks parsimisviga. Küsi uuesti või küsi väiksemat objekti.

Vead

Olek Tüüp Teade Millal
400 invalid_request_error <id> does not accept response_format Mudel ei võta kumbagi režiimi.
400 invalid_request_error <id> does not accept response_format json_schema; use json_object Mudel võtab json_object ja sina saatsid json_schema.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … response_format ei sisalda type või ei ole JSON-objekt.

Kaks 400 vastust saadetakse enne, kui sinu saldost midagi maha arvatakse. Vigade käsitlus