Собственный сервис распознавания¶

Некоторые данные нельзя распознать ни по форме, ни по списку названий. Номер клиента выглядит как любой другой номер, пока кто-нибудь не найдёт его в базе клиентов. Для таких данных защита (уровень безопасности Агента Атом, описанный в разделе Безопасность агентов) может спросить у небольшого веб-сервиса вашей организации, содержит ли текст такие данные. Эта страница — для инженеров, которые создают и поддерживают такой сервис. Детекторам, которые работают по примерам или по списку, всё это не нужно: они работают на платформе. Те, кто подключает сервис к защите, используют раздел Данные вашей организации на странице «Безопасность» — см. Данные вашей организации.

Что отправляет защита¶

Защита вызывает ваш сервис методом POST по адресу, указанному на странице «Безопасность», и передаёт JSON: тексты для проверки и время, которое она готова ждать.

{
  "segments": [
    {"id": "s1", "text": "Contract CN-123456 was signed", "lang": null}
  ],
  "deadline_ms": 1600
}

Каждый элемент segments — один текст. Его id для вас ничего не значит: верните его как segment_id всего, что найдёте в этом тексте.
Тексты — это то, что требуется проверить по правилам организации: части запроса к модели (инструкции агента, переписка, результаты инструментов) или значения аргументов вызова инструмента. Ожидайте, что в них будут персональные данные и секреты.
Больше ничего не передаётся — ни сведений о пользователе, агенте, организации, инструменте или правиле, — кроме токена, описанного ниже.
Один вызов содержит все новые тексты одного действия. Текст длиннее 32 КиБ разрезается по границам строк, и каждый кусок становится сегментом с id, который придумала защита; смещения отсчитываются внутри полученного вами куска.
lang — подсказка: ru для текста, написанного в основном кириллицей, иначе null. Не полагайтесь на неё.
deadline_ms — это 80% от времени ответа, заданного для вашего сервиса, то есть 1600 при значении по умолчанию 2000 мс.

Что отвечает ваш сервис¶

{
  "spans": [
    {"segment_id": "s1", "start": 9, "end": 18, "entity_type": "CONTRACT", "score": 0.95}
  ]
}

start и end считаются в кодовых точках Unicode, как индекс str в Python, причём end не включается. В 😀 CN-123456 номер начинается с позиции 2: эмодзи — это одна кодовая точка, а не две единицы UTF-16 и не четыре байта. Сервис на языке, где строки индексируются иначе, должен пересчитать смещения перед ответом. Защита отбрасывает фрагмент, который выходит за пределы указанного текста, поэтому неверные смещения стоят вам находок, а не ошибок.
entity_type — ваше собственное название того, что вы нашли. Тот, кто подключает сервис, сопоставляет каждое название с видом данных и подтипом на странице «Безопасность»; несопоставленные названия игнорируются. score — уверенность от 0 до 1.
Если ничего не найдено, верните пустой spans — и только если вы действительно проанализировали текст.
Сервис, который не может ответить, так и сообщает: "failed": true и короткое "error". Нехватка времени, нехватка памяти, незагрузившаяся модель — ни в одном из этих случаев нельзя возвращать пустой spans: защита понимает его как «ничего не найдено». spans в неудачном ответе игнорируются. Если всё прошло хорошо, оба поля можно не передавать.
Отвечайте со статусом 200 (принимается любой 2xx), в том числе когда failed равно true, и отвечайте по тому адресу, который вам дали: перенаправления не выполняются.
Отвечайте без сжатия и в пределах 1 МиБ. Защита запрашивает Accept-Encoding: identity и отклоняет ответ с любым другим Content-Encoding, поэтому не ставьте этот эндпоинт за прокси, который сжимает ответы сам.
Неизвестные защите поля игнорируются, так что можно добавлять свои. GET /healthz необязателен; защита его никогда не вызывает.

Не пишите тексты в логи

Тексты могут содержать персональные данные и секреты. Не записывайте их в логи и не храните, если ваши собственные правила этого не разрешают.

Путь содержит версию контракта, /v1/; изменения, при которых любой соответствующий контракту сервис продолжает работать, остаются в этой версии.

