АдминистрированиеХуки инференса

Настройка хуков инференса

Copy page



Разрешите хуки инференса для вашей организации Claude Enterprise, подключите ваш сервер безопасности ИИ и управляйте принудительным применением вердиктов, обработкой сбоев и развёртыванием.

«Inference hooks» (хуки инференса) отправляют подсказки из вашей организации на выбранный вами «AI security server» (сервер безопасности ИИ) и удерживают каждый запрос до получения вердикта «разрешить» или «отклонить», прежде чем Claude его обработает. На этой странице описано, как включить функцию, подключить ваш сервер и управлять принудительным применением вердиктов. Чтобы узнать, что такое Inference hooks и когда их использовать, см. обзор Inference hooks. Чтобы создать сам сервер безопасности ИИ, см. Разработка интеграции с хуками инференса.

Перед началом работы

Вам потребуется:

• Разрешение organization:manage в claude.ai, которое есть только у ролей Владелец и Основной владелец. У роли Администратор его нет.
• HTTPS-эндпоинт сервера безопасности ИИ, принимающий запросы вердиктов: URL https:// на порту 443, на публично маршрутизируемом хосте, доступный без перенаправлений. Хосты обратных туннелей (ngrok и аналогичные туннельные сервисы) не поддерживаются: сетевая политика Anthropic их блокирует. Не тестируйте через туннель; размещайте сервер на домене, которым вы управляете. Полные требования к размещению, а также сведения о создании сервера и проверке подписанных запросов см. в разделе Разработка интеграции с хуками инференса.

Настройка хуков инференса

Существует три состояния применения:

• Выключено: когда Применять вердикты выключен, к вашему серверу безопасности ИИ никогда не обращаются, и подсказки не проверяются.
• Теневой режим: когда Применять вердикты включён, а для параметра Режим выбрано Теневой режим, ваш сервер безопасности ИИ получает подсказки и возвращает вердикты, но ничего не блокируется.
• Применение: когда Применять вердикты включён, а для параметра Режим выбрано Разрешить запрос или Заблокировать запрос, запрет блокирует запрос.

Следующие шаги переводят новую конфигурацию из выключенного состояния в состояние применения.

1. 1

   Разрешите хуки инференса для вашей организации

   Перейдите в claude.ai > Настройки организации > Данные и конфиденциальность и найдите раздел Хуки инференса. Включите Разрешить для организации.

   Включение этого параметра открывает доступ к странице настроек хуков инференса и всегда принудительно выключает Применять вердикты, поэтому разрешение функции само по себе никогда не запускает проверку: даже конфигурация, в которой ранее было включено принудительное применение, остаётся без проверки, пока вы снова не включите Применять вердикты на последнем шаге.

2. 2

   Откройте страницу настроек «Хуки инференса»

   Оставаясь в разделе Данные и конфиденциальность, откройте раздел Хуки инференса, чтобы перейти на страницу настроек хуков инференса. Она находится в разделе Данные и конфиденциальность, а не представлена отдельным пунктом в навигации настроек, поэтому её навигационная цепочка выглядит как Данные и конфиденциальность / Хуки инференса. Пока вы не сохраните конечную точку, страница предупреждает, что подсказки ещё не проверяются, а Применять вердикты остаётся выключенным со значком Требуется эндпоинт.

3. 3

   Настройте эндпоинт

   Нажмите Настроить, чтобы открыть диалоговое окно Настроить эндпоинт, и введите URL конечной точки: URL https://, который получает запросы на вердикт. Принимаются только URL https://.

   На этом этапе диалоговое окно больше ничего не запрашивает: пользовательские заголовки запросов настраиваются на шаге 5, а обработка сбоев — на шаге 6. Нажмите Далее, чтобы сохранить. После сохранения конечной точки кнопка будет называться Изменить.

4. 4

   Сохраните секрет подписи

   При первом сохранении генерируется ваш секрет подписи вебхуков, который показывается один раз. Скопируйте его и надежно сохраните, прежде чем нажать Далее: секрет нельзя получить позже, его можно только заменить.

   Ваш сервер безопасности ИИ использует этот секрет для проверки подписи каждого получаемого запроса, включая проверку подключения на следующем шаге. Описание процедуры проверки см. в разделе Проверка подписи.

