Finestre di contesto

Man mano che le conversazioni crescono, finirai per avvicinarti ai limiti della finestra di contesto. Per conversazioni di lunga durata e flussi di lavoro agentici, la compattazione lato server è la strategia principale per la gestione del contesto.

Come funziona la finestra di contesto

La "context window" (finestra di contesto) si riferisce a tutto il testo che un modello linguistico può consultare quando genera una risposta, inclusa la risposta stessa. Questo è diverso dal grande corpus di dati su cui il modello linguistico è stato addestrato, e rappresenta invece una "memoria di lavoro" per il modello. Una finestra di contesto più ampia consente al modello di gestire prompt più complessi e lunghi, ma più contesto non è automaticamente meglio. Man mano che il numero di token cresce, l'accuratezza e il richiamo si degradano, un fenomeno noto come context rot (deterioramento del contesto). Questo rende la cura di ciò che si trova nel contesto importante tanto quanto lo spazio disponibile.

Il seguente diagramma illustra il comportamento standard della finestra di contesto per le richieste API¹:

¹ Le interfacce di chat come claude.ai possono anche gestire la finestra di contesto su base progressiva "first in, first out" (il primo a entrare è il primo a uscire).

• Accumulo progressivo dei token: Man mano che la conversazione avanza attraverso i turni, ogni messaggio dell'utente e ogni risposta dell'assistente si accumulano all'interno della finestra di contesto, e i turni precedenti vengono conservati completamente.
• Capacità della finestra di contesto: La finestra di contesto (fino a 1M di token, a seconda del modello) contiene la cronologia della conversazione più il nuovo output generato da Claude.
• Flusso input-output: Ogni turno è composto da:
  • Fase di input: Contiene tutta la cronologia precedente della conversazione più il messaggio corrente dell'utente
  • Fase di output: Genera una risposta testuale che diventa parte dell'input per il turno successivo

Tutto ciò che è presente nella richiesta viene conteggiato nella finestra di contesto: il "system prompt" (prompt di sistema), ogni messaggio in messages (inclusi risultati degli strumenti, immagini e documenti) e le definizioni dei tuoi strumenti. Anche l'output che Claude genera per il turno, incluso il suo pensiero esteso, viene conteggiato. Ogni risposta riporta ciò che la richiesta ha consumato nel suo campo usage. Se usi la cache dei prompt, il conteggio dell'input è suddiviso tra input_tokens, cache_read_input_tokens e cache_creation_input_tokens, e tutti e tre vengono conteggiati nella finestra. Per stimare una richiesta prima di inviarla, usa l'API di conteggio dei token.

Dimensioni della finestra di contesto per modello

Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5, Claude Sonnet 4.6 e Claude Mythos Preview hanno una finestra di contesto da 1M di token. Una singola richiesta a uno qualsiasi di essi può generare fino a 128k token di output (max_tokens). Gli altri modelli Claude, incluso Claude Sonnet 4.5, hanno una finestra di contesto da 200k token.

Per ogni modello con una finestra di contesto da 1M di token, 1M è il valore predefinito: non hai bisogno di un header beta, e le richieste con contesto lungo vengono fatturate ai prezzi standard.

Una singola richiesta può includere fino a 600 immagini o pagine PDF (100 per i modelli con una finestra di contesto da 200k token). Se invii molte immagini o documenti di grandi dimensioni, potresti raggiungere i limiti di dimensione della richiesta prima del limite di token.

Consulta la tabella di confronto dei modelli per un elenco delle dimensioni della finestra di contesto per modello.

La finestra di contesto con il thinking

Con il thinking (pensiero), tutti i token di input e output, inclusi i token di thinking, vengono conteggiati nel limite della finestra di contesto, con alcune sfumature nelle situazioni multi-turno.

I token di thinking sono un sottoinsieme del tuo parametro max_tokens, vengono fatturati come token di output e vengono conteggiati nei limiti di velocità. Con l'adaptive thinking (pensiero adattivo), Claude determina dinamicamente la propria allocazione di thinking, quindi l'uso dei token di thinking varia da richiesta a richiesta.

