Token: l’unità che conti e che paghi

Il modello non vede caratteri né parole: vede token, cioè le unità minime in cui il testo viene codificato, che possono corrispondere a parole, sotto-parole, caratteri o byte. Per Claude un token vale in media circa 3,5 caratteri di inglese, e la resa cambia sensibilmente con la lingua: lo stesso paragrafo in italiano costa più token dello stesso paragrafo in inglese. Il modello genera un token alla volta, condizionato su tutto quello che ha davanti — è per questo che l’ordine in cui metti le cose nel prompt ha effetto, e che una risposta troncata è troncata davvero, non riassunta.

Non stimare a occhio: ogni risposta riporta nel campo usage quello che la richiesta ha consumato, e prima di inviare c’è la token counting API. Con il prompt caching il conteggio in ingresso si divide fra input_tokens, cache_read_input_tokens e cache_creation_input_tokens, e tutti e tre contano verso la finestra.

La finestra di contesto è una sola, e ci sta dentro anche l’output

La finestra di contesto è la memoria di lavoro del modello: tutto ciò che può guardare mentre genera, compresa la risposta che sta generando. Ci finisce dentro il system prompt, ogni messaggio in messages (risultati di tool, immagini e documenti inclusi), le definizioni dei tuoi tool, e in uscita il testo più gli eventuali token di ragionamento.

I modelli attuali di punta hanno una finestra da 1 milione di token, con un massimo di 128k token di output per singola richiesta; Claude Sonnet 4.5 e gli altri modelli più vecchi si fermano a 200k. Ma più grande non vuol dire meglio: al crescere del numero di token accuratezza e recall degradano, un fenomeno che la documentazione chiama context rot. Curare cosa c’è dentro conta quanto lo spazio disponibile.

Due comportamenti al limite, da distinguere: se il solo input supera la finestra, la API risponde 400 invalid_request_error («prompt is too long») su qualunque modello; se invece input più max_tokens supera la finestra, sui modelli 4.5 e successivi la richiesta viene accettata e, se la generazione arriva al limite, si ferma con stop_reason: "model_context_window_exceeded". Nel primo caso hai un errore, nel secondo un 200 con una risposta tronca: sono due bug diversi da gestire.

Non determinismo: temperature: 0 non ti salva

La temperature controlla la casualità della predizione: alta, il modello esplora scelte lessicali rare; bassa, si attacca alle continuazioni più probabili. Il punto che rompe le pipeline di test è però un altro, e la documentazione lo mette nero su bianco: anche con temperature a 0 i risultati non sono pienamente deterministici, e input identici possono produrre output diversi fra una chiamata e l’altra — sia sull’inferenza di Anthropic sia tramite i provider cloud di terze parti.

Conseguenza operativa: non scrivere mai asserzioni su stringhe esatte. Verifica la struttura (schema JSON valido, campi presenti, valori nell’insieme ammesso), non il testo carattere per carattere. Se ti serve una forma garantita, usa gli structured outputs invece di sperare che il prompt tenga.

Le due manopole del ragionamento, più una della velocità

Si confondono in continuazione, e vale la pena separarle.

thinking decide se Claude ragiona in blocchi di pensiero prima di rispondere. Sui modelli più recenti è già attivo; su altri lo attivi con il tipo adaptive, e da lì è Claude a decidere quando e quanto pensare. Il vecchio extended thinking, cioè il tipo enabled con budget_tokens, vive ancora sui modelli che lo supportano, ma sui modelli 4.7 e successivi è stato rimosso: inviarlo restituisce un 400. È l’errore tipico di chi porta avanti codice scritto un anno fa.

effort decide quanto lavoro Claude mette in tutta la risposta, ragionamento compreso. I livelli sono low, medium, high, xhigh, max; il default è high, e passare high equivale a non passare nulla. Vale su tutti i token in uscita, quindi a effort basso avrai anche meno chiamate di tool e più concise. Attenzione al confine: effort è un segnale comportamentale, non un budget rigido — il tetto duro resta max_tokens. E adaptive non è un valore di effort, è una modalità di thinking.

{
  "model": "claude-opus-5",
  "max_tokens": 16000,
  "thinking": { "type": "adaptive", "display": "summarized" },
  "output_config": { "effort": "medium" }
}

Il testo che leggi in un blocco thinking è un riassunto del ragionamento, non la catena grezza, e ti viene fatturato per i token pieni generati, non per quelli del riassunto. Su molti modelli display è omitted per default: i blocchi arrivano vuoti finché non chiedi summarized.

Terza manopola, diversa dalle prime due: la fast mode, in research preview, si attiva con speed: "fast" più l’header beta su Claude Opus 5 e Opus 4.8. Non è un altro modello: sono gli stessi pesi con una configurazione di inferenza più veloce, fino a 2,5 volte i token di output al secondo, a tariffa premium. Il guadagno è sugli output token per second, non sul time to first token.

Zero-shot, one-shot, multi-shot

Zero-shot è il prompt con sole istruzioni. Aggiungere esempi — uno, o meglio più d’uno — è fra i modi più affidabili di governare formato, tono e struttura dell’output. La guida ne raccomanda da 3 a 5, e li vuole rilevanti (aderenti al caso reale), diversi (coprano i casi limite, così il modello non impara un pattern che non intendevi) e strutturati: racchiusi in tag XML dedicati, per distinguerli dalle istruzioni. Quando l’output ha una forma precisa da rispettare, un esempio ben scelto vale più di tre righe di spiegazione.