Обработка отказов при потоковой передаче

Начиная с моделей Claude 4, потоковые ответы от API Claude возвращают stop_reason: "refusal", когда потоковые классификаторы вмешиваются для обработки потенциальных нарушений политики. Эта функция безопасности помогает поддерживать соответствие контента требованиям во время «streaming» (потоковой передачи) в реальном времени.

Формат ответа 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 приходит в событии message_delta вместе с stop_reason.

Сброс контекста после отказа

Когда вы получаете 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 вместо показа отказа пользователю
• Используйте резервный кредит при ручных повторах: если вы реализуете повтор самостоятельно, передавайте токен резервного кредита из отказа, чтобы при повторе не оплачивать стоимость кэша подсказок дважды
• Предоставляйте собственные сообщения: создавайте понятные пользователю сообщения для улучшения UX при возникновении отказов
• Отслеживайте закономерности отказов: следите за частотой отказов, чтобы выявлять потенциальные проблемы с вашими подсказками

Примечания по миграции

Если вы реализовали обработку отказов, когда эта функция только появилась, или добавляете её в существующую интеграцию, проверьте следующее:

• Отказы — это ответы, а не ошибки. Отказ приходит как успешный ответ HTTP 200 с stop_reason: "refusal", поэтому мониторинг, построенный только на частоте ошибок, его не выявит. Отслеживайте отказы как отдельный сигнал.
• Отказы содержат структурированные сведения. На каждой модели отказ также включает объект stop_details, который указывает категорию политики, ставшую причиной отклонения. Полную структуру ответа см. в разделе Отказы и резервные варианты.
• Повторяйте на другой модели. Повторная отправка отклонённого запроса той же модели обычно приводит к очередному отказу. Вместо того чтобы только сбрасывать контекст, повторите запрос на резервной модели с помощью резервного варианта на стороне сервера, промежуточного ПО SDK или ручного повтора и используйте резервный кредит, если реализуете повтор самостоятельно.
• Проверяйте результаты пакетов на наличие отказов. Отклонённый запрос в пакете сообщений (Message Batch) возвращается как успешный результат с stop_reason: "refusal", а не как результат с ошибкой.
• Централизуйте обработку на основе stop_reason. API продолжает консолидировать обработку отказов вокруг stop_reason: "refusal", поэтому выполняйте ветвление по причине остановки, а не по поведению, специфичному для модели.

Следующие шаги