max_completion_tokens ja token-budjetti
Tällä sivulla
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_tokensjamax_output_tokensrajoittavat 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 mallillegrok-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 vastaus | Kohtuullinen tulostusraja |
|---|---|
| Tunniste, numero | muutama kymmenen tokenia |
| Kappale | 500–1 000 tokenia |
| Jäsennelty raportti | useita 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_tokensjamax_output_tokensrajoittavat vain näkyvää vastausta: päättelyä ei lasketa tähän- Ilman arvoa tulostusraja on oletuksena 128 000 tokenia;
max_tokenson vanhentunut - Päättelyn määrä määritetään effort-parametrilla (
reasoning_efforttaireasoning.effort) malleissa grok-4.5–4.7; mallillagrok-4.20-0309-reasoningtätä ei ole - Päättelytokenit näkyvät käyttötilastoissa ja sisältyvät laskutukseen
- Katkennut vastaus havaitaan arvosta
finish_reason: "length"tai tilastaincomplete