Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Format odgovora: id, choices in finish_reason

Lekcija 8 od 12 Posodobljeno 3. november 2026 Razvijalec
Na tej strani
  1. Anatomija odgovora Chat Completions
  2. Celotna struktura odgovora
  3. Polje choices
  4. Vrednosti finish_reason
  5. Obravnava različnih primerov
  6. Ključne ugotovitve

Posodobljeno 3. novembra 2026 na podlagi referenčne dokumentacije API-ja xAI Chat Completions: za polje finish_reason sta dokumentirana le stop in length, pri pretakanju (streaming) pa še end_turn ali null. Vrednosti tool_calls in content_filter iz starejše različice niso navedene; klice orodij zaznaš preko message.tool_calls. Parameter max_tokens je zastarel in ga nadomešča max_completion_tokens. Vir: Chat Completions.

Anatomija odgovora Chat Completions

Vsak klic končne točke Chat Completions vrne objekt JSON, strukturiran s standardiziranimi polji. Razumevanje te strukture je ključno za pravilno ekstrakcijo podatkov, obravnavo robnih primerov in odpravljanje napak v tvojih integracijah.

id
Edinstveni identifikator
choices
Polje odgovorov
usage
Števci žetonov
system_fingerprint
Prstni odtis sistema

Celotna struktura odgovora

Tukaj je primer tipičnega odgovora, ki ga vrne API:

{
  "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"
}

Polja na najvišji ravni

  • id: Edinstveni identifikator za dokončanje (oblika chatcmpl-...). Uporaben za sledenje in odpravljanje napak.
  • object: Vedno "chat.completion". Omogoča razlikovanje te vrste odgovora od drugih končnih točk.
  • created: Časovni žig Unix za trenutek ustvarjanja odgovora.
  • model: Model, ki je ustvaril odgovor. Lahko se rahlo razlikuje od zahtevanega modela, če uporabljaš vzdevek (alias).
  • choices: Polje, ki vsebuje ustvarjeni odgovor ali odgovore.
  • usage: Števci žetonov za obračunavanje.
  • system_fingerprint: Prstni odtis uporabljene sistemske konfiguracije.

Polje choices

Polje choices je polje, ki običajno vsebuje en sam element (indeks 0). Vsak element vsebuje:

  • index: Položaj v polju (začne se z 0)
  • message: Objekt z lastnostma role (vedno "assistant") in content (ustvarjeno besedilo)
  • finish_reason: Razlog za zaustavitev generiranja

Za ekstrakcijo besedilnega odgovora:

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

Vrednosti finish_reason

Polje finish_reason označuje, zakaj je model prenehal generirati besedilo:

stop

"finish_reason": "stop"

Model je naravno zaključil svoj odgovor. To je najpogostejši in najbolj zaželen primer: model je povedal vse, kar je bilo potrebno.

length

"finish_reason": "length"

Generiranje se je ustavilo, ker je bila dosežena omejitev izhoda – max_completion_tokens, ki nadomešča zdaj zastareli max_tokens in šteje le vidni odgovor. Odgovor je zato obrezan: povečaj omejitev ali ponovno zaženi zahtevo za nadaljevanje.

end_turn ali null pri pretakanju

Pri pretakanju (streaming) vsak vmesni delček (chunk) nosi "end_turn" ali null v polju finish_reason; le zadnji delček označi razlog za zaustavitev.

Kaj referenčna dokumentacija ne omenja

Referenčna dokumentacija API-ja xAI dokumentira le te vrednosti. Ne omenja niti content_filter niti vrednosti, vrnjene med klicem orodja: da ugotoviš, ali model zahteva orodje, preveri prisotnost message.tool_calls namesto vrednosti finish_reason.

Obravnava različnih primerov

V produkcijskem okolju moraš preveriti finish_reason, da prilagodiš svoje obnašanje:

choice = response.choices[0]

if choice.message.tool_calls:
    # Model želi poklicati eno ali več orodij
    for tool_call in choice.message.tool_calls:
        print(f"Tool requested: {tool_call.function.name}")

elif choice.finish_reason == "length":
    # Obrezan odgovor: obvesti uporabnika ali nadaljuj
    print(choice.message.content)
    print("[Truncated response: increase max_completion_tokens]")

else:
    # Popoln odgovor
    print(choice.message.content)

Ključne ugotovitve

  • Odgovor vsebuje edinstven id, polje choices in objekt usage
  • Ustvarjeno besedilo se nahaja v choices[0].message.content
  • finish_reason označuje, zakaj se je generiranje ustavilo: referenčna dokumentacija navaja stop in length (ter end_turn ali null pri pretakanju)
  • Preveri finish_reason za zaznavo obrezanih odgovorov in message.tool_calls za klice orodij
  • system_fingerprint identificira sistemsko konfiguracijo, uporabljeno za generiranje