5. 5

   Добавьте заголовки запросов и проверьте подключение

   Нажатие Далее в диалоговом окне секрета подписи снова открывает диалоговое окно конечной точки, теперь с двумя дополнительными элементами управления:

   • Пользовательские заголовки запросов: до 16 статических заголовков, отправляемых с каждым запросом вердикта, чтобы ваш сервер безопасности ИИ мог аутентифицировать вызывающую сторону. Значения заголовков хранятся в зашифрованном виде и больше никогда не отображаются; после сохранения показываются только имена заголовков. Поскольку значения доступны только для записи, для сохранения любого изменения заголовков необходимо заново ввести все значения. Изменение URL эндпоинта удаляет все сохраненные значения заголовков, чтобы ваши учетные данные никогда не отправлялись на новый адрес; введите их заново после изменения URL. Имена заголовков должны состоять из стандартных символов токенов HTTP с - вместо _ и не должны совпадать с зарезервированными именами (заголовками формирования запроса, такими как Content-* и Host, заголовками прокси и cookie, заголовками адреса клиента, такими как X-Forwarded-*, заголовками подписи webhook-* и префиксом X-Anthropic-*). Значения должны состоять из печатаемых символов ASCII.
   • Проверить соединение: Claude отправляет синтетическую тестовую подсказку на URL и с заголовками, которые в данный момент указаны в форме, а не с сохраненными значениями, поэтому перед проверкой заново введите все сохраненные значения заголовков. В случае успеха результат сообщает, вернул ли ваш сервер безопасности ИИ вердикт «разрешить» или «запретить» для тестовой подсказки, что позволяет выявить поведение «запрещать всё» по умолчанию до начала применения. Также отображается время приема-передачи, измеренное Anthropic для этого единственного тестового запроса по новому подключению, включая рукопожатие при подключении.

   Нажмите Сохранить, чтобы сохранить введенные заголовки.

   Распространённые результаты сбоев:

   Результат	Что проверить
   URL отклонен	URL не прошел структурную проверку. Используйте URL https:// на порту 443.
   Частный или внутренний IP	Хост URL является частным или внутренним IP-адресом, адресом IPv6 или localhost. Используйте публично маршрутизируемый хост.
   Тайм-аут	Сервер безопасности ИИ не вернул вердикт в пределах тайм-аута.
   Ошибка транспорта	Сбой разрешения DNS, TLS-рукопожатия или подключения, либо имя хоста разрешается в частный адрес.
   Статус, отличный от 200	Сервер безопасности ИИ ответил статусом, отличным от 200. Вердикты должны возвращаться с HTTP 200; перенаправления не выполняются и считаются сбоями.
   Ответ не удается разобрать	Сервер безопасности ИИ ответил, но тело ответа не является допустимым вердиктом.
   Требуется секрет подписи	У вашей организации нет секрета подписи, поэтому тест был бы отправлен без подписи. Нажмите Сгенерировать секрет в разделе Подписание запросов, затем повторите проверку.

6. 6

   Выберите обработку сбоев и тайм-аут

   В разделе Обработка сбоев задайте Режим, чтобы выбрать, что происходит, пока сервер безопасности ИИ недоступен или вердикты превышают тайм-аут:

   • Заблокировать запрос: остановить инференс, когда ваш сервер безопасности ИИ не может выдать вердикт (отказ с блокировкой, fail closed).
   • Разрешить запрос: позволить запросу перейти к модели без проверки (отказ с пропуском, fail open).

   Третий вариант раскрывающегося меню, Теневой режим, является инструментом поэтапного развёртывания, а не политикой обработки сбоев; см. Теневой режим.

   Затем установите Время ожидания вердикта по промпту (мс): от 1 до 10 000 мс, по умолчанию 5 000 мс. Этот бюджет покрывает весь обмен целиком, и более медленный вердикт считается недоступным сервером, поэтому установите наименьшее значение, которое ваш сервер может надёжно выдерживать.

   Изменения в этом разделе сохраняются по мере их внесения. При первом сохранении значения по умолчанию — Разрешить запрос и 5 000 мс.