Токен¶

Если сервису нужен токен, владелец аккаунта или администратор вводит его на странице «Безопасность». Платформа хранит его в зашифрованном виде, а защита передаёт его при каждом вызове как Authorization: Bearer <token>. Без токена защита вообще не передаёт заголовок Authorization.

Токен привязан к адресу, для которого он сохранён, — к схеме, хосту и порту адреса сервиса, — и защита отправляет его только на этот адрес и ни на какой другой. Если сервис переезжает на другой адрес, токен нужно сохранить заново для нового адреса: до этого защита не вызывает сервис по новому адресу, и каждая проверка, которую она сделала бы, считается неудачным вызовом.

Требовать ли токен — решать вам: сервис, который его требует, отвечает 401 на вызов без действительного токена, и защита считает это неудачным вызовом. Используйте токен из обычных печатных символов; токен, который нельзя передать в HTTP-заголовке, отклоняется ещё до отправки. Новый токен начинает действовать примерно через полминуты, поэтому, чтобы сменить его без перерыва, какое-то время принимайте оба.

Где может работать сервис¶

На облачной платформе Агента Атом адрес должен быть https и публичным. Платформа вызывает его извне вашей сети, поэтому отклоняет обычный http, адреса в частных сетях (например, 10.x, 192.168.x, loopback или link-local) и имена, которые в них разрешаются. Сертификат должен быть действителен для этого имени и выпущен публичным удостоверяющим центром.
В закрытой / on-prem установке можно разрешить внутренние адреса, включая http, чтобы сервис работал рядом с платформой. Если у установки есть собственный удостоверяющий центр, её администратор настраивает платформу так, чтобы она ему доверяла.

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

Нагрузка, скорость и сбои¶

Когда защита обращается к сервису. Только для действий, где правило может использовать то, что найдёт ваш сервис. Для правил, которые создаёт страница «Безопасность», это запросы к модели, когда находки маскируются, вызовы инструментов, когда они блокируются, и то и другое, когда находки только записываются. Запрос к модели каждый раз содержит всю переписку, но защита спрашивает о каждом тексте один раз: ответ используется повторно в течение часа, а неудачный ответ — никогда. Поэтому вызов делается только для действия с новым текстом и содержит только этот текст. Загруженные агенты вызывают сервис параллельно.
Как быстро. Когда находки маскируются или блокируются, запрос ждёт вашего ответа не дольше времени ответа (от 100 до 30000 мс, по умолчанию 2000). Быстрый сервис сохраняет агентов быстрыми. Сервису, который знает, что не успеет, лучше ответить failed: true, чем заставлять защиту ждать.
Когда вызов не удался. Нет ответа вовремя, статус ошибки, перенаправление, сжатый или слишком большой ответ, тело, не соответствующее контракту, и failed: true — всё это считается неудачным вызовом, как и отказ на стороне платформы: адрес, который ей вызывать нельзя, токен, который не сохранён или сохранён для другого адреса. Дальше всё решает выбор в поле Если сервис не отвечает. Не пропускать запрос (значение по умолчанию) останавливает запрос в режиме «Принудительно» с сообщением, что защита не смогла завершить проверку. Пропустить и пометить «не проверено» пропускает запрос дальше и помечает запись как не проверено в разделе Решения. Сервис, который используется только правилами записи, ничего не останавливает; его сбои тоже помечаются как не проверено.

Проверьте сервис перед подключением¶

Перед подключением убедитесь, что сервис соблюдает контракт: принимает пустой segments, считает смещения в кодовых точках (проверьте на тексте, который начинается с эмодзи) и при дедлайне в одну секунду отвечает — или сообщает о сбое — в течение полутора секунд.

Затем подключите сервис на странице «Безопасность». Проверить подключение вызывает его с придуманным примером текста и показывает типы сущностей, которые он возвращает. Проверить на тексте запускает его на вставленном вами тексте; этот текст уходит в ваш сервис, поэтому используйте свои тестовые примеры.

Что передать тому, кто будет подключать сервис¶

Адрес, токен, типы сущностей, которые возвращает ваш сервис, с пояснением, что означает каждый, и время ответа, которое вы можете гарантировать.