Fara í efni
Skipulögð úttök

Skipulögð úttök

Biddu um svarið sem JSON: hvaða JSON-hlut sem er, eða JSON sem fylgir skemanu sem þú sendir. Notaðu það þegar forrit, ekki manneskja, les svarið.

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-ið er texti svarsins, í 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}
  }
}

Hamir response_format

response_format er reitur í /v1/chat/completions. Án hans er svarið venjulegur texti.

Hamur Gildi Hvað þú færð
JSON hlutur {"type": "json_object"} Svarið er JSON án fyrirfram ákveðinnar lögunar. Segðu í prompt hvaða lykla þú vilt.
JSON schema {"type": "json_schema", "json_schema": {"name": "…", "schema": {…}}} Svarið fylgir skemanu sem þú sendir: lyklum þess, gerðum og nauðsynlegum reitum.
Strangt "strict": true Reitur í json_schema, ekki þriðji hamurinn. Hann er true nema þú sendir false.
Reitur Gerð Sjálfgefið Lýsing Notað af
type string json_object eða json_schema. Nauðsynlegt innan response_format. text er samþykkt og gefur venjulegt textasvar. Hvert líkan sem tekur við ham
json_schema.schema object JSON Schema sem svarið fylgir. Sendu það alltaf þegar type er json_schema. Hvert líkan sem tekur við ham
json_schema.name string Merkimiði fyrir skemað, eins og í OpenAI sniðinu. Hýst líkön með opnum þyngdum
json_schema.strict boolean true Hvort svarið þarf að fylgja skemanu nákvæmlega. Shannon líkönin beita öllum skemum sem strangri. Hýst líkön með opnum þyngdum

JSON hlutar hamurinn þarf ekkert skema. Nefndu lyklana í prompt:

Meginmál beiðni 
{
  "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"}
}

Stuðningur eftir líkani

Líkan json_object json_schema
Hvert Shannon líkan (shannon-*) Já Já
Hýst líkön með opnum þyngdum, nema þau sem eru nefnd hér að neðan Já Já
Laguna-S-2.1-W4A16-AUTOROUND-REAP — —
inkling-W4A16-AUTOROUND-REAP Já —

GET /v1/models skilar því sama fyrir hvert auðkenni: capabilities.json_schema á hverju líkani og capabilities.response_format á hýstu líkönunum með opnum þyngdum. Líkön og verð

Studd lykilorð skema

Hvað líkan fær af skemanu þínu fer eftir líkaninu og endapunktinum:

Líkön /v1/chat/completions /v1/responses
Shannon líkön Lykilorðaundirmengið hér að neðan, beitt sem strangt. Skemað eins og þú sendir það, beitt sem strangt.
Hýst líkön með opnum þyngdum Skemað eins og þú sendir það. strict er true nema þú sendir það. Skemað eins og þú sendir það. strict er true nema þú sendir það.

Lykilorðaundirmengi Shannon líkananna á /v1/chat/completions:

Lykilorð Hvernig það er lesið
Lykilorð sem eru lesin type, format, title, description, nullable, enum, items, properties, required, minItems, maxItems, minimum, maximum, minLength, maxLength, pattern, anyOf, default
$ref Leyst úr $defs eða definitions á efsta stigi skemans. Lykilorð sem skrifuð eru við hlið $ref, eins og description, eru geymd. Tilvísun án samsvarandi skilgreiningar er lesin sem {"type": "object"}.
allOf Meðlimirnir eru sameinaðir í eitt skema. Þar sem tveir meðlimir setja sama lykilorð gildir sá síðari.
oneOf Lesið sem anyOf.
Skemu sem vísa í sjálf sig Útvíkkuð í 24 stig. Dýpra stig er lesið sem {"type": "object"}.
Utan undirmengisins Öll önnur lykilorð, til dæmis additionalProperties, const, multipleOf, uniqueItems, exclusiveMinimum, exclusiveMaximum, patternProperties, prefixItems, minProperties, maxProperties, not og if / then / else. Þau eru ekki hluti af skemanu sem líkanið fær.

Á /v1/responses: text.format

/v1/responses skrifar sömu beiðni sem text.format. Skemað situr beint í format, við hlið name og strict, ekki undir json_schema lykli. Fyrir JSON hlutar haminn skaltu senda {"format": {"type": "json_object"}}.

Meginmál beiðni 
{
  "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-ið er text í output_text hluta message færslunnar:

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

Stuðningur eftir líkani og villurnar eru þau sömu og á /v1/chat/completions. Responses API

Á /v1/messages: tól sem skema

Messages sniðið hefur engan reit fyrir skipulagt úttak. Til að fá JSON úr sömu líkönum skaltu kalla á /v1/chat/completions eða /v1/responses með sama lykli.

Til að vera áfram á /v1/messages skaltu lýsa hlutnum sem tóli: settu skemað þitt í input_schema og nefndu tólið í tool_choice. input í tool_use blokkinni er þá hluturinn þinn, þegar þáttaður. Nefnt tool_choice er notað af hýstu líkönunum með opnum þyngdum.

Meginmál beiðni 
{
  "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"}
    }
  ]
}

Athugaðu að stop_reason sé tool_use áður en þú lest blokkina. Aðgerðaköll

Hvernig JSON-ið berst

  • JSON-ið er strengur. Svarið hefur engan þáttaðan hlut við hliðina: keyrðu JSON-þáttarann þinn á message.content.
  • Með stream: true berst JSON-ið í delta.content bútum. Sameinaðu þá og þáttaðu einu sinni þegar streyminu er lokið; stakur bútur er ekki gilt JSON.
  • Hýst líkan með opnum þyngdum svarar response_format beiðni án rökhugsunartexta: reasoning_content er null.

Athugaðu það sem þú færð

Skemað stýrir því hvernig líkanið skrifar. API ber fullbúið svar ekki saman við skemað þitt, svo kóðinn þinn gerir lokaathugunina:

  • Þáttaðu innan villumeðhöndlara, eins og dæmið efst gerir.
  • Staðfestu þáttaða hlutinn með sama skema í þínum eigin kóða, til dæmis með JSON Schema safni, Pydantic eða Zod.
  • Langt svar getur endað áður en JSON-ið er fullbúið. Svar sem er ekki streymt skilar aðeins finish_reason sem stop eða tool_calls, svo þáttunarvilla er merkið. Spyrðu aftur, eða biddu um minni hlut.

Villur

Staða Gerð Skilaboð Hvenær
400 invalid_request_error <id> does not accept response_format Líkanið tekur hvorugan hamanna.
400 invalid_request_error <id> does not accept response_format json_schema; use json_object Líkanið tekur við json_object og þú sendir json_schema.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … response_format hefur ekkert type, eða er ekki JSON-hlutur.

Bæði 400 svörin eru send áður en nokkuð er dregið af stöðunni þinni. Villumeðhöndlun