Menangani penolakan streaming

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



Format respons API

Ketika classifier 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 berkelanjutan.



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",
    ) as stream:
        for event in stream:
            # Periksa penolakan dalam delta pesan
            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 sehingga permintaan yang ditolak dicoba ulang pada model Claude lain alih-alih menampilkan penolakan kepada pengguna
• Tukarkan fallback credit pada percobaan ulang manual: Jika Anda membangun percobaan ulang sendiri, teruskan token fallback credit dari penolakan sehingga 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 dengan prompt Anda



Catatan migrasi

Jika Anda membangun penanganan penolakan ketika 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 lain. Alih-alih hanya mereset konteks, coba ulang pada model fallback dengan fallback sisi server, middleware SDK, atau percobaan ulang manual, dan tukarkan fallback credit 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 pada stop reason alih-alih pada perilaku spesifik model.



Langkah selanjutnya