Chuyển đến nội dung chính
Bạn đã gắn một guardrail và giờ bạn muốn thấy nó đã bắt cái gì. Matches feed là log match guardrail của OrcaRouter — mỗi lần một quy tắc kích hoạt (block, mask, flag, annotate, hoặc spotlight), gateway ghi lại một match bạn có thể xem xét trong console hoặc kéo qua API. Đó là cách bạn trả lời “quy tắc PII đã redact cái gì hôm qua?”, “key nào kích hoạt secrets blocker?”, và “quy tắc này có kích hoạt trên traffic thực hay chỉ nhiễu?”. Trang này là hướng dẫn tập trung để đọc và phân loại các match. Về cách quy tắc được soạn và mỗi hành động làm gì, xem tài liệu tham khảo Guardrails.

​
1. Log match guardrail ghi lại cái gì

Mỗi quy tắc đã kích hoạt viết một match vào một feed theo phạm vi workspace (GET /api/guardrail/match, mở cho bất kỳ Member nào). Feed tách biệt với request log của bạn — nó chỉ lưu cái một guardrail đã làm, không phải toàn bộ body request. Mỗi match ghi lại:
rule_type (keyword, regex, pii, max_chars, external, llm_judge, grounding), action hiệu lực (block / mask / flag / annotate / spotlight), và stage (input hoặc output) — nên bạn có thể biết ngay cái gì đã kích hoạt và nó làm gì.
guardrail_name, rule_label đang kích hoạt, cộng context request: model_name, token mà nó đi cùng, ip người gọi, và request_id nối lại với request log của bạn.
detail — ghi chú ngắn đọc-được-bởi-con-người của engine cho vi phạm (ví dụ entity hoặc pattern nào đã kích hoạt), luôn được ghi lại.
matched được điền chỉ khi công tắc Log raw content của guardrail được bật. Nó mặc định tắt, nên theo mặc định feed cho bạn biết một quy tắc đã kích hoạt và tại sao, nhưng không bao giờ lưu bản thân chuỗi nhạy cảm.
Raw content là opt-in và không hồi tố. Với Log raw content tắt (mặc định), trường matched giữ trống — feed ghi lại verdict và detail, không bao giờ địa chỉ email, secret, hoặc PII đã kích hoạt quy tắc. Bật nó cho từng guardrail chỉ khi bạn cần chuỗi con để phân loại; nó áp dụng cho các match được ghi lại sau khi bạn bật nó. Xem Logging & quyền riêng tư.

​
2. Liệt kê và lọc log match

