Streaming-Ablehnungen behandeln

Ab den Claude 4 Modellen geben Streaming-Antworten von Claudes API stop_reason: "refusal" zurück, wenn Streaming-Klassifikatoren eingreifen, um potenzielle Richtlinienverstöße zu behandeln. Diese Sicherheitsfunktion hilft dabei, die Inhaltskonformität während des Echtzeit-Streamings aufrechtzuerhalten.



API-Antwortformat

Wenn Streaming-Klassifikatoren Inhalte erkennen, die gegen Anthropics Richtlinien verstoßen, gibt die API diese Antwort zurück:

{
  "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."
  }
}

Im Event-Stream kommt stop_details im message_delta-Event zusammen mit stop_reason an.



Kontext nach Ablehnung zurücksetzen

Wenn du stop_reason: refusal erhältst, musst du den Gesprächskontext zurücksetzen, bevor du fortfährst. Du kannst den Turn, der die Ablehnung ausgelöst hat, entfernen oder umformulieren oder den Gesprächsverlauf vollständig löschen. Der Versuch, ohne Zurücksetzen fortzufahren, führt zu weiteren Ablehnungen.



Implementierungsleitfaden

So erkennst und behandelst du Streaming-Ablehnungen in deiner Anwendung:

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:
            # Prüfe auf Verweigerung im Message-Delta
            if event.type == "message_delta":
                if event.delta.stop_reason == "refusal":
                    reset_conversation()
                    break
except Exception as e:
    print(f"Error: {e}")



Aktuelle Ablehnungstypen

Die API behandelt Ablehnungen derzeit auf drei verschiedene Arten:



Best Practices

• Auf Ablehnungen überwachen: Nimm Prüfungen auf stop_reason: refusal in deine Fehlerbehandlung auf
• Automatisch zurücksetzen: Implementiere ein automatisches Zurücksetzen des Kontexts, wenn Ablehnungen erkannt werden
• Auf ein anderes Modell ausweichen: Konfiguriere serverseitigen Fallback oder die SDK-Middleware, damit abgelehnte Anfragen auf einem anderen Claude-Modell wiederholt werden, anstatt dem Benutzer eine Ablehnung anzuzeigen
• Fallback-Guthaben bei manuellen Retries einlösen: Wenn du den Retry selbst baust, übergib das Fallback-Guthaben-Token der Ablehnung, damit der Retry die Prompt-Cache-Kosten nicht doppelt bezahlt
• Benutzerdefinierte Meldungen bereitstellen: Erstelle benutzerfreundliche Meldungen für eine bessere UX, wenn Ablehnungen auftreten
• Ablehnungsmuster verfolgen: Überwache die Ablehnungshäufigkeit, um potenzielle Probleme mit deinen Prompts zu identifizieren



Migrationshinweise

Wenn du die Ablehnungsbehandlung gebaut hast, als diese Funktion zum ersten Mal ausgeliefert wurde, oder sie zu einer bestehenden Integration hinzufügst, prüfe Folgendes:

• Ablehnungen sind Antworten, keine Fehler. Eine Ablehnung kommt als erfolgreiche HTTP-200-Antwort mit stop_reason: "refusal" an, sodass ein Monitoring, das nur auf Fehlerraten aufbaut, sie nicht erfasst. Verfolge Ablehnungen als eigenes Signal.
• Ablehnungen enthalten strukturierte Details. Bei jedem Modell enthält eine Ablehnung auch ein stop_details-Objekt, das die Richtlinienkategorie hinter der Ablehnung identifiziert. Siehe Ablehnungen und Fallback für die vollständige Antwortstruktur.
• Auf einem anderen Modell wiederholen. Das erneute Senden einer abgelehnten Anfrage an dasselbe Modell führt in der Regel zu einer weiteren Ablehnung. Anstatt nur den Kontext zurückzusetzen, wiederhole die Anfrage auf einem Fallback-Modell mit serverseitigem Fallback, der SDK-Middleware oder einem manuellen Retry und löse Fallback-Guthaben ein, wenn du den Retry selbst baust.
• Batch-Ergebnisse auf Ablehnungen prüfen. Eine abgelehnte Anfrage in einem Message Batch wird als erfolgreiches Ergebnis mit stop_reason: "refusal" zurückgegeben, nicht als fehlerhaftes Ergebnis.
• Behandlung auf stop_reason zentralisieren. Die API konsolidiert die Ablehnungsbehandlung weiterhin um stop_reason: "refusal", verzweige also anhand des Stop-Grunds und nicht anhand modellspezifischen Verhaltens.



Nächste Schritte