Migrazione a Claude 4

Questa pagina fornisce una guida per migrare dai modelli Claude 3.7 ai modelli Claude 4 (Opus 4 e Sonnet 4).

Nella maggior parte dei casi, puoi passare ai modelli Claude 4 con modifiche minime:

1. Aggiorna il nome del tuo modello:

   • Da: claude-3-7-sonnet-20250219
   • A: claude-sonnet-4-20250514 o claude-opus-4-20250514

2. Le chiamate API esistenti dovrebbero continuare a funzionare senza modifiche, anche se il comportamento dell’API è cambiato leggermente nei modelli Claude 4 (vedi note di rilascio API per i dettagli).

​

Novità in Claude 4

​

Nuovo motivo di arresto per rifiuto

I modelli Claude 4 introducono un nuovo motivo di arresto refusal per contenuti che il modello rifiuta di generare per motivi di sicurezza, a causa della maggiore intelligenza dei modelli Claude 4:

{"id":"msg_014XEDjypDjFzgKVWdFUXxZP",
"type":"message",
"role":"assistant",
"model":"claude-sonnet-4-20250514",
"content":[{"type":"text","text":"I would be happy to assist you. You can "}],
"stop_reason":"refusal",
"stop_sequence":null,
"usage":{"input_tokens":564,"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"output_tokens":22}
}

Quando migri a Claude 4, dovresti aggiornare la tua applicazione per gestire i motivi di arresto refusal.

​

Pensiero riassunto

Con il pensiero esteso abilitato, l’API Messages per i modelli Claude 4 restituisce un riassunto del processo di pensiero completo di Claude. Il pensiero riassunto fornisce tutti i benefici di intelligenza del pensiero esteso, prevenendo al contempo l’uso improprio.

Mentre l’API è coerente tra i modelli Claude 3.7 e 4, le risposte in streaming per il pensiero esteso potrebbero essere restituite in un pattern di consegna “a blocchi”, con possibili ritardi tra gli eventi di streaming.

Per maggiori informazioni, vedi la documentazione del pensiero esteso.

​

Pensiero interlacciato

I modelli Claude 4 supportano l’interlacciamento dell’uso degli strumenti con il pensiero esteso, consentendo conversazioni più naturali dove l’uso degli strumenti e le risposte possono essere mescolati con messaggi regolari.

Per maggiori informazioni, vedi la documentazione del pensiero esteso.

​

Strumento editor di testo aggiornato

Lo strumento editor di testo è stato aggiornato per i modelli Claude 4 con le seguenti modifiche:

• Tipo di strumento: text_editor_20250728
• Nome dello strumento: str_replace_based_edit_tool
• Il comando undo_edit non è più supportato nei modelli Claude 4.

Se stai migrando da Claude Sonnet 3.7 e utilizzando lo strumento editor di testo:

# Claude Sonnet 3.7
tools=[
    {
        "type": "text_editor_20250124",
        "name": "str_replace_editor"
    }
]

# Claude 4
tools=[
    {
        "type": "text_editor_20250728",
        "name": "str_replace_based_edit_tool"
    }
]

Per maggiori informazioni, vedi la documentazione dello strumento editor di testo.

​

Uso degli strumenti token-efficiente non più supportato

L’uso degli strumenti token-efficiente è disponibile solo in Claude Sonnet 3.7.

Se stai migrando da Claude Sonnet 3.7 e utilizzando l’uso degli strumenti token-efficiente, raccomandiamo di rimuovere l’header beta token-efficient-tools-2025-02-19 dalle tue richieste.

L’header beta token-efficient-tools-2025-02-19 può ancora essere incluso nelle richieste Claude 4, ma non avrà alcun effetto.

​

Output esteso non più supportato

L’header beta output-128k-2025-02-19 per l’output esteso è disponibile solo in Claude Sonnet 3.7.

Se stai migrando da Claude Sonnet 3.7, raccomandiamo di rimuovere output-128k-2025-02-19 dalle tue richieste.

L’header beta output-128k-2025-02-19 può ancora essere incluso nelle richieste Claude 4, ma non avrà alcun effetto.

​

Considerazioni sulle prestazioni

​

Claude Sonnet 4

• Capacità di ragionamento e intelligenza migliorate rispetto a Claude Sonnet 3.7
• Precisione nell’uso degli strumenti migliorata

​

Claude Opus 4

• Modello più capace con ragionamento e intelligenza superiori
• Più lento dei modelli Sonnet
• Migliore per compiti complessi che richiedono analisi approfondite

​

Lista di controllo per la migrazione

• Aggiorna l’id del modello nelle tue chiamate API
• Testa le richieste esistenti (dovrebbero funzionare senza modifiche)
• Rimuovi l’header beta token-efficient-tools-2025-02-19 se applicabile
• Rimuovi l’header beta output-128k-2025-02-19 se applicabile
• Gestisci il nuovo motivo di arresto refusal
• Aggiorna il tipo e il nome dello strumento editor di testo se lo stai utilizzando
• Rimuovi qualsiasi codice che utilizza il comando undo_edit
• Esplora le nuove capacità di interlacciamento degli strumenti con il pensiero esteso
• Rivedi le migliori pratiche di prompt engineering per Claude 4 per risultati ottimali
• Testa in sviluppo prima del deployment in produzione

​

Hai bisogno di aiuto?

• Controlla la nostra documentazione API per le specifiche dettagliate.
• Rivedi le capacità del modello per confronti delle prestazioni.
• Rivedi le note di rilascio API per gli aggiornamenti dell’API.
• Contatta il supporto se incontri problemi durante la migrazione.