7. 7

   Выберите процент развёртывания

   В разделе Развертывание установите Проверено запросов (%), чтобы выполнять проверку для определённого процента запросов, пока вы вводите в строй ваш сервер безопасности ИИ. Значение варьируется от 0 до 100: 100 проверяет всё, а 0 выключает проверку.

   Для каждого запроса выбор делается один раз на весь ход разговора, поэтому один разговор может быть частично проверен на разных ходах. Запросы, не попавшие в выбранный процент, проходят без проверки, даже если обработка сбоев установлена в значение Заблокировать запрос.

8. 8

   Включите «Применять вердикты»

   Чтобы оценить вердикты на реальном трафике, поначалу никого не блокируя, установите Режим в Теневой режим (шаг 6) перед включением принудительного применения; см. Теневой режим.

   Включите Применять вердикты, чтобы работа Claude зависела от вердикта вашего сервера безопасности ИИ для каждой контролируемой подсказки, затем подтвердите действие в диалоговом окне, где повторно указан выбранный вами вариант обработки сбоев. Изменению требуется около минуты, чтобы достичь всех серверов Anthropic; запросы, уже находящиеся в обработке, завершаются со старой настройкой. Выключение прекращает отправку подсказок на ваш сервер безопасности ИИ, также примерно в течение минуты; ваша конфигурация сохраняется.

   Validate tool calls (проверять вызовы инструментов), расположенный под переключателем Применять вердикты, также отправляет вызовы инструментов из каждого ответа Claude на ваш сервер безопасности ИИ и ожидает его вердикта перед их выполнением; см. Кадр вызова инструментов. В новой конфигурации он включен по умолчанию. Он не действует, пока Применять вердикты выключен, а его изменению, как и в случае с переключателем Применять вердикты, требуется около минуты, чтобы дойти до всех серверов Anthropic.

Теневой режим

«Shadow mode» (теневой режим) запускает ваш хук на реальном трафике, ничего не блокируя. Ваш сервер безопасности ИИ получает контролируемые подсказки и возвращает вердикты точно так же, как при применении, но ничего не блокируется: каждый запрос переходит к модели, даже если ваш сервер его запрещает или недоступен, а конечный пользователь ничего не замечает. Используйте его, чтобы настроить свою политику на реальном трафике вашей организации перед началом применения. При включенном Validate tool calls ваш сервер в теневом режиме также получает кадры вызова инструментов, и ни один вызов инструмента не блокируется.

Чтобы использовать теневой режим, установите Режим в Теневой режим в разделе Обработка сбоев, затем включите Применять вердикты, чтобы подсказки поступали на ваш сервер безопасности ИИ. Пока он активен, на странице настроек отображается значок Теневой режим — без блокировки. Чтобы выйти из теневого режима, верните Режим в значение Разрешить запрос или Заблокировать запрос; вердикты снова применяются принудительно, как только принудительное применение включено.

Исключения

В разделе Who is inspected (кто проверяется), когда включено Limit by role (ограничить по ролям), выберите роли, участники которых не охватываются хуками инференса: их подсказки никогда не отправляются на ваш сервер безопасности ИИ. Исключить можно только пользовательские роли, созданные вашей организацией; встроенные роли не предлагаются. Выберите их в селекторе ролей, заполнитель которого гласит Выберите роли для исключения, и управляйте тем, кому назначена каждая роль, на странице администрирования ролей (Управление ролями); для изменения исключений требуется разрешение на управление удостоверениями. По умолчанию список пуст, и если ни одна роль не исключена, проверяется каждый контролируемый запрос, если только для параметра Inspect (проверять) не задано Only selected roles (только выбранные роли).

Исключение применяется к интерактивным сеансам пользователя. Изменения списка исключений записываются в ленту активности вашей организации как изменения разрешений ролей (rbac_role_permission_added и rbac_role_permission_removed).

Проверка только выбранных ролей

Всё в разделе Who is inspected управляется одним переключателем — Limit by role. Когда вы включаете переключатель, для параметра Inspect изначально задано Everyone except excluded roles, а исключённые роли выбираются под ним, как описано выше.

