防護欄

當你擁有工作區和 API 金鑰之後（參見簡介），防護欄就是你在每個模型前面擺放內容政策的方式。本頁是 OrcaRouter 防護欄引擎的權威參考—— 它是什麼、如何使用，以及它如何與閘道的其他部分組合。

1. 什麼是防護欄引擎

防護欄是一個工作區層級的、命名的內容政策—— 一份閘道會針對請求輸入和模型輸出執行的有序規則清單。你儲存一次防護欄，將任意 API 金鑰綁定到它（或將其中一個設為工作區預設值），閘道就會在上游模型之前與之後審查每次呼叫。每條規則決定一件事——尋找什麼（規則類型）、在哪裡尋找 （階段：請求輸入或模型輸出），以及要對它做什麼 （動作：block、mask 或 flag）。引擎執行每一條適用的規則並將結果摺疊成單一決策。編輯防護欄會在下次呼叫時對綁定到它的每個金鑰生效。無需重新部署。無需修改程式碼。無需升級 SDK。政策存在於閘道中，而不是你的應用程式中——你的應用程式像以前一樣繼續呼叫 /v1/chat/completions。對於內建規則類型，引擎是確定性且無依賴的：純字串與正規表示式匹配，沒有網路呼叫，可安全地在熱中繼路徑上執行。進階規則（外部廠商、LLM 評審、情境接地）會對外呼叫，並以並行方式派發，因此緩慢的檢查永遠不會串列地卡在另一個檢查後面。防護欄是工作區層級的——每個成員都能看到該工作區的防護欄；不會跨租戶邊界。

2. 快速開始——5 步審查你的第一個請求

建立防護欄

在主控台中前往 /console/guardrails，按一下 New guardrail。將其命名為 pii-shield。新增一條規則：

類型： PII detection
階段： Input（request）
動作： Mask——遮罩匹配項
實體： email、phone、ssn

儲存。

在沙盒中測試

在編輯器內開啟 Test 分頁，貼上 “email me at jane@acme.com”，選擇 input 階段，然後執行。沙盒會顯示裁決與渲染後的文字——email me at [EMAIL]——而不會向上游傳送任何東西。

綁定金鑰

前往 /console/token，建立或編輯一個 API 金鑰，從 Guardrail 下拉選單選擇 pii-shield。綁定關係存在於閘道中的金鑰上。

傳送請求

使用該金鑰，像以前一樣呼叫 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]。上游模型永遠看不到這個地址。

收緊政策

回到 /console/guardrails，編輯 pii-shield——透過每實體覆寫將 ssn 上的動作改為 Block。儲存。下一個包含 SSN 的請求就會以 HTTP 400 guardrail_blocked 被拒絕。無需修改應用程式。

這就是核心價值。

3. 概念：防護欄、規則、階段、動作

概念	定義
防護欄	一個命名的、工作區層級的政策。識別碼：`name`（≤ 64 字元）。具有 `enabled`、`is_default` 以及一個 `rules` JSON blob。
規則	政策內的一項檢查：一個 `type`、一個 `stage`、一個 `action`，加上類型特定欄位。規則按順序執行。
階段	`input`（請求）、`output`（模型的回應）或 `both`。
動作	`block`（拒絕呼叫）、`mask`（遮罩匹配項）或 `flag`（僅記錄——觀察而不改變流量）。

範圍限定與工作區預設值

防護欄的範圍與 API 金鑰完全一致：當你有作用中的工作區時為工作區共享，否則為每使用者。任何請求的解析方式：

金鑰綁定——如果金鑰有明確的 guardrail_id，則套用該防護欄（當它存在且已啟用時）。明確綁定永不會靜默回退；停用它就是關閉開關。
工作區預設值——如果金鑰沒有綁定，則套用工作區已啟用的 is_default 防護欄。
兩者皆無——不執行任何強制。請求與從未啟用此功能的工作區位元組完全一致。

每個工作區最多只能有一個防護欄作為預設值。晉升一個新的預設值會在同一交易中降級舊的那個。

設計上的失敗開放（fail-open）。 如果防護欄解析遇到暫時性錯誤（例如 DB 抖動），閘道會降級為不執行強制，而不是讓流量中斷。安全性降級；可用性得以保留。

封鎖的樣子

被封鎖的請求會傳回 HTTP 400，錯誤代碼為 guardrail_blocked，訊息會指明觸發的防護欄與規則。被封鎖的請求不消耗任何配額——input 階段的封鎖在計量之前觸發，而 output 階段的封鎖則會退還已預先扣除的配額——並且會被標記為 skip-retry（重跑同一個提示只會再次被封鎖）。

