Costruire con il pensiero esteso
Il pensiero esteso fornisce a Claude capacità di ragionamento migliorate per compiti complessi, offrendo diversi livelli di trasparenza nel suo processo di pensiero passo dopo passo prima di fornire la sua risposta finale.
Modelli supportati
Il pensiero esteso è supportato nei seguenti modelli:
- Claude Opus 4 (
claude-opus-4-20250514
) - Claude Sonnet 4 (
claude-sonnet-4-20250514
) - Claude Sonnet 3.7 (
claude-3-7-sonnet-20250219
)
Il comportamento dell’API differisce tra i modelli Claude 3.7 e Claude 4, ma le forme dell’API rimangono esattamente le stesse.
Per maggiori informazioni, vedere Differenze nel pensiero tra le versioni dei modelli.
Come funziona il pensiero esteso
Quando il pensiero esteso è attivato, Claude crea blocchi di contenuto thinking
dove produce il suo ragionamento interno. Claude incorpora le intuizioni da questo ragionamento prima di creare una risposta finale.
La risposta dell’API includerà blocchi di contenuto thinking
, seguiti da blocchi di contenuto text
.
Ecco un esempio del formato di risposta predefinito:
Per maggiori informazioni sul formato di risposta del pensiero esteso, vedere il Riferimento API Messages.
Come utilizzare il pensiero esteso
Ecco un esempio di utilizzo del pensiero esteso nell’API Messages:
Per attivare il pensiero esteso, aggiungi un oggetto thinking
, con il parametro type
impostato su enabled
e il budget_tokens
a un budget di token specificato per il pensiero esteso.
Il parametro budget_tokens
determina il numero massimo di token che Claude può utilizzare per il suo processo di ragionamento interno. Nei modelli Claude 4, questo limite si applica ai token di pensiero completi, e non all’output riassunto. Budget più grandi possono migliorare la qualità della risposta consentendo un’analisi più approfondita per problemi complessi, anche se Claude potrebbe non utilizzare l’intero budget allocato, specialmente a intervalli superiori a 32k.
budget_tokens
deve essere impostato su un valore inferiore a max_tokens
. Tuttavia, quando si utilizza il pensiero interlacciato con gli strumenti, è possibile superare questo limite poiché il limite di token diventa l’intera finestra di contesto (200k token).
Pensiero riassunto
Con il pensiero esteso abilitato, l’API Messages per i modelli Claude 4 restituisce un riassunto del processo di pensiero completo di Claude. Il pensiero riassunto fornisce tutti i benefici di intelligenza del pensiero esteso, prevenendo al contempo l’uso improprio.
Ecco alcune considerazioni importanti per il pensiero riassunto:
- Vieni addebitato per i token di pensiero completi generati dalla richiesta originale, non per i token del riassunto.
- Il conteggio dei token di output fatturati non corrisponderà al conteggio dei token che vedi nella risposta.
- Le prime righe dell’output del pensiero sono più verbose, fornendo un ragionamento dettagliato che è particolarmente utile per scopi di ingegneria dei prompt.
- Mentre Anthropic cerca di migliorare la funzione di pensiero esteso, il comportamento di riassunto è soggetto a modifiche.
- Il riassunto preserva le idee chiave del processo di pensiero di Claude con latenza aggiunta minima, consentendo un’esperienza utente streamabile e una facile migrazione dai modelli Claude 3.7 ai modelli Claude 4.
- Il riassunto è elaborato da un modello diverso da quello che scegli come target nelle tue richieste. Il modello di pensiero non vede l’output riassunto.
Claude Sonnet 3.7 continua a restituire l’output di pensiero completo.
In rari casi in cui hai bisogno di accesso all’output di pensiero completo per i modelli Claude 4, contatta il nostro team vendite.
Streaming del pensiero
Puoi trasmettere in streaming le risposte del pensiero esteso utilizzando eventi inviati dal server (SSE).
Quando lo streaming è abilitato per il pensiero esteso, ricevi il contenuto del pensiero tramite eventi thinking_delta
.
Per maggiore documentazione sullo streaming tramite l’API Messages, vedere Streaming Messages.
Ecco come gestire lo streaming con il pensiero:
Esempio di output streaming:
Quando utilizzi lo streaming con il pensiero abilitato, potresti notare che il testo a volte arriva in blocchi più grandi alternati con consegna più piccola, token per token. Questo è un comportamento previsto, specialmente per il contenuto del pensiero.
Il sistema di streaming deve elaborare il contenuto in lotti per prestazioni ottimali, il che può risultare in questo modello di consegna “a blocchi”, con possibili ritardi tra gli eventi di streaming. Stiamo continuamente lavorando per migliorare questa esperienza, con aggiornamenti futuri focalizzati sul rendere il contenuto del pensiero più fluido nello streaming.
Pensiero esteso con l’uso di strumenti
Il pensiero esteso può essere utilizzato insieme all’uso di strumenti, permettendo a Claude di ragionare attraverso la selezione degli strumenti e l’elaborazione dei risultati.
Quando utilizzi il pensiero esteso con l’uso di strumenti, sii consapevole delle seguenti limitazioni:
-
Limitazione della scelta dello strumento: L’uso di strumenti con il pensiero supporta solo
tool_choice: {"type": "auto"}
(il predefinito) otool_choice: {"type": "none"}
. Utilizzaretool_choice: {"type": "any"}
otool_choice: {"type": "tool", "name": "..."}
risulterà in un errore perché queste opzioni forzano l’uso dello strumento, che è incompatibile con il pensiero esteso. -
Preservare i blocchi di pensiero: Durante l’uso degli strumenti, devi passare i blocchi
thinking
di ritorno all’API per l’ultimo messaggio dell’assistente. Includi il blocco completo non modificato di ritorno all’API per mantenere la continuità del ragionamento.
Preservare i blocchi di pensiero
Durante l’uso degli strumenti, devi passare i blocchi thinking
di ritorno all’API, e devi includere il blocco completo non modificato di ritorno all’API. Questo è critico per mantenere il flusso di ragionamento del modello e l’integrità della conversazione.
Mentre puoi omettere i blocchi thinking
dai turni assistant
precedenti, suggeriamo di passare sempre tutti i blocchi di pensiero all’API per qualsiasi conversazione multi-turno. L’API:
- Filtrerà automaticamente i blocchi di pensiero forniti
- Utilizzerà i blocchi di pensiero rilevanti necessari per preservare il ragionamento del modello
- Fatturerà solo per i token di input per i blocchi mostrati a Claude
Quando Claude invoca strumenti, sta mettendo in pausa la costruzione di una risposta per attendere informazioni esterne. Quando i risultati degli strumenti vengono restituiti, Claude continuerà a costruire quella risposta esistente. Questo rende necessario preservare i blocchi di pensiero durante l’uso degli strumenti, per un paio di ragioni:
-
Continuità del ragionamento: I blocchi di pensiero catturano il ragionamento passo dopo passo di Claude che ha portato alle richieste degli strumenti. Quando pubblichi i risultati degli strumenti, includere il pensiero originale assicura che Claude possa continuare il suo ragionamento da dove si era fermato.
-
Mantenimento del contesto: Mentre i risultati degli strumenti appaiono come messaggi utente nella struttura dell’API, fanno parte di un flusso di ragionamento continuo. Preservare i blocchi di pensiero mantiene questo flusso concettuale attraverso multiple chiamate API. Per maggiori informazioni sulla gestione del contesto, vedere la nostra guida sulle finestre di contesto.
Importante: Quando fornisci blocchi thinking
, l’intera sequenza di blocchi thinking
consecutivi deve corrispondere agli output generati dal modello durante la richiesta originale; non puoi riorganizzare o modificare la sequenza di questi blocchi.
Pensiero interlacciato
Il pensiero esteso con l’uso di strumenti nei modelli Claude 4 supporta il pensiero interlacciato, che consente a Claude di pensare tra le chiamate agli strumenti e fare ragionamenti più sofisticati dopo aver ricevuto i risultati degli strumenti.
Con il pensiero interlacciato, Claude può:
- Ragionare sui risultati di una chiamata strumento prima di decidere cosa fare dopo
- Concatenare multiple chiamate strumento con passi di ragionamento in mezzo
- Prendere decisioni più sfumate basate sui risultati intermedi
Per abilitare il pensiero interlacciato, aggiungi l’header beta interleaved-thinking-2025-05-14
alla tua richiesta API.
Ecco alcune considerazioni importanti per il pensiero interlacciato:
- Con il pensiero interlacciato, il
budget_tokens
può superare il parametromax_tokens
, poiché rappresenta il budget totale attraverso tutti i blocchi di pensiero all’interno di un turno dell’assistente. - Il pensiero interlacciato è supportato solo per strumenti utilizzati tramite l’API Messages.
- Il pensiero interlacciato è supportato solo per i modelli Claude 4, con l’header beta
interleaved-thinking-2025-05-14
. - Le chiamate dirette all’API di Anthropic ti permettono di passare
interleaved-thinking-2025-05-14
nelle richieste a qualsiasi modello, senza effetto. - Su piattaforme di terze parti (ad es., Amazon Bedrock e Vertex AI), se passi
interleaved-thinking-2025-05-14
a qualsiasi modello diverso da Claude Opus 4 o Sonnet 4, la tua richiesta fallirà.
Pensiero esteso con cache dei prompt
Il cache dei prompt con il pensiero ha diverse considerazioni importanti:
I compiti di pensiero esteso spesso richiedono più di 5 minuti per essere completati. Considera di utilizzare la durata della cache di 1 ora per mantenere i hit della cache attraverso sessioni di pensiero più lunghe e flussi di lavoro multi-step.
Rimozione del contesto dei blocchi di pensiero
- I blocchi di pensiero dai turni precedenti vengono rimossi dal contesto, il che può influenzare i punti di interruzione della cache
- Quando si continuano conversazioni con l’uso di strumenti, i blocchi di pensiero vengono memorizzati nella cache e contano come token di input quando letti dalla cache
- Questo crea un compromesso: mentre i blocchi di pensiero non consumano spazio nella finestra di contesto visivamente, contano ancora verso il tuo utilizzo di token di input quando memorizzati nella cache
- Se il pensiero viene disabilitato, le richieste falliranno se passi contenuto di pensiero nel turno di uso strumento corrente. In altri contesti, il contenuto di pensiero passato all’API viene semplicemente ignorato
Modelli di invalidazione della cache
- Le modifiche ai parametri di pensiero (abilitato/disabilitato o allocazione budget) invalidano i punti di interruzione della cache dei messaggi
- Il pensiero interlacciato amplifica l’invalidazione della cache, poiché i blocchi di pensiero possono verificarsi tra multiple chiamate strumento
- I prompt di sistema e gli strumenti rimangono memorizzati nella cache nonostante le modifiche ai parametri di pensiero o la rimozione dei blocchi
Mentre i blocchi di pensiero vengono rimossi per il caching e i calcoli del contesto, devono essere preservati quando si continuano conversazioni con l’uso di strumenti, specialmente con il pensiero interlacciato.
Comprendere il comportamento di caching dei blocchi di pensiero
Quando si utilizza il pensiero esteso con l’uso di strumenti, i blocchi di pensiero mostrano un comportamento di caching specifico che influenza il conteggio dei token:
Come funziona:
- Il caching si verifica solo quando fai una richiesta successiva che include risultati degli strumenti
- Quando viene fatta la richiesta successiva, la cronologia della conversazione precedente (inclusi i blocchi di pensiero) può essere memorizzata nella cache
- Questi blocchi di pensiero memorizzati nella cache contano come token di input nelle tue metriche di utilizzo quando letti dalla cache
- Quando viene incluso un blocco utente non-tool-result, tutti i blocchi di pensiero precedenti vengono ignorati e rimossi dal contesto
Esempio di flusso dettagliato:
Richiesta 1:
Risposta 1:
Richiesta 2:
Risposta 2:
La Richiesta 2 scrive una cache del contenuto della richiesta (non della risposta). La cache include il messaggio utente originale, il primo blocco di pensiero, il blocco di uso strumento e il risultato dello strumento.
Richiesta 3:
Poiché è stato incluso un blocco utente non-tool-result, tutti i blocchi di pensiero precedenti vengono ignorati. Questa richiesta sarà elaborata allo stesso modo di:
Punti chiave:
- Questo comportamento di caching avviene automaticamente, anche senza marcatori
cache_control
espliciti - Questo comportamento è coerente sia che si utilizzi il pensiero regolare o il pensiero interlacciato
Token massimi e dimensione della finestra di contesto con il pensiero esteso
Nei modelli Claude più vecchi (precedenti a Claude Sonnet 3.7), se la somma dei token del prompt e max_tokens
superava la finestra di contesto del modello, il sistema regolava automaticamente max_tokens
per adattarsi al limite di contesto. Questo significava che potevi impostare un valore max_tokens
grande e il sistema lo riduceva silenziosamente secondo necessità.
Con i modelli Claude 3.7 e 4, max_tokens
(che include il tuo budget di pensiero quando il pensiero è abilitato) è applicato come limite rigoroso. Il sistema ora restituirà un errore di validazione se i token del prompt + max_tokens
superano la dimensione della finestra di contesto.
Puoi leggere la nostra guida sulle finestre di contesto per un approfondimento più completo.
La finestra di contesto con il pensiero esteso
Quando si calcola l’utilizzo della finestra di contesto con il pensiero abilitato, ci sono alcune considerazioni di cui essere consapevoli:
- I blocchi di pensiero dai turni precedenti vengono rimossi e non contati verso la tua finestra di contesto
- Il pensiero del turno corrente conta verso il tuo limite
max_tokens
per quel turno
Il diagramma sottostante dimostra la gestione specializzata dei token quando il pensiero esteso è abilitato:
La finestra di contesto effettiva è calcolata come:
Raccomandiamo di utilizzare l’API di conteggio token per ottenere conteggi di token accurati per il tuo caso d’uso specifico, specialmente quando si lavora con conversazioni multi-turno che includono il pensiero.
La finestra di contesto con pensiero esteso e uso di strumenti
Quando si utilizza il pensiero esteso con l’uso di strumenti, i blocchi di pensiero devono essere esplicitamente preservati e restituiti con i risultati degli strumenti.
Il calcolo della finestra di contesto effettiva per il pensiero esteso con l’uso di strumenti diventa:
Il diagramma sottostante illustra la gestione dei token per il pensiero esteso con l’uso di strumenti:
Gestire i token con il pensiero esteso
Dato il comportamento della finestra di contesto e max_tokens
con i modelli Claude 3.7 e 4 del pensiero esteso, potresti dover:
- Monitorare e gestire più attivamente il tuo utilizzo di token
- Regolare i valori
max_tokens
man mano che la lunghezza del tuo prompt cambia - Potenzialmente utilizzare gli endpoint di conteggio token più frequentemente
- Essere consapevole che i blocchi di pensiero precedenti non si accumulano nella tua finestra di contesto
Questo cambiamento è stato fatto per fornire un comportamento più prevedibile e trasparente, specialmente poiché i limiti massimi di token sono aumentati significativamente.
Crittografia del pensiero
Il contenuto completo del pensiero è crittografato e restituito nel campo signature
. Questo campo è utilizzato per verificare che i blocchi di pensiero siano stati generati da Claude quando passati di nuovo all’API.
È strettamente necessario rimandare i blocchi di pensiero solo quando si utilizzano strumenti con pensiero esteso. Altrimenti puoi omettere i blocchi di pensiero dai turni precedenti, o lasciare che l’API li rimuova per te se li passi di nuovo.
Se rimandi i blocchi di pensiero, raccomandiamo di passare tutto di nuovo come l’hai ricevuto per coerenza e per evitare potenziali problemi.
Ecco alcune considerazioni importanti sulla crittografia del pensiero:
- Quando si trasmettono in streaming le risposte, la firma viene aggiunta tramite un
signature_delta
all’interno di un eventocontent_block_delta
proprio prima dell’eventocontent_block_stop
. - I valori
signature
sono significativamente più lunghi in Claude 4 che nei modelli precedenti. - Il campo
signature
è un campo opaco e non dovrebbe essere interpretato o analizzato - esiste esclusivamente per scopi di verifica. - I valori
signature
sono compatibili tra piattaforme (API Anthropic, Amazon Bedrock, e Vertex AI). I valori generati su una piattaforma saranno compatibili con un’altra.
Redazione del pensiero
Occasionalmente il ragionamento interno di Claude sarà segnalato dai nostri sistemi di sicurezza. Quando questo accade, crittografiamo parte o tutto il blocco thinking
e te lo restituiamo come blocco redacted_thinking
. I blocchi redacted_thinking
vengono decrittografati quando passati di nuovo all’API, permettendo a Claude di continuare la sua risposta senza perdere contesto.
Quando costruisci applicazioni rivolte ai clienti che utilizzano il pensiero esteso:
- Sii consapevole che i blocchi di pensiero redatti contengono contenuto crittografato che non è leggibile dall’uomo
- Considera di fornire una spiegazione semplice come: “Parte del ragionamento interno di Claude è stata automaticamente crittografata per ragioni di sicurezza. Questo non influisce sulla qualità delle risposte.”
- Se mostri blocchi di pensiero agli utenti, puoi filtrare i blocchi redatti preservando i blocchi di pensiero normali
- Sii trasparente che l’utilizzo delle funzioni di pensiero esteso può occasionalmente risultare in qualche ragionamento crittografato
- Implementa una gestione degli errori appropriata per gestire con grazia il pensiero redatto senza rompere la tua UI
Ecco un esempio che mostra sia blocchi di pensiero normali che redatti:
Vedere blocchi di pensiero redatti nel tuo output è un comportamento previsto. Il modello può ancora utilizzare questo ragionamento redatto per informare le sue risposte mantenendo le protezioni di sicurezza.
Se hai bisogno di testare la gestione del pensiero redatto nella tua applicazione, puoi utilizzare questa stringa di test speciale come tuo prompt: ANTHROPIC_MAGIC_STRING_TRIGGER_REDACTED_THINKING_46C9A13E193C177646C7398A98432ECCCE4C1253D5E2D82641AC0E52CC2876CB
Quando passi blocchi thinking
e redacted_thinking
di nuovo all’API in una conversazione multi-turno, devi includere il blocco completo non modificato di nuovo all’API per l’ultimo turno dell’assistente. Questo è critico per mantenere il flusso di ragionamento del modello. Suggeriamo di passare sempre tutti i blocchi di pensiero di nuovo all’API. Per maggiori dettagli, vedere la sezione Preservare i blocchi di pensiero sopra.
Differenze nel pensiero tra le versioni dei modelli
L’API Messages gestisce il pensiero diversamente tra i modelli Claude Sonnet 3.7 e Claude 4, principalmente nel comportamento di redazione e riassunto.
Vedere la tabella sottostante per un confronto condensato:
Funzione | Claude Sonnet 3.7 | Modelli Claude 4 |
---|---|---|
Output del Pensiero | Restituisce output di pensiero completo | Restituisce pensiero riassunto |
Pensiero Interlacciato | Non supportato | Supportato con header beta interleaved-thinking-2025-05-14 |
Prezzi
Il pensiero esteso utilizza lo schema di prezzi standard dei token:
Modello | Token di Input Base | Scritture Cache | Hit Cache | Token di Output |
---|---|---|---|---|
Claude Opus 4 | $15 / MTok | $18.75 / MTok | $1.50 / MTok | $75 / MTok |
Claude Sonnet 4 | $3 / MTok | $3.75 / MTok | $0.30 / MTok | $15 / MTok |
Claude Sonnet 3.7 | $3 / MTok | $3.75 / MTok | $0.30 / MTok | $15 / MTok |
Il processo di pensiero comporta addebiti per:
- Token utilizzati durante il pensiero (token di output)
- Blocchi di pensiero dall’ultimo turno dell’assistente inclusi nelle richieste successive (token di input)
- Token di output di testo standard
Quando il pensiero esteso è abilitato, un prompt di sistema specializzato viene automaticamente incluso per supportare questa funzione.
Quando si utilizza il pensiero riassunto:
- Token di input: Token nella tua richiesta originale (esclude token di pensiero dai turni precedenti)
- Token di output (fatturati): I token di pensiero originali che Claude ha generato internamente
- Token di output (visibili): I token di pensiero riassunti che vedi nella risposta
- Nessun addebito: Token utilizzati per generare il riassunto
Il conteggio dei token di output fatturati non corrisponderà al cont eggio dei token visibili nella risposta. Vieni fatturato per il processo di pensiero completo, non per il riassunto che vedi.
Migliori pratiche e considerazioni per il pensiero esteso
Lavorare con i budget di pensiero
- Ottimizzazione del budget: Il budget minimo è 1.024 token. Suggeriamo di iniziare dal minimo e aumentare il budget di pensiero incrementalmente per trovare l’intervallo ottimale per il tuo caso d’uso. Conteggi di token più alti consentono ragionamenti più completi ma con rendimenti decrescenti a seconda del compito. Aumentare il budget può migliorare la qualità della risposta al compromesso di una maggiore latenza. Per compiti critici, testa diverse impostazioni per trovare l’equilibrio ottimale. Nota che il budget di pensiero è un obiettivo piuttosto che un limite rigoroso—l’utilizzo effettivo dei token può variare in base al compito.
- Punti di partenza: Inizia con budget di pensiero più grandi (16k+ token) per compiti complessi e regola in base alle tue esigenze.
- Budget grandi: Per budget di pensiero superiori a 32k, raccomandiamo di utilizzare l’elaborazione batch per evitare problemi di rete. Le richieste che spingono il modello a pensare sopra i 32k token causano richieste di lunga durata che potrebbero scontrarsi con timeout di sistema e limiti di connessione aperta.
- Tracciamento dell’utilizzo dei token: Monitora l’utilizzo dei token di pensiero per ottimizzare costi e prestazioni.
Considerazioni sulle prestazioni
- Tempi di risposta: Preparati per tempi di risposta potenzialmente più lunghi a causa dell’elaborazione aggiuntiva richiesta per il processo di ragionamento. Considera che generare blocchi di pensiero può aumentare il tempo di risposta complessivo.
- Requisiti di streaming: Lo streaming è richiesto quando
max_tokens
è maggiore di 21.333. Quando si fa streaming, preparati a gestire sia i blocchi di contenuto di pensiero che di testo mentre arrivano.
Compatibilità delle funzioni
- Il pensiero non è compatibile con modifiche di
temperature
otop_k
così come l’uso forzato di strumenti. - Quando il pensiero è abilitato, puoi impostare
top_p
a valori tra 1 e 0.95. - Non puoi pre-riempire le risposte quando il pensiero è abilitato.
- Le modifiche al budget di pensiero invalidano i prefissi di prompt memorizzati nella cache che includono messaggi. Tuttavia, i prompt di sistema memorizzati nella cache e le definizioni degli strumenti continueranno a funzionare quando i parametri di pensiero cambiano.
Linee guida per l’utilizzo
- Selezione del compito: Utilizza il pensiero esteso per compiti particolarmente complessi che beneficiano del ragionamento passo dopo passo come matematica, codifica e analisi.
- Gestione del contesto: Non hai bisogno di rimuovere i blocchi di pensiero precedenti da solo. L’API Anthropic ignora automaticamente i blocchi di pensiero dai turni precedenti e non sono inclusi quando si calcola l’utilizzo del contesto.
- Ingegneria dei prompt: Rivedi i nostri consigli per il prompting del pensiero esteso se vuoi massimizzare le capacità di pensiero di Claude.