Giao diện danh sách mặc định được phân trang theo cursor, mới-nhất-trước, và theo phạm vi workspace của bạn. Thu hẹp nó với các query param — console phơi bày những cái này như các filter chip:
ParamLọc theo
guardrail_id, rule_type, action, stageVerdict
token_id, model_name, request_idContext request
days / start_at + end_at, hide_fpCửa sổ và trạng thái dương-tính-giả
Một lần đọc “cho tôi xem mọi thứ guardrail secret đã block tuần này” điển hình, dùng session token console của bạn: 
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>"
Các route quản lý như /api/guardrail/* xác thực với session / access token console của bạn, không phải một relay key. Các key sk-orca-... chỉ dùng cho các cuộc gọi mô hình /v1/*. Trong dùng hằng ngày bạn sẽ đọc feed thẳng từ tab Matches trên trang Guardrails.

​
3. Nhóm theo request

Một request đơn lẻ có thể kích hoạt nhiều quy tắc cùng lúc — một mask PII input và một giới hạn độ dài tối đa, chẳng hạn. Giao diện đã nhóm (GET /api/guardrail/match/grouped, Member) gộp các match theo request_id để bạn thấy một hàng cho mỗi request vi phạm với các match của nó gấp inline, thay vì cuộn qua năm hàng cho cùng cuộc gọi. Tinh chỉnh bao nhiêu match hiển thị inline cho mỗi nhóm với inline_limit (mặc định 5).

​
4. Thống kê và dải xu hướng

Endpoint thống kê (GET /api/guardrail/match/stats, Member) cấp năng lượng cho dải đếm và biểu đồ trên tab Matches — tổng trên một cửa sổ days, tùy chọn phân tích với group_by:
group_byPhân tích
(bỏ qua)Chỉ tổng
rule_typeLoại quy tắc nào kích hoạt nhiều nhất
guardrail_idGuardrail nào chiếm hoạt động
Truyền request_id để nhận một số đếm match thời-gian-hằng cho một request (được dùng bởi cross-link request-log). Đây là nơi sử dụng theo từng guardrail, hỗn hợp hành động, và tỷ lệ dương tính giả nằm — cắt nó thay vì phân trang danh sách thô.

​
5. Export cho một audit trail

Khi bạn cần các match ngoài console — một gói bằng chứng, một bảng tính, một SIEM downstream — GET /api/guardrail/match/export (Member) stream bộ filter hiện tại của bạn dưới dạng CSV hoặc 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
Export mang cùng các cột mà feed ghi lại — thời gian, guardrail, loại quy tắc và label, giai đoạn, hành động, mô hình, token, detail, chuỗi con đã match (chỉ nếu bắt raw-content được bật lúc ghi), id request, ip, và dấu thời gian dương-tính-giả.
CSV an toàn-injection-công-thức: bất kỳ ô nào lẽ ra được đọc như một công thức bảng tính được vô hiệu hóa, nên mở một export trong Excel hoặc Sheets không thể thực thi một payload lén qua một chuỗi con đã match.

​
6. Phân loại dương tính giả

Không phải mọi match là một hit thực. Khi một quy tắc kích hoạt trên traffic lành tính, một Admin workspace có thể đánh dấu match như một dương tính giả (POST /api/guardrail/match/:id/mark-fp); nghịch đảo DELETE /api/guardrail/match/:id/mark-fp bỏ đánh dấu nó. Đánh dấu là chỉ-Admin mặc dù phần còn lại của feed đọc-được-bởi-Member — phân loại là một hành động đặc quyền. Đánh dấu một dương tính giả làm hai điều: nó gắn thẻ match (nên hide_fp=true lọc nó khỏi feed) và nhớ phát hiện để cùng quy tắc trên cùng nội dung được bỏ qua trên các request tương lai. Bỏ đánh dấu để khôi phục thực thi. Về workflow rộng hơn của tinh chỉnh một quy tắc nhiễu, xem Tinh chỉnh dương tính giả.
Một match là dữ liệu chẩn đoán, không phải một quyết định thực thi. Việc một request đã bị block, che, hay chỉ gắn cờ đã được giải quyết bởi hành động lúc request — feed là bản ghi sau sự việc. Đánh dấu một dương tính giả thay đổi hành vi tương lai, không bao giờ cuộc gọi đã xảy ra.

​
7. Match đến từ đâu

Match được tạo bởi engine guardrail trên đường relay, nên feed phản ánh chính xác cái chính sách đã gắn của bạn đã làm:
  • Match giai đoạn input ghi lại cái gateway đã sàng lọc trước khi mô hình thấy nó — xem Giai đoạn input.
  • Match giai đoạn output ghi lại cái nó đã sàng lọc trên phản hồi — xem Giai đoạn output.
  • Một request bị block cũng hiện ra như một HTTP 400 guardrail_blocked tới người gọi; match là bản ghi phía-server của nó.
Nếu không guardrail nào phân giải trên một request, không có gì được sàng lọc và không có gì đáp xuống feed — hành vi giống hệt một workspace chưa bao giờ bật tính năng này. Xem Gắn vào một key và Mặc định tài khoản cho cách một chính sách đi đến trước traffic ngay từ đầu.

​
8. Liên quan

Tài liệu tham khảo Guardrails

Engine đầy đủ: loại quy tắc, giai đoạn, hành động, preset, eval harness.

Logging & quyền riêng tư

Công tắc Log raw content và feed lưu — và không lưu — cái gì.

Tinh chỉnh dương tính giả

Dùng feed để tìm và làm im các quy tắc nhiễu mà không làm yếu chính sách.

Versioning

Diff và revert một guardrail khi feed cho thấy một thay đổi kích hoạt sai.
Về bức tranh lớn hơn của cách gateway kiểm tra traffic, xem Cách OrcaRouter kiểm tra và Guardrails so với firewall.