处理流式传输拒绝

从 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:
            # 检查消息增量中的拒绝情况
            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" 整合拒绝处理，因此请根据停止原因而不是特定于模型的行为进行分支处理。



后续步骤