Перейти к основному содержанию
Встроенный детектор pii покрывает распространённые сущности — email, телефон, кредитная карта, SSN, IBAN, JWT, облачные ключи. Но ваши чувствительные данные — ваши: ID сотрудников, внутренние номера дел, референсы клиентских аккаунтов, формат заказа партнёра. Пользовательская сущность PII позволяет научить то же маскирующее правило распознавать эти формы, так что шлюз редактирует их до того, как модель — или любой нижестоящий инструмент — их вообще увидит. Эта страница покрывает одну вещь, которую пользовательские сущности добавляют к правилу детекции PII: ваши собственные детекторы. Полный движок — каждый тип правила, стадия и маршрут — см. в справочнике Guardrails.
Каждый шаг здесь — действие консоли на хостед-шлюзе (api.orcarouter.ai). Вы создаёте guardrail под собственной сессией; только финальный вызов /v1/* использует relay-ключ sk-orca-.... Создание и редактирование guardrails требует Developer+ в рабочем пространстве.

​
1. Когда вам нужен guardrail с пользовательским детектором PII для LLM

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

Внутренние идентификаторы

ID сотрудников (EMP482915), номера дел, референсы тикетов, внутренние SKU — что угодно с фиксированным префиксом и набором цифр.

Номера аккаунтов и заказов

Референсы клиентских аккаунтов или формат заказа партнёра, который никогда не должен дойти до сторонней модели дословно.

Числа с контрольной суммой

Числа, похожие на карты или членские, проходящие проверку Luhn — добавьте контрольную сумму, чтобы срезать ложные срабатывания на похожих наборах цифр.

Доменно-специфичные коды

Номера полисов, ID претензий, серийники устройств — любой токен, который ваша отрасль трактует как чувствительный, но общие детекторы не знают.
Пользовательская сущность наслаивается поверх встроенного набора внутри одного правила pii. Она детектирует совпадения и применяет действие правила — mask, block или flag — ровно как делает встроенная сущность.

​
2. Анатомия пользовательской сущности

Пользовательская сущность — это три маленьких поля плюс опциональный тег маски. Вы добавляете их в редакторе правила pii под Custom entities:
ПолеОбязательноЧто делает
nameдаСтабильный ID, например employee_id. Строчные ASCII / цифры / _, должно начинаться с буквы. Попадает в ленту Matches и журналы аудита.
patternдаРегулярное выражение Go RE2 (линейное время, без обратных ссылок). Должно компилироваться.
checksumнетluhn валидирует каждое совпадение алгоритмом Луна. Принимаются только "" (нет) или "luhn".
mask_withнетДословная замена при действии mask. По умолчанию [<UPPERCASE_NAME>].
name следует той же конвенции ключей, что и остальной шлюз — строчные, начинается с буквы, без пробелов или дефисов. Выберите ясное (case_number, partner_order_id); это то, что вы увидите в ленте Matches, когда правило сработает.

​
Опциональная контрольная сумма Luhn

Многие идентификаторы «в форме чисел» — платёжные карты, некоторые членские и номера аккаунтов — несут контрольную цифру Luhn (mod-10). Голый regex вроде \d{16} совпадает с любым набором из 16 цифр, включая номера телефонов, временные метки и суммы заказов. Установка checksum: "luhn" заставляет детектор срабатывать только, когда совпавшие цифры также проходят проверку Luhn, так что похожие наборы проскальзывают чисто, и ваша частота ложных срабатываний остаётся низкой. Оставьте его пустым для токенов без контрольной суммы вроде ID сотрудника.

​
Ваш собственный тег маски

При действии mask встроенный email рендерится как [EMAIL]. Пользовательская сущность рендерится как [<UPPERCASE_NAME>] по умолчанию — совпадение employee_id становится [EMPLOYEE_ID]. Установите mask_with, чтобы переопределить это дословно (например, <id> или ***), когда вы хотите конкретный токен замены в тексте, который получает модель. См. Форматы маскирования для правил рендеринга по типам сущностей.

​
3. Один конкретный пример

Предположим, ваши промпты несут ID сотрудников в форме EMP, за которой следуют шесть цифр, и вы хотите замаскировать их на стадии input, чтобы вышестоящая модель никогда не видела реальный ID. Добавьте одну пользовательскую сущность к правилу pii: 
{
  "type": "pii",
  "stage": "input",
  "action": "mask",
  "entities": ["email"],
  "custom_entities": [
    {
      "name": "employee_id",
      "pattern": "EMP\\d{6}",
      "mask_with": "[EMPLOYEE_ID]"
    }
  ]
}
Это правило маскирует и стандартные emails, и ваши ID сотрудников за один проход. Протестируйте его во вкладке Test перед привязкой ключа: 
Forward EMP482915's note to jane@acme.com

Forward [EMPLOYEE_ID]'s note to [EMAIL]
Ничего не отправляется вышестоящей системе и ничего не тарифицируется. Затем привяжите guardrail к ключу (см. Привязка к ключу) и вызовите /v1/chat/completions ровно как раньше — шлюз маскирует запрос перед пересылкой, без изменения SDK.
Маскирование выполняется на обеих стадиях: правило input редактирует запрос до того, как модель его увидит, а правило output редактирует ответ модели — включая стриминговые ответы, где сканер переписывает совпадения in-band. Действия block применяются на обеих стадиях тоже. Чтобы шлюзовать ответы модели, см. Правила стадии output.

​
Пример с контрольной суммой

Для членского номера, похожего на карту, добавьте проверку Luhn, чтобы наборы из 16 цифр, которые не являются валидными номерами, не совпадали: 
{
  "name": "member_card",
  "pattern": "\\d{16}",
  "checksum": "luhn",
  "mask_with": "[MEMBER_CARD]"
}

​
4. Лимиты и валидация

Конструктор правил валидирует каждую пользовательскую сущность при сохранении — плохой детектор никогда не доходит до горячего пути.
Каждая пользовательская сущность — это regex-скан по всему тексту, так что лимит на правило — 25. Лимит держит горячий путь линейным; скомпилированные паттерны кэшируются между запросами. Нужно больше форм? Разбейте их по нескольким правилам pii в том же guardrail.
pattern — это регулярное выражение Go RE2 — линейное время, без обратных ссылок. Валидатор отклоняет паттерн, который не компилируется, с названной нарушающей сущностью в ошибке.
Принимаются только "" (нет проверки) и "luhn". Всё остальное — "sha256", "mod10", даже "LUHN" — отклоняется при сохранении.
name должно начинаться с буквы и использовать только строчные ASCII, цифры и подчёркивания. Две пользовательские сущности в одном правиле не могут делить имя.

​
5. Переопределения действия по сущности

Пользовательская сущность участвует в той же карте entity_actions, что и встроенная сущность. Одно правило pii может маскировать большинство вещей, но блокировать на высокочувствительном пользовательском детекторе — сошлитесь на сущность по её name: 
{
  "type": "pii",
  "stage": "input",
  "action": "mask",
  "entities": ["email", "phone"],
  "custom_entities": [
    { "name": "ssn_internal", "pattern": "ID-\\d{9}", "checksum": "luhn" }
  ],
  "entity_actions": {
    "ssn_internal": "block"
  }
}
Ключи в entity_actions должны ссылаться на встроенную сущность, включённую на правиле, или на name пользовательской сущности; значения должны быть block, mask, flag или annotate. Валидатор отклоняет всё остальное.

​
6. Куда двигаться дальше

PII Shield

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

Форматы маскирования

Как каждая сущность рендерится при действии mask и как mask_with это переопределяет.

Regex-детекторы

Когда простое правило regex подходит лучше, чем типизированная сущность PII.

Настройка ложных срабатываний

Используйте ленту Matches и контрольную сумму, чтобы настроить точность.
Прочтите справочник Guardrails для полного правила PII — каждое поле, eval-харнесс и полный API — или Создайте свой первый guardrail, чтобы пройти сквозной цикл с нуля.