Migrazione a Claude Sonnet 5

Claude Sonnet 5 offre la migliore combinazione di velocità e intelligenza nella famiglia di modelli Claude. Si basa su Claude Sonnet 4.6.

Claude Sonnet 5 è un aggiornamento diretto (drop-in) per Claude Sonnet 4.6, al prezzo di $2/$10 USD per milione di token di input/output; consulta Prezzi per i dettagli. Ci sono due modifiche incompatibili dell'API per il codice già in esecuzione su Claude Sonnet 4.6. Primo, l'adaptive thinking (pensiero adattivo) è attivo per impostazione predefinita e l'"extended thinking" (pensiero esteso) manuale (thinking: {type: "enabled", budget_tokens: N}) restituisce un errore 400, quindi le richieste che venivano eseguite senza pensiero possono ora restituire blocchi thinking prima del primo blocco text e il codice che legge il contenuto per posizione deve selezionare i blocchi di contenuto per type. Secondo, i parametri di campionamento (temperature, top_p, top_k) impostati su valori non predefiniti restituiscono un errore 400. Usa il pensiero adattivo con il parametro effort per controllare la profondità del pensiero. Claude Sonnet 5 supporta lo stesso insieme di funzionalità di Claude Sonnet 4.6, inclusa la "context window" (finestra di contesto) da 1M di token, il pensiero adattivo, la "prompt caching" (cache dei prompt), l'elaborazione batch, la Files API, il supporto PDF, la visione e l'insieme completo di strumenti lato server e lato client. Sulla Claude API e su Google Cloud, Claude Sonnet 5 supporta anche il computer use (uso del computer) come toolset stabile computer_toolset_20260801 e lo strumento browser use per attività all'interno di pagine web, nessuno dei quali è supportato da Claude Sonnet 4.6; le integrazioni esistenti sulla versione precedente computer_20251124 continuano a funzionare senza modifiche su entrambi i modelli. Per aggiornare un'integrazione esistente, consulta Migrare da computer_20251124. Il Priority Tier non è disponibile su Claude Sonnet 5. Claude Sonnet 5 utilizza inoltre un nuovo tokenizer.

Migrazione a Claude Sonnet 5 da Claude Sonnet 4.6

Aggiorna il nome del modello

# Migrazione a Sonnet
model = "claude-sonnet-4-6"  # Before
model = "claude-sonnet-5"  # After

Cosa è cambiato

Gli elementi 4 e 5 nell'elenco seguente sono modifiche incompatibili. max_tokens rimane un limite rigido sull'output totale (pensiero più testo della risposta), quindi rivedilo per i carichi di lavoro che venivano eseguiti senza pensiero su Claude Sonnet 4.6.

1. Nuovo tokenizer: Claude Sonnet 5 utilizza un nuovo tokenizer. Lo stesso testo di input produce circa il 30% di token in più rispetto a Claude Sonnet 4.6. L'aumento esatto dipende dal contenuto. Richieste, risposte ed eventi di streaming mantengono la stessa forma e non sono necessarie modifiche al codice, ma tutto ciò che misuri o pianifichi in token cambia: i campi usage e i risultati del conteggio dei token per lo stesso testo sono più alti, la finestra di contesto da 1M di token contiene meno testo e un limite max_tokens calibrato per Claude Sonnet 4.6 potrebbe troncare un output equivalente. Il prezzo per token è inferiore ($2/$10 USD contro i $3/$15 USD di Claude Sonnet 4.6 per milione di token di input/output), ma il costo di una richiesta equivalente non diminuisce in proporzione diretta. Esegui nuovamente il conteggio dei token su Claude Sonnet 5 invece di riutilizzare i conteggi misurati su modelli precedenti.

2. 128k token di output massimi (invariato): Claude Sonnet 5 supporta fino a 128k token di output, come Claude Sonnet 4.6. I valori max_tokens esistenti rimangono validi. Tieni conto del nuovo tokenizer quando li dimensioni.

3. Precompilazione del messaggio dell'assistente (invariato): La precompilazione del messaggio dell'assistente restituisce un errore 400 su Claude Sonnet 5, come su Claude Sonnet 4.6. Se hai rimosso la precompilazione durante la migrazione a Claude Sonnet 4.6, non sono necessarie ulteriori modifiche. Usa invece gli output strutturati, le istruzioni nel prompt di sistema o output_config.format.

