Перейти к основному содержанию
После того как у вас есть рабочее пространство и API-ключ (см. Введение), guardrails — это способ поставить контентную политику перед каждой моделью. Эта страница — канонический справочник по движку guardrails OrcaRouter: что это, как его использовать и как он сочетается с остальной частью шлюза.

1. Что такое движок guardrails

Guardrail — это именованная контентная политика в рамках рабочего пространства — упорядоченный список правил, которые шлюз прогоняет по входу запроса и выходу модели. Вы сохраняете guardrail один раз, привязываете к нему любой API-ключ (или назначаете его default’ом рабочего пространства), и шлюз проверяет каждый вызов до и после вышестоящей модели. Каждое правило решает одну вещь — что искать (тип правила), где искать (стадия: вход запроса или выход модели) и что с этим делать (действие: block, mask или flag). Движок выполняет каждое применимое правило и сворачивает результаты в единое решение. Редактирование guardrail вступает в силу на каждом привязанном к нему ключе уже на следующем вызове. Никакого передеплоя. Никаких изменений кода. Никаких обновлений SDK. Политика живёт в шлюзе, а не в вашем приложении — ваше приложение продолжает вызывать /v1/chat/completions ровно так же, как раньше. Движок детерминирован и не имеет зависимостей для встроенных типов правил: чистое сопоставление строк и регулярных выражений без сетевых вызовов, безопасное для выполнения на горячем пути ретрансляции. Продвинутые правила (внешние вендоры, LLM judge, контекстная заземлённость) выходят наружу и диспетчеризуются конкурентно, так что медленная проверка никогда не сериализуется за другой. Guardrails ограничены рабочим пространством — каждый участник видит guardrails своего пространства; ничего не пересекает границы тенантов.

2. Быстрый старт — проверьте свой первый запрос за 5 шагов

1

Создайте guardrail

В консоли перейдите в /console/guardrails и нажмите New guardrail. Назовите его pii-shield. Добавьте одно правило:
  • Тип: PII detection
  • Стадия: Input (request)
  • Действие: Mask — отредактировать совпадение
  • Сущности: email, phone, ssn
Сохраните.
2

Протестируйте в песочнице

Откройте вкладку Test внутри редактора, вставьте “email me at jane@acme.com, выберите стадию input и запустите. Песочница покажет вердикт и отрендеренный текст — email me at [EMAIL] — не отправляя ничего вышестоящей системе.
3

Привяжите ключ

Перейдите в /console/token, создайте или отредактируйте API-ключ и выберите pii-shield из выпадающего списка Guardrail. Привязка живёт на ключе в шлюзе.
4

Отправьте запрос

Используя этот ключ, вызовите OrcaRouter ровно как раньше:
curl https://api.orcarouter.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-orca-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "Reply to jane@acme.com please"}
    ]
  }'
Шлюз маскирует email в [EMAIL] перед пересылкой. Вышестоящая модель никогда не видит адрес.
5

Ужесточите политику

Вернитесь в /console/guardrails, отредактируйте pii-shield — измените действие для ssn на Block через переопределение по сущности. Сохраните. Уже следующий запрос, содержащий SSN, отклоняется с HTTP 400 guardrail_blocked. Никаких изменений в приложении.
В этом и заключается ключевая ценность.

3. Концепции: guardrails, правила, стадии, действия

КонцепцияОпределение
GuardrailИменованная политика в рамках рабочего пространства. Идентификатор: name (≤ 64 символов). Имеет enabled, is_default и JSON-блоб rules.
ПравилоОдна проверка внутри политики: type, stage, action плюс поля, специфичные для типа. Правила выполняются по порядку.
Стадияinput (запрос), output (ответ модели) или both.
Действиеblock (отклонить вызов), mask (отредактировать совпадение) или flag (только лог — наблюдать, не меняя трафик).

Область видимости и default рабочего пространства

Guardrails ограничены точно так же, как API-ключи: общие в рамках рабочего пространства, когда оно активно, и по пользователю в противном случае. Разрешение для любого запроса:
  1. Привязка ключа — если у ключа есть явный guardrail_id, применяется этот guardrail (когда он существует и включён). Явная привязка никогда не откатывается молча; её отключение — это выключатель.
  2. Default рабочего пространства — если у ключа нет привязки, применяется включённый guardrail с is_default рабочего пространства.
  3. Ни то, ни другое — нет применения. Запрос побайтно идентичен рабочему пространству, которое никогда не включало эту функцию.
В рабочем пространстве не более одного guardrail может быть default’ом. Продвижение нового default’а понижает старый в той же транзакции.
Fail-open по дизайну. Если разрешение guardrail упирается в переходную ошибку (например, сбой БД), шлюз деградирует до отсутствия применения, а не кладёт трафик. Безопасность деградирует; доступность сохраняется.

Как выглядит блокировка

Заблокированный запрос возвращает 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.
Guardrail смешивает любое количество правил любых типов. Продвинутые правила (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>].
До 25 пользовательских сущностей на правило (каждая — это regex-скан по всему тексту, так что лимит держит горячий путь линейным). Скомпилированные паттерны кэшируются между запросами.

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

