1. Что такое движок guardrails
Guardrail — это именованная контентная политика в рамках рабочего пространства — упорядоченный список правил, которые шлюз прогоняет по входу запроса и выходу модели. Вы сохраняете guardrail один раз, привязываете к нему любой API-ключ (или назначаете его default’ом рабочего пространства), и шлюз проверяет каждый вызов до и после вышестоящей модели. Каждое правило решает одну вещь — что искать (тип правила), где искать (стадия: вход запроса или выход модели) и что с этим делать (действие: block, mask или flag). Движок выполняет каждое применимое правило и сворачивает результаты в единое решение. Редактирование guardrail вступает в силу на каждом привязанном к нему ключе уже на следующем вызове. Никакого передеплоя. Никаких изменений кода. Никаких обновлений SDK. Политика живёт в шлюзе, а не в вашем приложении — ваше приложение продолжает вызывать/v1/chat/completions ровно так же, как раньше.
Движок детерминирован и не имеет зависимостей для встроенных типов
правил: чистое сопоставление строк и регулярных выражений без сетевых
вызовов, безопасное для выполнения на горячем пути ретрансляции.
Продвинутые правила (внешние вендоры, LLM judge, контекстная
заземлённость) выходят наружу и диспетчеризуются конкурентно, так что
медленная проверка никогда не сериализуется за другой.
Guardrails ограничены рабочим пространством — каждый участник видит
guardrails своего пространства; ничего не пересекает границы тенантов.
2. Быстрый старт — проверьте свой первый запрос за 5 шагов
Создайте guardrail
/console/guardrails и нажмите New
guardrail. Назовите его pii-shield. Добавьте одно правило:- Тип: PII detection
- Стадия: Input (request)
- Действие: Mask — отредактировать совпадение
- Сущности:
email,phone,ssn
Протестируйте в песочнице
input и запустите. Песочница
покажет вердикт и отрендеренный текст — email me at [EMAIL] — не
отправляя ничего вышестоящей системе.Привяжите ключ
/console/token, создайте или отредактируйте API-ключ
и выберите pii-shield из выпадающего списка Guardrail.
Привязка живёт на ключе в шлюзе.Отправьте запрос
[EMAIL] перед пересылкой. Вышестоящая
модель никогда не видит адрес.3. Концепции: guardrails, правила, стадии, действия
| Концепция | Определение |
|---|---|
| Guardrail | Именованная политика в рамках рабочего пространства. Идентификатор: name (≤ 64 символов). Имеет enabled, is_default и JSON-блоб rules. |
| Правило | Одна проверка внутри политики: type, stage, action плюс поля, специфичные для типа. Правила выполняются по порядку. |
| Стадия | input (запрос), output (ответ модели) или both. |
| Действие | block (отклонить вызов), mask (отредактировать совпадение) или flag (только лог — наблюдать, не меняя трафик). |
Область видимости и default рабочего пространства
Guardrails ограничены точно так же, как API-ключи: общие в рамках рабочего пространства, когда оно активно, и по пользователю в противном случае. Разрешение для любого запроса:- Привязка ключа — если у ключа есть явный
guardrail_id, применяется этот guardrail (когда он существует и включён). Явная привязка никогда не откатывается молча; её отключение — это выключатель. - Default рабочего пространства — если у ключа нет привязки,
применяется включённый guardrail с
is_defaultрабочего пространства. - Ни то, ни другое — нет применения. Запрос побайтно идентичен рабочему пространству, которое никогда не включало эту функцию.
Как выглядит блокировка
Заблокированный запрос возвращает HTTP 400 с кодом ошибкиguardrail_blocked и сообщением, называющим guardrail и сработавшее
правило. Заблокированный запрос не стоит вам квоты — блокировка на
стадии input срабатывает до тарификации, а блокировка на стадии output
возвращает предварительно списанную квоту — и он помечается
skip-retry (повторный прогон того же промпта просто снова
заблокируется).
4. Типы правил
Правила делятся на две группы: встроенные (детерминированные, без сети) и продвинутые (выходят к модели или вендору).| Тип | Группа | Что делает |
|---|---|---|
Keyword denylist (keyword) | Встроенное | Сопоставляет любой из списка литеральных терминов — без учёта регистра, по вхождению подстроки (поэтому class также совпадает с classic). |
Regular expression (regex) | Встроенное | Сопоставляет паттерн RE2 (линейное время, без обратных ссылок). |
PII detection (pii) | Встроенное | Детектирует встроенные типы сущностей (и ваши собственные). См. §5. |
Maximum length (max_chars) | Встроенное | Ограничивает число символов текста на стадии. |
External vendor (external) | Продвинутое | Делегирует проверку подключённому вендору (Aporia, Averta, BYO-webhook, …). См. §9. |
LLM judge (llm_judge) | Продвинутое | Выполняет семантическую проверку моделью в вашем рабочем пространстве. См. §6. |
Contextual grounding (grounding) | Продвинутое | Оценивает достоверность ответа относительно источников, извлечённых на запросе (RAG). См. §7. |
external, llm_judge, grounding) диспетчеризуются
конкурентно, так что одна медленная проверка не сериализуется за
другой.
5. PII detection в деталях
Правилоpii детектирует чувствительные сущности и применяет действие
правила к каждому совпадению. Набор встроенных детекторов закрыт и
разделяется движком, валидатором и конструктором правил:
email, phone, credit_card, ssn, ip, iban, mac_address,
api_key_openai, aws_access_key, jwt, bitcoin_address.
При действии mask каждое совпадение заменяется типизированным тегом
— email становится [EMAIL], SSN становится [SSN] и так далее.
Пользовательские сущности
Наслаивайте собственные детекторы поверх встроенного набора. Пользовательская сущность — это:name— строчные ASCII / цифры / подчёркивание, должно начинаться с буквы (например,employee_id). Попадает в журналы аудита и телеметрию без кавычек.pattern— регулярное выражение Go RE2 (линейное время, без обратных ссылок).checksum— опционально;luhnвалидирует совпадение алгоритмом Луна (например, для номеров, похожих на карты).mask_with— опциональная дословная замена; по умолчанию[<UPPERCASE_NAME>].
Переопределения действия по сущности
Одно правило PII может применять разные действия к разным сущностям черезentity_actions. Одно правило, которое по умолчанию маскирует
emails / phones / IP, но блокирует на credit_card или ssn —
вместо трёх перекрывающихся правил:
block / mask / flag. Валидатор отклоняет всё остальное.
6. LLM judge
Правилоllm_judge выполняет семантическую проверку моделью, которую
ваше рабочее пространство уже может вызывать. Используйте его для
нечётких политик, которые не ловит ни один regex — токсичность,
харассмент, оффтопик, намерение prompt-инъекции.
| Поле | Значение |
|---|---|
judge_model | Модель или алиас маршрутизатора для оценки (например, gpt-4o-mini, orcarouter/cheap). Разрешается по каналам вашего рабочего пространства. |
judge_rubric | Системный промпт, описывающий, что флагировать. |
judge_format | Одно из yes_no, score или category (обязательно; в консоли по умолчанию выбран yes_no). |
judge_threshold | Для score: блокировать/флагировать, когда оценка на уровне этого значения или выше. |
judge_categories | Для category: список запрещённых. |
judge_timeout_ms | Ограничивает вызов judge. 0 → дефолт движка. |
judge_fail_open | true (по умолчанию) → ошибка judge наблюдается, но запрос продолжается; false → трактовать ошибку/таймаут как блокировку. |
7. Контекстная заземлённость
Правилоgrounding измеряет ответ ассистента относительно
источников, извлечённых на запросе (ваш RAG-контекст), и флагирует
или блокирует ответы, которые им не верны. Оно переиспользует шов
judge — те же каналы рабочего пространства, та же атрибуция стоимости.
| Поле | По умолчанию | Значение |
|---|---|---|
grounding_model | выбор пространства | Модель, к которой раннер разрешает проверку достоверности. |
grounding_rubric | встроенная | Переопределяет рубрику достоверности по умолчанию. |
grounding_threshold | 0.7 | Нижний порог достоверности, 0.0–1.0. Ниже него срабатывает действие. |
grounding_strict | false | Когда true, «источники не предоставлены» трактуется как блокировка (вместо разрешения по умолчанию). |
grounding_max_bytes | 100000 | Ограничивает объединённый контекст источников, передаваемый judge. |
grounding_timeout_ms | 3000 | Ограничивает вызов judge. |
8. Шаблоны, песочница и eval-харнесс
Библиотека шаблонов
Split-кнопка New guardrail открывается прямо в шаблон, а полная библиотека — в одном клике. Пресеты создаются на стороне сервера, так что консоль, песочница и эта документация описывают одно и то же поведение. Категории включают:- PII (
pii) — PII Shield, PII Blocker (strict), Contact-Info Redactor, редактор PII в ответе. - Secrets (
secrets) — блокировщики учётных данных AWS / OpenAI / GitHub, приватные ключи и облачные токены, криптокошельки, секреты в выводе. - Compliance (
compliance) — GDPR (EU PII), PCI (полная блокировка карт), HIPAA (PHI), финансовые данные, логгер соответствия, принудительное правовое уведомление. - Brand (
brand) — ненормативная лексика (block / mask / многоязычно), упоминания конкурентов, ключевые слова детской безопасности. - Safety (
safety) — prompt-инъекции, jailbreak, утечка системного промпта, self-harm. - Cost (
cost) — лимиты размера промпта/ответа и лимиты токенов. - Agent (
agent) — фильтры URL, markdown-изображений, shell-вызовов инструментов и SQL-инъекций в выводе.
Тестовая песочница
У каждого редактора есть вкладка Test. Вставьте образец, выберите стадию и прогоните текущую политику локально — без вышестоящего вызова, без квоты. Песочница возвращает вердикт и (для правил mask) отрендеренный текст, так что вы можете доказать, что правило делает то, что вы ожидаете, прежде чем привязывать ключ.Eval / red-team харнесс
Вкладка Eval прогоняет guardrail по корпусу входов и сообщает, как он отработал — полезно для настройки рубрики judge или доказательства, что политика ловит известные атаки, прежде чем вы её зашипите.- Поставляемые корпусы идут со шлюзом — состязательные и red-team наборы (промпты вредного поведения, инъекции инструментов, многоязычный red-teaming) плюс безобидные наборы для измерения ложных срабатываний.
- Пользовательские корпусы — загрузите свой JSONL для тестирования против ваших реальных форм трафика.
- Прогоны перечисляются с их оценками; откройте прогон, чтобы инспектировать отказы образец за образцом.
9. Внешние вендоры
Правилоexternal делегирует проверку подключённому вендору.
Подключите вендора один раз в разделе Integrations (CTA в шапке на
странице Guardrails), затем ссылайтесь на подключение из правила.
Поддерживаемые вендоры
| Вендор | Что это такое |
|---|---|
Aporia Guardrails (aporia) | Движок политик на ансамбле SLM для запросов и ответов. |
Averta (averta) | Универсальный эндпоинт SLM-классификатора (POST текста → безопасно / небезопасно + опциональная перезапись). |
BYO Webhook (webhook) | Ваш собственный URL — получает запросы и возвращает вердикты allow / block / mask / flag. |
Поля правила
| Поле | Значение |
|---|---|
connection_id | Подключённая интеграция для использования (рекомендуемый путь — вендор + секреты разрешаются из интеграции рабочего пространства во время выполнения). |
timeout_ms | Ограничивает единственный вызов вендора. 0 → дефолт. |
fail_open | true (по умолчанию) → ошибка вендора наблюдается, но запрос продолжается; false → трактовать ошибку транспорта / таймаут / неизвестного провайдера как блокировку. |
10. Наблюдаемость
Guardrails оставляют хлебные крошки, по которым можно действовать.Лента совпадений
Каждое сработавшее правило записывает совпадение — тип правила, действие, строку-деталь, стадию и (когда включено) совпавшую подстроку. Вкладка Matches на странице Guardrails — это лента по всему рабочему пространству: список, группировка, фильтрация, переход к одному совпадению, экспорт в CSV и пометка ложных срабатываний.Статистика
Лента Matches питает статистику по каждому guardrail — каждая карточка guardrail показывает 7-дневный спарклайн совпадений и счётчик, а вкладка Matches несёт общий итог по рабочему пространству. Чтобы резать активность по политике, используйте сгруппированное представление и фильтры ленты Matches (по guardrail, типу правила, действию) — именно там живут использование по каждому guardrail, набор действий и частота ложных срабатываний.История версий и аудит
Каждое создание, обновление и удаление пишет версионированную строку истории в той же транзакции, что и изменение. Откройте History в строке guardrail, чтобы:- Увидеть каждую версию с тем, кто её изменил и когда.
- Сравнить (diff) любые две версии.
- Откатиться (revert) к более старой версии (записывается как новая версия — история никогда не мутируется).
11. Отношение к остальной части шлюза
| Поверхность | Как сочетается с Guardrails? |
|---|---|
| Models | Guardrails модель-агностичны. Одна и та же политика едет поверх GPT-5, Claude, Gemini — она проверяет текст, а не выбор модели. |
| Routing | Независимы. Маршрутизация решает, какая модель/канал обслуживает запрос; guardrails проверяют тот же текст запроса/ответа независимо от этого и никогда не переопределяют выбор модели. Проверка input выполняется до вызова вышестоящего канала, проверка output — после ответа модели. Правила judge и grounding разрешают собственную модель через каналы вашего рабочего пространства, отдельно от маршрутизации запроса. |
| Prompts | Независимы и взаимодополняющи. Prompts внедряют системное сообщение; guardrails инспектируют и шлюзуют содержимое. Оба могут применяться к одному запросу, и guardrails всегда срабатывают. Важен порядок: правила input проверяют запрос вызывающей стороны до того, как внедряется промпт из реестра (внедрение происходит позже, на этапе маршрутизации), поэтому правила input видят сообщения вызывающей стороны, а не внедрённый системный промпт; правила output в любом случае проверяют ответ модели. |
| API Keys | Ключ привязывается к guardrail через guardrail_id. Привязка живёт на ключе в шлюзе, так что редактирование guardrail сдвигает все привязанные ключи сразу; отсутствие привязки откатывается к default’у рабочего пространства. |
| Лента Matches | Каждое сработавшее правило попадает в ленту Matches рабочего пространства (собственное хранилище, отдельное от лога запросов). Группируйте и фильтруйте её по guardrail, типу правила и действию, чтобы видеть использование, набор действий и частоту ложных срабатываний по каждому guardrail. |
12. API-справочник
Все маршруты ограничены рабочим пространством через заголовокX-Workspace-Id. RBAC применяется последовательно: чтения и тестовая
песочница открыты каждому участнику; записи требуют Developer+ (и
разрешения guardrails:write); изменения production-трафика
(удаление, откат, конфигурация вендора) шлюзуются соответственно.
Guardrails
| Метод и путь | Роль | Назначение |
|---|---|---|
GET /api/guardrail/ | Member | Список guardrails (со счётчиками привязанных ключей). |
GET /api/guardrail/meta | Member | Словарь движка — типы правил, стадии, действия, PII-сущности, пресеты, категории пресетов. |
GET /api/guardrail/my-permissions | Member | Разрешения guardrail вызывающего (для шлюзования UI). |
GET /api/guardrail/:id | Member | Детали одного guardrail. |
GET /api/guardrail/:id/tokens | Member | API-ключи, привязанные к этому guardrail (с лимитом, с истинным итогом). |
POST /api/guardrail/test | Member | Песочница — оценить политику по образцу текста на стадии. Ничего не сохраняется. |
POST /api/guardrail/ | Developer+ | Создать guardrail. |
PUT /api/guardrail/ | Developer+ | Обновить guardrail (пишет новую версию истории). |
DELETE /api/guardrail/:id | Developer+ | Удалить guardrail. |
История
| Метод и путь | Роль | Назначение |
|---|---|---|
GET /api/guardrail/:id/history | Member | История версий (новые первыми). |
GET /api/guardrail/:id/history/diff | Member | Сравнить две версии. |
GET /api/guardrail/:id/history/:version | Member | Одна историческая версия. |
POST /api/guardrail/:id/revert | Developer+ | Восстановить более старую версию как новую версию. |
Eval и корпусы
| Метод и путь | Роль | Назначение |
|---|---|---|
POST /api/guardrail/:id/eval | Member | Прогнать eval по корпусу (поставляемое имя или загруженный JSONL). |
GET /api/guardrail/:id/eval/runs | Member | Список eval-прогонов для guardrail (с пагинацией). |
GET /api/guardrail/eval/runs/:run_id | Member | Детали одного eval-прогона. |
GET /api/guardrail/eval/corpora | Member | Список корпусов рабочего пространства + поставляемых корпусов. |
POST /api/guardrail/eval/corpora | Developer+ | Загрузить JSONL-корпус. |
GET /api/guardrail/eval/corpora/:id | Member | Детали корпуса. |
DELETE /api/guardrail/eval/corpora/:id | Developer+ | Удалить корпус. |
Совпадения
| Метод и путь | Роль | Назначение |
|---|---|---|
GET /api/guardrail/match | Member | Список совпадений (в рамках рабочего пространства). |
GET /api/guardrail/match/grouped | Member | Совпадения, сгруппированные (например, по правилу или guardrail). |
GET /api/guardrail/match/stats | Member | Статистика совпадений (поддерживает ?days= и ?group_by=). |
GET /api/guardrail/match/export | Member | Экспорт совпадений как CSV. |
GET /api/guardrail/match/:id | Member | Детали одного совпадения. |
POST /api/guardrail/match/:id/mark-fp | Admin | Пометить совпадение как ложное срабатывание (rate-limited). |
DELETE /api/guardrail/match/:id/mark-fp | Admin | Снять пометку ложного срабатывания (rate-limited). |
Привязка ключа
Установитеguardrail_id на API-ключе (через редактор ключей или
token API). 0/null означает отсутствие явной привязки — ключ
откатывается к default-guardrail рабочего пространства, если он задан.
13. FAQ
Что если на запросе не разрешается ни один guardrail?
Что если на запросе не разрешается ни один guardrail?
Стоит ли заблокированный запрос квоты?
Стоит ли заблокированный запрос квоты?
guardrail_blocked, и запрос помечается skip-retry (повторный
прогон того же промпта по другому каналу просто снова
заблокировался бы).Применяются ли правила output (ответа) на стриминге?
Применяются ли правила output (ответа) на стриминге?
В чём разница между mask и block?
В чём разница между mask и block?
jane@acme.com →
[EMAIL]) и пропускает запрос дальше с очищенным текстом —
вышестоящая модель никогда не видит оригинал. Block отклоняет
весь запрос с HTTP 400. Flag ничего не меняет в трафике и лишь
записывает совпадение — используйте его, чтобы измерить правило
перед применением.Тарифицируются ли внедрённые токены промпта и токены judge?
Тарифицируются ли внедрённые токены промпта и токены judge?
llm_judge или
grounding вызывает модель через каналы вашего рабочего
пространства, так что эти токены тарифицируются и атрибутируются как
под-строка judge.Как увидеть, что именно совпало в правиле?
Как увидеть, что именно совпало в правиле?
Могу ли я откатить изменение guardrail?
Могу ли я откатить изменение guardrail?
Что происходит, если внешний вендор или judge таймаутит?
Что происходит, если внешний вендор или judge таймаутит?
fail_open (external) или judge_fail_open (judge) в
false, чтобы fail closed — трактовать ошибку как блокировку —
для политик, где пропущенная проверка недопустима.