4. Pensiero adattivo attivo per impostazione predefinita: Su Claude Sonnet 4.6, le richieste senza un campo thinking vengono eseguite senza pensiero; su Claude Sonnet 5, le stesse richieste vengono eseguite con il pensiero adattivo. Per disattivare il pensiero, passa thinking: {type: "disabled"}. Il pensiero esteso manuale (thinking: {type: "enabled", budget_tokens: N}) non è supportato e restituisce un errore 400. Usa il parametro effort (predefinito high) per controllare la profondità del pensiero.

   Con il pensiero attivo, una risposta può iniziare con uno o più blocchi thinking prima del primo blocco text, restituiti con un campo thinking vuoto con l'impostazione predefinita display: "omitted". Il codice che legge la risposta per posizione, come content[0].text o un gestore di stream che tratta il primo blocco di contenuto come testo, deve invece selezionare i blocchi di contenuto in base al loro campo type, e i cicli di uso degli strumenti devono restituire i blocchi thinking completi e non modificati insieme ai risultati degli strumenti (consulta Preservare i blocchi di pensiero). I token di pensiero vengono fatturati come token di output anche quando il testo del pensiero non viene restituito. Se usavi il pensiero su Claude Sonnet 4.6 e visualizzi il testo del pensiero restituito, nota che thinking.display lì aveva come valore predefinito "summarized" mentre su Claude Sonnet 5 il valore predefinito è "omitted"; imposta display: "summarized", come fa l'esempio seguente, per continuare a ricevere riepiloghi leggibili (consulta Controllare la visualizzazione del pensiero).

   Claude Sonnet 5Claude Sonnet 4.6

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

   

   client = anthropic.Anthropic()
   
   response = client.messages.create(
       model="claude-sonnet-5",
       max_tokens=16000,
       thinking={"type": "adaptive", "display": "summarized"},
       output_config={"effort": "high"},
       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}")

5. Parametri di campionamento rimossi: I parametri di campionamento (temperature, top_p, top_k) impostati su un valore non predefinito non sono accettati e restituiscono un errore 400.

6. Protezioni di cybersecurity: Claude Sonnet 5 è il primo modello di livello Sonnet con protezioni di cybersecurity in tempo reale. Le richieste che riguardano argomenti di cybersecurity proibiti o ad alto rischio potrebbero essere rifiutate. I rifiuti vengono restituiti come risposta HTTP 200 riuscita con stop_reason: "refusal", non come errore. Consulta Protezioni cyber in tempo reale su Claude Opus e Sonnet per sapere cosa bloccano le protezioni e come il lavoro di sicurezza legittimo può candidarsi al Cyber Verification Program.

Checklist di migrazione

• Aggiorna il nome del modello da claude-sonnet-4-6 a claude-sonnet-5.
• Esegui nuovamente il conteggio dei token su Claude Sonnet 5. Il nuovo tokenizer produce circa il 30% di token in più per lo stesso testo, il che può modificare il costo per richiesta anche se il prezzo per token è inferiore. L'aumento esatto dipende dal contenuto e dalla forma del carico di lavoro.
• Rivedi i limiti max_tokens dimensionati vicino alla lunghezza di output prevista e aumentali fino al massimo di 128k (invariato rispetto a Claude Sonnet 4.6) dove utile.
• Rimuovi la configurazione thinking: {type: "enabled", budget_tokens: N} (restituisce un errore 400). Il pensiero adattivo è attivo per impostazione predefinita; passa {type: "disabled"} per disattivarlo, oppure usa il parametro effort per controllarne la profondità.
• Aggiorna il parsing delle risposte che legge il contenuto per posizione, come content[0].text: con il pensiero attivo, i blocchi thinking arrivano prima dei blocchi text. Seleziona invece i blocchi di contenuto per type e restituisci i blocchi thinking non modificati nei cicli di uso degli strumenti; i blocchi modificati restituiscono un errore 400.
• Verifica che qualsiasi codice che analizza il campo thinking lo tratti solo come testo da visualizzare. thinking.display ha come valore predefinito "omitted" su Claude Sonnet 5 (era "summarized" su Claude Sonnet 4.6), quindi i blocchi di pensiero arrivano con un campo thinking vuoto; imposta display: "summarized" per ricevere riepiloghi leggibili. Consulta Controllare la visualizzazione del pensiero.
• Rimuovi i parametri temperature, top_p e top_k impostati su valori non predefiniti (restituiscono un errore 400 su Claude Sonnet 5).
• Aggiungi la gestione di stop_reason: "refusal" se il tuo carico di lavoro può toccare argomenti di cybersecurity.
• Ricalcola la baseline dei costi sul tuo carico di lavoro tipico prima della distribuzione in produzione.
• Rivedi max_tokens per i carichi di lavoro che in precedenza venivano eseguiti senza pensiero.

Migrazione a Claude Sonnet 5 da Claude Sonnet 4.5 e modelli Sonnet precedenti

Se stai migrando da Claude Sonnet 4.5 o da un modello Sonnet precedente direttamente a Claude Sonnet 5, applica le modifiche di Migrazione a Claude Sonnet 5 da Claude Sonnet 4.6 più le modifiche di questa sezione.

Modifiche incompatibili

Quando si migra da Sonnet 4.5