4. 規則類型

規則分為兩組：內建（確定性、無網路）與進階（對外呼叫模型或廠商）。

類型	分組	作用
關鍵字封鎖清單 (`keyword`)	內建	匹配一份字面詞彙清單中的任何一項——不分大小寫、以子字串方式比對（因此 `class` 也會匹配 `classic`）。
正規表示式 (`regex`)	內建	匹配一個 RE2 模式（線性時間、無回溯參照）。
PII 偵測 (`pii`)	內建	偵測內建實體類型（以及你自己的自訂類型）。參見 §5。
最大長度 (`max_chars`)	內建	限制某階段文字的字元數上限。
外部廠商 (`external`)	進階	將檢查委派給已連接的廠商（Aporia、Averta、自帶 webhook，……）。參見 §9。
LLM 評審 (`llm_judge`)	進階	針對你工作區中的某個模型執行語意檢查。參見 §6。
情境接地 (`grounding`)	進階	針對請求上擷取的來源（RAG）對答案的忠實度評分。參見 §7。

一個防護欄可混用任意數量、任意類型的規則。進階規則（external、llm_judge、grounding）以並行方式派發，因此一個緩慢的檢查不會串列地卡在另一個後面。

5. PII 偵測詳解

pii 規則偵測敏感實體，並對每個匹配項套用規則的動作。內建的偵測器集合是封閉的，由引擎、驗證器與規則建構器共用： email、phone、credit_card、ssn、ip、iban、mac_address、 api_key_openai、aws_access_key、jwt、bitcoin_address。在 mask 動作下，每個匹配項會被替換為一個具型別的標籤——電子郵件會變成 [EMAIL]，SSN 會變成 [SSN]，依此類推。

自訂實體

在內建集合之上疊加你自己的偵測器。一個自訂實體是：

name——小寫 ASCII／數字／底線，必須以字母開頭（例如 employee_id）。會以不加引號的形式流入稽核日誌與遙測。
pattern——一個 Go RE2 正規表示式（線性時間、無回溯參照）。
checksum——可選；luhn 會以 Luhn 演算法驗證匹配項（例如用於卡號類數字）。
mask_with——可選的逐字替換；預設為 [<UPPERCASE_NAME>]。

每條規則最多 25 個自訂實體（每個都是對全文的一次正規表示式掃描，所以這個上限讓熱路徑保持線性）。已編譯的模式會在跨請求間快取。

每實體動作覆寫

單一 PII 規則可透過 entity_actions 對不同實體套用不同動作。一條規則預設遮罩 emails／phones／IPs，但對 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 評審

llm_judge 規則會針對你工作區已能呼叫的某個模型執行語意檢查。用它來處理沒有正規表示式能捕捉的模糊政策—— 有害性、騷擾、離題、提示注入意圖。

欄位	含義
`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`	限制評審呼叫的時長。`0` → 引擎預設值。
`judge_fail_open`	`true`（預設）→ 評審錯誤會被觀察但請求繼續；`false` → 將錯誤／逾時視為封鎖。

評審呼叫會路由通過你工作區的通道，所以它的 token 會像任何其他呼叫一樣計費並歸因（作為評審子項）。引擎會在你的 rubric 後附加一段 JSON-schema 附錄，讓模型傳回可解析的輸出。

7. 情境接地

grounding 規則會將助理的答案與請求上擷取的來源 （你的 RAG 情境）進行衡量，並標記或封鎖那些對其不忠實的答案。它重用評審接縫——相同的工作區通道、相同的成本歸因。

欄位	預設值	含義
`grounding_model`	工作區選擇	執行器解析忠實度檢查所用的模型。
`grounding_rubric`	內建	覆寫預設的忠實度 rubric。
`grounding_threshold`	`0.7`	忠實度下限，`0.0`–`1.0`。低於它時觸發動作。
`grounding_strict`	`false`	當為 `true` 時，「未提供來源」被視為封鎖（相對於預設的允許）。
`grounding_max_bytes`	`100000`	限制交給評審的串接來源情境上限。
`grounding_timeout_ms`	`3000`	限制評審呼叫的時長。

8. 範本、沙盒與評測工具

範本庫

New guardrail 分割按鈕會直接開啟一個範本，完整的範本庫只需一鍵即可開啟。預設值在伺服器端撰寫，因此主控台、沙盒與本文件描述的是完全相同的行為。類別包括：

