Válaszformátum: id, choices és finish_reason
Ezen az oldalon
Frissítve: 2026. november 3. az xAI Chat Completions API referenciája alapján: a
finish_reasonesetében csak astop, alength, valamint streamelés esetén azend_turnvagy anullértékek vannak dokumentálva; a régebbi verzióból ismerttool_callséscontent_filterértékek nem szerepelnek, a hívóeszközöket pedig amessage.tool_callsalapján észleljük. Amax_tokensparaméter elavult, helyette amax_completion_tokenshasználandó. Forrás: Chat Completions.
A Chat Completions válasz felépítése
A Chat Completions végpontra irányuló minden hívás szabványosított mezőkkel rendelkező JSON objektumot ad vissza. Ezen struktúra megértése elengedhetetlen az adatok helyes kinyeréséhez, a szélsőséges esetek kezeléséhez és az integrációid hibakereséséhez.
Teljes válaszstruktúra
Íme egy példa az API által visszaadott tipikus válaszra:
{
"id": "chatcmpl-abc123xyz",
"object": "chat.completion",
"created": 1712345678,
"model": "grok-4.20-0309-reasoning",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "A mélytanulás a gépi tanulás egyik ága..."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 42,
"completion_tokens": 156,
"total_tokens": 198
},
"system_fingerprint": "fp_abc123"
}
Legfelső szintű mezők
id: A kiegészítés egyedi azonosítója (chatcmpl-...formátumban). Nyomon követéshez és hibakereséshez hasznos.object: Mindig"chat.completion". Segít megkülönböztetni ezt a választípust más végpontokétól.created: Unix időbélyeg, amely jelzi, mikor jött létre a válasz.model: A választ generáló modell. Kismértékben eltérhet a kért modelltől, ha álnevet (alias) használsz.choices: A generált választ vagy válaszokat tartalmazó tömb.usage: Token-számlálók számlázási célokra.system_fingerprint: A használt rendszerkonfiguráció ujjlenyomata.
A choices tömb
A choices mező egy tömb, amely általában egyetlen elemet tartalmaz (0. index). Minden elem a következőket tartalmazza:
index: Pozíció a tömbön belül (0-tól indul)message: Objektum, amely tartalmazza arole(mindig"assistant") és acontent(a generált szöveg) mezőketfinish_reason: Az ok, ami miatt a generálás leállt
A szöveges válasz kinyerése:
# Python
response_text = response.choices[0].message.content
// JavaScript
const responseText = response.choices[0].message.content;
A finish_reason értékei
A finish_reason mező azt jelzi, miért állt le a modell a szöveg generálásával:
stop
"finish_reason": "stop"
A modell természetesen fejezte be a választ. Ez a leggyakoribb és legkívánatosabb eset: a modell elmondta mindazt, amit kellett.
length
"finish_reason": "length"
A generálás azért állt le, mert elérte a kimeneti limitet – ez a max_completion_tokens, amely felváltotta a már elavult max_tokens paramétert, és csak a látható választ számolja. A válasz tehát csonkolt: növeld a limitet, vagy indíts egy folytatási kérést.
end_turn vagy null streamelés esetén
Streamelés közben minden egyes közbenső csomag finish_reason mezője "end_turn" vagy null; csak az utolsó csomag jelzi a leállás okát.
Amit a referencia nem dokumentál
Az xAI API referenciája csak ezeket az értékeket dokumentálja. Nem említi sem a content_filter értéket, sem pedig azt az értéket, amely eszközlehívás (tool call) során tér vissza: annak ellenőrzésére, hogy a modell eszközt kér-e, a message.tool_calls jelenlétét kell vizsgálnod, nem pedig a finish_reason értékét.
Különböző esetek kezelése
Éles környezetben ellenőrizned kell a finish_reason értékét, hogy aszerint igazítsd a viselkedésedet:
choice = response.choices[0]
if choice.message.tool_calls:
# A modell egy vagy több eszközt hívni szeretne
for tool_call in choice.message.tool_calls:
print(f"Lekért eszköz: {tool_call.function.name}")
elif choice.finish_reason == "length":
# Csonkolt válasz: értesítsd a felhasználót vagy folytasd
print(choice.message.content)
print("[Csonkolt válasz: növeld a max_completion_tokens értékét]")
else:
# Teljes válasz
print(choice.message.content)
Főbb megállapítások
- A válasz tartalmaz egy egyedi
id-t, egychoicestömböt és egyusageobjektumot - A generált szöveg a
choices[0].message.contentmezőben található - A
finish_reasonjelzi, miért állt le a generálás: a referencia astopés alengthértékeket dokumentálja (valamint streamelés esetén azend_turnvagynullértékeket) - A
finish_reasonellenőrzésével fedezheted fel a csonkolt válaszokat, amessage.tool_callssegítségével pedig az eszközlehívásokat - A
system_fingerprintazonosítja a generáláshoz használt rendszerkonfigurációt