1. La precompilazione dei messaggi dell'assistente non è più supportata

   La precompilazione dei messaggi dell'assistente restituisce un errore 400 su Claude Sonnet 4.6 e modelli successivi, incluso Claude Sonnet 5. Usa invece gli output strutturati, le istruzioni nel prompt di sistema o output_config.format.

   Casi d'uso comuni della precompilazione e relative migrazioni:

   • Controllo della formattazione dell'output (forzare output JSON/YAML): Usa gli output strutturati o strumenti con campi enum per attività di classificazione.

   • Eliminazione dei preamboli (rimuovere frasi come "Ecco..."): Aggiungi istruzioni dirette nel prompt di sistema: "Rispondi direttamente senza preambolo. Non iniziare con frasi come 'Ecco...', 'In base a...', ecc."

   • Evitare rifiuti inappropriati: Claude ora è molto migliore nei rifiuti appropriati. Un prompting chiaro nel messaggio dell'utente senza precompilazione dovrebbe essere sufficiente.

   • Continuazioni (riprendere risposte interrotte): Sposta la continuazione nel messaggio dell'utente: "La tua risposta precedente è stata interrotta e terminava con [previous_response]. Continua da dove ti eri fermato."

   • Idratazione del contesto / coerenza del ruolo (aggiornare il contesto in conversazioni lunghe): Inserisci invece nel turno dell'utente quelli che in precedenza erano promemoria precompilati dell'assistente.

2. L'escaping JSON dei parametri degli strumenti potrebbe differire

   L'escaping delle stringhe JSON nei parametri degli strumenti potrebbe differire dai modelli precedenti. I parser JSON standard lo gestiscono automaticamente, ma il parsing personalizzato basato su stringhe potrebbe richiedere aggiornamenti.

Modifiche al pensiero esteso: Le configurazioni budget_tokens di Claude Sonnet 4.5 (thinking: {type: "enabled", budget_tokens: N}) non sono supportate su Claude Sonnet 5 e restituiscono un errore 400. Il pensiero adattivo è attivo per impostazione predefinita, quindi la maggior parte dei carichi di lavoro non necessita di alcuna configurazione thinking; usa il parametro effort per controllare la profondità del pensiero. Se eseguivi Claude Sonnet 4.5 senza pensiero esteso, passa thinking: {type: "disabled"} per preservare quel comportamento.

Quando si migra da Claude 3.x

3. Rimuovi i parametri di campionamento

   I parametri di campionamento (temperature, top_p, top_k) impostati su un valore non predefinito restituiscono un errore 400 su Claude Sonnet 5. Rimuovili dalle richieste e usa invece il prompting per guidare il comportamento del modello.

4. Aggiorna le versioni degli strumenti

   Aggiorna alle versioni più recenti degli strumenti (text_editor_20250728, code_execution_20260521). Rimuovi qualsiasi codice che utilizza il comando undo_edit.

5. Gestisci lo stop reason refusal

   Aggiorna la tua applicazione per gestire gli stop reason refusal.

6. Aggiorna i tuoi prompt per i cambiamenti comportamentali

   I modelli Claude 4 hanno uno stile di comunicazione più conciso e diretto. Consulta le best practice di prompting per indicazioni sull'ottimizzazione.

Migrazione a Claude Sonnet 5 da Claude Haiku 4.5

Claude Haiku 4.5 e Claude Sonnet 5 differiscono a livello di API più di quanto differiscano modelli adiacenti all'interno di una stessa classe: Claude Haiku 4.5 utilizza il pensiero esteso manuale (disattivato per impostazione predefinita), una finestra di contesto da 200k token e fino a 64k token di output, mentre Claude Sonnet 5 viene eseguito con il pensiero adattivo attivo per impostazione predefinita, offre una finestra di contesto da 1M di token per impostazione predefinita e supporta fino a 128k token di output.

Aggiorna il nome del modello

model = "claude-haiku-4-5-20251001"  # Before
model = "claude-sonnet-5"  # After

Cosa è cambiato