PII（pii）——PII Shield、PII Blocker（嚴格）、Contact-Info Redactor、回應 PII redactor。
Secrets（secrets）——AWS／OpenAI／GitHub 憑證封鎖器、私鑰與雲端權杖、加密錢包、輸出中的密鑰。
Compliance（compliance）——GDPR（EU PII）、PCI（完整卡號封鎖）、 HIPAA（PHI）、財務資料、合規記錄器、法律免責聲明強制。
Brand（brand）——髒話（封鎖／遮罩／多語言）、競爭對手提及、兒童安全關鍵字。
Safety（safety）——提示注入、越獄、系統提示詞外洩、自我傷害。
Cost（cost）——提示／回應大小上限與權杖上限。
Agent（agent）——URL 過濾器、markdown 圖片、shell 工具呼叫，以及輸出中的 SQL 注入過濾器。

把預設值當作起點套用，然後自由編輯——預設值是種子，不是鎖。

測試沙盒

每個編輯器都有一個 Test 分頁。貼上一個樣本，選擇一個階段，然後在本機執行目前的政策——沒有上游呼叫、不消耗配額。沙盒會傳回裁決，並且（對於 mask 規則）傳回渲染後的文字，所以你可以在綁定金鑰之前證明某條規則確實如你所期望地運作。

評測／紅隊工具

Eval 分頁會針對一個輸入語料庫執行防護欄，並回報它的評分結果——對調校評審 rubric 或在上線前證明某政策能捕捉已知攻擊很有用。

內建語料庫隨閘道一起出貨——對抗性與紅隊集合（有害行為提示、工具注入、多語言紅隊）外加用於衡量誤報的良性集合。
自訂語料庫——上傳你自己的 JSONL，針對你真實的流量形態進行測試。
執行會連同其分數一起列出；開啟一次執行可逐樣本檢視失敗項。

9. 外部廠商

external 規則會將檢查委派給已連接的廠商。在 Integrations 下（Guardrails 頁面標頭上的 CTA）連接一次廠商，然後從規則引用該連接。

支援的廠商

廠商	是什麼
Aporia Guardrails (`aporia`)	針對提示與回應的 SLM 整合策略引擎。
Averta (`averta`)	通用 SLM 分類器端點（POST 文字 → 安全／不安全 + 可選的改寫）。
BYO Webhook (`webhook`)	你自己的 URL——接收提示並回傳允許／封鎖／遮罩／標記的判定。

Aporia 與 Averta 需要基底 URL + API 金鑰；webhook 需要 URL + 驗證標頭 + HMAC 密鑰。

規則欄位

欄位	含義
`connection_id`	要使用的已連接整合（建議路徑——廠商 + 密鑰在執行時從工作區的整合解析）。
`timeout_ms`	限制單次廠商呼叫的時長。`0` → 預設值。
`fail_open`	`true`（預設）→ 廠商錯誤會被觀察但請求繼續；`false` → 將傳輸錯誤／逾時／未知 provider 視為封鎖。

密鑰以加密方式儲存，讀取時遮罩。檢查呼叫會攜帶中繼請求的取消訊號，因此被取消的請求不會讓某個廠商呼叫懸而未決。

10. 可觀測性

防護欄會留下你可以採取行動的麵包屑。

匹配動態

每條觸發的規則都會記錄一個 match——規則類型、動作、一個詳細字串、階段，以及（當啟用時）匹配到的子字串。 Guardrails 頁面上的 Matches 分頁是工作區範圍的動態：列出、分組、篩選、深入單個匹配、匯出為 CSV，並標記誤報。

原始內容擷取為選擇加入。 防護欄的 Log raw content 切換預設為關閉——這是隱私保守的姿態。在它關閉時， Matches 動態會記錄某條規則觸發了以及它的詳細元字串，但不記錄實際匹配到的子字串（例如電子郵件地址本身）。當你需要子字串進行分流時，可逐個防護欄開啟它；該設定不可追溯生效。

統計

Matches 動態驅動每個防護欄的統計資料——每張防護欄卡片都會顯示 7 天匹配走勢圖與計數，Matches 分頁則帶有工作區總計。若要按政策切片活動，請使用 Matches 動態的分組檢視與篩選器（按防護欄、規則類型、動作）——每個防護欄的用量、動作組合與誤報率都在那裡。

版本歷史與稽核

每次建立、更新與刪除都會在與變更相同的交易中寫入一筆版本化的歷史列。在防護欄列上開啟 History 可以：

查看每個版本，以及是誰在何時做的變更。
Diff 任意兩個版本。
Revert 到較舊的版本（會記錄為一個新版本——歷史永不可變）。

11. 與閘道其他部分的關係

