max_completion_tokens și bugetul de tokeni
Pe această pagină
Lecție rescrisă la 3 noiembrie 2026 pe baza referinței API xAI (Chat Completions și Responses), a ghidului Reasoning și a celor mai bune practici xAI:
max_completion_tokensșimax_output_tokenslimitează doar răspunsul vizibil—tokenii de raționament și cei de apelare a funcțiilor nu se iau în calcul pentru această limită—și au implicit valoarea de 128.000. Versiunea anterioară susținea contrariul și dimensiona limita pe baza raționamentului; seta, de asemenea, un efort pentrugrok-4.20-0309-reasoning, model care nu acceptă acest parametru. Surse: Chat Completions · Responses · Reasoning.
Ce limitează de fapt plafonul
În cazul unui model de raționament, ați putea crede că limita de ieșire își împarte bugetul între gândire și răspuns. La xAI, lucrurile nu stau deloc așa. Referința API este explicită: max_completion_tokens (Chat Completions) și max_output_tokens (Responses API) se aplică exclusiv tokenilor de ieșire vizibili; tokenii de raționament și cei de apelare a funcțiilor nu sunt numărați.
max_completion_tokens → doar răspunsul vizibil
reasoning tokens → în afara limitei, setați prin efort
Fără o valoare specificată, acest plafon are implicit 128.000 de tokeni. În ceea ce privește vechiul max_tokens, acesta este depreciat în favoarea lui max_completion_tokens.
Dirijarea raționamentului: efortul, nu plafonul
Deoarece plafonul nu afectează raționamentul, cantitatea acestuia este reglată prin efort. Pentru grok-4.7, grok-4.6 și grok-4.5, parametrul este reasoning_effort în Chat Completions și reasoning.effort în Responses API; valoarea implicită este high, acceptă low și medium, iar de la Grok 4.6 încolo acceptă și xhigh. Raționamentul nu poate fi dezactivat.
grok-4.20-0309-reasoning nu primește acest parametru: raționează întotdeauna, iar varianta sa grok-4.20-0309-non-reasoning răspunde fără raționament. În sfârșit, la grok-4.20-multi-agent, efortul nu setează profunzimea raționamentului, ci numărul de agenți mobilizați (4 sau 16).
response = client.chat.completions.create(
model="grok-4.7",
reasoning_effort="low", # sarcină simplă: puțin raționament
messages=[{"role": "user", "content": "Clasificați acest tichet: facturare, acces sau bug?"}],
)
print(response.usage.completion_tokens_details.reasoning_tokens)
Numărul de tokeni de raționament apare în utilizarea răspunsului: usage.completion_tokens_details.reasoning_tokens în Chat Completions, usage.output_tokens_details.reasoning_tokens în Responses API. Aceștia fac parte din tokenii facturați: deci efortul, nu plafonul de ieșire, este cel care influențează această linie de cost.
Dimensionarea plafonului de ieșire
Plafonul servește doar la limitarea lungimii răspunsului propriu-zis. Cele mai bune practici xAI oferă o regulă simplă: setați-l peste lungimea maximă a răspunsului pe care îl anticipați sau lăsați valoarea sa implicită de 128.000 de tokeni. Un plafon prea restrictiv va trunchia răspunsul vizibil, indiferent de efortul de raționament.
| Răspuns anticipat | Plafon de ieșire rezonabil |
|---|---|
| O etichetă, un număr | câteva zeci de tokeni |
| Un paragraf | 500 până la 1.000 de tokeni |
| Un raport structurat | câteva mii de tokeni |
| Nicio idee precisă | valoarea implicită |
Detectarea trunchierii
Când răspunsul vizibil atinge plafonul, Chat Completions returnează "length" în câmpul finish_reason în loc de "stop", iar Responses API returnează un status incomplete. Puteți detecta această situație și puteți reîncerca cu un plafon mai mare:
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":
# Răspunsul vizibil a fost tăiat: reîncercați cu un plafon mai mare
response = client.chat.completions.create(
model="grok-4.7",
messages=[{"role": "user", "content": question}],
max_completion_tokens=8000,
)
A nu se confunda cu limita de context
Plafonul de ieșire este independent de fereastra de context a modelului—500.000 de tokeni pentru grok-4.7, 1 milion pentru grok-4.20-0309-reasoning—care limitează întreaga conversație. De asemenea, o cerere de raționament profund poate dura câteva minute: xAI recomandă să alocați cel puțin 900 de secunde per cerere și să preferați streaming-ul.
Puncte cheie
max_completion_tokensșimax_output_tokenslimitează doar răspunsul vizibil: raționamentul nu contează pentru această limită- Fără o valoare specificată, plafonul de ieșire are implicit 128.000 de tokeni;
max_tokenseste depreciat - Cantitatea de raționament este setată prin efort (
reasoning_effortsaureasoning.effort) la grok-4.5 până la 4.7;grok-4.20-0309-reasoningnu dispune de acest parametru - Tokenii de raționament apar în utilizare și fac parte din facturare
- Un răspuns trunchiat se detectează prin
finish_reason: "length"sau statusulincomplete