Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Utilizzo dei token e reasoning_tokens

Lezione 9 di 12 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Comprendere la fatturazione dei token
  2. La struttura standard dell’oggetto usage
  3. reasoning_tokens: specifico per i modelli di ragionamento
  4. Strategie di ottimizzazione dei costi
  5. Punti chiave

Aggiornato il 3 novembre 2026. In base al riferimento API Chat Completions di xAI: max_tokens è deprecato a favore di max_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 usage contiene prompt_tokens, completion_tokens e total_tokens
  • I prompt_tokens aumentano a ogni scambio a causa della cronologia inviata
  • I modelli di ragionamento aggiungono reasoning_tokens in completion_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_tokens e scegliendo il modello appropriato