Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Vastuse vorming: id, choices ja finish_reason

Õppetund 8 / 12 Värskendatud 3. november 2026 Arendajatele
Sellel lehel
  1. Chat Completions vastuse anatoomia
  2. Täielik vastuse struktuur
  3. Massiiv choices
  4. finish_reason väärtused
  5. Erinevate juhtumite käsitlemine
  6. Peamised punktid

Uuendatud 3. novembril 2026 vastavalt xAI Chat Completions API dokumentatsioonile: väljal finish_reason on dokumenteeritud ainult väärtused stop, length ning voogedastuse korral end_turn või null. Vanemas versioonis olnud väärtused tool_calls ja content_filter puuduvad ning tööriistakutsed tuvastatakse välja message.tool_calls kaudu. max_tokens on aegunud ja selle asemel kasutatakse max_completion_tokens. Allikas: Chat Completions.

Chat Completions vastuse anatoomia

Iga päring Chat Completions lõpp-punktile tagastab standardiseeritud väljadega JSON-objekti. Selle struktuuri mõistmine on hädavajalik andmete korrektseks eraldamiseks, äärmuslike olukordade lahendamiseks ja integratsioonide silumiseks.

id
Unikaalne identifikaator
choices
Vastuste massiiv
usage
Tokenite loendurid
system_fingerprint
Süsteemi sõrmejälg

Täielik vastuse struktuur

Siin on näide API poolt tagastatavast tüüpilisest vastusest:

{
  "id": "chatcmpl-abc123xyz",
  "object": "chat.completion",
  "created": 1712345678,
  "model": "grok-4.20-0309-reasoning",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Deep learning is a branch of machine learning..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 42,
    "completion_tokens": 156,
    "total_tokens": 198
  },
  "system_fingerprint": "fp_abc123"
}

Ülemise taseme väljad

  • id: Unikaalne identifikaator lõpetuse jaoks (vormingus chatcmpl-...). Kasulik jälgimiseks ja silumiseks.
  • object: Alati "chat.completion". Võimaldab eristada seda vastusetüüpi teistest lõpp-punktidest.
  • created: Unixi ajatempel, millal vastus loodi.
  • model: Mudel, mis vastuse genereeris. Võib veidi erineda päritud mudelist, kui kasutad aliast.
  • choices: Massiiv, mis sisaldab genereeritud vastust või vastuseid.
  • usage: Tokenite loendurid arveldamiseks.
  • system_fingerprint: Kasutatud süsteemi konfiguratsiooni sõrmejälg.

Massiiv choices

Väli choices on massiiv, mis sisaldab tavaliselt ühte elementi (indeksiga 0). Iga element sisaldab:

  • index: Positsioon massiivis (algab 0-st)
  • message: Objekt, mis sisaldab välja role (alati "assistant") ja content (genereeritud tekst)
  • finish_reason: Põhjus, miks genereerimine peatus

Tekstivastuse eraldamiseks:

# Python
response_text = response.choices[0].message.content
// JavaScript
const responseText = response.choices[0].message.content;

finish_reason väärtused

Väli finish_reason näitab, miks mudel teksti genereerimise lõpetas:

stop

"finish_reason": "stop"

Mudel lõpetas vastuse loomulikul teel. See on kõige levinum ja soovitavaim juhtum: mudel ütles kõik, mida ta öelda tahtis.

length

"finish_reason": "length"

Genereerimine peatus, kuna väljundi piirang oli saavutatud – tegemist on väljaga max_completion_tokens, mis asendab nüüd aegunud max_tokens ja loendab ainult nähtavat vastust. Seetõttu on vastus lühendatud: suurenda piirangut või taotle jätkamist.

end_turn või null voogedastuse korral

Voogedastuse korral sisaldab iga vahepealne tükk väljal finish_reason väärtust "end_turn" või null; ainult viimane tükk näitab peatumise põhjust.

Mida dokumentatsioon ei maini

xAI API dokumentatsioon toob välja ainult need väärtused. Seal ei mainita ei content_filter ega tööriistakutse ajal tagastatavat väärtust: et teada saada, kas mudel soovib tööriista kasutada, kontrolli välja message.tool_calls olemasolu, mitte finish_reason väärtust.

Erinevate juhtumite käsitlemine

Tootmiskeskkonnas pead kontrollima finish_reason, et oma käitumist kohandada:

choice = response.choices[0]

if choice.message.tool_calls:
    # Mudel soovib kutsuda üht või mitut tööriista
    for tool_call in choice.message.tool_calls:
        print(f"Tool requested: {tool_call.function.name}")

elif choice.finish_reason == "length":
    # Lühendatud vastus: teavita kasutajat või jätka
    print(choice.message.content)
    print("[Truncated response: increase max_completion_tokens]")

else:
    # Täielik vastus
    print(choice.message.content)

Peamised punktid

  • Vastus sisaldab unikaalset id, massiivi choices ja objekti usage
  • Genereeritud tekst asub aadressil choices[0].message.content
  • finish_reason näitab, miks genereerimine peatus: dokumentatsioon toob välja stop ja length (ning voogedastuse korral end_turn või null)
  • Lühendatud vastuste tuvastamiseks kontrolli finish_reason ja tööriistakutsete jaoks message.tool_calls
  • system_fingerprint identifitseerib genereerimisel kasutatud süsteemi konfiguratsiooni