Gestire i rifiuti in streaming

A partire dai modelli Claude 4, le risposte in streaming dall'API di Claude restituiscono stop_reason: "refusal" quando i classificatori di streaming intervengono per gestire potenziali violazioni delle policy. Questa funzionalità di sicurezza aiuta a mantenere la conformità dei contenuti durante lo streaming in tempo reale.



Formato della risposta API

Quando i classificatori di streaming rilevano contenuti che violano le policy di Anthropic, l'API restituisce questa risposta:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello.."
    }
  ],
  "stop_reason": "refusal",
  "stop_details": {
    "type": "refusal",
    "category": "cyber",
    "explanation": "This request was declined because it could enable cyber harm."
  }
}

Nel flusso di eventi, stop_details arriva nell'evento message_delta insieme a stop_reason.



Reimpostare il contesto dopo un rifiuto

Quando ricevi stop_reason: refusal, devi reimpostare il contesto della conversazione prima di continuare. Puoi rimuovere o riformulare il turno che ha attivato il rifiuto, oppure cancellare completamente la cronologia della conversazione. Tentare di continuare senza reimpostare comporterà ulteriori rifiuti.



Guida all'implementazione

Ecco come rilevare e gestire i rifiuti in streaming nella tua applicazione:

client = anthropic.Anthropic()
messages = []


def reset_conversation():
    """Reset conversation context after refusal"""
    global messages
    messages = []
    print("Conversation reset due to refusal")


try:
    with client.messages.stream(
        max_tokens=1024,
        messages=messages + [{"role": "user", "content": "Hello"}],
        model="claude-opus-5",
    ) as stream:
        for event in stream:
            # Verifica la presenza di un rifiuto nel delta del messaggio
            if event.type == "message_delta":
                if event.delta.stop_reason == "refusal":
                    reset_conversation()
                    break
except Exception as e:
    print(f"Error: {e}")



Tipi di rifiuto attuali

L'API attualmente gestisce i rifiuti in tre modi diversi:



Best practice

• Monitora i rifiuti: Includi controlli su stop_reason: refusal nella tua gestione degli errori
• Reimposta automaticamente: Implementa la reimpostazione automatica del contesto quando vengono rilevati rifiuti
• Esegui il fallback su un altro modello: Configura il fallback lato server o il middleware dell'SDK in modo che le richieste rifiutate vengano riprovate su un altro modello Claude invece di mostrare un rifiuto all'utente
• Riscatta il credito di fallback nei nuovi tentativi manuali: Se costruisci tu stesso il nuovo tentativo, passa il token di credito di fallback del rifiuto in modo che il nuovo tentativo non paghi due volte il costo della cache dei prompt
• Fornisci messaggi personalizzati: Crea messaggi intuitivi per una migliore UX quando si verificano rifiuti
• Traccia i pattern di rifiuto: Monitora la frequenza dei rifiuti per identificare potenziali problemi con i tuoi prompt



Note di migrazione

Se hai costruito la gestione dei rifiuti quando questa funzionalità è stata rilasciata per la prima volta, o la stai aggiungendo a un'integrazione esistente, verifica quanto segue:

• I rifiuti sono risposte, non errori. Un rifiuto arriva come risposta HTTP 200 riuscita con stop_reason: "refusal", quindi un monitoraggio basato solo sui tassi di errore non lo rileverà. Traccia i rifiuti come segnale a sé stante.
• I rifiuti includono dettagli strutturati. Su ogni modello, un rifiuto include anche un oggetto stop_details che identifica la categoria di policy alla base del rifiuto. Consulta Rifiuti e fallback per la struttura completa della risposta.
• Riprova su un modello diverso. Reinviare una richiesta rifiutata allo stesso modello di solito produce un altro rifiuto. Invece di limitarti a reimpostare il contesto, riprova su un modello di fallback con il fallback lato server, il middleware dell'SDK o un nuovo tentativo manuale, e riscatta il credito di fallback quando costruisci tu stesso il nuovo tentativo.
• Controlla i risultati dei batch per i rifiuti. Una richiesta rifiutata in un Message Batch viene restituita come risultato riuscito con stop_reason: "refusal", non come risultato in errore.
• Centralizza la gestione su stop_reason. L'API continua a consolidare la gestione dei rifiuti attorno a stop_reason: "refusal", quindi basa la logica sullo stop reason piuttosto che sul comportamento specifico del modello.



Prossimi passi