Чтобы сначала опробовать хуки инференса на части вашей организации, включите Limit by role, задайте для параметра Inspect значение Only selected roles и выберите роли в открывшемся диалоговом окне. С этого момента проверяются только участники, для которых задано Пользовательские роли и которым назначена выбранная роль. Участники с любой другой ролью, например Пользователь или Владелец, не проверяются, даже если им назначена выбранная роль. Это относится и к вам, если для вас задано Владелец или Основной владелец. Перед переключением удалите все исключённые роли: организация использует либо исключения, либо выбранные роли, но не то и другое одновременно. После переключения добавляйте или удаляйте роли в селекторе ролей под Inspect. Чтобы вернуться к проверке всех, выключите Limit by role: после подтверждения это удалит все исключённые роли и выключит Only selected roles.

Пока задано Only selected roles:

• Пользовательская роль, у которой Доступ к возможностям имеет значение Все возможности или Все общедоступные, учитывается, только если вы её выберете, как и любая другая роль.
• Если ни одному участнику, для которого задано Пользовательские роли, не назначена выбранная роль, ни один участник не проверяется.
• Запросы, за которыми не стоит ни один участник, не проверяются, например запросы, выполненные с ключами API, и беседы Claude Tag в Slack.

Изменения параметра Inspect и проверяемых ролей записываются в ленту активности вашей организации.

Пользовательское сообщение о заблокированном запросе

В разделе Пользовательское сообщение о заблокированном запросе задайте пользовательский текст длиной до 500 символов, который добавляется к ошибке, которую видит конечный пользователь, когда ваш сервер безопасности ИИ отклоняет запрос (обычно — к кому обратиться или где запросить исключение). Итоговое сообщение состоит из deny_reason вашего сервера безопасности ИИ для конкретного запроса (если присутствует), пустой строки, а затем этого текста. Если пользовательский текст не настроен, встроенное сообщение по умолчанию направляет пользователя к его администраторам; вы также можете полностью отключить добавляемое сообщение, чтобы пользователь видел только deny_reason.

Мониторинг вашего сервера безопасности ИИ

Область состояния эндпоинта на странице настроек хуков инференса показывает:

• Статус эндпоинта: Работает исправно, Сработал, Не применяется или Не настроено до сохранения конечной точки.
• Сбои в минуту: сбои вебхука за последние 2 минуты, усреднённые.
• Доля блокировок: доля запретов среди вердиктов вашего сервера безопасности ИИ; отображается, пока процент поэтапного развертывания ниже 100.
• Сработал предохранитель: когда размыкатель сработал в последний раз, если это происходило.
• Недавние ошибки: в каждой записи указаны время сбоя, тип ошибки и категория. Категория — webhook_error для проблемы с вашим эндпоинтом или подключением к нему либо relay_error для сбоя внутри систем Anthropic. Запись DlpWebhookStatusError может также показывать HTTP-статус, возвращённый вашим сервером безопасности ИИ, и размер тела запроса, отправленного Anthropic, например HTTP 413 · 1.3 MB. Записи никогда не содержат содержимое запроса или URL вашего эндпоинта. Список хранит 10 последних сбоев и очищается через час после последнего из них.

Типы ошибок в разделе Недавние ошибки означают следующее:

В теневом режиме ни одна ошибка не учитывается размыкателем.

Панель работает по принципу «насколько возможно»: если Anthropic не может прочитать счётчики, она показывает ноль сбоев и отсутствие ошибок, а не собственную ошибку, поэтому выглядящая исправной панель сама по себе не доказывает, что ваш сервер безопасности ИИ исправен. Показатель Сбои в минуту учитывает каждый сбой, включая сетевые ошибки и ошибки DNS, которые никогда не приводят к срабатыванию размыкателя, поэтому это значение может быть высоким, пока поле Сработал предохранитель остаётся пустым.

Размыкатель

Продолжительные сбои вебхука, относимые к вашему серверу безопасности ИИ, приводят к срабатыванию «circuit breaker» (размыкателя), который останавливает принудительное применение: ваш сервер больше не вызывается, и ваш выбор в разделе Обработка сбоев применяется к каждому проверяемому запросу. Если выбрано Заблокировать запрос, пользователи вашей организации блокируются до сброса размыкателя. Когда размыкатель срабатывает, администраторы также получают уведомление в центре уведомлений claude.ai.

