Siirry sisältöön
Strukturoidut lähdöt

Strukturoidut lähdöt

Pyydä vastaus JSON-muodossa: mikä tahansa JSON-objekti, tai JSON, joka noudattaa lähettämääsi skeemaa. Käytä sitä, kun vastauksen lukee ohjelma, ei ihminen.

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 vastauksen teksti kentässä 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-kentän tilat

response_format on päätepisteen /v1/chat/completions kenttä. Ilman sitä vastaus on tavallista tekstiä.

Tila Arvo Mitä saat
JSON-objekti {"type": "json_object"} Vastaus on JSONia ilman määrättyä muotoa. Kerro promptissa, mitä avaimia haluat.
JSON-skeema {"type": "json_schema", "json_schema": {"name": "…", "schema": {…}}} Vastaus noudattaa lähettämääsi skeemaa: sen avaimia, tyyppejä ja pakollisia kenttiä.
Tiukka "strict": true json_schema-tilan kenttä, ei kolmas tila. Se on true, ellet lähetä arvoa false.
Kenttä Tyyppi Oletus Kuvaus Käyttävät mallit
type string json_object tai json_schema. Pakollinen kentän response_format sisällä. text hyväksytään ja tuottaa tavallisen tekstivastauksen. Jokainen malli, joka ottaa tilan
json_schema.schema object JSON Schema, jota vastaus noudattaa. Lähetä se aina, kun type on json_schema. Jokainen malli, joka ottaa tilan
json_schema.name string Skeeman nimike, kuten OpenAI-muodossa. Hostatut avoimen painon mallit
json_schema.strict boolean true Onko vastauksen noudatettava skeemaa täsmälleen. Shannon-mallit soveltavat jokaista skeemaa tiukkana. Hostatut avoimen painon mallit

JSON-objektitila ei tarvitse skeemaa. Nimeä avaimet promptissa:

Pyynnön runko
{
  "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"}
}

Tuki mallikohtaisesti

Malli json_object json_schema
Jokainen Shannon-malli (shannon-*) Kyllä Kyllä
Hostatut avoimen painon mallit, paitsi alla nimetyt Kyllä Kyllä
Laguna-S-2.1-W4A16-AUTOROUND-REAP — —
inkling-W4A16-AUTOROUND-REAP Kyllä —

GET /v1/models ilmoittaa saman id:kohtaisesti: capabilities.json_schema jokaiselle mallille ja capabilities.response_format hostatuille avoimen painon malleille. Mallit ja hinnoittelu

Tuetut skeeman avainsanat

Se, minkä malli saa skeemastasi, riippuu mallista ja päätepisteestä:

Mallit /v1/chat/completions /v1/responses
Shannon-mallit Alla oleva avainsanojen osajoukko, sovellettuna tiukkana. Skeema sellaisena kuin lähetät sen, sovellettuna tiukkana.
Hostatut avoimen painon mallit Skeema sellaisena kuin lähetät sen. strict on true, ellet lähetä sitä. Skeema sellaisena kuin lähetät sen. strict on true, ellet lähetä sitä.

Shannon-mallien avainsanojen osajoukko päätepisteessä /v1/chat/completions:

Avainsana Miten se luetaan
Luettavat avainsanat type, format, title, description, nullable, enum, items, properties, required, minItems, maxItems, minimum, maximum, minLength, maxLength, pattern, anyOf, default
$ref Ratkaistaan skeeman ylimmän tason $defs- tai definitions-kentästä. $ref-viittauksen vieressä olevat avainsanat, kuten description, säilytetään. Viittaus ilman vastaavaa määritystä luetaan muodossa {"type": "object"}.
allOf Jäsenet yhdistetään yhdeksi skeemaksi. Kun kaksi jäsentä asettaa saman avainsanan, myöhempi ratkaisee.
oneOf Luetaan kuten anyOf.
Skeemat, jotka viittaavat itseensä Laajennetaan 24 tasoon. Syvempi taso luetaan muodossa {"type": "object"}.
Osajoukon ulkopuolella Jokainen muu avainsana, esimerkiksi additionalProperties, const, multipleOf, uniqueItems, exclusiveMinimum, exclusiveMaximum, patternProperties, prefixItems, minProperties, maxProperties, not ja if / then / else. Nämä eivät kuulu skeemaan, jonka malli saa.

Päätepisteessä /v1/responses: text.format

/v1/responses kirjoittaa saman pyynnön muodossa text.format. Skeema on suoraan kentässä format, kenttien name ja strict vieressä, ei json_schema-avaimen alla. JSON-objektitilaa varten lähetä {"format": {"type": "json_object"}}.

Pyynnön runko
{
  "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-alkion output_text-osan 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": []
        }
      ]
    }
  ]
}

Tuki mallikohtaisesti ja virheet ovat samat kuin päätepisteessä /v1/chat/completions. Responses API

Päätepisteessä /v1/messages: työkalu skeemana

Messages-muodossa ei ole strukturoidun tulosteen kenttää. Saadaksesi JSONia samoilta malleilta kutsu /v1/chat/completions tai /v1/responses samalla avaimella.

Jos haluat pysyä päätepisteessä /v1/messages, kuvaa objekti työkaluna: pane skeemasi kenttään input_schema ja nimeä työkalu kentässä tool_choice. tool_use-lohkon input on silloin objektisi, jo jäsennettynä. Hostatut avoimen painon mallit ottavat nimetyn tool_choice-arvon huomioon.

Pyynnön runko
{
  "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"}
    }
  ]
}

Tarkista, että stop_reason on tool_use, ennen kuin luet lohkon. Toiminto kutsu

Miten JSON saapuu

  • JSON on merkkijono. Vastauksessa ei ole sen vieressä jäsennettyä objektia: aja JSON-jäsentimesi kentälle message.content.
  • Kun stream: true, JSON saapuu delta.content-paloina. Yhdistä ne ja jäsennä kerran striimin päätyttyä; yksittäinen pala ei ole kelvollista JSONia.
  • Hostattu avoimen painon malli vastaa response_format-pyyntöön ilman päättelytekstiä: reasoning_content on null.

Tarkista saamasi

Skeema ohjaa sitä, miten malli kirjoittaa. API ei vertaa valmista vastausta skeemaasi, joten lopullisen tarkistuksen tekee koodisi:

  • Jäsennä virheenkäsittelijän sisällä, kuten ylimmän esimerkin koodi tekee.
  • Validoi jäsennetty objekti samalla skeemalla omassa koodissasi, esimerkiksi JSON Schema -kirjastolla, Pydanticilla tai Zodilla.
  • Pitkä vastaus voi päättyä ennen kuin JSON on valmis. Ei-striimattu vastaus ilmoittaa finish_reason-arvoksi vain stop tai tool_calls, joten jäsennysvirhe on merkki. Kysy uudelleen tai pyydä pienempi objekti.

Virheet

Tila Tyyppi Viesti Milloin
400 invalid_request_error <id> does not accept response_format Malli ei ota kumpaakaan tilaa.
400 invalid_request_error <id> does not accept response_format json_schema; use json_object Malli ottaa json_object-tilan ja lähetit json_schema.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … response_format-kentässä ei ole type-kenttää, tai se ei ole JSON-objekti.

Molemmat 400-vastaukset lähetetään ennen kuin saldostasi vähennetään mitään. Virheiden käsittely