Claude Platform Docs
Modelli e prezziClaude Haiku 5.5

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-5

Questa 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

  1. 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.
  2. Riconteggia i tuoi prompt e rivedi i limiti di max_tokens e 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.
  3. Se le tue richieste inviano thinking: {"type": "enabled", "budget_tokens": N}, modifica thinking in {"type": "adaptive"}. Consulta Configura il ragionamento.
  4. Se il tuo codice legge il primo blocco di contenuto come risposta, seleziona invece i blocchi in base a type. Consulta Configura il ragionamento.
  5. Rimuovi temperature, top_p e top_k dalle tue richieste. Consulta Rimuovi i parametri di campionamento.
  6. Se le tue richieste terminano messages con un turno dell’assistente che il modello deve continuare, terminale invece con un turno dell’utente. Consulta Sostituisci il prefill dell’assistente.
  7. Se usi il “computer use” (uso del computer), sostituisci computer_20250124 con il toolset computer_toolset_20260801. Su Amazon Bedrock, funziona anche computer_20251124. Consulta Sposta il computer use al toolset.
  8. 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.
  9. Se il tuo codice modifica system, tools o i messages precedenti 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.
  10. 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.
  11. 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 categoria reasoning_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

  1. 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.
  2. Se usi lo strumento code_execution_20250522, passa a code_execution_20250825 o successivo.
  3. Se usi lo strumento di modifica del testo, passa a text_editor_20250728.
  4. Gestisci i motivi di interruzione refusal e model_context_window_exceeded.
  5. Se il tuo codice confronta esattamente i parametri stringa delle chiamate agli strumenti, tieni conto dei caratteri di nuova riga finali.
  6. 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.

PiattaformaClaude Haiku 4.5Claude Haiku 5.5
Claude APIclaude-haiku-4-5-20251001 o claude-haiku-4-5claude-haiku-5-5
Amazon Bedrockanthropic.claude-haiku-4-5anthropic.claude-haiku-5-5
Claude Platform on AWSclaude-haiku-4-5claude-haiku-5-5
Claude Models on Google Cloud (Anthropic managed)claude-haiku-4-5-20251001claude-haiku-5-5
Claude Models on Google Cloud (Google managed)claude-haiku-4-5@20251001claude-haiku-5-5
Microsoft Foundryclaude-haiku-4-5claude-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 usage e i risultati del conteggio dei token sono più alti per lo stesso testo.
  • Un determinato numero di token contiene meno testo.
  • Un limite max_tokens calibrato 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:

PassaggioMantiene 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 precedentiSì
A Claude Haiku 5.5, da qualsiasi altro modelloNo. 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.2Sì, solo sulla Claude API e su Claude Models on Google Cloud (Google managed)
Da Claude Haiku 5.5, a qualsiasi altro modelloNo

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 alias claude-3-5-haiku-latest o claude-3-haiku-20240307 con claude-haiku-5-5. Su Claude Models on Google Cloud (Google managed), sostituisci claude-3-5-haiku@20241022 con claude-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_20250825 e le versioni successive. Se usi lo strumento solo Python code_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 strumento str_replace_based_edit_tool), che non dispone del comando undo_edit. Consulta Strumento di modifica del testo.
  • Motivi di interruzione: Gestisci refusal e model_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?