处理流式传输拒绝

从 Claude 4 模型开始，当流式传输分类器介入以处理潜在的策略违规时，Claude API 的 "streaming"（流式传输）响应会返回 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-5",
    ) as stream:
        for event in stream:
            # 检查 message 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" 整合拒绝处理，因此请根据停止原因进行分支判断，而不是依赖特定模型的行为。

后续步骤