Одно правило PII может применять разные действия к разным сущностям через entity_actions. Одно правило, которое по умолчанию маскирует emails / phones / IP, но блокирует на credit_card или ssn — вместо трёх перекрывающихся правил:
{
  "type": "pii",
  "stage": "input",
  "action": "mask",
  "entities": ["email", "phone", "ip", "credit_card", "ssn"],
  "entity_actions": {
    "credit_card": "block",
    "ssn": "block"
  }
}
Ключи должны быть включённой сущностью на правиле; значения должны быть 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_opentrue (по умолчанию) → ошибка judge наблюдается, но запрос продолжается; false → трактовать ошибку/таймаут как блокировку.
Вызов judge маршрутизируется через каналы вашего рабочего пространства, так что его токены тарифицируются и атрибутируются как любой другой вызов (как под-строка judge). Движок добавляет к вашей рубрике приложение с JSON-схемой, чтобы модель возвращала разбираемый вывод.

7. Контекстная заземлённость

Правило grounding измеряет ответ ассистента относительно источников, извлечённых на запросе (ваш RAG-контекст), и флагирует или блокирует ответы, которые им не верны. Оно переиспользует шов judge — те же каналы рабочего пространства, та же атрибуция стоимости.
ПолеПо умолчаниюЗначение
grounding_modelвыбор пространстваМодель, к которой раннер разрешает проверку достоверности.
grounding_rubricвстроеннаяПереопределяет рубрику достоверности по умолчанию.
grounding_threshold0.7Нижний порог достоверности, 0.01.0. Ниже него срабатывает действие.
grounding_strictfalseКогда true, «источники не предоставлены» трактуется как блокировка (вместо разрешения по умолчанию).
grounding_max_bytes100000Ограничивает объединённый контекст источников, передаваемый judge.
grounding_timeout_ms3000Ограничивает вызов 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.
Aporia и Averta принимают базовый URL + ключ API; вебхук принимает URL + заголовок аутентификации + секрет HMAC.

Поля правила

ПолеЗначение
connection_idПодключённая интеграция для использования (рекомендуемый путь — вендор + секреты разрешаются из интеграции рабочего пространства во время выполнения).
timeout_msОграничивает единственный вызов вендора. 0 → дефолт.
fail_opentrue (по умолчанию) → ошибка вендора наблюдается, но запрос продолжается; false → трактовать ошибку транспорта / таймаут / неизвестного провайдера как блокировку.
Секреты хранятся зашифрованными и маскируются при чтении. Вызов проверки несёт отмену запроса ретрансляции, так что отменённый запрос не оставляет вызов вендора висеть.

10. Наблюдаемость

Guardrails оставляют хлебные крошки, по которым можно действовать.

Лента совпадений

Каждое сработавшее правило записывает совпадение — тип правила, действие, строку-деталь, стадию и (когда включено) совпавшую подстроку. Вкладка Matches на странице Guardrails — это лента по всему рабочему пространству: список, группировка, фильтрация, переход к одному совпадению, экспорт в CSV и пометка ложных срабатываний.
Захват сырого содержимого включается по выбору. Переключатель Log raw content у guardrail по умолчанию выключен — наиболее консервативная по приватности позиция. Когда он выключен, лента Matches фиксирует, что правило сработало, и его мета-строку-деталь, но не фактическую совпавшую подстроку (например, сам адрес email). Включайте его для каждого guardrail, когда подстрока нужна для разбора; настройка не ретроактивна.

Статистика

Лента Matches питает статистику по каждому guardrail — каждая карточка guardrail показывает 7-дневный спарклайн совпадений и счётчик, а вкладка Matches несёт общий итог по рабочему пространству. Чтобы резать активность по политике, используйте сгруппированное представление и фильтры ленты Matches (по guardrail, типу правила, действию) — именно там живут использование по каждому guardrail, набор действий и частота ложных срабатываний.

История версий и аудит

Каждое создание, обновление и удаление пишет версионированную строку истории в той же транзакции, что и изменение. Откройте History в строке guardrail, чтобы:
  • Увидеть каждую версию с тем, кто её изменил и когда.
  • Сравнить (diff) любые две версии.
  • Откатиться (revert) к более старой версии (записывается как новая версия — история никогда не мутируется).

11. Отношение к остальной части шлюза

ПоверхностьКак сочетается с Guardrails?
ModelsGuardrails модель-агностичны. Одна и та же политика едет поверх 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/metaMemberСловарь движка — типы правил, стадии, действия, PII-сущности, пресеты, категории пресетов.
GET /api/guardrail/my-permissionsMemberРазрешения guardrail вызывающего (для шлюзования UI).
GET /api/guardrail/:idMemberДетали одного guardrail.
GET /api/guardrail/:id/tokensMemberAPI-ключи, привязанные к этому guardrail (с лимитом, с истинным итогом).
POST /api/guardrail/testMemberПесочница — оценить политику по образцу текста на стадии. Ничего не сохраняется.
POST /api/guardrail/Developer+Создать guardrail.
PUT /api/guardrail/Developer+Обновить guardrail (пишет новую версию истории).
DELETE /api/guardrail/:idDeveloper+Удалить guardrail.

