Il pensiero esteso fornisce a Claude 3.7 Sonnet capacità di ragionamento avanzate per compiti complessi, fornendo anche trasparenza sul suo processo di pensiero passo dopo passo prima di fornire la risposta finale.

​
Come funziona il pensiero esteso

Quando il pensiero esteso è attivato, Claude crea blocchi di contenuto thinking dove mostra il suo ragionamento interno. Claude incorpora le intuizioni da questo ragionamento prima di elaborare una risposta finale.

La risposta API includerà sia blocchi di contenuto thinking che text.

Nelle conversazioni multi-turno, solo i blocchi di pensiero associati a una sessione di utilizzo degli strumenti o al turno assistant nell’ultima posizione del messaggio sono visibili a Claude e vengono fatturati come token di input; i blocchi di pensiero associati a messaggi assistant precedenti non sono visibili a Claude durante il campionamento e non vengono fatturati come token di input.

​
Implementare il pensiero esteso

Aggiungi il parametro thinking e un budget di token specificato da utilizzare per il pensiero esteso alla tua richiesta API.

Il parametro budget_tokens determina il numero massimo di token che Claude può utilizzare per il suo processo di ragionamento interno. 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 per intervalli superiori a 32K.

Il tuo budget_tokens deve sempre essere inferiore al max_tokens specificato.

La risposta API includerà sia blocchi di pensiero che di testo:

{
    "content": [
        {
            "type": "thinking",
            "thinking": "To approach this, let's think about what we know about prime numbers...",
            "signature": "zbbJhbGciOiJFU8zI1NiIsImtakcjsu38219c0.eyJoYXNoIjoiYWJjMTIzIiwiaWFxxxjoxNjE0NTM0NTY3fQ...."
        },
        {
            "type": "text",
            "text": "Yes, there are infinitely many prime numbers such that..."
        }
    ]
}

​
Comprendere i blocchi di pensiero

I blocchi di pensiero rappresentano il processo di pensiero interno di Claude. Per consentire a Claude di lavorare attraverso i problemi con restrizioni interne minime mantenendo i nostri standard di sicurezza e le nostre API stateless, abbiamo implementato quanto segue:

  • I blocchi di pensiero contengono un campo signature. Questo campo contiene un token crittografico che verifica che il blocco di pensiero è stato generato da Claude, e viene verificato quando i blocchi di pensiero vengono restituiti all’API. Durante lo streaming delle risposte, la firma viene aggiunta tramite un signature_delta all’interno di un evento content_block_delta appena prima dell’evento content_block_stop. È strettamente necessario restituire i blocchi di pensiero solo quando si utilizza l’uso degli 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 indietro.
  • Occasionalmente il ragionamento interno di Claude verrà segnalato dai nostri sistemi di sicurezza. Quando ciò accade, crittografiamo alcuni o tutti i blocchi thinking e li restituiamo come blocco redacted_thinking. Questi blocchi di pensiero redatti vengono decrittografati quando passati nuovamente all’API, permettendo a Claude di continuare la sua risposta senza perdere il contesto.

Ecco un esempio che mostra sia blocchi di pensiero normali che redatti:

{
  "content": [
    {
      "type": "thinking",
      "thinking": "Let me analyze this step by step...",
      "signature": "WaUjzkypQ2mUEVM36O2TxuC06KN8xyfbJwyem2dw3URve/op91XWHOEBLLqIOMfFG/UvLEczmEsUjavL...."
    },
    {
      "type": "redacted_thinking",
      "data": "EmwKAhgBEgy3va3pzix/LafPsn4aDFIT2Xlxh0L5L8rLVyIwxtE3rAFBa8cr3qpP..."
    },
    {
      "type": "text",
      "text": "Based on my analysis..."
    }
  ]
}

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 prompt: ANTHROPIC_MAGIC_STRING_TRIGGER_REDACTED_THINKING_46C9A13E193C177646C7398A98432ECCCE4C1253D5E2D82641AC0E52CC2876CB

Quando si passano blocchi thinking e redacted_thinking all’API in una conversazione multi-turno, è necessario includere il blocco completo non modificato all’API per l’ultimo turno dell’assistente.

Questo è fondamentale per mantenere il flusso di ragionamento del modello. Suggeriamo di passare sempre indietro tutti i blocchi di pensiero all’API. Per maggiori dettagli, vedi la sezione Preservare i blocchi di pensiero.

​
Suggerimenti per gestire il pensiero redatto in produzione

