Gestione dei motivi di arresto
Comprendi i valori stop_reason nell’API Messages di Claude e come gestire diversi tipi di risposta nelle tue applicazioni.
Quando fai una richiesta all’API Messages, la risposta di Claude include un campo stop_reason
che indica perché il modello ha smesso di generare la sua risposta. Comprendere questi valori è cruciale per costruire applicazioni robuste che gestiscano appropriatamente diversi tipi di risposta.
Per dettagli su stop_reason
nella risposta dell’API, vedi il riferimento API Messages.
Cos’è stop_reason?
Il campo stop_reason
fa parte di ogni risposta di successo dell’API Messages. A differenza degli errori, che indicano fallimenti nell’elaborazione della tua richiesta, stop_reason
ti dice perché Claude ha completato con successo la generazione della sua risposta.
Valori del motivo di arresto
end_turn
Il motivo di arresto più comune. Indica che Claude ha finito la sua risposta naturalmente.
max_tokens
Claude si è fermato perché ha raggiunto il limite max_tokens
specificato nella tua richiesta.
stop_sequence
Claude ha incontrato una delle tue sequenze di arresto personalizzate.
tool_use
Claude sta chiamando uno strumento e si aspetta che tu lo esegua.
pause_turn
Utilizzato con strumenti server come la ricerca web quando Claude deve mettere in pausa un’operazione di lunga durata.
refusal
Claude ha rifiutato di generare una risposta a causa di preoccupazioni di sicurezza.
Migliori pratiche per gestire i motivi di arresto
1. Controlla sempre stop_reason
Prendi l’abitudine di controllare il stop_reason
nella tua logica di gestione delle risposte:
2. Gestisci max_tokens con grazia
Quando una risposta è troncata a causa dei limiti di token:
3. Implementa logica di ripetizione per pause_turn
Per strumenti server che potrebbero mettere in pausa:
Motivi di arresto vs. errori
È importante distinguere tra valori stop_reason
ed errori effettivi:
Motivi di arresto (risposte di successo)
- Parte del corpo della risposta
- Indicano perché la generazione si è fermata normalmente
- La risposta contiene contenuto valido
Errori (richieste fallite)
- Codici di stato HTTP 4xx o 5xx
- Indicano fallimenti nell’elaborazione delle richieste
- La risposta contiene dettagli dell’errore
Considerazioni sullo streaming
Quando usi lo streaming, stop_reason
è:
null
nell’evento inizialemessage_start
- Fornito nell’evento
message_delta
- Non fornito in nessun altro evento
Modelli comuni
Gestione dei flussi di lavoro degli strumenti
Assicurare risposte complete
Gestendo correttamente i valori stop_reason
, puoi costruire applicazioni più robuste che gestiscono con grazia diversi scenari di risposta e forniscono migliori esperienze utente.