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

max_completion_tokens ja token-budjetti

Oppitunti 10 / 12 Päivitetty 3. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Mitä raja todellisuudessa rajoittaa
  2. Päättelyn ohjaus: effort, ei raja
  3. Tulostusrajan mitoitus
  4. Katkaisun havaitseminen
  5. Älä sekoita kontekstirajaan
  6. Keskeiset asiat

Oppitunti kirjoitettu uudelleen 3. marraskuuta 2026 xAI:n API-oppaan (Chat Completions ja Responses), Reasoning-oppaan sekä xAI:n parhaiden käytäntöjen perusteella: max_completion_tokens ja max_output_tokens rajoittavat vain näkyvää vastausta – päättelytokenit ja funktiokutsutokenit eivät lasketa tähän rajaan – ja niiden oletusarvo on 128 000. Edellinen versio väitti päinvastaista ja määritti rajan päättelyn perusteella; se asetti myös effort-parametrin mallille grok-4.20-0309-reasoning, joka ei hyväksy sitä. Lähteet: Chat Completions · Responses · Reasoning.

Mitä raja todellisuudessa rajoittaa

Päättelymallin kohdalla saatat olettaa, että tulostusraja jakaa budjetin ajattelun ja vastauksen kesken. Näin ei ole xAI:n järjestelmässä. API-opas on täysin selvä: max_completion_tokens (Chat Completions) ja max_output_tokens (Responses API) koskevat vain näkyviä tulostokeneja; päättelytokenit ja funktiokutsutokenit eivät sisälly tähän laskentaan.

max_completion_tokens → vain näkyvä vastaus
päättelytokenit → rajan ulkopuolella, määräytyy effort-parametrin mukaan

Ilman määritettyä arvoa tämä raja on oletuksena 128 000 tokenia. Vanha max_tokens on vanhentunut ja korvattu parametrilla max_completion_tokens.

Päättelyn ohjaus: effort, ei raja

Koska raja ei vaikuta päättelyyn, sen määrää effort-parametri. Malleissa grok-4.7, grok-4.6 ja grok-4.5 parametri on reasoning_effort Chat Completionsissa ja reasoning.effort Responses API:ssa. Oletusarvo on high, hyväksytyt arvot ovat low ja medium, ja Grok 4.6:sta alkaen myös xhigh. Päättelyä ei voi ottaa kokonaan pois käytöstä.

Malli grok-4.20-0309-reasoning ei hyväksy tätä parametria: se päättelee aina, kun taas sen muunnos grok-4.20-0309-non-reasoning vastaa ilman päättelyä. Mallissa grok-4.20-multi-agent effort ei määritä päättelyn syvyyttä, vaan mobilisoitujen agenttien määrän (4 tai 16).

response = client.chat.completions.create(
    model="grok-4.7",
    reasoning_effort="low",  # yksinkertainen tehtävä: vähän päättelyä
    messages=[{"role": "user", "content": "Luokittele tämä tiketti: laskutus, käyttöoikeus vai bugi?"}],
)
print(response.usage.completion_tokens_details.reasoning_tokens)

Päättelytokenien määrä näkyy vastauksen käyttötilastoissa: usage.completion_tokens_details.reasoning_tokens Chat Completionsissa ja usage.output_tokens_details.reasoning_tokens Responses API:ssa. Ne sisältyvät laskutettaviin tokeneihin: siis effort, ei tulostusraja, vaikuttaa tähän kuluerään.

Tulostusrajan mitoitus

Rajan ainoa tarkoitus on rajoittaa itse vastauksen pituutta. xAI:n parhaat käytännöt antavat yksinkertaisen säännön: aseta raja odotettua pisimmän vastauksen yläpuolelle tai jätä oletusarvo 128 000 tokenia voimaan. Liian tiukka raja katkaisee näkyvän vastauksen riippumatta päättelyn määrästä.

Odotettu vastausKohtuullinen tulostusraja
Tunniste, numeromuutama kymmenen tokenia
Kappale500–1 000 tokenia
Jäsennelty raporttiuseita tuhansia tokeneja
Ei tarkkaa käsitystäoletusarvo

Katkaisun havaitseminen

Kun näkyvä vastaus osuu rajaan, Chat Completions palauttaa "length" kentässä finish_reason arvon "stop" sijaan, ja Responses API palauttaa tilan incomplete. Voit havaita tämän tilanteen ja yrittää uudelleen suuremmalla rajalla:

response = client.chat.completions.create(
    model="grok-4.7",
    messages=[{"role": "user", "content": question}],
    max_completion_tokens=2000,
)

if response.choices[0].finish_reason == "length":
    # Näkyvä vastaus katkesi: yritä uudelleen suuremmalla rajalla
    response = client.chat.completions.create(
        model="grok-4.7",
        messages=[{"role": "user", "content": question}],
        max_completion_tokens=8000,
    )

Älä sekoita kontekstirajaan

Tulostusraja on riippumaton mallin konteksti-ikkunasta – 500 000 tokenia mallille grok-4.7, 1 miljoona mallille grok-4.20-0309-reasoning – joka rajoittaa koko keskustelua. Syvä päättelypyyntö voi lisäksi kestää useita minuutteja: xAI suosittelee varaamaan vähintään 900 sekuntia pyyntöä kohden ja suosimaan suoratoistoa (streaming).

Keskeiset asiat

  • max_completion_tokens ja max_output_tokens rajoittavat vain näkyvää vastausta: päättelyä ei lasketa tähän
  • Ilman arvoa tulostusraja on oletuksena 128 000 tokenia; max_tokens on vanhentunut
  • Päättelyn määrä määritetään effort-parametrilla (reasoning_effort tai reasoning.effort) malleissa grok-4.5–4.7; mallilla grok-4.20-0309-reasoning tätä ei ole
  • Päättelytokenit näkyvät käyttötilastoissa ja sisältyvät laskutukseen
  • Katkennut vastaus havaitaan arvosta finish_reason: "length" tai tilasta incomplete