Перейти к основному содержанию
Вы привязали guardrail и теперь хотите увидеть, что он поймал. Лента Matches — это лог совпадений guardrail OrcaRouter — каждый раз, когда правило срабатывает (block, mask, flag, annotate или spotlight), шлюз записывает совпадение, которое вы можете разобрать в консоли или вытянуть через API. Это то, как вы отвечаете на «что правило PII отредактировало вчера?», «какой ключ задевает блокировщик секретов?» и «срабатывает ли это правило на реальном трафике или это просто шум?». Эта страница — сфокусированный гид по чтению и сортировке совпадений. О том, как создаются правила и что делает каждое действие, см. в справочнике Guardrails.

​
1. Что записывает лог совпадений guardrail

Каждое сработавшее правило пишет одно совпадение в ленту, ограниченную рабочим пространством (GET /api/guardrail/match, открыта любому Member). Лента отдельна от вашего лога запросов — она хранит только то, что сделал guardrail, а не полное тело запроса. Каждое совпадение записывает:
rule_type (keyword, regex, pii, max_chars, external, llm_judge, grounding), эффективное action (block / mask / flag / annotate / spotlight) и stage (input или output) — так что вы можете мгновенно сказать, что сработало и что оно сделало.
guardrail_name, сработавший rule_label плюс контекст запроса: model_name, token, на котором оно приехало, IP вызывающего ip и request_id, который джойнится назад к вашему логу запросов.
detail — короткая человекочитаемая заметка движка о нарушении (например, какая сущность или паттерн задели), всегда записывается.
matched заполняется только, когда у guardrail включён переключатель Log raw content. По умолчанию он выключен, так что по умолчанию лента говорит вам, что правило сработало и почему, но никогда не хранит саму чувствительную строку.
Сырое содержимое — по согласию и не ретроактивно. С Log raw content выключенным (по умолчанию) поле matched остаётся пустым — лента записывает вердикт и detail, никогда адрес email, секрет или PII, которые задели правило. Включайте его для каждого guardrail только когда нужна подстрока для сортировки; оно применяется к совпадениям, записанным после того, как вы его включите. См. Логирование и приватность.

​
2. Перечисление и фильтрация лога совпадений

Вью списка по умолчанию пагинирован курсором, новые-первыми и ограничен вашим рабочим пространством. Сузьте его параметрами запроса — консоль выставляет их как чипы-фильтры:
ПараметрФильтрует по
guardrail_id, rule_type, action, stageВердикт
token_id, model_name, request_idКонтекст запроса
days / start_at + end_at, hide_fpОкно и состояние ложного срабатывания
Типичное чтение «покажи мне всё, что guardrail секретов заблокировал на этой неделе», используя ваш токен сессии консоли: 
curl "https://api.orcarouter.ai/api/guardrail/match?guardrail_id=42&action=block&days=7" \
  -H "Authorization: Bearer <your-session-token>" \
  -H "X-Workspace-Id: <workspace-id>"
Маршруты управления вроде /api/guardrail/* аутентифицируются вашим session / access token консоли, а не relay-ключом. Ключи sk-orca-... только для вызовов модели /v1/*. В повседневном использовании вы будете читать ленту прямо со вкладки Matches на странице Guardrails.

​
3. Группировка по запросу

Один запрос может задеть несколько правил сразу — input-маску PII и лимит max-length, скажем. Сгруппированный вью (GET /api/guardrail/match/grouped, Member) сворачивает совпадения по request_id, так что вы видите одну строку на нарушающий запрос с его совпадениями, сложенными inline, вместо прокрутки пяти строк для того же вызова. Настройте, сколько совпадений показывать inline на группу, через inline_limit (по умолчанию 5).

​
4. Статистика и полоса трендов

Эндпоинт статистики (GET /api/guardrail/match/stats, Member) питает полосу счётчика и график на вкладке Matches — итоги за окно days, опционально разбитые через group_by:
group_byРазбивка
(опущено)Только итоги
rule_typeКакие типы правил срабатывают чаще
guardrail_idКакой guardrail отвечает за активность
Передайте request_id, чтобы получить счётчик совпадений за константное время для одного запроса (используется перекрёстной ссылкой лога запросов). Именно здесь живут использование по каждому guardrail, набор действий и частота ложных срабатываний — режьте это, а не пагинируйте сырой список.

​
5. Экспорт для журнала аудита

Когда вам нужны совпадения вне консоли — пакет доказательств, таблица, нижестоящий SIEM — GET /api/guardrail/match/export (Member) стримит ваш текущий набор фильтров как CSV или JSON: 
curl "https://api.orcarouter.ai/api/guardrail/match/export?format=csv&guardrail_id=42&days=30" \
  -H "Authorization: Bearer <your-session-token>" \
  -H "X-Workspace-Id: <workspace-id>" \
  -o guardrail-matches.csv
Экспорт несёт те же колонки, что записывает лента — время, guardrail, тип и метку правила, стадию, действие, модель, токен, деталь, совпавшую подстроку (только если захват сырого содержимого был включён в момент записи), id запроса, ip и временную метку ложного срабатывания.
CSV безопасен к формула-инъекции: любая ячейка, которая иначе была бы прочитана как формула таблицы, нейтрализуется, так что открытие экспорта в Excel или Sheets не может исполнить полезную нагрузку, протащенную контрабандой через совпавшую подстроку.

​
6. Сортировка ложных срабатываний

Не каждое совпадение — реальное попадание. Когда правило срабатывает на безобидном трафике, Admin рабочего пространства может пометить совпадение как ложное срабатывание (POST /api/guardrail/match/:id/mark-fp); обратное DELETE /api/guardrail/match/:id/mark-fp снимает пометку. Пометка — только для Admin, хотя остальная лента читаема Member’ом — сортировка это привилегированное действие. Пометка ложного срабатывания делает две вещи: она тегирует совпадение (так что hide_fp=true фильтрует его из ленты) и запоминает находку, так что то же правило на том же содержимом пропускается на будущих запросах. Снимите пометку, чтобы восстановить применение. Для более широкого рабочего процесса настройки шумного правила см. Настройку ложных срабатываний.
Совпадение — это диагностические данные, а не решение применения. Был ли запрос заблокирован, замаскирован или лишь флагирован, уже решено действием во время запроса — лента это запись постфактум. Пометка ложного срабатывания меняет будущее поведение, никогда вызов, который уже произошёл.

​
7. Откуда берутся совпадения

Совпадения производятся движком guardrail на пути ретрансляции, так что лента отражает ровно то, что сделали ваши привязанные политики:
  • Совпадения стадии input записывают то, что шлюз проверил до того, как модель это увидела — см. Стадия input.
  • Совпадения стадии output записывают то, что он проверил на ответе — см. Стадия output.
  • Заблокированный запрос также всплывает как HTTP 400 guardrail_blocked вызывающему; совпадение — это его серверная запись.
Если на запросе не разрешается ни один guardrail, ничего не проверяется и ничего не попадает в ленту — поведение идентично рабочему пространству, которое никогда не включало эту функцию. См. Привязку к ключу и Default аккаунта для того, как политика вообще встаёт перед трафиком.

​
8. Связанное

Справочник Guardrails

Полный движок: типы правил, стадии, действия, пресеты, eval-харнесс.

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

Переключатель Log raw content и что лента хранит — и не хранит.

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

Используйте ленту, чтобы найти и утихомирить шумные правила, не ослабляя политику.

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

Сравните и откатите guardrail, когда лента показывает, что изменение дало осечку.
Для большей картины того, как шлюз инспектирует трафик, см. Как OrcaRouter инспектирует и Guardrails vs firewall.