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 die Richtlinien von Anthropic 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 einer 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:
            # Auf Ablehnung im Message-Delta prüfen
            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 zurückfallen: Konfiguriere serverseitiges 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 Wiederholungen einlösen: Wenn du die Wiederholung selbst baust, übergib das Fallback-Guthaben-Token der Ablehnung, damit die Wiederholung die Prompt-Cache-Kosten nicht zweimal zahlt
• Eigene Meldungen bereitstellen: Erstelle benutzerfreundliche Meldungen für eine bessere UX, wenn Ablehnungen auftreten
• Ablehnungsmuster verfolgen: Überwache die Häufigkeit von Ablehnungen, um potenzielle Probleme mit deinen Prompts zu identifizieren

Migrationshinweise

Wenn du eine Ablehnungsbehandlung gebaut hast, als diese Funktion erstmals 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 basiert, sie nicht sichtbar macht. 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 auf einem Fallback-Modell mit serverseitigem Fallback, der SDK-Middleware oder einer manuellen Wiederholung und löse Fallback-Guthaben ein, wenn du die Wiederholung 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 rund um stop_reason: "refusal", verzweige also anhand des Stop-Reasons statt anhand modellspezifischen Verhaltens.

Nächste Schritte