Quando si costruiscono 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 semplice spiegazione come: “Parte del ragionamento interno di Claude è stato automaticamente crittografato per motivi di sicurezza. Questo non influisce sulla qualità delle risposte.”
  • Se mostri blocchi di pensiero agli utenti, puoi filtrare i blocchi redatti mantenendo i blocchi di pensiero normali
  • Sii trasparente sul fatto che l’utilizzo delle funzionalità di pensiero esteso può occasionalmente risultare in alcuni ragionamenti crittografati
  • Implementa una gestione appropriata degli errori per gestire elegantemente il pensiero redatto senza rompere la tua UI

​
Streaming del pensiero esteso

Quando lo streaming è abilitato, riceverai contenuti di pensiero tramite eventi thinking_delta. Ecco come gestire lo streaming con il pensiero:

Esempio di output streaming:

event: message_start
data: {"type": "message_start", "message": {"id": "msg_01...", "type": "message", "role": "assistant", "content": [], "model": "claude-3-7-sonnet-20250219", "stop_reason": null, "stop_sequence": null}}

event: content_block_start
data: {"type": "content_block_start", "index": 0, "content_block": {"type": "thinking", "thinking": ""}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "Let me solve this step by step:\n\n1. First break down 27 * 453"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "\n2. 453 = 400 + 50 + 3"}}

// Additional thinking deltas...

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "signature_delta", "signature": "EqQBCgIYAhIM1gbcDa9GJwZA2b3hGgxBdjrkzLoky3dl1pkiMOYds..."}}

event: content_block_stop
data: {"type": "content_block_stop", "index": 0}

event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "text", "text": ""}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "text_delta", "text": "27 * 453 = 12,231"}}

// Additional text deltas...

event: content_block_stop
data: {"type": "content_block_stop", "index": 1}

event: message_delta
data: {"type": "message_delta", "delta": {"stop_reason": "end_turn", "stop_sequence": null}}

event: message_stop
data: {"type": "message_stop"}

Sul comportamento dello streaming con il pensiero

Quando si utilizza lo streaming con il pensiero abilitato, potresti notare che il testo a volte arriva in blocchi più grandi alternati con una consegna più piccola, token per token. Questo è un comportamento previsto, specialmente per il contenuto di pensiero.

Il sistema di streaming deve elaborare il contenuto in batch per prestazioni ottimali, il che può risultare in questo pattern di consegna “a blocchi”. Stiamo continuamente lavorando per migliorare questa esperienza, con aggiornamenti futuri focalizzati sul rendere lo streaming del contenuto di pensiero più fluido.

I blocchi redacted_thinking non avranno delta associati e verranno inviati come un singolo evento.

​
Considerazioni importanti quando si utilizza il pensiero esteso

Lavorare con il budget di pensiero: Il budget minimo è di 1.024 token. Suggeriamo di iniziare dal minimo e aumentare incrementalmente il budget di pensiero per trovare l’intervallo ottimale per far funzionare bene Claude per il tuo caso d’uso. Conteggi di token più alti possono permetterti di ottenere un ragionamento più completo e sfumato, ma potrebbero esserci anche rendimenti decrescenti a seconda del compito.

  • Il budget di pensiero è un obiettivo piuttosto che un limite rigido - l’utilizzo effettivo dei token può variare in base al compito.
  • Sii preparato per tempi di risposta potenzialmente più lunghi a causa dell’elaborazione aggiuntiva richiesta per il processo di ragionamento.
  • Lo streaming è richiesto quando max_tokens è maggiore di 21.333.

Per budget di pensiero superiori a 32K: Raccomandiamo di utilizzare l’elaborazione batch per carichi di lavoro dove il budget di pensiero è impostato sopra i 32K 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 i timeout di sistema e i limiti di connessioni aperte.

Compatibilità del pensiero con altre funzionalità:

  • Il pensiero non è compatibile con modifiche di temperature, top_p, o top_k così come con l’uso forzato degli strumenti.
  • 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.

​
Prezzi e utilizzo dei token per il pensiero esteso

I token del pensiero esteso contano verso la finestra di contesto e vengono fatturati come token di output. Poiché i token di pensiero sono trattati come normali token di output, contano anche verso i tuoi limiti di velocità. Assicurati di tenere conto di questo aumento dell’utilizzo dei token quando pianifichi il tuo utilizzo dell’API.

Per Claude 3.7 Sonnet, i prezzi sono:

Uso dei tokenCosto
Token di input$3 / MTok
Token di output (inclusi i token di pensiero)$15 / MTok
Scrittura cache prompt$3.75 / MTok
Lettura cache prompt$0.30 / MTok

L’elaborazione batch per il pensiero esteso è disponibile al 50% di sconto su questi prezzi e spesso si completa in meno di 1 ora.

Tutti i token di pensiero esteso (inclusi i token di pensiero redatti) vengono fatturati come token di output e contano verso i tuoi limiti di velocità.

Nelle conversazioni multi-turno, i blocchi di pensiero associati a messaggi assistente precedenti non vengono fatturati come token di input.

