Menangani penolakan streaming

Mulai dari model Claude 4, respons streaming dari API Claude mengembalikan stop_reason: "refusal" ketika pengklasifikasi streaming melakukan intervensi untuk menangani potensi pelanggaran kebijakan. Fitur keamanan ini membantu menjaga kepatuhan konten selama streaming real-time.

Format respons API

Ketika pengklasifikasi streaming mendeteksi konten yang melanggar kebijakan Anthropic, API mengembalikan respons ini:

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

Dalam event stream, stop_details tiba pada event message_delta bersama dengan stop_reason.

Reset konteks setelah penolakan

Ketika Anda menerima stop_reason: refusal, Anda harus mereset konteks percakapan sebelum melanjutkan. Anda dapat menghapus atau menyusun ulang giliran yang memicu penolakan, atau menghapus riwayat percakapan sepenuhnya. Mencoba melanjutkan tanpa mereset akan mengakibatkan penolakan yang berlanjut.

Panduan implementasi

Berikut cara mendeteksi dan menangani penolakan streaming dalam aplikasi Anda:

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-5",
    ) as stream:
        for event in stream:
            # Periksa penolakan dalam message delta
            if event.type == "message_delta":
                if event.delta.stop_reason == "refusal":
                    reset_conversation()
                    break
except Exception as e:
    print(f"Error: {e}")

Jenis penolakan saat ini

API saat ini menangani penolakan dengan tiga cara berbeda:

Praktik terbaik

• Pantau penolakan: Sertakan pemeriksaan stop_reason: refusal dalam penanganan error Anda
• Reset secara otomatis: Implementasikan reset konteks otomatis ketika penolakan terdeteksi
• Fallback ke model lain: Konfigurasikan fallback sisi server atau middleware SDK agar permintaan yang ditolak dicoba ulang pada model Claude lain alih-alih menampilkan penolakan kepada pengguna
• Tukarkan kredit fallback pada percobaan ulang manual: Jika Anda membangun percobaan ulang sendiri, teruskan token kredit fallback dari penolakan tersebut agar percobaan ulang tidak membayar biaya prompt-cache dua kali
• Sediakan pesan kustom: Buat pesan yang ramah pengguna untuk UX yang lebih baik ketika penolakan terjadi
• Lacak pola penolakan: Pantau frekuensi penolakan untuk mengidentifikasi potensi masalah pada prompt Anda

Catatan migrasi

Jika Anda membangun penanganan penolakan saat fitur ini pertama kali dirilis, atau Anda menambahkannya ke integrasi yang sudah ada, periksa hal-hal berikut:

• Penolakan adalah respons, bukan error. Penolakan tiba sebagai respons HTTP 200 yang berhasil dengan stop_reason: "refusal", sehingga pemantauan yang hanya dibangun berdasarkan tingkat error tidak akan menampilkannya. Lacak penolakan sebagai sinyal tersendiri.
• Penolakan menyertakan detail terstruktur. Pada setiap model, penolakan juga menyertakan objek stop_details yang mengidentifikasi kategori kebijakan di balik penolakan tersebut. Lihat Penolakan dan fallback untuk bentuk respons lengkap.
• Coba ulang pada model yang berbeda. Mengirim ulang permintaan yang ditolak ke model yang sama biasanya menghasilkan penolakan lagi. Alih-alih hanya mereset konteks, coba ulang pada model cadangan dengan fallback sisi server, middleware SDK, atau percobaan ulang manual, dan tukarkan kredit fallback ketika Anda membangun percobaan ulang sendiri.
• Periksa hasil batch untuk penolakan. Permintaan yang ditolak dalam Message Batch dikembalikan sebagai hasil yang berhasil dengan stop_reason: "refusal", bukan sebagai hasil yang error.
• Pusatkan penanganan pada stop_reason. API terus mengonsolidasikan penanganan penolakan di sekitar stop_reason: "refusal", jadi lakukan percabangan berdasarkan stop reason alih-alih perilaku spesifik model.

Langkah selanjutnya