Pāriet uz saturu
Strukturēti izvadi

Strukturēti izvadi

Pieprasiet atbildi kā JSON: jebkuru JSON objektu vai JSON, kas seko jūsu nosūtītai shēmai. Izmantojiet to, kad atbildi lasa programma, nevis cilvēks.

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 ir atbildes teksts laukā 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žīmi

response_format ir galapunkta /v1/chat/completions lauks. Bez tā atbilde ir parasts teksts.

Režīms Vērtība Ko saņemat
JSON objekts {"type": "json_object"} Atbilde ir JSON bez noteiktas formas. Uzvednē pasakiet, kādas atslēgas vēlaties.
JSON shēma {"type": "json_schema", "json_schema": {"name": "…", "schema": {…}}} Atbilde seko jūsu nosūtītajai shēmai: tās atslēgām, tipiem un obligātajiem laukiem.
Stingrs "strict": true Lauks json_schema, nevis trešais režīms. Tas ir true, ja nesūtāt false.
Lauks Tips Noklusējums Apraksts Piemēro
type string json_object vai json_schema. Obligāts laukā response_format. text tiek pieņemts un dod parastu teksta atbildi. Katrs modelis, kas pieņem režīmu
json_schema.schema object JSON Schema, kurai atbilde seko. Sūtiet to vienmēr, kad type ir json_schema. Katrs modelis, kas pieņem režīmu
json_schema.name string Shēmas nosaukums, kā OpenAI formātā. Hostētie atvērto svaru modeļi
json_schema.strict boolean true Vai atbildei jāseko shēmai precīzi. Shannon modeļi katru shēmu piemēro kā stingru. Hostētie atvērto svaru modeļi

JSON objekta režīmam shēma nav vajadzīga. Nosauciet atslēgas uzvednē:

Pieprasījuma pamatteksts
{
  "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"}
}

Atbalsts katram modelim

Modelis json_object json_schema
Katrs Shannon modelis (shannon-*) Jā Jā
Hostētie atvērto svaru modeļi, izņemot tos, kas nosaukti zemāk Jā Jā
Laguna-S-2.1-W4A16-AUTOROUND-REAP — —
inkling-W4A16-AUTOROUND-REAP Jā —

GET /v1/models to pašu ziņo katram id: capabilities.json_schema katram modelim un capabilities.response_format hostētajiem atvērto svaru modeļiem. Modeļi un cenas

Atbalstītie shēmas atslēgvārdi

Ko modelis no jūsu shēmas saņem, ir atkarīgs no modeļa un no galapunkta:

Modeļi /v1/chat/completions /v1/responses
Shannon modeļi Zemāk redzamā atslēgvārdu apakškopa, piemērota kā stingra. Shēma, kā jūs to sūtāt, piemērota kā stingra.
Hostētie atvērto svaru modeļi Shēma, kā jūs to sūtāt. strict ir true, ja to nesūtāt. Shēma, kā jūs to sūtāt. strict ir true, ja to nesūtāt.

Shannon modeļu atslēgvārdu apakškopa galapunktā /v1/chat/completions:

Atslēgvārds Kā tas tiek lasīts
Lasītie atslēgvārdi type, format, title, description, nullable, enum, items, properties, required, minItems, maxItems, minimum, maximum, minLength, maxLength, pattern, anyOf, default
$ref Tiek atrisināts no $defs vai definitions shēmas augšējā līmenī. Atslēgvārdi, kas rakstīti blakus $ref, piemēram, description, tiek saglabāti. Atsauce bez atbilstošas definīcijas tiek lasīta kā {"type": "object"}.
allOf Locekļi tiek sapludināti vienā shēmā. Ja divi locekļi iestata vienu un to pašu atslēgvārdu, spēkā ir vēlākais.
oneOf Tiek lasīts kā anyOf.
Shēmas, kas atsaucas uz sevi Izvērstas līdz 24 līmeņiem. Dziļāks līmenis tiek lasīts kā {"type": "object"}.
Ārpus apakškopas Katrs cits atslēgvārds, piemēram, additionalProperties, const, multipleOf, uniqueItems, exclusiveMinimum, exclusiveMaximum, patternProperties, prefixItems, minProperties, maxProperties, not un if / then / else. Tie nav daļa no shēmas, ko modelis saņem.

Galapunktā /v1/responses: text.format

/v1/responses to pašu pieprasījumu raksta kā text.format. Shēma atrodas tieši laukā format, blakus name un strict, nevis zem atslēgas json_schema. JSON objekta režīmam sūtiet {"format": {"type": "json_object"}}.

Pieprasījuma pamatteksts
{
  "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 ir elementa message daļas output_text lauks 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": []
        }
      ]
    }
  ]
}

Atbalsts katram modelim un kļūdas ir tādas pašas kā galapunktā /v1/chat/completions. Responses API

Galapunktā /v1/messages: rīks kā shēma

Messages formātam nav strukturētas izvades lauka. Lai iegūtu JSON no tiem pašiem modeļiem, izsauciet /v1/chat/completions vai /v1/responses ar to pašu atslēgu.

Lai paliktu galapunktā /v1/messages, aprakstiet objektu kā rīku: ievietojiet savu shēmu laukā input_schema un nosauciet rīku laukā tool_choice. Bloka tool_use input tad ir jūsu objekts, jau parsēts. Nosauktu tool_choice piemēro hostētie atvērto svaru modeļi.

Pieprasījuma pamatteksts
{
  "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"}
    }
  ]
}

Pirms bloka lasīšanas pārbaudiet, vai stop_reason ir tool_use. Funkciju izsaukšana

Kā ierodas JSON

  • JSON ir virkne. Atbildei līdzās nav parsēta objekta: palaidiet savu JSON parsētāju uz message.content.
  • Ar stream: true JSON ierodas delta.content gabalos. Savienojiet tos un parsējiet vienreiz, kad straume ir beigusies; atsevišķs gabals nav derīgs JSON.
  • Hostēts atvērto svaru modelis uz response_format pieprasījumu atbild bez spriešanas teksta: reasoning_content ir null.

Pārbaudiet saņemto

Shēma vada to, kā modelis raksta. API pabeigto atbildi ar jūsu shēmu nesalīdzina, tāpēc galīgo pārbaudi veic jūsu kods:

  • Parsējiet kļūdu apstrādātāja iekšienē, kā to dara piemērs augšā.
  • Validējiet parsēto objektu ar to pašu shēmu savā kodā, piemēram, ar JSON Schema bibliotēku, Pydantic vai Zod.
  • Gara atbilde var beigties, pirms JSON ir pilns. Nestraumēta atbilde ziņo finish_reason tikai kā stop vai tool_calls, tāpēc signāls ir parsēšanas kļūda. Pajautājiet vēlreiz vai pieprasiet mazāku objektu.

Kļūdas

Statuss Veids Ziņojums Kad
400 invalid_request_error <id> does not accept response_format Modelis nepieņem nevienu režīmu.
400 invalid_request_error <id> does not accept response_format json_schema; use json_object Modelis pieņem json_object, un jūs nosūtījāt json_schema.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … response_format nav type vai nav JSON objekts.

Abas 400 atbildes tiek sūtītas, pirms no jūsu atlikuma kaut kas tiek norakstīts. Kļūdu apstrāde