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

Настройка Inference hooks

Copy page



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

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

Прежде чем начать

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

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

Настройка Inference hooks

Существует три состояния принудительного применения: выключено (Enforce verdicts выключен: ваш сервер безопасности ИИ никогда не вызывается, и подсказки не проверяются), теневое (Enforce verdicts включён, а Mode установлен в Shadow mode: ваш сервер безопасности ИИ получает подсказки и возвращает вердикты, но ничего не блокируется) и принудительное (Enforce verdicts включён, а Mode установлен в Allow the request или Block the request: отклонение блокирует запрос). Следующие шаги переводят новую конфигурацию из состояния «выключено» в состояние «принудительное».

1. 1

   Разрешите Inference hooks для вашей организации

   Перейдите в claude.ai > Organization settings > Data and privacy и найдите раздел Inference hooks. Включите Allow for your organization.

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

2. 2

   Откройте страницу настроек Inference hooks

   Оставаясь в разделе Data and privacy, откройте раздел Inference hooks, чтобы перейти на страницу настроек Inference hooks. Она находится внутри Data and privacy, а не как отдельный пункт в навигации настроек, поэтому её навигационная цепочка выглядит как Data and privacy / Inference hooks. Пока вы не сохраните эндпоинт, страница предупреждает, что подсказки ещё не проверяются, а Enforce verdicts остаётся выключенным со значком Requires endpoint.

3. 3

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

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

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

4. 4

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

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

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

5. 5

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

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

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

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

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

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

6. 6

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

   В разделе Failure handling установите Mode, чтобы выбрать, что происходит, пока сервер безопасности ИИ недоступен или вердикты не приходят вовремя:

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

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

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

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

7. 7

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

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

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

8. 8

   Включите Enforce verdicts

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

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

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

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

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

Чтобы использовать теневой режим, установите Mode в Shadow mode в разделе Failure handling, затем включите Enforce verdicts, чтобы подсказки поступали на ваш сервер безопасности ИИ. Пока он активен, на странице настроек отображается значок Shadow mode — not blocking. Чтобы выйти из теневого режима, верните Mode в Allow the request или Block the request; вердикты снова применяются принудительно, как только принудительное применение включено.

Исключения

В разделе Exclusions выберите роли, участники которых не охватываются Inference hooks: их подсказки никогда не отправляются на ваш сервер безопасности ИИ. Исключить можно только пользовательские роли, созданные вашей организацией; встроенные роли не предлагаются. Выберите их в селекторе ролей, заполнитель которого гласит Select roles to exclude, и управляйте тем, кто обладает каждой ролью, на странице администрирования ролей (Manage roles); изменение исключений требует разрешения на управление идентификацией. По умолчанию список пуст, и если ни одна роль не исключена, проверяется каждый контролируемый запрос.

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

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

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

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

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

• Endpoint status: Healthy, Tripped, Not enforcing или Not configured до сохранения эндпоинта.
• Failures per minute: сбои вебхука за последние две минуты, усредненные.
• Block rate: доля запретов среди вердиктов вашего сервера безопасности ИИ; отображается, пока процент поэтапного развертывания ниже 100.
• Circuit breaker tripped: когда размыкатель сработал в последний раз, если это происходило.
• Recent errors: каждая запись показывает, когда произошел сбой, тип ошибки и категорию. Категория — webhook_error для проблемы с вашим эндпоинтом или подключением к нему либо relay_error для сбоя внутри систем Anthropic. Записи никогда не содержат содержимое запроса или URL вашего эндпоинта. Список хранит 10 последних сбоев и очищается через час после последнего из них.

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

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

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

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

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

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

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

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

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

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

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

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

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

Действия Inference hooks записываются в Activity Feed вашей организации: изменения конфигурации, запреты, срабатывания размыкателя и запросы, прошедшие без проверки, поскольку вердикт получить не удалось. Последний тип записывается только пока Enforce verdicts включен, а Mode установлен в Allow the request. Его причина — endpoint_timeout, endpoint_error для любой другой проблемы при обращении к вашему серверу безопасности ИИ или internal_error для сбоя на стороне Anthropic. При Block the request или Shadow mode неудавшиеся запросы по отдельности не записываются. Автоматическое восстановление размыкателя не записывается ни в одном режиме. Пока размыкатель находится в сработавшем состоянии, действия Inference hooks для отдельных запросов не записываются; действие срабатывания является записью ленты об этом периоде. Записи о запретах содержат идентификаторы, позволяющие сопоставить каждый запрет с соответствующей записью в вашей собственной системе.

Выключение Inference hooks

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

• Enforce verdicts выключен, на странице настроек Inference hooks: в течение примерно минуты подсказки из вашей организации перестают отправляться на ваш сервер безопасности ИИ; запросы, уже находящиеся в обработке, завершаются по старой настройке. Страница настроек остаётся доступной, поэтому используйте этот вариант, чтобы приостановить принудительное применение, пока вы работаете над вашим сервером безопасности ИИ.
• Allow for your organization выключен, в настройках Data and privacy: подсказки больше не проверяются, а настройки Inference hooks становятся недоступными, пока вы не включите его снова. Конфигурация вашего эндпоинта, пользовательские заголовки и секрет подписи сохраняются в любом случае; повторное включение принудительно выключает Enforce verdicts и сбрасывает сработавший размыкатель, поэтому снова включите принудительное применение, когда будете готовы.

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