跳轉到主要內容
你綁定了一個防護欄，現在你想看看它捕捉到了什麼。匹配動態是 OrcaRouter 的防護欄匹配日誌——每當一條規則觸發時（block、mask、flag、annotate 或 spotlight），閘道都會記錄一個你可以在主控台中審查或透過 API 拉取的匹配。它就是你回答「PII 規則昨天遮罩了什麼？」、「哪把金鑰觸發了密鑰封鎖器？」以及「這條規則是在實際流量上觸發還是只是雜訊？」的方式。 本頁是讀取與分流匹配的聚焦指南。關於規則如何撰寫以及每個動作做什麼，參見 防護欄參考。

​
1. 防護欄匹配日誌記錄什麼

每條觸發的規則都會把一個匹配寫入一個工作區限定的動態（GET /api/guardrail/match，對任何 Member 開放）。動態與你的請求日誌分離——它只儲存一個防護欄做了什麼，而非完整的請求主體。每個匹配記錄：
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，以及接回你請求日誌的 request_id。
detail——引擎對該違規的簡短人類可讀註記（例如哪個實體或模式觸發了），總是被記錄。
matched 只在防護欄的 Log raw content 切換開啟時才會被填入。它預設為關閉，所以預設情況下動態告訴你一條規則觸發了以及為何，但永不儲存敏感字串本身。
原始內容是選擇加入且不可追溯生效的。 在 Log raw content 關閉時（預設），matched 欄位保持空白——動態記錄裁決與 detail，永不記錄觸發規則的電子郵件地址、密鑰或 PII。只在你需要子字串進行分流時才逐個防護欄開啟它；它套用於你啟用它之後記錄的匹配。參見 日誌與隱私。

​
2. 列出並篩選匹配日誌

預設的清單檢視是游標分頁、最新優先，並限定於你的工作區。用查詢參數收窄它——主控台把這些公開為篩選晶片：
參數依據篩選
guardrail_id、rule_type、action、stage裁決
token_id、model_name、request_id請求情境
days / start_at + end_at、hide_fp窗口與誤報狀態
一個典型的「給我看密鑰防護欄這週封鎖的一切」讀取，使用你的主控台工作階段權杖： 
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/* 這樣的管理路由以你的主控台工作階段／存取權杖驗證，而非一把中繼金鑰。sk-orca-... 金鑰只用於 /v1/* 模型呼叫。在日常使用中，你會直接從 Guardrails 頁面上的 Matches 分頁讀取動態。

​
3. 按請求分組

單一請求可以一次觸發數條規則——比方說一個輸入 PII 遮罩與一個最大長度上限。分組檢視（GET /api/guardrail/match/grouped，Member）按 request_id 摺疊匹配，這樣你就能看到每個違規請求一列，其匹配內嵌摺疊在內，而非為同一個呼叫捲過五列。用 inline_limit（預設 5）調整每組內嵌顯示多少個匹配。

​
4. 統計與走勢條

統計端點（GET /api/guardrail/match/stats，Member）驅動 Matches 分頁上的計數條與圖表——一個 days 窗口內的總計，可選地用 group_by 拆分：
group_by拆分
(省略)僅總計
rule_type哪些規則類型觸發最多
guardrail_id哪個防護欄佔了該活動
傳入 request_id 以取得一個請求的常數時間匹配計數（由請求日誌交叉連結使用）。這就是每個防護欄的用量、動作組合與誤報率所在的地方——切片它，而不是分頁原始清單。

​
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
匯出攜帶動態記錄的相同欄位——時間、防護欄、規則類型與標籤、階段、動作、模型、權杖、詳情、匹配到的子字串（只在記錄時原始內容擷取已開啟的情況下）、請求 id、ip，以及誤報時間戳。
CSV 是公式注入安全的：任何原本會被當作試算表公式讀取的儲存格都會被中和，所以在 Excel 或 Sheets 中開啟一份匯出無法執行透過一個匹配子字串偷渡的酬載。

​
6. 分流誤報

不是每個匹配都是真命中。當一條規則在良性流量上觸發時，工作區 Admin 可以把匹配標記為誤報（POST /api/guardrail/match/:id/mark-fp）；相反的 DELETE /api/guardrail/match/:id/mark-fp 會取消標記它。即使動態的其餘部分對 Member 可讀，標記也是僅 Admin 的——分流是一個特權動作。 標記一個誤報做兩件事：它為匹配加標籤（這樣 hide_fp=true 就把它從動態中濾掉）並記住該發現，這樣同一內容上的同一條規則在未來的請求上就會被略過。取消標記以還原強制執行。關於調校一條吵雜規則的更廣工作流程，參見 調校誤報。
一個匹配是診斷資料，而非一個強制執行決策。 一個請求是被封鎖、遮罩還是僅被標記，在請求時就已經由 動作 確定了——動態是事後的紀錄。標記一個誤報改變未來的行為，永不改變已經發生的呼叫。

​
7. 匹配從何而來

匹配由中繼路徑上的防護欄引擎產生，所以動態確切反映你綁定的政策做了什麼：
  • 輸入階段匹配記錄閘道在模型看到之前審查了什麼——參見 輸入階段。
  • 輸出階段匹配記錄它在回應上審查了什麼——參見 輸出階段。
  • 一個被封鎖的請求也會作為一個 HTTP 400 guardrail_blocked 呈現給呼叫方；匹配是它的伺服器端紀錄。
如果一個請求上沒有解析出任何防護欄，就不會審查任何東西也不會有東西落入動態——行為與從未啟用此功能的工作區完全相同。一個政策一開始如何來到流量前面，參見 綁定到金鑰 和 帳戶預設值。

​
8. 相關

防護欄參考

完整引擎：規則類型、階段、動作、預設、評測工具。

日誌與隱私

Log raw content 切換，以及動態儲存——與不儲存——什麼。

調校誤報

使用動態在不削弱政策的情況下找出並平息吵雜規則。

版本控制

當動態顯示一次變更失誤時，比對與還原一個防護欄。
關於閘道如何審查流量的更大圖景，參見 OrcaRouter 如何審查 和 防護欄與防火牆。