Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Il pensiero esteso in modalità manuale ti offre il controllo diretto su quanto Claude pensa. Imposti un budget di token di pensiero su ogni richiesta con thinking: {type: "enabled", budget_tokens: N}, e Claude pensa entro quel budget prima di iniziare la sua risposta finale. La modalità manuale rimane utile quando il tuo carico di lavoro richiede una latenza prevedibile o un controllo preciso sui costi del pensiero. Questa pagina spiega come impostare e ottimizzare il budget, come la modalità manuale interagisce con il pensiero intercalato e la cache dei prompt, e come migrare al pensiero adattivo.
Per il funzionamento del pensiero stesso, inclusi i blocchi di pensiero e la forma della risposta, il parametro display, lo streaming, il pensiero con l'uso degli strumenti e la crittografia, consulta la panoramica sul pensiero.
La disponibilità del pensiero esteso per modello, inclusi i modelli in cui il pensiero esteso è l'unica modalità, è elencata nella tabella di configurazione per modello.
Ecco un esempio di utilizzo del pensiero esteso nella Messages API:
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=16000,
thinking={"type": "enabled", "budget_tokens": 10000},
messages=[
{
"role": "user",
"content": "Are there an infinite number of prime numbers such that n mod 4 == 3?",
}
],
)
# La risposta contiene blocchi di pensiero riassunti e blocchi di testo
for block in response.content:
match block.type:
case "thinking":
print(f"\nThinking summary: {block.thinking}")
case "text":
print(f"\nResponse: {block.text}")Per attivare il pensiero esteso manuale, aggiungi un oggetto thinking con type impostato su enabled e un valore budget_tokens.
Il parametro budget_tokens imposta un obiettivo per il numero di token che Claude può utilizzare per il suo processo di ragionamento interno. Budget più ampi possono migliorare la qualità della risposta consentendo un'analisi più approfondita per problemi complessi.
budget_tokens deve soddisfare questi vincoli:
max_tokens. I token di pensiero contano ai fini del limite max_tokens per il turno, quindi il budget deve lasciare spazio per la risposta finale. L'unica eccezione è il pensiero intercalato, dove budget_tokens può superare max_tokens perché il budget copre tutti i blocchi di pensiero all'interno di un singolo turno dell'assistente.budget_tokens deve essere inferiore a max_tokens, il pensiero esteso non può essere combinato con max_tokens: 0 (pre-riscaldamento della cache).Il budget è un obiettivo piuttosto che un limite rigido. L'utilizzo effettivo dei token varia in base al compito, e Claude potrebbe interrompere il ragionamento ben prima che il budget sia esaurito; max_tokens rimane il tetto massimo assoluto sull'output totale.
Su Claude Opus 4.5, l'unico modello con solo pensiero esteso che supporta effort, effort modella la risposta complessiva mentre budget_tokens imposta la profondità del pensiero; imposta entrambi.
Per ottimizzare il budget:
Per monitorare quanto ti costa effettivamente un budget, controlla il campo usage.output_tokens_details.thinking_tokens nella risposta, che riporta quanti dei token di output fatturati erano ragionamento interno. Durante lo streaming, questa suddivisione appare solo nell'evento finale message_delta.
Quando sei pronto ad abbandonare i budget manuali, consulta Migrazione al pensiero adattivo.
Il pensiero intercalato consente a Claude di pensare tra le chiamate agli strumenti all'interno di un singolo turno dell'assistente, ragionando su ogni risultato dello strumento prima di decidere cosa fare dopo. Per il concetto, la struttura del turno e il comportamento sui modelli con pensiero adattivo, consulta pensiero intercalato nella panoramica sul pensiero. Questa sezione spiega come abilitarlo quando utilizzi il pensiero manuale type: "enabled".
Su Claude Opus 4.5, Claude Sonnet 4.5 e i modelli Claude 4 precedenti (Claude Opus 4.1, Claude Opus 4 e Claude Sonnet 4), aggiungi il beta header interleaved-thinking-2025-05-14 alla tua richiesta API.
La generazione 4.6 si divide in modalità manuale:
type: "enabled" manuale è ancora funzionante ma deprecato. Preferisci il pensiero adattivo, che intercala automaticamente senza header.thinking: {type: "adaptive"} se hai bisogno di ragionamento tra le chiamate agli strumenti su questo modello.Claude Haiku 4.5 non supporta il pensiero intercalato. Sulla Claude API, il beta header viene accettato ma ignorato.
Altre due considerazioni per il pensiero intercalato in modalità manuale:
budget_tokens può superare max_tokens qui; le regole del budget spiegano questa eccezione.Il modo in cui le piattaforme trattano il beta header differisce. La Claude API e Claude Platform su AWS accettano interleaved-thinking-2025-05-14 su qualsiasi modello e lo ignorano dove non supportato. L'accettazione non equivale all'effetto: sui modelli che rifiutano type: "enabled" (4.7 e successivi) o che non hanno l'intercalazione in modalità manuale (Claude Opus 4.6), l'header non ha alcun effetto in modalità manuale; il pensiero adattivo intercala automaticamente lì.
Le piattaforme gestite dai partner (Amazon Bedrock e Google Cloud) accettano allo stesso modo l'header su qualsiasi modello senza restituire un errore, e lo ignorano sui modelli che non supportano il pensiero intercalato.
Le regole generali sulla struttura del turno, incluso il ciclo di uso degli strumenti a turno singolo, la gestione dei conflitti a metà turno e l'attivazione/disattivazione del pensiero tra i turni, si trovano in Pensiero con l'uso degli strumenti.
La modalità manuale aggiunge un requisito: il turno finale dell'assistente di una richiesta con pensiero abilitato deve iniziare con un blocco di pensiero (il pensiero adattivo elimina questo requisito). Anche la modifica della configurazione del pensiero tra i turni invalida la cache dei prompt; consulta la sezione seguente.
La modalità manuale aggiunge una regola al comportamento di caching indipendente dalla modalità descritto in pensiero e cache dei prompt: la modifica di budget_tokens tra le richieste invalida i breakpoint della cache, proprio come il cambio di modalità di pensiero, perché il valore del budget viene renderizzato nel prompt. I breakpoint a livello di messaggio falliscono sempre dopo una modifica del budget; se anche i breakpoint degli strumenti e del prompt di sistema falliscono dipende da dove il modello renderizza la configurazione.
In pratica, scegli un budget e mantienilo stabile per tutta la durata di una conversazione in cache. Eseguendo una conversazione multi-turno con caching a livello di messaggio su Claude Sonnet 4.6 e modificando il budget alla terza richiesta da 4.000 a 8.000 token, l'invalidazione si mostra direttamente:
First request - establishing cache
First response usage: { cache_creation_input_tokens: 1370, cache_read_input_tokens: 0, input_tokens: 17, output_tokens: 700 }
Second request - same thinking parameters (cache hit expected)
Second response usage: { cache_creation_input_tokens: 0, cache_read_input_tokens: 1370, input_tokens: 303, output_tokens: 874 }
Third request - different thinking budget (cache miss expected)
Third response usage: { cache_creation_input_tokens: 1370, cache_read_input_tokens: 0, input_tokens: 747, output_tokens: 619 }La terza richiesta ricrea la cache (cache_creation_input_tokens=1370, cache_read_input_tokens=0) perché il budget è cambiato tra le richieste. Per una versione eseguibile dello stesso esperimento in modalità adattiva, dove il livello di effort svolge il ruolo di cache che budget_tokens svolge qui, consulta Cache dei prompt nella pagina di steering.
La maggior parte del comportamento del pensiero è indipendente dalla modalità ed è documentata una sola volta nella pagina Pensiero. Tutto ciò che vi è descritto si applica anche in modalità manuale:
Se il tuo modello supporta solo il pensiero esteso (Claude Sonnet 4.5, Claude Opus 4.5, Claude Haiku 4.5 e i modelli Claude 4 precedenti), non è necessaria alcuna azione ora: il pensiero adattivo non è disponibile lì, e type: "adaptive" restituisce un errore 400. Mantieni budget_tokens finché non passi a un modello che supporta il pensiero adattivo, quindi applica la mappatura che segue.
Devi migrare da type: "enabled" se:
budget_tokens è deprecato.type: "enabled" restituisce un errore 400.La mappatura è semplice: rimuovi budget_tokens, imposta thinking: {type: "adaptive"} e controlla la profondità del ragionamento con output_config: {effort: ...} invece di un budget di token.
{
"model": "claude-sonnet-4-6",
"max_tokens": 16000,
"thinking": {
"type": "enabled",
"budget_tokens": 10000
}
}diventa:
{
"model": "claude-sonnet-4-6",
"max_tokens": 16000,
"thinking": {
"type": "adaptive"
},
"output_config": {
"effort": "high"
}
}effort: "high" corrisponde al valore predefinito dell'API; appare qui solo per mostrare dove si trova ora il controllo della profondità, e ometterlo produce un comportamento identico.
Aspettati una differenza comportamentale, non solo un cambio di sintassi. Con un budget fisso, Claude pensa a ogni richiesta. Con il pensiero adattivo, Claude decide se e quanto pensare a ogni richiesta, e con impostazioni di effort più basse potrebbe saltare completamente il pensiero su input semplici. Puoi anche rimuovere il beta header interleaved-thinking-2025-05-14 dopo la migrazione: il pensiero adattivo intercala automaticamente, e la Claude API ignora l'header su questi modelli. Anche la conservazione dei blocchi di pensiero cambia: Claude Opus 4.5 e i modelli numerati 4.6 e superiori mantengono i blocchi di pensiero dei turni precedenti nel contesto e li fatturano come input, mentre Claude Sonnet 4.5, Claude Haiku 4.5 e i modelli precedenti li rimuovevano; consulta conservazione dei blocchi di pensiero per modello.
Il cambio di modalità è una modifica della configurazione del pensiero, quindi la prima richiesta dopo il cambio invalida i breakpoint della cache, come descritto in Cache dei prompt in modalità manuale.
Per indicazioni complete, consulta pensiero adattivo, effort e la guida alla migrazione dei modelli.
Scopri come funziona il pensiero: blocchi, visualizzazione, streaming e uso degli strumenti.
Lascia che Claude decida quando e quanto pensare a ogni richiesta.
Conserva i blocchi di pensiero e gestisci il pensiero tra chiamate agli strumenti e turni.
Was this page helpful?