Каждое срабатывание также записывается в ленту активности вашей организации как действие inference_hooks_circuit_breaker_tripped, поэтому ваша команда безопасности или поставщик могут настроить оповещения о срабатываниях в уже используемых системах мониторинга, например в SIEM, которая принимает эту ленту. Для каждого срабатывания записывается одно действие, а не по одному на каждый затронутый запрос. Для записи требуется, чтобы для вашей организации был включён Compliance API; см. Настройка Compliance API.

Для восстановления исправьте сервер, затем снова включите Применять вердикты, чтобы сбросить размыкатель.

Выключатель также может сброситься самостоятельно. Начиная через 10 минут после срабатывания, Anthropic проверяет, восстановился ли ваш сервер, отправляя ему тестовый запрос в фоновом режиме не чаще примерно одного раза в минуту; пользовательские запросы при этом не задействуются. Если ваш сервер отвечает допустимым вердиктом, «разрешить» или «запретить», выключатель сбрасывается и применение возобновляется. В противном случае выключатель остается в сработавшем состоянии, и проверки продолжаются.

Автоматическое восстановление выполняется только до тех пор, пока ваши настройки хуков инференса не изменялись с момента срабатывания. Если после срабатывания вы измените любую настройку хуков инференса, включая замену секрета подписи, проверки прекращаются, и выключатель больше не сбрасывается самостоятельно; снова включите Применять вердикты, когда ваш сервер будет исправлен. Автоматическое восстановление применяется только к срабатываниям: если вы сами выключите Применять вердикты, применение останется выключенным, пока вы снова его не включите.

Ротация вашего секрета подписи

Нажмите Обновить секрет в разделе Подписание запросов, чтобы заменить секрет подписи. Если у вашей организации еще нет секрета, та же кнопка называется Сгенерировать секрет и создает первый секрет. Замена происходит мгновенно: новый секрет генерируется и показывается один раз, старый секрет больше нельзя получить, и ни один запрос никогда не подписывается обоими секретами, поэтому рассчитывать на период перекрытия нельзя.

Запросы, подписанные предыдущим секретом, могут ещё недолго поступать после ротации; в разделе Проверка подписи описано, как ваш сервер безопасности ИИ должен обрабатывать переключение.

Журнал аудита

Действия хуков инференса записываются в ленту активности вашей организации: изменения конфигурации, запреты, срабатывания размыкателя и запросы, прошедшие без проверки, поскольку вердикт получить не удалось. Последний тип записывается только пока Применять вердикты включен, а Режим установлен в значение Разрешить запрос. Его причина — endpoint_timeout, endpoint_error для любой другой проблемы при обращении к вашему серверу безопасности ИИ или internal_error для сбоя на стороне Anthropic. При значении Заблокировать запрос или Теневой режим неудавшиеся запросы по отдельности не записываются. Автоматическое восстановление размыкателя не записывается ни в одном режиме. Пока размыкатель находится в сработавшем состоянии, действия хуков инференса для отдельных запросов не записываются; действие срабатывания является записью ленты об этом периоде. Записи о запретах содержат идентификаторы, позволяющие сопоставить каждый запрет с соответствующей записью в вашей собственной системе.

Выключение хуков инференса

Существует два уровня выключения:

• Выключение Применять вердикты на странице настроек хуков инференса: примерно в течение минуты подсказки из вашей организации перестают отправляться на ваш сервер безопасности ИИ; запросы, уже находящиеся в обработке, завершаются со старой настройкой. Страница настроек остаётся доступной, поэтому используйте этот вариант, чтобы приостановить применение, пока вы работаете над своим сервером безопасности ИИ.
• Параметр Разрешить для организации выключен, в настройках Данные и конфиденциальность: подсказки больше не проверяются, а настройки хуков инференса становятся недоступными, пока вы не включите его снова. Конфигурация вашего эндпоинта, пользовательские заголовки и секрет подписи сохраняются в любом случае; повторное включение принудительно выключает Применять вердикты и сбрасывает сработавший размыкатель, поэтому снова включите принудительное применение, когда будете готовы.

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