Quando il pensiero esteso è abilitato, un prompt di sistema specializzato di 28 o 29 token viene automaticamente incluso per supportare questa funzionalità.

​
Capacità di output estese (beta)

Claude 3.7 Sonnet può produrre risposte sostanzialmente più lunghe rispetto ai modelli precedenti con supporto fino a 128K token di output (beta)—più di 15 volte più lunghe rispetto agli altri modelli Claude. Questa capacità espansa è particolarmente efficace per casi d’uso di pensiero esteso che coinvolgono ragionamento complesso, generazione di codice ricca e creazione di contenuti completi.

Questa funzionalità può essere abilitata passando un header anthropic-beta di output-128k-2025-02-19.

Quando si utilizza il pensiero esteso con output più lunghi, puoi allocare un budget di pensiero più grande per supportare un ragionamento più approfondito, mantenendo comunque ampi token disponibili per la risposta finale.

Suggeriamo di utilizzare lo streaming o la modalità batch con questa capacità di output estesa; per maggiori dettagli consulta la nostra guida sulle considerazioni di affidabilità della rete per richieste lunghe.

​
Utilizzare il pensiero esteso con la cache dei prompt

La cache dei prompt con il pensiero ha diverse considerazioni importanti:

Inclusione dei blocchi di pensiero nei prompt memorizzati nella cache

  • Il pensiero è incluso solo quando si genera un turno dell’assistente e non è destinato ad essere memorizzato nella cache.
  • I blocchi di pensiero dei turni precedenti vengono ignorati.
  • Se il pensiero viene disabilitato, qualsiasi contenuto di pensiero passato all’API viene semplicemente ignorato.

Regole di invalidazione della cache

  • Le alterazioni ai parametri di pensiero (abilitazione/disabilitazione o modifiche al budget) invalidano i punti di interruzione della cache impostati nei messaggi.
  • I prompt di sistema e gli strumenti mantengono la memorizzazione nella cache anche quando i parametri di pensiero cambiano.

​
Esempi di cache dei prompt con pensiero esteso

​
Max token e dimensione della finestra di contesto con pensiero esteso

Nei modelli Claude più vecchi (prima di Claude 3.7 Sonnet), 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 del contesto. Questo significava che potevi impostare un valore max_tokens grande e il sistema lo avrebbe ridotto silenziosamente secondo necessità.

Con Claude 3.7 Sonnet, max_tokens (che include il tuo budget di pensiero quando il pensiero è abilitato) viene applicato come un limite rigoroso. Il sistema ora restituirà un errore di validazione se i token del prompt + max_tokens supera la dimensione della finestra di contesto.

​
Come viene calcolata 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 da tenere presenti:

  • I blocchi di pensiero dai turni precedenti vengono rimossi e non contano verso la tua finestra di contesto
  • Il pensiero del turno corrente conta verso il tuo limite max_tokens per quel turno

Il diagramma seguente dimostra la gestione specializzata dei token quando il pensiero esteso è abilitato:

La finestra di contesto effettiva viene calcolata come:

finestra di contesto =
  (token di input correnti - token di pensiero precedenti) +
  (token di pensiero + token di pensiero redatti + token di output di testo)

Raccomandiamo di utilizzare l’API di conteggio dei token per ottenere conteggi accurati dei token per il tuo caso d’uso specifico, specialmente quando si lavora con conversazioni multi-turno che includono il pensiero.

Puoi leggere la nostra guida sulle finestre di contesto per un’analisi più approfondita.

​
Gestire i token con il pensiero esteso

Dato il nuovo comportamento della finestra di contesto e max_tokens con modelli di pensiero esteso come Claude 3.7 Sonnet, potresti dover:

  • Monitorare e gestire più attivamente il tuo utilizzo dei token
  • Regolare i valori max_tokens mentre la lunghezza del tuo prompt cambia
  • Potenzialmente utilizzare gli endpoint di conteggio dei 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 dato che i limiti massimi dei token sono aumentati significativamente.

​
Pensiero esteso con uso degli strumenti

Quando si utilizza il pensiero esteso con l’uso degli strumenti, bisogna essere consapevoli del seguente pattern di comportamento:

  1. Primo turno dell’assistente: Quando invii un messaggio utente iniziale, la risposta dell’assistente includerà blocchi di pensiero seguiti da richieste di utilizzo degli strumenti.

  2. Turno del risultato dello strumento: Quando passi il messaggio utente con blocchi di risultato dello strumento, il successivo messaggio dell’assistente non conterrà blocchi di pensiero aggiuntivi.

