处理流式传输拒绝
检测并处理流式传输响应中的拒绝停止原因,并在回退模型上重试被拒绝的请求。
API 支持:用法因产品而异。
- Messages API:流以
stop_reason"refusal"结束,stop_details(category和explanation)随message_delta事件送达。 - Managed Agents:被拒绝的轮次会结束,会话进入空闲状态。如果
stop_details.type或stop_reason.type为"refusal",则应将该轮次视为被拒绝。
从 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 时,必须在继续之前重置对话上下文。您可以删除或改写触发拒绝的那一轮对话,也可以完全清除对话历史。若不重置而尝试继续,将导致持续的拒绝。
实现指南
以下是在您的应用程序中检测和处理流式传输拒绝的方法:
在流中检测拒绝并重置对话需要的逻辑超出了单个 shell 命令所能实现的范围。请使用 Anthropic SDK 运行它。
在流中检测拒绝并重置对话需要的逻辑超出了单个 shell 命令所能实现的范围。请使用 Anthropic SDK 运行它。
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}")
const client = new Anthropic();
let messages: Anthropic.MessageParam[] = [];
function resetConversation() {
// 拒绝后重置对话上下文
messages = [];
console.log("Conversation reset due to refusal");
}
try {
const stream = await client.messages.stream({
messages: [...messages, { role: "user", content: "Hello" }],
model: "claude-opus-5-5",
max_tokens: 1024
});
for await (const event of stream) {
// 检查 message delta 中是否包含拒绝
if (event.type === "message_delta" && event.delta.stop_reason === "refusal") {
resetConversation();
break;
}
}
} catch (error) {
console.error("Error:", error);
}
List<Message> messages = new();
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
Messages = [new UserMessageParam { Content = "Hello" }]
};
try
{
await foreach (var streamEvent in client.Messages.CreateStreaming(parameters))
{
if (
streamEvent.TryPickDelta(out var deltaEvent)
&& deltaEvent.Delta.StopReason == StopReason.Refusal
)
{
ResetConversation();
break;
}
}
}
catch (Exception e)
{
Console.WriteLine($"Error: {e.Message}");
}
void ResetConversation()
{
messages.Clear();
Console.WriteLine("Conversation reset due to refusal");
}
var messages []anthropic.MessageParam
func resetConversation() {
messages = []anthropic.MessageParam{}
fmt.Println("Conversation reset due to refusal")
}
// ...
client := anthropic.NewClient()
stream := client.Messages.NewStreaming(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Hello")),
},
})
streamLoop:
for stream.Next() {
event := stream.Current()
switch eventVariant := event.AsAny().(type) {
case anthropic.MessageDeltaEvent:
if eventVariant.Delta.StopReason == anthropic.StopReasonRefusal {
resetConversation()
break streamLoop
}
}
}
if err := stream.Err(); err != nil {
log.Fatal(err)
}
import com.anthropic.core.http.StreamResponse;
import com.anthropic.models.messages.RawMessageStreamEvent;
import com.anthropic.models.messages.StopReason;
// ...
List<MessageParam> messages = new ArrayList<>();
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024L)
.addUserMessage("Hello")
.build();
try (StreamResponse<RawMessageStreamEvent> stream = client.messages().createStreaming(params)) {
stream.stream().forEach(event -> {
event.messageDelta().ifPresent(deltaEvent -> {
deltaEvent.delta().stopReason().ifPresent(stopReason -> {
if (stopReason.equals(StopReason.REFUSAL)) {
resetConversation();
}
});
});
});
} catch (Exception e) {
System.err.println("Error: " + e.getMessage());
}
}
void resetConversation() {
messages.clear();
IO.println("Conversation reset due to refusal");
}
$client = new Client();
$messages = [];
function resetConversation(&$messages)
{
$messages = [];
echo "Conversation reset due to refusal\n";
}
try {
$stream = $client->messages->createStream(
maxTokens: 1024,
messages: [
['role' => 'user', 'content' => 'Hello']
],
model: 'claude-opus-5-5',
);
foreach ($stream as $event) {
if ($event->type === 'message_delta' && $event->delta->stopReason === 'refusal') {
resetConversation($messages);
break;
}
}
} catch (\Exception $e) {
echo 'Error: ' . $e->getMessage() . "\n";
}
client = Anthropic::Client.new
messages = []
def reset_conversation(messages)
messages.clear
puts "Conversation reset due to refusal"
end
begin
stream = client.messages.stream(
model: :"claude-opus-5-5",
max_tokens: 1024,
messages: [{ role: "user", content: "Hello" }]
)
stream.each do |event|
if event.type == :message_delta && event.delta.stop_reason == :refusal
reset_conversation(messages)
break
end
end
rescue => e
puts "Error: #{e.message}"
end
当前的拒绝类型
API 目前以三种不同的方式处理拒绝:
| 拒绝类型 | 响应格式 | 发生时机 |
|---|---|---|
| 流式传输分类器拒绝 | stop_reason: refusal | 流式传输期间内容违反策略时 |
| API 输入和版权验证 | 400 错误代码 | 输入未通过验证检查时 |
| 模型生成的拒绝 | 标准文本响应 | 模型自身拒绝时 |
最佳实践
- 监控拒绝: 在您的错误处理中加入
stop_reason:refusal检查。 - 自动重置: 在检测到拒绝时实现自动上下文重置。
- 回退到另一个模型: 配置服务器端回退或 SDK 中间件,使被拒绝的请求在另一个 Claude 模型上重试,而不是向用户呈现拒绝。Claude Haiku 5.5 没有服务器端回退,因此请在您的客户端中设置其重试。
- 在手动重试时兑换回退额度: 如果您自行构建重试,请传递拒绝的回退额度令牌,这样重试就不会重复支付提示缓存成本。Claude Haiku 5.5 的拒绝不附带回退额度。
- 提供自定义消息: 在发生拒绝时创建用户友好的消息,以获得更好的用户体验。
- 跟踪拒绝模式: 监控拒绝频率,以识别您的提示中的潜在问题。
迁移说明
如果您在此功能首次发布时就构建了拒绝处理逻辑,或者正在将其添加到现有集成中,请检查以下事项:
- 拒绝是响应,而不是错误。 拒绝以成功的 HTTP 200 响应形式到达,并带有
stop_reason:"refusal",因此仅基于错误率构建的监控无法发现它。请将拒绝作为独立的信号进行跟踪。 - 拒绝包含结构化详细信息。 在所有模型上,拒绝还包含一个
stop_details对象,用于标识拒绝背后的政策类别。有关完整的响应结构,请参阅拒绝是什么样的。 - 在不同的模型上重试。 将被拒绝的请求重新发送到同一模型通常会导致再次被拒绝。与其仅重置上下文,不如通过服务器端回退、SDK 中间件或手动重试在回退模型上重试,并在自行构建重试时兑换回退抵扣。Claude Haiku 5.5 没有服务器端回退,其拒绝也不附带回退抵扣,因此请在您的客户端中为其设置重试。
- 检查批处理结果中的拒绝。 消息批次中被拒绝的请求会作为成功结果返回,并带有
stop_reason:"refusal",而不是作为出错结果返回。 - 围绕
stop_reason集中处理。 API 将继续围绕stop_reason:"refusal"整合拒绝处理,因此请根据停止原因进行分支判断,而不是依赖特定模型的行为。
后续步骤
拒绝与回退
在服务器端或您的客户端中,在另一个 Claude 模型上重试被拒绝的请求。
停止原因与回退
每个 stop_reason 值及其处理方式。
流式传输消息
流式传输响应,并在 message_delta 事件到达时从中读取 stop_reason。
多语言支持
利用 Claude 的跨语言能力为不同语言的用户提供服务。
可用性
流式拒绝可用或处于 beta 阶段,具体取决于API。
API 支持
Messages API
- 可用性:始终开启
- 用法:流以
stop_reason"refusal"结束,stop_details(category和explanation)随message_delta事件送达。
| 状态 | 云平台 |
|---|---|
| 可用 | Claude API, Amazon Bedrock, Amazon Bedrock (bedrock-runtime), Claude Platform on AWS, Claude Models on Google Cloud (Google managed), Microsoft Foundry |
Managed Agents
- 可用性:始终开启
- 用法:被拒绝的轮次会结束,会话进入空闲状态。如果
session.status_idle事件上的stop_details.type或stop_reason.type为"refusal",则应将该轮次视为被拒绝。在被拒绝的轮次中,stop_reason.type可能为"end_turn"。在其他任何轮次中,stop_details均为null,在被拒绝的轮次中也可能为null。
| 状态 | 云平台 |
|---|---|
| Beta | Claude API, Claude Platform on AWS |
文档内容持续同步更新