介面	如何與防護欄組合？
Models	防護欄與模型無關。同一個政策可以跨 GPT-5、Claude、Gemini 運行——它審查的是文字，而不是模型選擇。
Routing	相互獨立。路由決定由哪個模型／通道處理請求；防護欄無論如何都會審查相同的請求／回應文字，且絕不覆寫模型選擇。輸入審查在呼叫上游之前執行，輸出審查在模型回應之後執行。判定（Judge）與接地（grounding）規則透過你工作區的通道解析各自的模型，與請求的路由相互分離。
Prompts	相互獨立且互補。提示詞注入系統訊息；防護欄檢查並把關內容。一個請求可以同時套用兩者，且防護欄始終執行。順序很重要：輸入規則在註冊表提示詞被注入之前就審查呼叫方的請求（注入發生在較晚的路由階段），所以輸入規則看到的是呼叫方的訊息，而不是被注入的系統提示詞；輸出規則則無論如何都會審查模型的回應。
API Keys	金鑰透過 `guardrail_id` 綁定到防護欄。綁定存在於閘道中的金鑰上，所以編輯防護欄會一次性切換每個綁定的金鑰；沒有綁定則回退到工作區預設值。
Matches 動態	每條觸發的規則都會落入工作區的 Matches 動態（它有自己的儲存，與請求日誌分離）。按防護欄、規則類型與動作對其分組與篩選，即可查看每個防護欄的用量、動作組合與誤報率。

12. API 參考

所有路由都透過 X-Workspace-Id 標頭進行工作區限定。RBAC 執行一致：讀取與測試沙盒對每個成員開放；寫入需要 Developer+（以及 guardrails:write 權限）；生產流量變更（刪除、還原、廠商設定）相應地受到限制。

方法與路徑	角色	用途
`GET /api/guardrail/`	Member	列出防護欄（含綁定金鑰計數）。
`GET /api/guardrail/meta`	Member	引擎詞彙——規則類型、階段、動作、PII 實體、預設值、預設值類別。
`GET /api/guardrail/my-permissions`	Member	呼叫方的防護欄權限（用於 UI 把關）。
`GET /api/guardrail/:id`	Member	單個防護欄詳情。
`GET /api/guardrail/:id/tokens`	Member	綁定到此防護欄的 API 金鑰（有上限，附真實總數）。
`POST /api/guardrail/test`	Member	沙盒——在某階段對樣本文字評估一個政策。不持久化任何東西。
`POST /api/guardrail/`	Developer+	建立防護欄。
`PUT /api/guardrail/`	Developer+	更新防護欄（寫入一個新的歷史版本）。
`DELETE /api/guardrail/:id`	Developer+	刪除防護欄。

歷史

方法與路徑	角色	用途
`GET /api/guardrail/:id/history`	Member	版本歷史（最新優先）。
`GET /api/guardrail/:id/history/diff`	Member	比對兩個版本。
`GET /api/guardrail/:id/history/:version`	Member	單個歷史版本。
`POST /api/guardrail/:id/revert`	Developer+	將舊版本還原為新版本。

評測與語料庫

方法與路徑	角色	用途
`POST /api/guardrail/:id/eval`	Member	針對一個語料庫執行評測（內建名稱或上傳的 JSONL）。
`GET /api/guardrail/:id/eval/runs`	Member	列出某防護欄的評測執行（分頁）。
`GET /api/guardrail/eval/runs/:run_id`	Member	單個評測執行詳情。
`GET /api/guardrail/eval/corpora`	Member	列出工作區語料庫 + 內建語料庫。
`POST /api/guardrail/eval/corpora`	Developer+	上傳一個 JSONL 語料庫。
`GET /api/guardrail/eval/corpora/:id`	Member	語料庫詳情。
`DELETE /api/guardrail/eval/corpora/:id`	Developer+	刪除一個語料庫。

匹配

方法與路徑	角色	用途
`GET /api/guardrail/match`	Member	列出匹配（工作區限定）。
`GET /api/guardrail/match/grouped`	Member	分組的匹配（例如按規則或防護欄）。
`GET /api/guardrail/match/stats`	Member	匹配統計（支援 `?days=` 和 `?group_by=`）。
`GET /api/guardrail/match/export`	Member	將匹配匯出為 CSV。
`GET /api/guardrail/match/:id`	Member	單個匹配詳情。
`POST /api/guardrail/match/:id/mark-fp`	Admin	將一個匹配標記為誤報（限速）。
`DELETE /api/guardrail/match/:id/mark-fp`	Admin	取消標記一個誤報（限速）。

綁定金鑰

