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

Настройка 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	Хост разрешается в частный или внутренний адрес. Используйте публично маршрутизируемый хост.
   Тайм-аут	Сервер безопасности ИИ не вернул вердикт в пределах тайм-аута.
   Ошибка транспорта	Сбой разрешения 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; запросы, уже находящиеся в обработке, завершаются по старой настройке. Выключение прекращает отправку подсказок на ваш сервер безопасности ИИ, также в течение примерно минуты; ваша конфигурация сохраняется.

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

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

Чтобы использовать теневой режим, установите 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); изменение исключений требует разрешения на управление идентификацией. По умолчанию список пуст, и если ни одна роль не исключена, проверяется каждый контролируемый запрос.

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

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

В разделе 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: каждая запись сведена к метке времени, типу ошибки и однострочной причине. Записи никогда не включают содержимое запроса или URL вашего эндпоинта.

Панель работает по принципу «насколько возможно»: если 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 вашей организации: изменения конфигурации, отклонения, срабатывания размыкателя и запросы, прошедшие без проверки в соответствии с вашей настройкой обработки сбоев. Пока размыкатель находится в сработавшем состоянии, активности Inference hooks по отдельным запросам не записываются; активность срабатывания является записью потока об этом периоде. Записи об отклонениях содержат идентификаторы, позволяющие сопоставить каждое отклонение с соответствующей записью в вашей собственной системе.

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

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

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

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