串流拒絕

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



API 回應格式

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

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello.."
    }
  ],
  "stop_reason": "refusal"
}



拒絕後重設上下文

當您收到 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-4-8",
    ) as stream:
        for event in stream:
            # 檢查訊息差異中是否有拒絕回應
            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"，因此僅基於錯誤率建立的監控機制無法偵測到它。請將拒絕作為獨立的訊號進行追蹤。
• 較新的模型會回傳更多詳細資訊。 在 Claude Fable 5 上，拒絕還會包含一個 stop_details 物件，用於識別拒絕背後的政策類別。完整的回應結構請參閱拒絕與備援。
• 在不同的模型上重試。 將被拒絕的請求重新傳送至同一個模型通常會再次收到拒絕。與其僅重設上下文，不如透過伺服器端備援、SDK 中介軟體或手動重試在備援模型上重試，並在自行建置重試機制時兌換備援額度。
• 檢查批次結果中的拒絕。 在訊息批次中被拒絕的請求會以帶有 stop_reason: "refusal" 的成功結果回傳，而非錯誤結果。
• 以 stop_reason 為中心進行處理。 API 持續將拒絕處理整合至 stop_reason: "refusal"，因此請根據停止原因進行分支處理，而非依據特定模型的行為。



後續步驟