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

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



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

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

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



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