Conteggio e budget dei token
In questa pagina
Comprendere i token
I token sono l’unità fondamentale di misura per gli LLM. Ogni chiamata API viene fatturata in token e ogni modello rifiuta le richieste che superano la sua finestra di contesto. Padroneggiare il conteggio dei token ti permette di fare tre cose che le approssimazioni non consentono: prevedere i costi prima di sostenerli, ottimizzare i tuoi prompt basandoti su numeri concreti invece che sull’istinto e rispettare i limiti di contesto senza scoprire un overflow solo quando l’API genera un errore.
Contare con tiktoken
La libreria tiktoken applica esattamente la stessa tokenizzazione del modello. Istanzii un encoder per il modello target, poi conti la lunghezza della sequenza codificata.
import tiktoken
# Encoder per i modelli GPT
encoder = tiktoken.encoding_for_model("gpt-5.6-terra")
def count_tokens(text: str) -> int:
"""Conta il numero di token in un testo."""
return len(encoder.encode(text))
# Esempi
print(count_tokens("Hello")) # ~1-2 token
print(count_tokens("Hello world")) # ~3-4 token
print(count_tokens("Development")) # ~2-3 token (gli accenti costano di più)
Il terzo esempio merita una pausa. “Development” costa più di quanto suggerirebbe la sua lunghezza in caratteri perché i caratteri accentati si tokenizzano in modo meno efficiente. In pratica, un corpus in francese consuma più token di uno equivalente in inglese: se hai stimato il tuo budget usando prompt in inglese per poi distribuire in francese, la tua fattura reale supererà le previsioni.
Una chiamata API contiene più del semplice testo grezzo: ogni messaggio include un ruolo, a volte un nome, e l’API aggiunge token strutturali. La funzione seguente incorpora questo sovraccarico per fornire un totale realistico.
def count_conversation_tokens(messages: list[dict]) -> int:
"""Conta i token in una conversazione (messaggi + sovraccarico)."""
total = 0
for message in messages:
total += 4 # Sovraccarico per messaggio (ruolo, ecc.)
total += count_tokens(message["content"])
if message.get("name"):
total += count_tokens(message["name"])
total += 2 # Token di fine
return total
conversation = [
{"role": "system", "content": "You are a technical assistant."},
{"role": "user", "content": "Explain microservices."},
{"role": "assistant", "content": "Microservices are an architecture..."},
]
print(f"Total tokens: {count_conversation_tokens(conversation)}")
In una conversazione di tre messaggi, il sovraccarico è trascurabile. Su uno storico di duecento messaggi brevi, tipico di una chat di supporto, si accumulano quasi mille token che non avevi considerato.
Fare budget prima di chiamare
La finestra di contesto non è un budget di input: è un budget condiviso tra ciò che invii e ciò che il modello genera. Se riempi la finestra fino all’orlo con il tuo prompt, la risposta verrà troncata. La struttura BudgetTokens rende esplicita questa allocazione riservando preventivamente una porzione per l’output.
from dataclasses import dataclass
@dataclass
class BudgetTokens:
"""Gestisce il budget dei token per una chiamata."""
context_limit: int # Finestra del modello
system_tokens: int = 0 # Prompt di sistema
history_tokens: int = 0 # Storico conversazione
user_tokens: int = 0 # Messaggio corrente
output_reserve: int = 2000 # Riservato per la risposta
@property
def available_tokens(self) -> int:
used = (
self.system_tokens
+ self.history_tokens
+ self.user_tokens
)
return self.context_limit - used - self.output_reserve
@property
def is_over(self) -> bool:
return self.available_tokens < 0
def report(self) -> str:
return (
f"Context: {self.context_limit} | "
f"System: {self.system_tokens} | "
f"History: {self.history_tokens} | "
f"User: {self.user_tokens} | "
f"Output reserve: {self.output_reserve} | "
f"Available: {self.available_tokens}"
)
# Esempio con una finestra di contesto di 128K token
budget = BudgetTokens(
context_limit=128_000,
system_tokens=count_tokens(system_prompt),
history_tokens=count_conversation_tokens(history),
user_tokens=count_tokens(user_message),
)
if budget.is_over:
print("Budget superato — necessaria compattazione")
Il metodo report fa più che aiutare nel debug. Registrandolo su un campione di richieste in produzione, vedrai immediatamente quale componente sta consumando il tuo contesto. Nella maggior parte delle applicazioni, la sorpresa viene dallo storico, raramente dal prompt di sistema che tutti monitorano.
Successivamente, devi agire quando il budget viene superato. La funzione prepare_context applica la regola più semplice e robusta: mantieni i messaggi più recenti ed elimina i più vecchi non appena il budget è esaurito. L’iterazione avviene al contrario, inserendo all’inizio per ripristinare l’ordine cronologico.
def prepare_context(
system_prompt: str,
history: list[dict],
message: str,
model_limit: int = 128_000,
output_reserve: int = 4_000,
) -> list[dict]:
"""Prepara il contesto rispettando il budget dei token."""
system_tokens = count_tokens(system_prompt)
message_tokens = count_tokens(message)
history_budget = (
model_limit - system_tokens - message_tokens - output_reserve
)
# Mantieni i messaggi più recenti entro il budget
kept_messages = []
used_tokens = 0
for msg in reversed(history):
msg_tokens = count_tokens(msg["content"]) + 4
if used_tokens + msg_tokens > history_budget:
break
kept_messages.insert(0, msg)
used_tokens += msg_tokens
return (
[{"role": "system", "content": system_prompt}]
+ kept_messages
+ [{"role": "user", "content": message}]
)
Questo troncamento è brutale: tutto ciò che cade fuori dal budget viene perso. Quando il contesto più vecchio conta davvero, ad esempio un file cliente tracciato per diverse settimane, sostituisci la pura cancellazione con la strategia di compattazione trattata nella lezione precedente.
Stimare il costo prima di spendere
Gli errori di fatturazione più costosi derivano dall’elaborazione batch: esegui un passaggio su 10.000 documenti e scopri l’importo il giorno dopo. Stimare prima, in pochi millisecondi di calcolo locale, evita questo scenario.
def estimate_cost(
input_tokens: int,
estimated_output_tokens: int,
model: str = "gpt-5.6-terra",
) -> dict:
"""Stima il costo di una chiamata prima di eseguirla."""
# Tariffe per milione di token (luglio 2026 — verificare i prezzi ufficiali)
rates = {
"gpt-5.6-luna": {"input": 0.20, "output": 1.20},
"gpt-5.6-terra": {"input": 2.00, "output": 12.00},
"gpt-5.6-sol": {"input": 5.00, "output": 30.00},
}
rate = rates.get(model, rates["gpt-5.6-terra"])
input_cost = (input_tokens / 1_000_000) * rate["input"]
output_cost = (estimated_output_tokens / 1_000_000) * rate["output"]
return {
"model": model,
"input_tokens": input_tokens,
"estimated_output_tokens": estimated_output_tokens,
"input_cost": f"${input_cost:.6f}",
"output_cost": f"${output_cost:.6f}",
"total_cost": f"${input_cost + output_cost:.6f}",
}
# Prima di inviare un prompt grande
estimation = estimate_cost(
input_tokens=50_000,
estimated_output_tokens=2_000,
model="gpt-5.6-sol",
)
print(estimation)
La tabella delle tariffe è hardcoded in questo esempio, con la data in un commento. Trattala come dati di configurazione da verificare regolarmente rispetto alla griglia dei prezzi ufficiale: una stima calcolata su prezzi obsoleti è più pericolosa di nessuna stima, perché ispira una falsa sicurezza.
Infine, conosci i limiti di ogni modello per pianificare il tuo budget. Le finestre di contesto variano da modello a modello all’interno della famiglia GPT-5.6: consulta la pagina ufficiale dei modelli OpenAI per i valori attuali e configura context_limit dalle tue impostazioni invece di hardcodedarlo nel codice di chiamata.
Punti chiave
- Usa
tiktokenper contare i token prima di ogni chiamata, tenendo conto del sovraccarico per messaggio - Il francese consuma più token dell’inglese per contenuti equivalenti: adatta le tue stime
- Riserva sempre un budget per i token di output all’interno della finestra di contesto
- Gestisci il contesto automaticamente eliminando i messaggi più vecchi
- Stima i costi prima di inviare richieste costose, utilizzando tariffe verificate