Guida alla migrazione a Claude Haiku 5.5
Passa a Claude Haiku 5.5 dai modelli Haiku precedenti con questa guida alla migrazione. Le indicazioni per abilitare Claude Haiku 5.5 includono il nuovo ID del modello, le impostazioni che restituiscono errori, le modifiche al ragionamento e una checklist per ciascun modello di partenza.
Claude Code
Lascia che Claude Code migri il tuo codice per te
/claude-api migrate questo progetto a claude-haiku-5-5Questa guida tratta il passaggio del codice che chiama Claude Haiku 4.5 a Claude Haiku 5.5. Per il codice che chiama Claude Haiku 3.5 o Claude Haiku 3, apporta anche le modifiche descritte in Migrazione a Claude Haiku 5.5 da Claude Haiku 3.5 e modelli Haiku precedenti. Per passare invece a un modello Sonnet o Opus, consulta Guide alla migrazione. Per sapere per quanto tempo Claude Haiku 4.5 rimane disponibile, consulta Deprecazioni dei modelli.
Checklist di migrazione per modello di partenza
Procedi lungo i gruppi e fermati dopo quello che riporta il tuo modello attuale. Se usi Claude Haiku 4.5, il primo gruppo costituisce l’intero elenco. Ogni voce corrisponde a una modifica da apportare al tuo codice.
Ogni modello di partenza
- Sostituisci l’ID del modello con l’ID di Claude Haiku 5.5 per la tua piattaforma. Consulta Usa l’ID del modello Claude Haiku 5.5.
- Riconteggia i tuoi prompt e rivedi i limiti di
max_tokense le stime dei costi, perché lo stesso testo conta come più token e le immagini di grandi dimensioni contano come più token visivi. Consulta Riconteggia i token. - Se le tue richieste inviano
thinking: {"type": "enabled", "budget_tokens": N}, modificathinkingin{"type": "adaptive"}. Consulta Configura il ragionamento. - Se il tuo codice legge il primo blocco di contenuto come risposta, seleziona invece i blocchi in base a
type. Consulta Configura il ragionamento. - Rimuovi
temperature,top_petop_kdalle tue richieste. Consulta Rimuovi i parametri di campionamento. - Se le tue richieste terminano
messagescon un turno dell’assistente che il modello deve continuare, terminale invece con un turno dell’utente. Consulta Sostituisci il prefill dell’assistente. - Se usi il “computer use” (uso del computer), sostituisci
computer_20250124con il toolsetcomputer_toolset_20260801. Su Amazon Bedrock, funziona anchecomputer_20251124. Consulta Sposta il computer use al toolset. - Se riproduci conversazioni memorizzate tramite un account diverso, riproduci ciascuna tramite l’account che l’ha prodotta. Consulta Riproduci i blocchi di ragionamento tramite l’account che li ha prodotti.
- Se il tuo codice modifica
system,toolso imessagesprecedenti tra una richiesta e l’altra in una conversazione e rinvia i blocchi di ragionamento, mantieni la conversazione in modalità “append-only” (solo aggiunta). Consulta Mantieni invariati i turni precedenti. - Gestisci
stop_reason: "refusal". Claude Haiku 5.5 esegue classificatori di sicurezza che possono rifiutare una richiesta e non dispone di un fallback lato server. Consulta Rifiuti delle salvaguardie. - Se i tuoi prompt chiedono al modello di scrivere il proprio ragionamento nella risposta, ad esempio in tag
<thinking>o<reasoning>, rimuovi queste istruzioni. Claude Haiku 5.5 potrebbe rifiutare una richiesta che le include e restituire la categoriareasoning_extraction. Consulta Rifiuti delle salvaguardie.
Se la tua organizzazione ha un impegno Priority Tier su Claude Haiku 4.5, pianifica la capacità separatamente: Priority Tier non è supportato su Claude Haiku 5.5.
Claude Haiku 3.5 o precedenti
- Sostituisci l’ID del modello Claude Haiku 3.5 o Claude Haiku 3 con l’ID di Claude Haiku 5.5 per la tua piattaforma. Consulta Migrazione a Claude Haiku 5.5 da Claude Haiku 3.5 e modelli Haiku precedenti.
- Se usi lo strumento
code_execution_20250522, passa acode_execution_20250825o successivo. - Se usi lo strumento di modifica del testo, passa a
text_editor_20250728. - Gestisci i motivi di interruzione
refusalemodel_context_window_exceeded. - Se il tuo codice confronta esattamente i parametri stringa delle chiamate agli strumenti, tieni conto dei caratteri di nuova riga finali.
- Rivedi i tuoi prompt.
Usa l’ID del modello Claude Haiku 5.5
Sostituisci l’ID del modello Claude Haiku 4.5 con l’ID di Claude Haiku 5.5 per la tua piattaforma.
| Piattaforma | Claude Haiku 4.5 | Claude Haiku 5.5 |
|---|---|---|
| Claude API | claude-haiku-4-5-20251001 o claude-haiku-4-5 | claude-haiku-5-5 |
| Amazon Bedrock | anthropic.claude-haiku-4-5 | anthropic.claude-haiku-5-5 |
| Claude Platform on AWS | claude-haiku-4-5 | claude-haiku-5-5 |
| Claude Models on Google Cloud (Anthropic managed) | claude-haiku-4-5-20251001 | claude-haiku-5-5 |
| Claude Models on Google Cloud (Google managed) | claude-haiku-4-5@20251001 | claude-haiku-5-5 |
| Microsoft Foundry | claude-haiku-4-5 | claude-haiku-5-5 |
claude-haiku-5-5 è un ID del modello fisso, senza suffisso di data e senza alias separato.
Riconteggia i token
Claude Haiku 5.5 usa lo stesso tokenizer di Claude 4.7 e dei modelli successivi. Come per tutti i modelli che usano questo tokenizer, lo stesso testo di input produce circa il 30 percento di token in più su Claude Haiku 5.5 rispetto a Claude Haiku 4.5. L’aumento esatto dipende dal contenuto. Richieste, risposte ed eventi di streaming mantengono la stessa struttura. Ciò che cambia è tutto ciò che misuri o per cui stanzi un budget in token:
- I campi
usagee i risultati del conteggio dei token sono più alti per lo stesso testo. - Un determinato numero di token contiene meno testo.
- Un limite
max_tokenscalibrato per Claude Haiku 4.5 potrebbe troncare un output equivalente. - Le stime dei costi basate sui conteggi dei token di Claude Haiku 4.5 devono essere ricalcolate con i conteggi e i prezzi di Claude Haiku 5.5, inclusi i suoi prezzi più alti per i prompt lunghi. Consulta Prezzi e Prezzi del contesto lungo.
Anche le immagini di grandi dimensioni possono costare più token. Claude Haiku 5.5 usa il livello di immagini ad alta risoluzione, che ridimensiona le immagini oltre i 2.576 pixel sul lato lungo o i 4.784 token visivi. Claude Haiku 4.5 e i modelli Haiku precedenti usano il livello standard, che ridimensiona le immagini oltre i 1.568 pixel sul lato lungo o i 1.568 token visivi. Un’immagine di 2.000 per 1.500 pixel costa circa 2,5 volte più token visivi su Claude Haiku 5.5 rispetto a Claude Haiku 4.5. Consulta Risoluzione e costo in token.
Conta i token dei tuoi prompt con model impostato su claude-haiku-5-5 invece di riutilizzare i conteggi misurati su Claude Haiku 4.5.
Configura il ragionamento
Claude Haiku 5.5 configura il “thinking” (ragionamento) in modo diverso rispetto a Claude Haiku 4.5. Un valore thinking di {"type": "enabled", "budget_tokens": N} restituisce un errore 400, quindi una richiesta che lo invia necessita di un nuovo valore thinking.
Prima, una richiesta a Claude Haiku 4.5 impostava thinking su enabled con un budget di token:
{
"model": "claude-haiku-4-5",
"max_tokens": 16000,
"thinking": { "type": "enabled", "budget_tokens": 8000 },
"messages": [{ "role": "user", "content": "..." }]
}Dopo, la stessa richiesta a Claude Haiku 5.5 usa il ragionamento adattivo. Il valore thinking cambia e output_config.effort imposta quanto il modello ragiona:
{
"model": "claude-haiku-5-5",
"max_tokens": 16000,
"thinking": { "type": "adaptive" },
"output_config": { "effort": "medium" },
"messages": [{ "role": "user", "content": "..." }]
}Il ragionamento adattivo è attivo per impostazione predefinita, quindi una risposta può iniziare con uno o più blocchi thinking anche quando la richiesta non imposta thinking. Lascia thinking non impostato o impostalo su {"type": "adaptive"} e usa l’effort come controllo: dove Claude Haiku 4.5 funzionava senza ragionamento, o con un budget ridotto per risparmiare token, scegli un livello di effort più basso. A un livello più basso il modello ragiona meno e può saltare del tutto il ragionamento nelle richieste più semplici. Per indicazioni sui prompt, consulta Usa l’effort per controllare il ragionamento. Seleziona i blocchi di contenuto in base al loro campo type anziché alla posizione, e reinvia i blocchi thinking senza modifiche insieme ai risultati degli strumenti.
I token di ragionamento vengono conteggiati in max_tokens, quindi una richiesta con un max_tokens ridotto può interrompersi con stop_reason: "max_tokens" dopo un blocco thinking e prima di qualsiasi testo. Se hai impostato un max_tokens ridotto per Claude Haiku 4.5, aumentalo per lasciare spazio al ragionamento, oppure scegli un livello di effort più basso.
I blocchi di ragionamento dei turni precedenti dell’assistente restano nel contesto e vengono conteggiati come token di input, mentre Claude Haiku 4.5 mantiene solo quelli dell’ultimo turno. Le conversazioni a più turni comportano quindi più token di input di quanto spieghi il solo cambio di tokenizer. Per rimuovere i blocchi più vecchi, usa la cancellazione dei blocchi di ragionamento. Consulta Conservazione dei blocchi di ragionamento per modello.
Per impostazione predefinita, Claude Haiku 5.5 restituisce ogni blocco thinking con un campo thinking vuoto e solo una signature, mentre Claude Haiku 4.5 restituisce il ragionamento riassunto. Per ricevere il ragionamento riassunto, imposta thinking: {"type": "adaptive", "display": "summarized"}.
Claude Haiku 5.5 accetta un tool_choice forzato (any o uno strumento specifico), ma la risposta inizia con la chiamata allo strumento e non contiene alcun blocco thinking. Per consentire al modello di ragionare prima di chiamare uno strumento, usa tool_choice: {"type": "auto"} e indica nel prompt quando usare lo strumento.
Una conversazione che passi da Claude Haiku 4.5 a Claude Haiku 5.5 mantiene il suo ragionamento. Per gli altri passaggi, dipende dai due modelli:
| Passaggio | Mantiene il suo ragionamento |
|---|---|
| A Claude Haiku 5.5, da Claude Haiku 4.5 o precedenti, Claude Sonnet 5 o precedenti, o Claude Opus 4.8 o precedenti | Sì |
| A Claude Haiku 5.5, da qualsiasi altro modello | No. L’API scarta i blocchi di ragionamento di quel modello senza errori. |
| Da Claude Haiku 5.5, a Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.2 o Claude Mythos 5.2 | Sì, solo sulla Claude API e su Claude Models on Google Cloud (Google managed) |
| Da Claude Haiku 5.5, a qualsiasi altro modello | No |
Consulta Cambiare modello e tornare indietro. Per i cambi che non coinvolgono Claude Haiku 5.5, consulta Quali cambi di modello mantengono il ragionamento sulla Claude API.
Rimuovi i parametri di campionamento
Su Claude Haiku 5.5, ometti temperature, top_p e top_k e usa invece il prompt per guidare il comportamento del modello.
Sostituisci il prefill dell’assistente
Un “prefill” (precompilazione) è un turno finale dell’assistente in messages che il modello continua. Claude Haiku 4.5 lo accetta quando il ragionamento è disattivato. Claude Haiku 5.5 lo rifiuta con un errore 400, anche con il ragionamento disattivato. Termina messages con un turno dell’utente e sostituisci ogni prefill in base al suo scopo:
- Formato dell’output: usa gli output strutturati, oppure strumenti con campi enum per la classificazione.
- Preamboli: chiedi nel prompt di sistema una risposta diretta.
- Continuazioni: spostale nel messaggio dell’utente, ad esempio “La tua risposta precedente è stata interrotta e terminava con
[previous_response]. Continua da dove avevi lasciato.” - Promemoria di contesto: inseriscili nel turno dell’utente.
Sposta il computer use al toolset
Claude Haiku 4.5 supporta il computer use tramite lo strumento computer_20250124, con l’header beta computer-use-2025-01-24. Claude Haiku 5.5 supporta il computer use tramite il toolset computer_toolset_20260801. Una richiesta a Claude Haiku 5.5 che dichiara computer_20250124 restituisce un errore 400.
Per spostare un’integrazione al toolset, rimuovi l’header beta computer-use-2025-01-24 e sostituisci la voce tools con {"type": "computer_toolset_20260801"}. Quindi apporta le altre modifiche alla richiesta e al ciclo dell’agente descritte in Migra da computer_20251124. Smista ogni blocco tool_use membro in base a name e toolset_name anziché in base a input.action. Gestisci ogni blocco di questo tipo in un turno e riporta toolset_name nei risultati. Lo zoom è attivo per impostazione predefinita nel toolset; se il tuo ambiente non lo implementa, aggiungi "configs": {"zoom": {"enabled": false}}. Se invii l’header beta fine-grained-tool-streaming-2025-05-14, rimuovilo. Insieme a una voce toolset, restituisce un errore 400.
Su Amazon Bedrock, Claude Haiku 5.5 accetta anche lo strumento computer_20251124 con l’header beta computer-use-2025-11-24.
Claude Haiku 5.5 supporta lo strumento browser use (browser_toolset_20260801) per le attività all’interno delle pagine web. Claude Haiku 4.5 non lo supporta.
Riproduci i blocchi di ragionamento tramite l’account che li ha prodotti
I blocchi di ragionamento di Claude Haiku 5.5 funzionano solo nell’account che li ha prodotti o in un account collegato a esso. Quando un altro account invia uno di questi blocchi, l’API scarta il blocco prima che il modello lo riceva e la richiesta va a buon fine senza quel ragionamento. Questo riguarda il codice che archivia le conversazioni e le riproduce tramite un account diverso, ad esempio un servizio che serve più clienti da un unico archivio di conversazioni. Riproduci ogni conversazione tramite l’account che l’ha prodotta. Consulta Account e piattaforme cloud.
Mantieni invariati i turni precedenti
Mantieni le conversazioni in modalità append-only. Un blocco di ragionamento di Claude Haiku 5.5 resta valido solo finché tutto ciò che è stato inviato prima di esso rimane invariato: il prompt system, i tools e ogni messaggio precedente.
Non superare il “prefix check” (controllo del prefisso) potrebbe causare oppure no un errore 400. Per identificare e gestire entrambi i casi, consulta Controlli del prefisso sui blocchi di ragionamento.
Per le modifiche che attivano l’errore e cosa fare invece, consulta Se il tuo codice modifica il prompt di sistema, gli strumenti o la cronologia.
Migrazione a Claude Haiku 5.5 da Claude Haiku 3.5 e modelli Haiku precedenti
Claude Haiku 3.5 è ritirato sulla Claude API, su Amazon Bedrock e su Claude Models on Google Cloud (Google managed). Claude Haiku 3 è ritirato sulla Claude API e su Claude Models on Google Cloud (Google managed). Consulta Deprecazioni dei modelli.
Da uno qualsiasi dei due modelli, applica prima tutte le sezioni precedenti, quindi queste modifiche:
- ID del modello: Sostituisci
claude-3-5-haiku-20241022, il suo aliasclaude-3-5-haiku-latestoclaude-3-haiku-20240307conclaude-haiku-5-5. Su Claude Models on Google Cloud (Google managed), sostituisciclaude-3-5-haiku@20241022conclaude-haiku-5-5. Su Amazon Bedrock, usa l’ID di Claude Haiku 5.5 indicato in Usa l’ID del modello Claude Haiku 5.5. - Esecuzione del codice: Claude Haiku 5.5 accetta
code_execution_20250825e le versioni successive. Se usi lo strumento solo Pythoncode_execution_20250522, passa a una di esse. Consulta Aggiorna all’ultima versione dello strumento. - Editor di testo: Se usi lo strumento di modifica del testo, passa a
text_editor_20250728(nome dello strumentostr_replace_based_edit_tool), che non dispone del comandoundo_edit. Consulta Strumento di modifica del testo. - Motivi di interruzione: Gestisci
refusalemodel_context_window_exceeded. Consulta Motivi di arresto e fallback. - Caratteri di nuova riga finali: Claude 4.5 e i modelli successivi mantengono i caratteri di nuova riga finali nei parametri stringa delle chiamate agli strumenti. Se il tuo codice confronta esattamente queste stringhe, tienine conto.
- Prompt: Claude 4 e i modelli successivi hanno uno stile comunicativo più conciso e diretto e necessitano di indicazioni esplicite. Rivedi i tuoi prompt alla luce di Prompting per Claude Haiku 5.5 e delle Best practice per il prompting.
Questa pagina ti è stata utile?