Dumphani kupita ku zomwe zili
Zotuluka zokonzedwa

Zotuluka zokonzedwa

Pemphani yankho ngati JSON: JSON object iliyonse, kapena JSON yotsatira schema yomwe mutumiza. Gwiritsani ntchito pamene pulogalamu, osati munthu, ikuwerenga yankho.

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 ndi text ya yankho, mu 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}
  }
}

Ma mode a response_format

response_format ndi field ya /v1/chat/completions. Popanda iyo yankho ndi text yanthawi zonse.

Mode Mtengo Zomwe mumapeza
JSON object {"type": "json_object"} Yankho ndi JSON yopanda mawonekedwe operekedwa. Nenani mu prompt ma key omwe mukufuna.
JSON schema {"type": "json_schema", "json_schema": {"name": "…", "schema": {…}}} Yankho limatsatira schema yomwe mutumiza: ma key ake, ma type ndi ma field ofunika.
Strict "strict": true Field ya json_schema, osati mode yachitatu. Ndi true pokhapokha mutatumiza false.
Field Mtundu Yokhazikika Kufotokozera Imagwira ntchito pa
type string json_object kapena json_schema. Yofunika mkati mwa response_format. text imalandiridwa ndipo imapereka yankho la text lanthawi zonse. Model iliyonse yolandira mode
json_schema.schema object JSON Schema yotsatiridwa ndi yankho. Itumizeni nthawi iliyonse type ikakhala json_schema. Model iliyonse yolandira mode
json_schema.name string Dzina la schema, monga mu mtundu wa OpenAI. Hosted open-weight model
json_schema.strict boolean true Kaya yankho liyenera kutsatira schema molondola. Ma model a Shannon amagwiritsa ntchito schema iliyonse ngati strict. Hosted open-weight model

JSON object mode siifuna schema. Tchulani ma key mu prompt:

Body ya pempho 
{
  "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"}
}

Kuthandizira pa model iliyonse

Model json_object json_schema
Model iliyonse ya Shannon (shannon-*) Inde Inde
Hosted open-weight model, kupatula zomwe zatchulidwa pansipa Inde Inde
Laguna-S-2.1-W4A16-AUTOROUND-REAP — —
inkling-W4A16-AUTOROUND-REAP Inde —

GET /v1/models imanena zomwezo pa id iliyonse: capabilities.json_schema pa model iliyonse, ndi capabilities.response_format pa hosted open-weight model. Ma model ndi mitengo

Ma keyword a schema ovomerezeka

Zomwe model imalandira za schema yanu zimadalira model ndi endpoint:

Ma model /v1/chat/completions /v1/responses
Ma model a Shannon Gawo la ma keyword lomwe lili pansipa, logwiritsidwa ntchito ngati strict. Schema monga mwaitumizira, yogwiritsidwa ntchito ngati strict.
Hosted open-weight model Schema monga mwaitumizira. strict ndi true pokhapokha mutaitumiza. Schema monga mwaitumizira. strict ndi true pokhapokha mutaitumiza.

Gawo la ma keyword la ma model a Shannon pa /v1/chat/completions:

Keyword Momwe imawerengedwera
Ma keyword owerengedwa type, format, title, description, nullable, enum, items, properties, required, minItems, maxItems, minimum, maximum, minLength, maxLength, pattern, anyOf, default
$ref Imathetsedwa kuchokera ku $defs kapena definitions pa mlingo wapamwamba wa schema. Ma keyword olembedwa pambali pa $ref, monga description, amasungidwa. Reference yopanda definition yofanana imawerengedwa ngati {"type": "object"}.
allOf Ma member amaphatikizidwa kukhala schema imodzi. Ma member awiri akakhazikitsa keyword yomweyo, yomaliza ndiyo imawerengedwa.
oneOf Imawerengedwa ngati anyOf.
Ma schema odzitchula okha Amakulitsidwa kufika pa milingo 24. Mlingo wozama kwambiri umawerengedwa ngati {"type": "object"}.
Kunja kwa gawo Keyword ina iliyonse, mwachitsanzo additionalProperties, const, multipleOf, uniqueItems, exclusiveMinimum, exclusiveMaximum, patternProperties, prefixItems, minProperties, maxProperties, not ndi if / then / else. Izi siili gawo la schema yomwe model imalandira.

Pa /v1/responses: text.format

/v1/responses imalemba pempho lomwelo ngati text.format. Schema ili mwachindunji mu format, pambali pa name ndi strict, osati pansi pa key ya json_schema. Pa JSON object mode tumizani {"format": {"type": "json_object"}}.

Body ya pempho 
{
  "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 ndi text ya part ya output_text ya item ya message:

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

Kuthandizira pa model iliyonse ndi zolakwika ndi zofanana ndi za /v1/chat/completions. Responses API

Pa /v1/messages: tool ngati schema

Mtundu wa Messages ulibe field ya structured output. Kuti mupeze JSON kuchokera ku ma model omwewo, itanani /v1/chat/completions kapena /v1/responses ndi kiyi yomweyo.

Kuti mukhalebe pa /v1/messages, fotokozani object ngati tool: ikani schema yanu mu input_schema ndipo tchulani tool mu tool_choice. input ya block ya tool_use imakhala object yanu, yosanthulidwa kale. tool_choice yotchulidwa imagwiritsidwa ntchito ndi hosted open-weight model.

Body ya pempho 
{
  "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"}
    }
  ]
}

Onetsetsani kuti stop_reason ndi tool_use musanawerenge block. Kuyitana mafunkseni

Momwe JSON imafikira

  • JSON ndi string. Yankho lilibe object yosanthulidwa pambali pake: yendetsani JSON parser yanu pa message.content.
  • Ndi stream: true JSON imafika mu zigawo za delta.content. Zilumikizeni ndi kuzisanthula stream ikatha; chigawo chimodzi chokha si JSON yovomerezeka.
  • Hosted open-weight model imayankha pempho la response_format popanda text ya reasoning: reasoning_content ndi null.

Yang'anani zomwe mwalandira

Schema imatsogolera momwe model imalembera. API siifanizira yankho lomalizidwa ndi schema yanu, choncho code yanu imachita kuyang'ana komaliza:

  • Santhulani mkati mwa error handler, monga chitsanzo chapamwamba chimachitira.
  • Tsimikizirani object yosanthulidwa ndi schema yomweyo mu code yanu, mwachitsanzo ndi JSON Schema library, Pydantic kapena Zod.
  • Yankho lalitali lingathe JSON isanakwane. Yankho lopanda stream limanena finish_reason ngati stop kapena tool_calls yokha, choncho cholakwika cha parse ndi chizindikiro. Funsaninso, kapena pemphani object yaying'ono.

Zolakwika

Status Mtundu Message Liti
400 invalid_request_error <id> does not accept response_format Model siilandira mode iliyonse.
400 invalid_request_error <id> does not accept response_format json_schema; use json_object Model imalandira json_object ndipo mwatumiza json_schema.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … response_format ilibe type, kapena si JSON object.

Mayankho awiri a 400 amatumizidwa chilichonse chisanachotsedwe pa balance yanu. Zolakwika