在 API 金鑰上設定 guardrail_id（透過金鑰編輯器或 token API）。 0／null 表示沒有明確綁定——金鑰會回退到工作區預設防護欄（如果有設定的話）。

13. FAQ

如果請求上沒有解析出任何防護欄會怎樣？

行為與從未啟用該功能的工作區位元組完全一致。如果金鑰沒有綁定，也沒有設定工作區預設值，閘道不做任何修改。沒有東西被封鎖、遮罩，或記錄到 Matches 動態。

被封鎖的請求會消耗配額嗎？

不會。input 階段的封鎖在用量計量之前觸發；output 階段的封鎖則會在回應被拒絕後退還已預先扣除的配額。無論哪種情況，呼叫方都不支付任何配額、會得到 HTTP 400 guardrail_blocked，並且請求被標記為 skip-retry（針對另一個通道重跑同一個提示只會再次被封鎖）。

輸出（回應）規則在串流上會被強制執行嗎？

這取決於 action。Block 在兩種情況下都會被強制執行：在非串流回應上，答案會在返回前先被篩查；在串流回應上，一個掃描器會在串流途中將其切斷，並在任何被封鎖的內容抵達客戶端之前發出一條替代訊息。輸出上的 Mask 目前只套用於非串流回應——在串流回應上，原始 chunk 會未經遮罩直接通過（帶內的串流改寫是一項規劃中的增強功能）。對於今天的輸出遮罩，請使用非串流請求，或依賴 input 階段的遮罩。在依賴它之前，請在沙盒中以及透過一次評測執行證明你特定的階段／串流組合。

mask 和 block 有什麼差別？

Mask 遮罩匹配項（例如 jane@acme.com → [EMAIL]）並以淨化後的文字讓請求通過——上游模型永遠看不到原始內容。Block 以 HTTP 400 拒絕整個請求。 Flag 不改變流量的任何部分，只記錄一個匹配——用它來在強制執行前衡量一條規則。

注入的提示詞 token 和評審 token 會計費嗎？

內建規則（keyword／regex／PII／max_chars）不做模型呼叫，也不計費。llm_judge 或 grounding 規則會透過你工作區的通道呼叫一個模型，所以那些 token 會被計費並歸因為一個評審子項。

我如何查看一條規則實際匹配到了什麼？

為該防護欄開啟 Log raw content。在它關閉時（預設）， Matches 動態會記錄某條規則觸發了以及它的詳細元字串，但不記錄匹配到的子字串——這是隱私保守的姿態。該切換不可追溯生效：它只影響你啟用後記錄的匹配。

我可以回滾一次防護欄變更嗎？

可以。在防護欄上開啟 History，比對版本，然後 Revert 到你想要的那個。Revert 會將該版本的內容向前複製為一個新版本——歷史永不可變——並且變更會在下次請求時生效。

如果外部廠商或評審逾時會發生什麼？

預設情況下，進階規則失敗開放（fail open）：逾時或傳輸錯誤會被記錄為遙測，請求繼續。將 fail_open（external）或 judge_fail_open（judge）設為 false 以 失敗關閉（fail closed）——將錯誤視為封鎖——適用於漏掉一次檢查就無法接受的政策。

​1. 什麼是防護欄引擎

​2. 快速開始——5 步審查你的第一個請求

​3. 概念：防護欄、規則、階段、動作

​範圍限定與工作區預設值

​封鎖的樣子

​4. 規則類型

​5. PII 偵測詳解

​自訂實體

​每實體動作覆寫

​6. LLM 評審

​7. 情境接地

​8. 範本、沙盒與評測工具

​範本庫

​測試沙盒

​評測／紅隊工具

​9. 外部廠商

​支援的廠商

​規則欄位

​10. 可觀測性

​匹配動態

​統計

​版本歷史與稽核

​11. 與閘道其他部分的關係

​12. API 參考

​防護欄

​歷史

​評測與語料庫

​匹配

​綁定金鑰

​13. FAQ

1. 什麼是防護欄引擎

2. 快速開始——5 步審查你的第一個請求

3. 概念：防護欄、規則、階段、動作

範圍限定與工作區預設值

封鎖的樣子

4. 規則類型

5. PII 偵測詳解

自訂實體

每實體動作覆寫

6. LLM 評審

7. 情境接地

8. 範本、沙盒與評測工具

範本庫

測試沙盒

評測／紅隊工具

9. 外部廠商

支援的廠商

規則欄位

10. 可觀測性

匹配動態

統計

版本歷史與稽核

11. 與閘道其他部分的關係

12. API 參考

防護欄

歷史

評測與語料庫

匹配

綁定金鑰

13. FAQ