Migrazione da Text Completions
Migrazione da Text Completions a Messages
Quando si migra da Text Completions a Messages, considera le seguenti modifiche.
Input e output
Il cambiamento più grande tra Text Completions e Messages è il modo in cui specifichi gli input del modello e ricevi gli output dal modello.
Con Text Completions, gli input sono stringhe grezze:
Con Messages, specifichi una lista di messaggi di input invece di un prompt grezzo:
Ogni messaggio di input ha un role
e un content
.
Nomi dei ruoli
L’API Text Completions si aspetta turni alternati \n\nHuman:
e \n\nAssistant:
, ma l’API Messages si aspetta ruoli user
e assistant
. Potresti vedere documentazione che fa riferimento a turni “human” o “user”. Questi si riferiscono allo stesso ruolo, e sarà “user” andando avanti.
Con Text Completions, il testo generato dal modello viene restituito nei valori completion
della risposta:
Con Messages, la risposta è il valore content
, che è una lista di blocchi di contenuto:
Mettere parole in bocca a Claude
Con Text Completions, puoi pre-riempire parte della risposta di Claude:
Con Messages, puoi ottenere lo stesso risultato facendo in modo che l’ultimo messaggio di input abbia il ruolo assistant
:
Quando lo fai, il content
della risposta continuerà dall’ultimo content
del messaggio di input:
System prompt
Con Text Completions, il system prompt viene specificato aggiungendo testo prima del primo turno \n\nHuman:
:
Con Messages, specifichi il system prompt con il parametro system
:
Nomi dei modelli
L’API Messages richiede che tu specifichi la versione completa del modello (ad es. claude-sonnet-4-20250514
).
In precedenza supportavamo la specifica solo del numero di versione principale (ad es. claude-2
), che risultava in aggiornamenti automatici alle versioni minori. Tuttavia, non raccomandiamo più questo pattern di integrazione, e Messages non lo supporta.
Stop reason
Text Completions ha sempre un stop_reason
di:
"stop_sequence"
: Il modello ha terminato il suo turno naturalmente, o una delle tue sequenze di stop personalizzate è stata generata."max_tokens"
: Il modello ha generato il numero specificato dimax_tokens
di contenuto, o ha raggiunto il suo massimo assoluto.
Messages ha un stop_reason
di uno dei seguenti valori:
"end_turn"
: Il turno conversazionale è terminato naturalmente."stop_sequence"
: Una delle tue sequenze di stop personalizzate specificate è stata generata."max_tokens"
: (invariato)
Specificare max tokens
- Text Completions: parametro
max_tokens_to_sample
. Nessuna validazione, ma valori limitati per modello. - Messages: parametro
max_tokens
. Se passi un valore più alto di quello supportato dal modello, restituisce un errore di validazione.
Formato streaming
Quando usi "stream": true
con Text Completions, la risposta includeva qualsiasi evento server-sent di completion
, ping
, e error
. Vedi Text Completions streaming per i dettagli.
Messages può contenere più blocchi di contenuto di tipi diversi, e quindi il suo formato streaming è un po’ più complesso. Vedi Messages streaming per i dettagli.