1. Configurazione del pensiero: Claude Haiku 4.5 supporta il pensiero esteso manuale (thinking: {type: "enabled", budget_tokens: N}) e rifiuta thinking: {type: "adaptive"}. Su Claude Sonnet 5, il supporto è invertito: il pensiero adattivo è attivo per impostazione predefinita e il pensiero esteso manuale restituisce un errore 400. Rimuovi le configurazioni thinking: {type: "enabled", budget_tokens: N} e affidati al valore predefinito, oppure passa thinking: {type: "disabled"} per disattivare il pensiero. budget_tokens non ha un sostituto diretto; usa il parametro effort per controllare la profondità del pensiero. L'effort non è disponibile su Claude Haiku 4.5 e ha come valore predefinito high su Claude Sonnet 5.

   La forma della risposta cambia per entrambi i tipi di richiesta di Claude Haiku 4.5. Le richieste che venivano eseguite senza pensiero esteso possono ora restituire uno o più blocchi thinking prima del primo blocco text, quindi il codice che legge la risposta per posizione, come content[0].text, deve invece selezionare i blocchi di contenuto in base al loro campo type, e i cicli di uso degli strumenti devono restituire i blocchi thinking completi e non modificati insieme ai risultati degli strumenti (consulta Preservare i blocchi di pensiero). Le richieste che usavano il pensiero esteso continuano a ricevere blocchi thinking, ma thinking.display ha come valore predefinito "omitted" su Claude Sonnet 5 anziché "summarized", quindi quei blocchi arrivano con un campo thinking vuoto; imposta display: "summarized" per continuare a ricevere riepiloghi leggibili (consulta Controllare la visualizzazione del pensiero). I token di pensiero vengono fatturati come token di output anche quando il testo del pensiero non viene restituito.

2. Parametri di campionamento rimossi: temperature e top_p funzionano su Claude Haiku 4.5 (uno alla volta, non entrambi). Su Claude Sonnet 5, impostare temperature, top_p o top_k su un valore non predefinito restituisce un errore 400. Rimuovi questi parametri e usa il prompting per guidare il comportamento del modello.

3. Precompilazione dell'assistente rimossa: La precompilazione del messaggio dell'assistente funziona su Claude Haiku 4.5 ma restituisce un errore 400 su Claude Sonnet 5. Usa invece gli output strutturati, le istruzioni nel prompt di sistema o output_config.format.

4. Finestra di contesto e output più ampi: Claude Sonnet 5 offre una finestra di contesto da 1M di token per impostazione predefinita, rispetto ai 200k token di Claude Haiku 4.5, e supporta fino a 128k token di output, rispetto ai 64k. Claude Sonnet 5 utilizza inoltre un tokenizer diverso, quindi esegui nuovamente il conteggio dei token invece di riutilizzare i conteggi misurati su Claude Haiku 4.5.

5. Prezzi: Claude Haiku 4.5 ha un prezzo di $1/$5 USD per milione di token di input/output. Claude Sonnet 5 ha un prezzo di $2/$10 USD per milione di token di input/output. Consulta Prezzi di Claude.

6. Protezioni di cybersecurity: Claude Sonnet 5 dispone di protezioni di cybersecurity in tempo reale. Le richieste che riguardano argomenti di cybersecurity proibiti o ad alto rischio potrebbero essere rifiutate, restituite come risposta HTTP 200 riuscita con stop_reason: "refusal". Consulta Protezioni cyber in tempo reale su Claude Opus e Sonnet per sapere cosa bloccano le protezioni e come il lavoro di sicurezza legittimo può candidarsi al Cyber Verification Program.

Checklist di migrazione

• Aggiorna il nome del modello da claude-haiku-4-5-20251001 (o l'alias claude-haiku-4-5) a claude-sonnet-5.
• Rimuovi la configurazione thinking: {type: "enabled", budget_tokens: N} (restituisce un errore 400). Il pensiero adattivo è attivo per impostazione predefinita; passa thinking: {type: "disabled"} per preservare il comportamento senza pensiero e rivedi max_tokens per i carichi di lavoro che venivano eseguiti senza pensiero.
• Aggiorna il parsing delle risposte che legge il contenuto per posizione, come content[0].text: con il pensiero attivo, i blocchi thinking arrivano prima dei blocchi text. Seleziona invece i blocchi di contenuto per type e restituisci i blocchi thinking non modificati nei cicli di uso degli strumenti; i blocchi modificati restituiscono un errore 400.
• Se la tua interfaccia utente visualizza il contenuto del pensiero, imposta display: "summarized". thinking.display ha come valore predefinito "omitted" su Claude Sonnet 5, quindi altrimenti i blocchi di pensiero arrivano con un campo thinking vuoto. Consulta Controllare la visualizzazione del pensiero.
• Usa il parametro effort (predefinito high) per controllare la profondità del pensiero e la spesa in token; non è disponibile su Claude Haiku 4.5, quindi nessuna impostazione esistente viene trasferita.
• Rimuovi le impostazioni temperature e top_p (i valori non predefiniti restituiscono un errore 400 su Claude Sonnet 5).
• Rimuovi qualsiasi precompilazione del messaggio dell'assistente (restituisce un errore 400 su Claude Sonnet 5).
• Esegui nuovamente il conteggio dei token su Claude Sonnet 5 e rivedi i limiti max_tokens, che puoi aumentare fino al massimo di 128k.
• Aggiungi la gestione di stop_reason: "refusal" se il tuo carico di lavoro può toccare argomenti di cybersecurity.
• Ricalcola la baseline dei costi sul tuo carico di lavoro tipico prima della distribuzione in produzione; il prezzo per token è diverso.