Vastuse vormingu mõistmine
Sellel lehel
Vastuse anatoomia
Kui saadad päringu aadressile POST /v1/responses, tagastab xAI server struktureeritud JSON-objekti. Iga välja mõistmine selles objektis on hädavajalik, et saaksid tulemusi oma rakenduses õigesti kasutada.
Täielik struktuur
Siin on tüüpiline vastus:
{
"id": "resp-abc123def456",
"object": "response",
"created_at": 1712000000,
"status": "completed",
"model": "grok-4.20-0309-reasoning",
"output": [
{
"type": "message",
"content": [
{
"type": "output_text",
"text": "Le machine learning est une branche de l'IA...",
"annotations": []
}
],
"status": "completed"
}
],
"usage": {
"input_tokens": 45,
"output_tokens": 180,
"total_tokens": 225,
"output_tokens_details": {
"reasoning_tokens": 120
},
"cost_in_nano_usd": 500000
}
}
Peamised väljad
id
Vastuse kordumatu identifikaator formaadis resp-xxx. Kasutad seda järgmisteks tegevusteks:
- Vestluste aheldamiseks kasutades
previous_response_id - Salvestatud vastuse toomiseks päringuga
GET /v1/responses/{id} - Vastuse kustutamiseks päringuga
DELETE /v1/responses/{id}
status
Vastuse olek:
| Olek | Tähendus |
|---|---|
completed | Vastus genereeriti edukalt |
failed | Viga genereerimise käigus |
incomplete | Vastus katkestati (tokenite piirang, sisufilter) |
in_progress | Genereerimine pooleli (voogedastus) |
Kontrolli alati olekut enne, kui kasutad vastuse sisu oma koodis.
output
Massiiv, mis sisaldab vastuse elemente. Igal elemendil on väli type:
message: Mudeli tekstivastusfunction_call: Mudeli taotletud tööriista kutse
Tekstisisu asub aadressil output[0].content[0].text. Annotatsioonid (tsitaadid, lingid) paiknevad sama objekti massiivis annotations.
usage
Kasutusteave, mida käsitleme allpool täpsemalt.
Kasutusobjekti mõistmine
Objekt usage on kulude jälgimiseks ülioluline:
{
"input_tokens": 45,
"output_tokens": 180,
"total_tokens": 225,
"output_tokens_details": {
"reasoning_tokens": 120
},
"cost_in_nano_usd": 500000
}
Sisend- ja väljundtokenid
input_tokens: Tokenite arv sinu vihjes (ja ajaloos, kui vestlusi aheldad)output_tokens: Genereeritud tokenite koguarv, kaasa arvatud arutluskäiktotal_tokens: Mõlema summa
Arutlustokenid
output_tokens_details.reasoning_tokens näitab, mitu tokenit mudel oma sisemiseks arutluskäiguks kasutas. Nende tokenite eest tasutakse, kuid need ei ole tekstivastuses nähtavad.
Ülaltoodud näites on 180 väljundtokenist 120 mõeldud arutluskäiguks ja vaid 60 moodustavad nähtava vastuse. See on arutlusmudelite jaoks tüüpiline suhe.
Kulu nano-USD-des
cost_in_nano_usd annab päringu täpse hinna. Teisendamine on lihtne:
Hind USD-des = cost_in_nano_usd / 1 000 000 000
Meie näite puhul: 500000 / 1 000 000 000 = 0,0005 USD (0,0005 dollarit).
Serveripoolne tööriistade kasutamine
Kui mudel kasutab sisseehitatud tööriistu, sisaldab objekt usage ka järgmist:
{
"server_side_tool_usage_details": {
"web_search_calls": 2,
"code_interpreter_calls": 0,
"x_search_calls": 1,
"document_search_calls": 0,
"file_search_calls": 0,
"mcp_calls": 0
}
}
See annab sulle täpse ülevaate, milliseid tööriistu ja mitu korda kutsuti.
Teksti eraldamine Pythonis
Siin on töökindel muster tekstisisu eraldamiseks:
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="Explique les listes en Python."
)
# Kontrolli olekut
if response.status == "completed":
text = response.output[0].content[0].text
print(text)
else:
print(f"Error: status {response.status}")
# Kuva kasutusstatistika
print(f"Tokens used: {response.usage.total_tokens}")
print(f"Cost: {response.usage.cost_in_nano_usd / 1e9:.6f} USD")
Peamised punktid
- Igal vastusel on kordumatu
id, mida saab kasutada aheldamiseks või taastamiseks - Kontrolli alati välja
statusenne sisu kasutamist - Tekst asub aadressil
output[0].content[0].text reasoning_tokenson tasulised, kuid vastuses nähtamatudcost_in_nano_usdjagatuna ühe miljardiga annab hinna dollarites