스트리밍 거부 처리하기

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",
    ) 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 검사를 포함하세요
• 자동 재설정: 거부가 감지되면 자동으로 컨텍스트를 재설정하도록 구현하세요
• 다른 모델로 폴백: 거부된 요청이 사용자에게 거부로 표시되는 대신 다른 Claude 모델에서 재시도되도록 서버 측 폴백 또는 SDK 미들웨어를 구성하세요
• 수동 재시도 시 폴백 크레딧 사용: 재시도를 직접 구축하는 경우, 재시도가 프롬프트 캐시 비용을 두 번 지불하지 않도록 거부의 폴백 크레딧 토큰을 전달하세요
• 맞춤 메시지 제공: 거부 발생 시 더 나은 UX를 위해 사용자 친화적인 메시지를 만드세요
• 거부 패턴 추적: 거부 빈도를 모니터링하여 프롬프트의 잠재적 문제를 식별하세요

마이그레이션 참고 사항

이 기능이 처음 출시되었을 때 거부 처리를 구축했거나 기존 통합에 추가하는 경우, 다음 사항을 확인하세요:

• 거부는 오류가 아니라 응답입니다. 거부는 stop_reason: "refusal"이 포함된 성공적인 HTTP 200 응답으로 도착하므로, 오류율만을 기반으로 구축된 모니터링에서는 드러나지 않습니다. 거부를 별도의 신호로 추적하세요.
• 거부에는 구조화된 세부 정보가 포함됩니다. 모든 모델에서 거부에는 거절의 원인이 된 정책 카테고리를 식별하는 stop_details 객체도 포함됩니다. 전체 응답 형태는 거부와 폴백을 참조하세요.
• 다른 모델에서 재시도하세요. 거부된 요청을 같은 모델에 다시 보내면 대개 또 다른 거부가 발생합니다. 컨텍스트만 재설정하는 대신, 서버 측 폴백, SDK 미들웨어 또는 수동 재시도를 사용하여 폴백 모델에서 재시도하고, 재시도를 직접 구축하는 경우 폴백 크레딧을 사용하세요.
• 배치 결과에서 거부를 확인하세요. Message Batch에서 거부된 요청은 오류 결과가 아니라 stop_reason: "refusal"이 포함된 성공 결과로 반환됩니다.
• stop_reason을 중심으로 처리를 일원화하세요. API는 계속해서 stop_reason: "refusal"을 중심으로 거부 처리를 통합하고 있으므로, 모델별 동작이 아닌 중단 사유를 기준으로 분기하세요.

다음 단계