Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Vastausmuoto: id, choices ja finish_reason

Oppitunti 8 / 12 Päivitetty 3. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Chat Completions -vastauksen anatomia
  2. Täydellinen vastausrakenne
  3. choices-matriisi
  4. finish_reason-arvot
  5. Eri tapausten käsittely
  6. Keskeiset asiat

Päivitetty 3. marraskuuta 2026 xAI Chat Completions API -viitteiden perusteella: vain arvot stop, length sekä suoratoistossa end_turn tai null on dokumentoitu kentälle finish_reason. Vanhemman version arvoja tool_calls ja content_filter ei ole lueteltu, ja työkalukutsut havaitaan kohdasta message.tool_calls. max_tokens on vanhentunut ja korvattu parametrilla max_completion_tokens. Lähde: Chat Completions.

Chat Completions -vastauksen anatomia

Jokainen Chat Completions -päätepisteen kutsu palauttaa JSON-objektin, joka on jäsennelty standardoitujen kenttien avulla. Tämän rakenteen ymmärtäminen on välttämätöntä datan oikeaoppista käsittelyä, reunatapausten hallintaa ja integraatioiden vianetsintää varten.

id
Unikki tunniste
choices
Vastausmatriisi
usage
Token-laskurit
system_fingerprint
Järjestelmän sormenjälki

Täydellinen vastausrakenne

Tässä on esimerkki tyypillisestä API:n palauttamasta vastauksesta:

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

Ylimmän tason kentät

  • id: Unikki tunniste suoritukselle (muoto chatcmpl-...). Hyödyllinen seurantaan ja vianetsintään.
  • object: Aina "chat.completion". Mahdollistaa tämän vastauksen erottamisen muista päätepisteistä.
  • created: Unix-aikaleima vastauksen luomishetkelle.
  • model: Malli, joka tuotti vastauksen. Saattaa poiketa hieman pyydetystä mallista, jos käytät aliasta.
  • choices: Matriisi, joka sisältää tuotetun vastauksen tai vastaukset.
  • usage: Token-laskurit laskutusta varten.
  • system_fingerprint: Käytetyn järjestelmäkokoonpanon sormenjälki.

choices-matriisi

Kenttä choices on matriisi, joka sisältää yleensä yhden alkion (indeksi 0). Jokainen alkio sisältää:

  • index: Sijainti matriisissa (alkaa nollasta)
  • message: Objekti, jossa on role (aina "assistant") ja content (tuotettu teksti)
  • finish_reason: Syy, miksi generointi pysähtyi

Tekstivastauksen erottaminen:

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

finish_reason-arvot

Kenttä finish_reason ilmoittaa syyn, miksi malli lopetti tekstin tuottamisen:

stop

"finish_reason": "stop"

Malli viimeisteli vastauksensa luonnollisesti. Tämä on yleisin ja toivotuin tapaus: malli sanoi kaiken, mitä sen tarvitsi sanoa.

length

"finish_reason": "length"

Generointi pysähtyi, koska tulostusrajoitus saavutettiin – kyseessä on max_completion_tokens, joka korvaa vanhentuneen max_tokens-parametrin ja laskee vain näkyvän vastauksen. Vastaus on siis katkaistu: kasvata rajaa tai käynnistä jatkokutsu.

end_turn tai null suoratoistossa

Suoratoistossa jokainen väliosio sisältää arvon "end_turn" tai null kentässä finish_reason; vain viimeinen osio ilmoittaa varsinaisen pysäytyssyyn.

Mitä viite ei dokumentoi

xAI:n API-viite dokumentoi vain nämä arvot. Se ei mainitse arvoa content_filter eikä työkalukutsun aikana palautettavaa arvoa: selvittääksesi, pyytääkö malli työkalua, tarkista kentän message.tool_calls olemassaolo äläkä luota finish_reason-arvoon.

Eri tapausten käsittely

Tuotantoympäristössä sinun on tarkistettava finish_reason mukauttaaksesi toimintaasi:

choice = response.choices[0]

if choice.message.tool_calls:
    # Malli haluaa kutsua yhtä tai useampaa työkalua
    for tool_call in choice.message.tool_calls:
        print(f"Tool requested: {tool_call.function.name}")

elif choice.finish_reason == "length":
    # Katkaistu vastaus: ilmoita käyttäjälle tai jatka
    print(choice.message.content)
    print("[Truncated response: increase max_completion_tokens]")

else:
    # Täydellinen vastaus
    print(choice.message.content)

Keskeiset asiat

  • Vastaus sisältää unikin id:n, choices-matriisin ja usage-objektin
  • Tuotettu teksti löytyy kohdasta choices[0].message.content
  • finish_reason kertoo, miksi generointi pysähtyi: viite dokumentoi arvot stop ja length (sekä end_turn tai null suoratoistossa)
  • Tarkista finish_reason havaitaksesi katkaistut vastaukset ja message.tool_calls työkalukutsuja varten
  • system_fingerprint tunnistaa generointiin käytetyn järjestelmäkokoonpanon