Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
MessaggiGestione del contesto
Finestre di contesto
Comprendi come funziona la finestra di contesto, come il pensiero esteso e l'uso degli strumenti vengono conteggiati al suo interno e come gestire il contesto man mano che le conversazioni crescono.
Man mano che le conversazioni crescono, alla fine ti avvicinerai 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 (degradazione del contesto). Questo rende la cura di ciò che è nel contesto altrettanto importante quanto lo spazio disponibile.
Il seguente diagramma illustra il comportamento standard della finestra di contesto per le richieste API1:
1 Le interfacce di chat come claude.ai possono anche gestire la finestra di contesto su base continua "first in, first out".
- Accumulo progressivo di token: Man mano che la conversazione avanza attraverso i turni, ogni messaggio dell'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 corrente dell'utente
- Fase di output: Genera una risposta testuale che diventa parte dell'input per il turno successivo
Tutto ciò che è nella richiesta viene conteggiato nella finestra di contesto: il prompt di sistema, ogni messaggio in messages (inclusi i risultati degli strumenti, le immagini e i 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 Opus 5, 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.
Anche Claude Fable 5 e Claude Mythos 5 ( e ) hanno una finestra di contesto da 1M di token. Una singola richiesta a qualsiasi modello con una finestra di contesto da 1M di token 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 a 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 delle richieste 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
Con il pensiero, tutti i token di input e output, inclusi i token di pensiero, vengono conteggiati nel limite della finestra di contesto, con alcune sfumature nelle situazioni multi-turno.
I token di pensiero sono un sottoinsieme del tuo parametro max_tokens, vengono fatturati come token di output e vengono conteggiati nei limiti di velocità. Con il pensiero adattivo, Claude determina dinamicamente la sua allocazione di pensiero, quindi l'uso 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 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 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 è abilitato su un modello che rimuove i blocchi di pensiero precedenti:
- Rimozione dei blocchi di pensiero: Sui modelli che rimuovono i blocchi di pensiero precedenti, i blocchi di pensiero (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 è necessario rimuovere i blocchi di pensiero da solo: se li ripassi, la Claude API li rimuove automaticamente.
- Fatturazione: I token di pensiero vengono fatturati come token di output una sola volta, quando vengono generati. Sui modelli che mantengono i blocchi di pensiero precedenti, i blocchi mantenuti diventano 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 il pensiero e l'uso degli strumenti
Il seguente diagramma illustra come vengono gestiti i token quando combini il pensiero con l'uso degli strumenti su un modello che rimuove i blocchi di pensiero precedenti:
Architettura del primo turno
- Componenti di input: Configurazione degli strumenti e messaggio dell'utente
- Componenti di output: Pensiero + 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.
Gestione del risultato dello strumento (turno 2)
- Componenti di input: Ogni blocco del primo turno e il
tool_result. Devi restituire il blocco di pensiero con i risultati degli strumenti corrispondenti. Questo è l'unico caso in cui devi restituire i blocchi di pensiero. - Componenti di output: Dopo che i risultati degli strumenti sono stati ripassati a Claude, Claude risponde solo con testo (nessun pensiero aggiuntivo fino al prossimo messaggio
user, a meno che il pensiero intercalato non sia abilitato). - 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.
- Componenti di input: Ogni blocco del primo turno e il
Nuovo turno utente (turno 3)
- Componenti di input: Tutti gli input e l'output del turno precedente vengono riportati. Il blocco di pensiero del ciclo di uso degli strumenti completato non deve più rimanere nel contesto: sui modelli che rimuovono i blocchi di pensiero precedenti, l'API lo scarta automaticamente quando lo ripassi, e sui modelli che mantengono i blocchi di pensiero precedenti, puoi rimuoverlo tu stesso in questa fase. Questo è anche il punto in cui aggiungi il prossimo turno
user. - Componenti di output: Poiché c'è un nuovo turno
useral di fuori del ciclo di uso degli strumenti, Claude genera un nuovo blocco di pensiero e continua da lì. - Calcolo dei token: Sui modelli che rimuovono i blocchi di pensiero precedenti, i token di pensiero 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 pensiero nel turno
assistantcorrente.
- Componenti di input: Tutti gli input e l'output del turno precedente vengono riportati. Il blocco di pensiero del ciclo di uso degli strumenti completato non deve più rimanere nel contesto: sui modelli che rimuovono i blocchi di pensiero precedenti, l'API lo scarta automaticamente quando lo ripassi, e sui modelli che mantengono i blocchi di pensiero precedenti, puoi rimuoverlo tu stesso in questa fase. Questo è anche il punto in cui aggiungi il prossimo turno
- Considerazioni per l'uso degli strumenti con il pensiero:
- Quando invii i risultati degli strumenti, devi includere l'intero blocco di pensiero non modificato che accompagna quella richiesta di strumento, inclusa la sua firma.
- L'API usa firme crittografiche per verificare l'autenticità dei blocchi 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 rimanda 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 una 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.
Claude Opus 4.7 e i modelli Opus successivi, Claude Fable 5 e Claude Mythos 5 non ricevono questi tag iniettati. Su Claude Opus 4.7 e i modelli Opus successivi, Claude Fable 5 e Claude Mythos 5, puoi fornire al modello un budget esplicito con i budget delle attività, che sono in beta.
Per indicazioni sui prompt per l'uso della consapevolezza del contesto, consulta Best practice per i prompt.
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 i modelli Claude 4.6 e successivi e per Claude Mythos Preview.
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 dei prompt memorizzati nella 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 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 più recenti, 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 ferma 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 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
Compattazione del contesto lato server per gestire conversazioni lunghe che si avvicinano ai limiti della finestra di contesto.
Gestisci automaticamente il contesto della conversazione man mano che cresce con la modifica del contesto.
Consulta la tabella di confronto dei modelli per un elenco delle dimensioni della finestra di contesto e dei prezzi dei token di input/output per modello.
Fornisci a Claude un ragionamento potenziato per attività complesse e controlla come viene restituito il contenuto del pensiero.
Was this page helpful?