Se i blocchi di thinking dei turni precedenti dell'assistente rimangono nella finestra di contesto dipende dal modello. Su Claude Opus 4.5 e modelli Opus successivi, Claude Sonnet 4.6 e modelli Sonnet successivi, Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5 e Claude Mythos Preview, l'API mantiene i blocchi di thinking precedenti per impostazione predefinita, e questi vengono conteggiati nella finestra di contesto come qualsiasi altro token di input. Sui modelli Opus e Sonnet precedenti e su tutti i modelli Haiku, l'API rimuove automaticamente i blocchi di thinking precedenti dalla cronologia della conversazione quando li ripassi, il che preserva la capacità di token per il contenuto della conversazione. Per i valori predefiniti per modello, consulta conservazione dei blocchi di thinking per modello. Per sovrascrivere il valore predefinito in entrambe le direzioni, usa la cancellazione dei blocchi di thinking.

Il seguente diagramma mostra come vengono gestiti i token quando il thinking è abilitato su un modello che rimuove i blocchi di thinking precedenti:

• Rimozione dei blocchi di thinking: Sui modelli che rimuovono i blocchi di thinking precedenti, i blocchi di thinking (mostrati in grigio scuro) vengono generati durante la fase di output di ogni turno ma non vengono riportati come token di input per i turni successivi. Non devi rimuovere tu stesso i blocchi di thinking: se li ripassi, la Claude API li rimuove automaticamente.
• Fatturazione: I token di thinking vengono fatturati come token di output una sola volta, quando vengono generati. Sui modelli che mantengono i blocchi di thinking precedenti, i blocchi mantenuti fanno poi parte dell'input delle richieste successive e vengono fatturati come token di input, come il resto della cronologia della conversazione.

La finestra di contesto con thinking e uso degli strumenti

Il seguente diagramma illustra come vengono gestiti i token quando combini il thinking con il "tool use" (uso degli strumenti) su un modello che rimuove i blocchi di thinking precedenti:

1. 1

   Architettura del primo turno

   • Componenti di input: Configurazione degli strumenti e messaggio dell'utente
   • Componenti di output: Thinking + risposta testuale + richiesta di uso degli strumenti
   • Calcolo dei token: Tutti i componenti di input e output vengono conteggiati nella finestra di contesto, e tutti i componenti di output vengono fatturati come token di output.