История

Метод и путьРольНазначение
GET /api/guardrail/:id/historyMemberИстория версий (новые первыми).
GET /api/guardrail/:id/history/diffMemberСравнить две версии.
GET /api/guardrail/:id/history/:versionMemberОдна историческая версия.
POST /api/guardrail/:id/revertDeveloper+Восстановить более старую версию как новую версию.

Eval и корпусы

Метод и путьРольНазначение
POST /api/guardrail/:id/evalMemberПрогнать eval по корпусу (поставляемое имя или загруженный JSONL).
GET /api/guardrail/:id/eval/runsMemberСписок eval-прогонов для guardrail (с пагинацией).
GET /api/guardrail/eval/runs/:run_idMemberДетали одного eval-прогона.
GET /api/guardrail/eval/corporaMemberСписок корпусов рабочего пространства + поставляемых корпусов.
POST /api/guardrail/eval/corporaDeveloper+Загрузить JSONL-корпус.
GET /api/guardrail/eval/corpora/:idMemberДетали корпуса.
DELETE /api/guardrail/eval/corpora/:idDeveloper+Удалить корпус.

Совпадения

Метод и путьРольНазначение
GET /api/guardrail/matchMemberСписок совпадений (в рамках рабочего пространства).
GET /api/guardrail/match/groupedMemberСовпадения, сгруппированные (например, по правилу или guardrail).
GET /api/guardrail/match/statsMemberСтатистика совпадений (поддерживает ?days= и ?group_by=).
GET /api/guardrail/match/exportMemberЭкспорт совпадений как CSV.
GET /api/guardrail/match/:idMemberДетали одного совпадения.
POST /api/guardrail/match/:id/mark-fpAdminПометить совпадение как ложное срабатывание (rate-limited).
DELETE /api/guardrail/match/:id/mark-fpAdminСнять пометку ложного срабатывания (rate-limited).

Привязка ключа

Установите guardrail_id на API-ключе (через редактор ключей или token API). 0/null означает отсутствие явной привязки — ключ откатывается к default-guardrail рабочего пространства, если он задан.

13. FAQ

Поведение побайтно идентично рабочему пространству, в котором эта функция никогда не была включена. Если ключ не привязан и default рабочего пространства не задан, шлюз не делает никаких модификаций. Ничего не блокируется, не маскируется и не логируется в ленту Matches.
Нет. Блокировка на стадии input срабатывает до тарификации использования; блокировка на стадии output возвращает предварительно списанную квоту после того, как ответ отклонён. В любом случае вызывающий не платит квотой, получает HTTP 400 guardrail_blocked, и запрос помечается skip-retry (повторный прогон того же промпта по другому каналу просто снова заблокировался бы).
Это зависит от действия. Block применяется в обоих случаях: на нестриминговом ответе результат проверяется до того, как он возвращается, а на стриминговом ответе сканер прерывает поток на лету и выдаёт заменяющее сообщение прежде, чем заблокированный контент дойдёт до клиента. Mask на output сейчас применяется только к нестриминговым ответам — на стриминговом ответе исходный чанк проходит без маскирования (потоковое переписывание in-band запланировано как будущее улучшение). Для маскирования output на сегодняшний день используйте нестриминговые запросы или полагайтесь на маскирование на стадии input. Докажите вашу конкретную комбинацию стадии/потока в песочнице и eval-прогоном, прежде чем на неё полагаться.
Mask редактирует совпадение (например, jane@acme.com[EMAIL]) и пропускает запрос дальше с очищенным текстом — вышестоящая модель никогда не видит оригинал. Block отклоняет весь запрос с HTTP 400. Flag ничего не меняет в трафике и лишь записывает совпадение — используйте его, чтобы измерить правило перед применением.
Встроенное правило (keyword / regex / PII / max_chars) не делает вызова модели и ничего не тарифицирует. Правило llm_judge или grounding вызывает модель через каналы вашего рабочего пространства, так что эти токены тарифицируются и атрибутируются как под-строка judge.
Включите Log raw content для guardrail. Когда он выключен (по умолчанию), лента Matches фиксирует, что правило сработало, и его мета-строку-деталь, но не совпавшую подстроку — наиболее консервативная по приватности позиция. Переключатель не ретроактивен: он влияет только на совпадения, записанные после того, как вы его включите.
Да. Откройте History у guardrail, сравните версии и откатитесь (Revert) к той, которую хотите. Revert копирует содержимое той версии вперёд как новую версию — история никогда не мутируется — и изменение вступает в силу на следующем запросе.
По умолчанию продвинутые правила fail open: таймаут или ошибка транспорта записываются как телеметрия, и запрос продолжается. Установите fail_open (external) или judge_fail_open (judge) в false, чтобы fail closed — трактовать ошибку как блокировку — для политик, где пропущенная проверка недопустима.