處理串流拒絕

從 Claude 4 模型開始，當串流分類器介入處理潛在的政策違規時，Claude API 的串流回應會回傳 stop_reason: "refusal"。此安全功能有助於在即時串流期間維持內容合規性。



API 回應格式

當串流分類器偵測到違反 Anthropic 政策的內容時，API 會回傳以下回應：

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

在事件串流中，stop_details 會與 stop_reason 一起出現在 message_delta 事件上。



拒絕後重設上下文

當您收到 stop_reason: refusal 時，您必須在繼續之前重設對話上下文。您可以移除或改寫觸發拒絕的回合，或完全清除對話歷史記錄。嘗試在不重設的情況下繼續將導致持續的拒絕。



實作指南

以下是如何在您的應用程式中偵測和處理串流拒絕：

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:
            # 檢查訊息 delta 中是否有拒絕
            if event.type == "message_delta":
                if event.delta.stop_reason == "refusal":
                    reset_conversation()
                    break
except Exception as e:
    print(f"Error: {e}")



目前的拒絕類型

API 目前以三種不同的方式處理拒絕：



最佳實務

• 監控拒絕： 在您的錯誤處理中包含 stop_reason: refusal 檢查
• 自動重設： 在偵測到拒絕時實作自動上下文重設
• 備援至另一個模型： 設定伺服器端備援或 SDK 中介軟體，讓被拒絕的請求在另一個 Claude 模型上重試，而不是向使用者顯示拒絕
• 在手動重試時兌換備援額度： 如果您自行建構重試機制，請傳遞拒絕的備援額度權杖，這樣重試就不會重複支付提示快取的成本
• 提供自訂訊息： 在發生拒絕時建立使用者友善的訊息以獲得更好的使用者體驗
• 追蹤拒絕模式： 監控拒絕頻率以識別您的提示可能存在的問題



遷移注意事項

如果您在此功能首次推出時建構了拒絕處理，或者您正在將其新增到現有的整合中，請檢查以下事項：

• 拒絕是回應，而非錯誤。 拒絕會以成功的 HTTP 200 回應形式出現，並帶有 stop_reason: "refusal"，因此僅基於錯誤率建構的監控無法發現它。請將拒絕作為獨立的訊號進行追蹤。
• 拒絕包含結構化的詳細資訊。 在每個模型上，拒絕還包含一個 stop_details 物件，用於識別拒絕背後的政策類別。請參閱拒絕與備援以了解完整的回應結構。
• 在不同的模型上重試。 將被拒絕的請求重新發送到同一個模型通常會導致另一次拒絕。與其只重設上下文，不如透過伺服器端備援、SDK 中介軟體或手動重試在備援模型上重試，並在您自行建構重試機制時兌換備援額度。
• 檢查批次結果中的拒絕。 Message Batch 中被拒絕的請求會以帶有 stop_reason: "refusal" 的成功結果回傳，而不是錯誤結果。
• 將處理集中在 stop_reason 上。 API 持續將拒絕處理整合到 stop_reason: "refusal" 上，因此請根據停止原因進行分支處理，而不是根據特定模型的行為。



後續步驟