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) import OpenAI from "openai";
const client = new OpenAI({ apiKey: "YOUR_API_KEY", baseURL: "https://api.shannon-ai.com/v1" });
const response = await 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.
let person = null;
try {
person = JSON.parse(response.choices[0].message.content);
} catch {
// ask again, or report the failure
}
console.log(person); curl https://api.shannon-ai.com/v1/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"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"]
}
}
}
}' JSON on vastuse tekst, väljas choices[0].message.content:
{
"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:
{
"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"}}.
{
"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:
{
"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.
{
"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"}
} {
"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: truesaabub JSONdelta.contenttü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_formatpäringule ilma arutlusteksti:reasoning_contentonnull.
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_reasonainult kuistopvõitool_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