Utilizzo dei token e reasoning_tokens
In questa pagina
Aggiornato il 3 novembre 2026. In base al riferimento API Chat Completions di xAI:
max_tokensè deprecato a favore dimax_completion_tokens, che limita solo la risposta visibile. Fonte: Chat Completions.
Comprendere la fatturazione dei token
Ogni richiesta all’API Chat Completions viene fatturata in base al numero di token consumati. L’oggetto usage nella risposta ti fornisce un conteggio esatto, essenziale per monitorare i costi, ottimizzare i prompt e dimensionare i tuoi budget API.
La struttura standard dell’oggetto usage
Ecco la struttura dell’oggetto usage restituito con ogni risposta:
{
"usage": {
"prompt_tokens": 127,
"completion_tokens": 342,
"total_tokens": 469
}
}
I tre contatori di base
prompt_tokens: numero di token nella tua richiesta (messaggio di sistema + cronologia + nuovo messaggio). Questo è il lato “input” della fatturazione.completion_tokens: numero di token generati dal modello nella sua risposta. Questo è il lato “output”.total_tokens: somma dei due precedenti. Questo è il totale fatturato per questa richiesta.
Impatto della cronologia sui costi
Poiché l’endpoint è stateless, la cronologia viene inviata con ogni richiesta. Ciò significa che prompt_tokens aumenta a ogni scambio:
Scambio 1 : prompt_tokens = 50 (sistema + 1 messaggio utente)
Scambio 2 : prompt_tokens = 150 (sistema + 2 utente + 1 assistente)
Scambio 3 : prompt_tokens = 300 (sistema + 3 utente + 2 assistente)
Scambio 10: prompt_tokens = 1500 (sistema + 10 utente + 9 assistente)
Per conversazioni lunghe, il costo della cronologia può superare rapidamente il costo della risposta stessa.
reasoning_tokens: specifico per i modelli di ragionamento
I modelli Grok con capacità di ragionamento (come grok-4.20-0309-reasoning) aggiungono un campo extra all’oggetto usage:
{
"usage": {
"prompt_tokens": 127,
"completion_tokens": 892,
"total_tokens": 1019,
"completion_tokens_details": {
"reasoning_tokens": 550
}
}
}
Cosa sono i reasoning_tokens?
I reasoning_tokens rappresentano i token utilizzati dal modello per il suo ragionamento interno — il “pensiero” che elabora prima di produrre la risposta finale. Questi token vengono generati ma non sono visibili nel campo content della risposta.
Nell’esempio sopra:
- Il modello ha generato 892 token in totale (
completion_tokens) - Di cui 550 token di ragionamento interno (
reasoning_tokens) - Lasciando 342 token di risposta visibile (892 - 550)
Perché è importante
I token di ragionamento sono fatturati come normali token di completamento. Per un modello di ragionamento, la risposta visibile può rappresentare solo una frazione del costo totale:
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}%")
Non è raro che i token di ragionamento rappresentino dal 50 all’80% dei token di completamento per domande complesse.
Strategie di ottimizzazione dei costi
Ridurre i prompt_tokens
- Riassumi la cronologia: invece di inviare l’intera conversazione, riassumi gli scambi più vecchi
- Limita il messaggio di sistema: un prompt di sistema di 500 token è raramente necessario — punta a 100–200 token
- Filtra i messaggi: invia solo gli scambi rilevanti per la domanda corrente
Controllare i completion_tokens
- Usa
max_completion_tokens(max_tokensè deprecato): limita la risposta visibile, non il ragionamento - Specifica il formato: “Rispondi in 3 frasi” costa meno di “Spiega in dettaglio”
- Scegli il modello giusto: un modello non dedicato al ragionamento è meno costoso se il compito non richiede un pensiero complesso
Monitorare i costi in produzione
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))
Punti chiave
- L’oggetto
usagecontieneprompt_tokens,completion_tokensetotal_tokens - I
prompt_tokensaumentano a ogni scambio a causa della cronologia inviata - I modelli di ragionamento aggiungono
reasoning_tokensincompletion_tokens_details - I token di ragionamento sono fatturati alla tariffa di output ma sono invisibili nella risposta: la loro quota di costo dipende dal compito e dallo sforzo, quindi misurala
- Ottimizza riassumendo la cronologia, regolando lo sforzo di ragionamento, limitando
max_completion_tokense scegliendo il modello appropriato