Обзор guardrails

Guardrail — это слой контентной политики шлюза OrcaRouter. Вы создаёте одну именованную политику в своём рабочем пространстве, привязываете её к API-ключу, и каждый вызов /v1/*, который делает этот ключ, проверяется — прежде чем модель увидит промпт и после того, как модель ответит — без передеплоя и без изменений SDK. Эта страница — хаб раздела Guardrails: что такое guardrail, типы правил, стадии и действия, и как политика привязывается к ключу. Каждое ответвление углубляется в детали. Полный справочник по движку см. в Guardrails.

1. Что ИИ-guardrails делают на шлюзе

Большинство команд обращаются к guardrails, чтобы не пускать чувствительные данные в промпты (PII, секреты), отсекать небезопасный контент (джейлбрейки, намерения prompt-injection) или удовлетворять требование комплаенса. Guardrail — это ответ шлюза: именованная политика в рамках рабочего пространства — упорядоченный список правил, которые шлюз прогоняет по входу запроса и выходу модели. Поскольку привязка живёт на API-ключе в шлюзе — а не в вашем приложении — редактирование guardrail смещает каждый привязанный ключ уже на следующем вызове. Ваш код продолжает вызывать /v1/chat/completions ровно так же, как раньше.

Guardrails — это контентная политика (текст на вход, текст на выход). Сопутствующий Agent Firewall — это политика инструментов: он управляет тем, какие вызовы инструментов может делать агент. Эти два слоя сочетаются; см. Guardrails vs. firewall.

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

Создайте guardrail с именем pii-shield в консоли (/console/guardrails), добавьте единственное правило PII — стадия input, действие mask, сущности email, ssn — и привяжите его к ключу. С этого момента:

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"}
    ]
  }'

Шлюз переписывает промпт в Reply to [EMAIL] please перед пересылкой — вышестоящая модель никогда не видит адрес. Переключите эту сущность ssn на block, и следующий запрос, содержащий SSN, отклоняется с HTTP 400. Никаких изменений в приложении.

Создание — это действие в консоли / management-API в рамках вашей сессии; relay-ключ sk-orca-... нужен только для трафика /v1/*, никогда — для редактирования политики. Создание или изменение guardrail требует роли Developer+.

3. Правила: тип, стадия, действие

Каждое правило отвечает на три вопроса. Движок выполняет все применимые правила и сворачивает их в единое решение.

Тип — что искать

Семь типов правил. Встроенные детерминированы (чистые строки/regex, без сети); продвинутые обращаются к модели или вендору и выполняются конкурентно.

keyword — литеральный denylist, подстрочное совпадение без учёта регистра.
regex — шаблон RE2 (линейное время, без обратных ссылок).
pii — встроенные детекторы сущностей плюс ваши собственные. См. §5.
max_chars — ограничивает число символов на стадии.
external — делегирует подключённому вендору (Aporia, Averta или вашему собственному webhook).
llm_judge — семантическая проверка против модели в вашем рабочем пространстве.
grounding — оценивает достоверность ответа относительно извлечённых источников запроса (RAG).

Стадия — где искать

input (запрос), output (ответ модели) или both. Правила входа выполняются до вышестоящего вызова; правила выхода — после того, как модель ответит. См. стадию input и стадию output.

Действие — что делать

Пять действий доступны в конструкторе правил:

block — отклонить вызов с HTTP 400.
mask — отредактировать совпадение и пропустить очищенный текст.
flag — ничего не менять в трафике; только записать совпадение.
annotate — оставить текст как есть, но внедрить вышестоящей системе примечание о безопасности (например, предупреждение о CVE перед тем, как модель ответит).
spotlight — обернуть совпавший недоверенный текст в разделители и сказать модели обращаться с ним как с данными, а не инструкциями.

См. Действия. Используйте flag, чтобы измерить правило на живом трафике прежде, чем применять его.

4. Как guardrail привязывается и разрешается

Guardrail привязывается к ключу через guardrail_id, или рабочее пространство может пометить один guardrail как свой default. Для любого запроса шлюз разрешает в таком порядке:

Явная привязка — если guardrail_id ключа указывает на guardrail, который существует и включён, применяется именно он. Явная привязка никогда не откатывается: её отключение — это выключатель.
Default рабочего пространства — если у ключа нет привязки, применяется включённый default-guardrail.
Ни то, ни другое — нет применения; запрос побайтно идентичен рабочему пространству, которое никогда не включало эту функцию.

Это отличается от firewall. Отключённая привязанная политика firewall откатывается на default рабочего пространства; отключённый привязанный guardrail переходит в none. Для guardrails выключатель буквален.

Пошаговые руководства: создайте свой первый guardrail, привяжите к ключу, задайте default аккаунта.

5. PII-детекторы

Правило pii поставляется с закрытым набором встроенных детекторов: email, phone, credit_card, ssn, ip, iban, mac_address, jwt, aws_access_key, api_key_openai, bitcoin_address — плюс региональные jp_mynumber, kr_rrn и cn_resident_id. При действии mask каждое совпадение становится типизированным тегом — email рендерится как [EMAIL], SSN — как [SSN]. Вы можете наслоить до 25 пользовательских сущностей на правило (regex с опциональной контрольной суммой Luhn) и направить разные сущности к разным действиям в одном правиле через переопределения по сущности.

Готовая отправная точка — пресет PII Shield — единственное правило pii, mask, стадия both. Маскирование на стадии input переписывает запрос перед моделью (потоковый или нет); маскирование на выходе переписывает ответ только для непотоковых ответов — внутрипотоковое переписывание выхода в планах. См. PII Shield, пользовательские сущности и форматы маскирования.

6. Выбор пресета

New guardrail открывается в шаблоне. Пресеты создаются на стороне сервера, поэтому консоль, песочница и эта документация описывают одно и то же поведение. Селектор группирует их по категориям:

Категория	Примеры пресетов	Ответвление
pii / секреты	PII Shield, блокировщики секретов-учётных данных	блокировка секретов
безопасность	prompt-injection, джейлбрейк, самоповреждение	prompt injection
комплаенс	GDPR, PCI, HIPAA, логгер комплаенса	логгер комплаенса
бренд / стоимость	ненормативная лексика, упоминания конкурентов, лимиты размера	безопасность бренда · стоимость
агент	фильтры URL / shell-инструментов / SQL-в-выводе	агентские
code_security	блокировка секретных файлов, проверка copyleft-лицензий	безопасность кода

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

7. Когда guardrail блокирует

Заблокированный запрос возвращает HTTP 400 с кодом ошибки guardrail_blocked и сообщением, называющим guardrail и сработавшее правило.

Квота не списывается. Блокировка на стадии input срабатывает до учёта; блокировка на стадии output возвращает предварительно списанную квоту.
Запрос помечается как skip-retry — повторный прогон того же промпта просто заблокировался бы снова, поэтому шлюз не тратит ретрай на другой канал.

В потоковом режиме block применяется по принципу best-effort — сканер буферизует небольшой просмотр вперёд и обрывает поток при срабатывании правила, поэтому уже отправленные байты нельзя отозвать. Mask на выходе применяется только к непотоковым ответам — для потокового ответа шлюз вычисляет маску, но не пересылает отредактированный текст; внутрипотоковое переписывание выхода в планах. (Маскирование на стадии input работает как для потоковых, так и для непотоковых.) См. ошибку guardrail_blocked и покрытие потоков.

8. После запуска

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

Каждое сработавшее правило записывает тип, действие, стадию и детали. Группируйте, фильтруйте, экспортируйте и углубляйтесь в отдельное совпадение.

Логирование и приватность

Совпавшая подстрока записывается только при включённом Log raw content — по умолчанию выключено, консервативная в отношении приватности позиция.

Версионирование

Каждое изменение пишет строку истории. Сравните любые две версии и откатитесь как новая версия — история никогда не изменяется.

Тестирование и оценка

Вкладка песочницы Test оценивает текущую политику без вышестоящего вызова, а инструмент оценки прогоняет её против встроенных или пользовательских корпусов.

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

9. Куда дальше

Выберите правильный тип правила

Denylist-ы чувствительных слов · regex-детекторы · стадия input · стадия output · потокобезопасные правила.

Поймите модель

Guardrails vs. firewall · как OrcaRouter инспектирует трафик · режимы применения · область: ключи, политики, рабочие пространства.

Сопоставьте с угрозами

Prompt injection · джейлбрейки · эксфильтрация данных.

Полный справочник по движку

Guardrails — каждое поле, каждый маршрут, правила LLM-judge и grounding, а также внешние вендоры подробно.

​1. Что ИИ-guardrails делают на шлюзе

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

​3. Правила: тип, стадия, действие

​4. Как guardrail привязывается и разрешается

​5. PII-детекторы

​6. Выбор пресета

​7. Когда guardrail блокирует

​8. После запуска

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

Логирование и приватность

Версионирование

Тестирование и оценка

​9. Куда дальше

1. Что ИИ-guardrails делают на шлюзе

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

3. Правила: тип, стадия, действие

4. Как guardrail привязывается и разрешается

5. PII-детекторы

6. Выбор пресета

7. Когда guardrail блокирует

8. После запуска

9. Куда дальше