2. 2

   Gestione del risultato dello strumento (turno 2)

   • Componenti di input: Ogni blocco del primo turno e il tool_result. Devi restituire il blocco di thinking con i risultati degli strumenti corrispondenti. Questo è l'unico caso in cui devi restituire i blocchi di thinking.
   • Componenti di output: Dopo che i risultati degli strumenti sono stati ripassati a Claude, Claude risponde solo con testo (nessun thinking aggiuntivo fino al prossimo messaggio user, a meno che non sia abilitato l'interleaved thinking).
   • Calcolo dei token: Tutti i componenti di input e output vengono conteggiati nella finestra di contesto, e tutti i componenti di output vengono fatturati come token di output.
3. 3

   Nuovo turno utente (turno 3)

   • Componenti di input: Tutti gli input e l'output del turno precedente vengono riportati. Il blocco di thinking del ciclo di uso degli strumenti completato non deve più rimanere nel contesto: sui modelli che rimuovono i blocchi di thinking precedenti, l'API lo scarta automaticamente quando lo ripassi, e sui modelli che mantengono i blocchi di thinking precedenti, rimane a meno che tu non lo cancelli con la cancellazione dei blocchi di thinking. Questo è anche il punto in cui aggiungi il turno user successivo.
   • Componenti di output: Poiché c'è un nuovo turno user al di fuori del ciclo di uso degli strumenti, Claude genera un nuovo blocco di thinking e continua da lì.
   • Calcolo dei token: Sui modelli che rimuovono i blocchi di thinking precedenti, i token di thinking precedenti non vengono più conteggiati nella finestra di contesto. Tutti gli altri blocchi precedenti vengono ancora conteggiati nella finestra di contesto, così come il blocco di thinking nel turno assistant corrente.

• Considerazioni per l'uso degli strumenti con il thinking:
  • Quando invii i risultati degli strumenti, devi includere l'intero blocco di thinking non modificato che accompagna quella richiesta di strumento, inclusa la sua firma.
  • L'API usa firme crittografiche per verificare l'autenticità dei blocchi di thinking. Se modifichi un blocco di thinking, l'API restituisce un errore.

Per ridurre il contesto consumato dalle definizioni degli strumenti stesse, consulta Gestire il contesto degli strumenti, oppure rinvia le definizioni degli strumenti con lo strumento di ricerca strumenti.

Consapevolezza del contesto

Claude Sonnet 5, Claude Sonnet 4.6, Claude Sonnet 4.5 e Claude Haiku 4.5 hanno la "context awareness" (consapevolezza del contesto): questi modelli tengono traccia della finestra di contesto rimanente (il loro "budget di token") durante tutta la conversazione. Questo consente al modello di gestire attività di lunga durata in base allo spazio rimanente invece di indovinare quanti token restano. La consapevolezza del contesto è automatica: non c'è nulla da abilitare, e non invii mai tu stesso i tag mostrati in questa sezione. È l'API a iniettarli.

Come funziona

Nel prompt di sistema di ogni richiesta, l'API fornisce a Claude la sua finestra di contesto totale:

<budget:token_budget>200000</budget:token_budget>

Il budget corrisponde alla finestra di contesto disponibile per la tua richiesta: 1M di token per Claude Sonnet 5 e Claude Sonnet 4.6, e 200k token per Claude Sonnet 4.5 e Claude Haiku 4.5. Gli esempi in questa sezione mostrano un modello con una finestra di contesto da 200k token.

Dopo ogni chiamata a uno strumento, l'API fornisce a Claude un aggiornamento sulla capacità rimanente:

<system_warning>Token usage: 35000/200000; 165000 remaining</system_warning>

I token delle immagini sono inclusi in questi budget.

Claude Opus 4.7 e i modelli Opus successivi, Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5 e Claude Mythos 5 non ricevono questi tag iniettati. Su questi modelli, puoi fornire al modello un budget esplicito con i task budget, che sono in beta.

Per indicazioni di prompting sull'uso della consapevolezza del contesto, consulta Best practice di prompting.

Gestire il contesto con la compattazione

Se le tue conversazioni si avvicinano regolarmente ai limiti della finestra di contesto, usa la compattazione lato server. La compattazione riassume automaticamente sul server le parti precedenti della conversazione, così la conversazione può continuare oltre il limite della finestra di contesto. È disponibile in beta per i modelli Claude 4.6 e successivi e per Claude Mythos Preview.

Per esigenze più specializzate, la modifica del contesto offre strategie aggiuntive:

• Cancellazione dei risultati degli strumenti: Cancella i vecchi risultati degli strumenti nei flussi di lavoro agentici
• Cancellazione dei blocchi di thinking: Gestisci i blocchi di thinking quando usi il pensiero esteso

I prefissi di prompt in cache occupano comunque la finestra di contesto: la cache dei prompt cambia quanto paghi per quei token, non se vengono conteggiati.

Comportamento in caso di superamento della finestra di contesto

Se il solo input supera già la finestra di contesto del modello, l'API restituisce un errore 400 invalid_request_error ("prompt is too long") su ogni modello.

Sui modelli Claude 4.5 e successivi, se i token di input più max_tokens superano la dimensione della finestra di contesto, l'API accetta la richiesta. Se la generazione raggiunge poi il limite della finestra di contesto, si interrompe con stop_reason: "model_context_window_exceeded". Sui modelli precedenti, l'API restituisce invece un errore di validazione. Per aderire al comportamento model_context_window_exceeded su quei modelli, usa l'header beta model-context-window-exceeded-2025-08-26. Consulta Motivi di arresto e fallback per i dettagli.

Per rimanere entro i limiti della finestra di contesto, usa l'API di conteggio dei token per stimare l'uso dei token prima di inviare messaggi a Claude.

Prossimi passi