Utilizarea tokenilor și reasoning_tokens
Pe această pagină
Actualizat la 3 noiembrie 2026. Conform documentației de referință a API-ului Chat Completions xAI:
max_tokenseste depreciat în favoarea luimax_completion_tokens, care limitează doar răspunsul vizibil. Sursă: Chat Completions.
Înțelegerea facturării pe baza tokenilor
Fiecare solicitare către API-ul Chat Completions este facturată în funcție de numărul de tokeni consumați. Obiectul usage din răspuns vă oferă un număr exact, esențial pentru monitorizarea costurilor, optimizarea prompturilor și dimensionarea bugetelor pentru API.
Obiectul standard usage
Iată structura obiectului usage returnat cu fiecare răspuns:
{
"usage": {
"prompt_tokens": 127,
"completion_tokens": 342,
"total_tokens": 469
}
}
Cei trei contori de bază
prompt_tokens: numărul de tokeni din solicitarea dumneavoastră (mesajul de sistem + istoricul + noul mesaj). Aceasta reprezintă partea de „intrare“ a facturării.completion_tokens: numărul de tokeni generați de model în răspunsul său. Aceasta este partea de „ieșire“.total_tokens: suma celor două precedente. Acesta este totalul facturat pentru această solicitare.
Impactul istoricului asupra costurilor
Deoarece endpoint-ul este fără stare (stateless), istoricul este trimis cu fiecare solicitare. Aceasta înseamnă că prompt_tokens crește la fiecare schimb:
Schimb 1 : prompt_tokens = 50 (sistem + 1 mesaj utilizator)
Schimb 2 : prompt_tokens = 150 (sistem + 2 utilizator + 1 asistent)
Schimb 3 : prompt_tokens = 300 (sistem + 3 utilizator + 2 asistent)
Schimb 10: prompt_tokens = 1500 (sistem + 10 utilizator + 9 asistent)
Pentru conversațiile lungi, costul istoricului poate depăși rapid costul răspunsului propriu-zis.
reasoning_tokens: specific modelelor de raționament
Modelele Grok cu capacități de raționament (cum ar fi grok-4.20-0309-reasoning) adaugă un câmp suplimentar în obiectul usage:
{
"usage": {
"prompt_tokens": 127,
"completion_tokens": 892,
"total_tokens": 1019,
"completion_tokens_details": {
"reasoning_tokens": 550
}
}
}
Ce sunt reasoning_tokens?
reasoning_tokens reprezintă tokenii utilizați de model pentru raționamentul său intern — „gândirea“ pe care o face înainte de a produce răspunsul final. Acești tokeni sunt generați, dar nu sunt vizibili în câmpul content al răspunsului.
În exemplul de mai sus:
- Modelul a generat 892 de tokeni în total (
completion_tokens) - Din care 550 sunt tokeni de raționament intern (
reasoning_tokens) - Rămânând 342 de tokeni pentru răspunsul vizibil (892 - 550)
De ce este important acest aspect
Tokenii de raționament sunt facturați la fel ca tokenii normali de completare. Pentru un model de raționament, răspunsul vizibil poate reprezenta doar o fracțiune din costul total:
usage = response.usage
visible_tokens = usage.completion_tokens - usage.completion_tokens_details.reasoning_tokens
reasoning_tokens = usage.completion_tokens_details.reasoning_tokens
print(f"Visible tokens: {visible_tokens}")
print(f"Reasoning tokens: {reasoning_tokens}")
print(f"Reasoning ratio: {reasoning_tokens / usage.completion_tokens * 100:.0f}%")
Nu este neobișnuit ca tokenii de raționament să reprezinte între 50% și 80% din tokenii de completare pentru întrebările complexe.
Strategii de optimizare a costurilor
Reducerea lui prompt_tokens
- Sumarizați istoricul: în loc să trimiteți întreaga conversație, sumarizați schimburile mai vechi
- Limitați mesajul de sistem: un prompt de sistem de 500 de tokeni este rareori necesar — țintiți spre 100–200 de tokeni
- Filtrați mesajele: trimiteți doar schimburile relevante pentru întrebarea curentă
Controlul lui completion_tokens
- Utilizați
max_completion_tokens(max_tokenseste depreciat): acesta limitează răspunsul vizibil, nu raționamentul - Specificați formatul: „Răspundeți în 3 propoziții“ costă mai puțin decât „Explicați în detaliu“
- Alegeți modelul potrivit: un model fără capacități de raționament este mai puțin costisitor dacă sarcina nu necesită o gândire complexă
Monitorizarea costurilor în producție
import json
def log_usage(response, requete_id: str):
usage = response.usage
log = {
"id": requete_id,
"prompt": usage.prompt_tokens,
"completion": usage.completion_tokens,
"total": usage.total_tokens,
}
if hasattr(usage, "completion_tokens_details") and usage.completion_tokens_details:
log["reasoning"] = usage.completion_tokens_details.reasoning_tokens
print(json.dumps(log))
Puncte cheie
- Obiectul
usageconțineprompt_tokens,completion_tokensșitotal_tokens prompt_tokenscrește la fiecare schimb din cauza istoricului trimis- Modelele de raționament adaugă
reasoning_tokensîncompletion_tokens_details - Tokenii de raționament sunt facturați la tariful de ieșire, dar sunt invizibili în răspuns; ponderea lor în cost depinde de sarcină și efort, așa că măsurați-i
- Optimizați prin sumarizarea istoricului, ajustarea efortului de raționament, limitarea lui
max_completion_tokensși alegerea modelului adecvat