Per espandere qui, l’ordine normale di una conversazione con uso degli strumenti con pensiero segue questi passaggi:

  1. L’utente invia il messaggio iniziale
  2. L’assistente risponde con blocchi di pensiero e richieste di strumenti
  3. L’utente invia il messaggio con i risultati degli strumenti
  4. L’assistente risponde con altre chiamate agli strumenti o solo testo (nessun blocco di pensiero in questa risposta)
  5. Se vengono richiesti più strumenti, ripetere i passaggi 3-4 fino al completamento della conversazione

Questo design permette a Claude di mostrare il suo processo di ragionamento prima di fare richieste agli strumenti, ma non ripetere il processo di pensiero dopo aver ricevuto i risultati degli strumenti. Claude non produrrà un altro blocco di pensiero fino a dopo il prossimo turno user non tool_result.

Il diagramma seguente illustra la gestione dei token della finestra di contesto quando si combina il pensiero esteso con l’uso degli strumenti:

​
Preservare i blocchi di pensiero

Durante l’uso degli strumenti, devi passare i blocchi thinking e redacted_thinking all’API, e devi includere il blocco completo non modificato all’API. Questo è fondamentale per mantenere il flusso di ragionamento del modello e l’integrità della conversazione.

Mentre puoi omettere i blocchi thinking e redacted_thinking dai turni precedenti con ruolo assistant, suggeriamo di passare sempre indietro tutti i blocchi di pensiero all’API per qualsiasi conversazione multi-turno. L’API:

  • Filtrerà automaticamente i blocchi di pensiero forniti
  • Userà i blocchi di pensiero rilevanti necessari per preservare il ragionamento del modello
  • Fatturerà solo i token di input per i blocchi mostrati a Claude

​
Perché i blocchi di pensiero devono essere preservati

Quando Claude invoca gli strumenti, sta mettendo in pausa la costruzione di una risposta per attendere informazioni esterne. Quando vengono restituiti i risultati degli strumenti, Claude continuerà a costruire quella risposta esistente. Questo necessita di preservare i blocchi di pensiero durante l’uso degli strumenti, per un paio di ragioni:

  1. Continuità del ragionamento: I blocchi di pensiero catturano il ragionamento passo-passo di Claude che ha portato alle richieste degli strumenti. Quando posti i risultati degli strumenti, includere il pensiero originale assicura che Claude possa continuare il suo ragionamento da dove si era fermato.

  2. Mantenimento del contesto: Mentre i risultati degli strumenti appaiono come messaggi utente nella struttura API, sono parte di un flusso di ragionamento continuo. Preservare i blocchi di pensiero mantiene questo flusso concettuale attraverso multiple chiamate API.

Importante: Quando si forniscono blocchi thinking o redacted_thinking, l’intera sequenza di blocchi thinking o redacted_thinking consecutivi deve corrispondere agli output generati dal modello durante la richiesta originale; non puoi riorganizzare o modificare la sequenza di questi blocchi.

​
Suggerimenti per utilizzare al meglio la modalità di pensiero esteso

Per ottenere il massimo dal pensiero esteso:

  1. Imposta budget appropriati: Inizia con budget di pensiero più grandi (16.000+ token) per compiti complessi e regola in base alle tue necessità.

  2. Sperimenta con i budget di token di pensiero: Il modello potrebbe performare diversamente con diverse impostazioni del budget massimo di pensiero. Aumentare il budget massimo di pensiero può far pensare meglio/più duramente il modello, al costo di una maggiore latenza. Per compiti critici, considera di testare diverse impostazioni di budget per trovare l’equilibrio ottimale tra qualità e performance.

  3. 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 vengono inclusi quando si calcola l’utilizzo del contesto.

  4. Monitora l’utilizzo dei token: Tieni traccia dell’utilizzo dei token di pensiero per ottimizzare costi e performance.

  5. Usa il pensiero esteso per compiti particolarmente complessi: Abilita il pensiero per compiti che beneficiano del ragionamento passo-passo come matematica, codifica e analisi.

  6. Tieni conto del tempo di risposta esteso: Considera che generare blocchi di pensiero potrebbe aumentare il tempo di risposta complessivo.

  7. Gestisci lo streaming appropriatamente: Durante lo streaming, sii preparato a gestire sia blocchi di contenuto di pensiero che di testo mentre arrivano.

  8. Ingegneria dei prompt: Rivedi i nostri suggerimenti per i prompt con pensiero esteso se vuoi massimizzare le capacità di pensiero di Claude.

​
Prossimi passi

Prova il ricettario del pensiero esteso

Esplora esempi pratici di pensiero nel nostro ricettario.

Suggerimenti per i prompt con pensiero esteso

Impara le migliori pratiche di ingegneria dei prompt per il pensiero esteso.

Was this page helpful?

Suggerimenti per il pensiero estesoSupporto multilingue