Finestre di contesto

Man mano che le conversazioni crescono, ti avvicinerai inevitabilmente 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ò referenziare 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 è 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 rotativa "first in, first out".

• Accumulo progressivo di token: Man mano che la conversazione avanza attraverso i turni, ogni messaggio utente e risposta dell'assistente si accumula all'interno della finestra di contesto, e i turni precedenti vengono preservati 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 che Claude genera.
• Flusso input-output: Ogni turno consiste in:
  • Fase di input: Contiene tutta la cronologia della conversazione precedente più il messaggio utente corrente
  • Fase di output: Genera una risposta testuale che diventa parte dell'input per il turno successivo

Tutto ciò che è nella richiesta conta ai fini della finestra di contesto: il prompt di sistema, ogni messaggio in messages (inclusi risultati degli strumenti, immagini e documenti) e le tue definizioni degli strumenti. Anche l'output che Claude genera per il turno, incluso il suo pensiero esteso, conta. 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 contano ai fini della finestra. Per stimare una richiesta prima di inviarla, usa l'API di conteggio dei token.



Dimensioni della finestra di contesto per modello

Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5 e Claude Sonnet 4.6 hanno una finestra di contesto da 1M di token sulla Claude API, Amazon Bedrock, Google Cloud e Microsoft Foundry. Anche Claude Mythos Preview ha una finestra di contesto da 1M di token.

Claude Fable 5 e Claude Mythos 5 (claude-fable-5 e claude-mythos-5) hanno una finestra di contesto da 1M di token, e una singola richiesta a questi modelli può generare fino a 128k token di output (max_tokens). 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 pensiero esteso

Con il pensiero esteso, tutti i token di input e output, inclusi i token di pensiero, contano ai fini del limite della finestra di contesto, con alcune sfumature nelle situazioni multi-turno.

I token del budget di pensiero sono un sottoinsieme del tuo parametro max_tokens, vengono fatturati come token di output e contano ai fini dei limiti di velocità. Con il pensiero adattivo, Claude determina dinamicamente la sua allocazione di pensiero, quindi l'utilizzo dei token di pensiero varia da richiesta a richiesta.

Il fatto che i blocchi di pensiero dei turni precedenti dell'assistente rimangano 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, Claude Mythos 5 e Claude Mythos Preview, l'API mantiene i blocchi di pensiero precedenti per impostazione predefinita, e questi contano ai fini della 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 pensiero precedenti dalla cronologia della conversazione quando li ripassi, il che preserva la capacità di token per il contenuto della conversazione. Per le impostazioni predefinite per modello, consulta preservazione dei blocchi di pensiero per modello. Per sovrascrivere l'impostazione predefinita in entrambe le direzioni, usa la rimozione dei blocchi di pensiero.

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

• Rimozione del pensiero esteso: Sui modelli che rimuovono i blocchi di pensiero precedenti, i blocchi di pensiero esteso (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 i blocchi di pensiero tu stesso: se li ripassi, la Claude API li rimuove automaticamente.
• Fatturazione: I token di pensiero esteso vengono fatturati come token di output una sola volta, quando vengono generati. Sui modelli che mantengono i blocchi di pensiero 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 pensiero esteso e uso degli strumenti

Il seguente diagramma illustra come vengono gestiti i token quando combini il pensiero esteso con l'uso degli strumenti su un modello che rimuove i blocchi di pensiero precedenti:

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

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



Consapevolezza del contesto

Claude Sonnet 5, Claude Sonnet 4.6, Claude Sonnet 4.5 e Claude Haiku 4.5 hanno la consapevolezza del contesto: questi modelli tengono traccia della loro 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 anziché indovinare quanti token restano. La consapevolezza del contesto è automatica: non c'è nulla da abilitare, e non devi mai inviare tu stesso i tag mostrati in questa sezione. L'API li inietta.



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 sua capacità rimanente:

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

I token delle immagini sono inclusi in questi budget.

I modelli più recenti non ricevono questi tag iniettati. Su Claude Opus 4.7 e successivi, Claude Fable 5 e Claude Mythos 5, puoi fornire al modello un budget esplicito con i budget di attività, che sono in beta.

Per indicazioni sul prompting relative all'uso della consapevolezza del contesto, consulta Best practice per il 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 le parti precedenti della conversazione sul server, in modo che la conversazione possa continuare oltre il limite della finestra di contesto. È disponibile in beta per Claude Fable 5, Claude Mythos 5, Claude Opus 4.8, Claude Mythos Preview, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5 e Claude Sonnet 4.6.

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

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

I prefissi di prompt memorizzati nella cache occupano comunque la finestra di contesto: la cache dei prompt cambia ciò che paghi per quei token, non se contano.



Comportamento di overflow della finestra di contesto

Se l'input da solo 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 attivare il comportamento model_context_window_exceeded su quei modelli, usa l'header beta model-context-window-exceeded-2025-08-26. Consulta Motivi di interruzione e fallback per i dettagli.

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



Passaggi successivi