跳轉到主要內容
內建的 pii 偵測器涵蓋了常見實體——電子郵件、電話、信用卡、SSN、IBAN、JWT、雲端金鑰。但你的敏感資料是你的：員工編號、內部案件號、客戶帳號參照、合作夥伴的訂單格式。一個自訂 PII 實體讓你教會同一條遮罩規則辨識那些形狀，這樣閘道就會在模型——或任何下游工具——看到它們之前遮罩它們。 本頁涵蓋自訂實體為 PII 偵測規則 增添的那一件事：你自己的偵測器。完整引擎——每種規則類型、階段與路由——請見 防護欄參考。
這裡的每個步驟都是託管閘道（api.orcarouter.ai）上的一個主控台動作。你在自己的工作階段下撰寫防護欄；只有最後的 /v1/* 呼叫使用 sk-orca-... 中繼金鑰。建立與編輯防護欄需要工作區中的 Developer+。

​
1. 何時你需要一個自訂 LLM PII 偵測器防護欄

內建的實體集合是封閉的，且跨引擎、驗證器與規則建構器共用。它是標準識別碼的正確工具。當你想遮罩的資料有一個沒有任何內建涵蓋的可預測形狀時，使用自訂實體：

內部識別碼

員工編號（EMP482915）、案件號、工單參照、內部 SKU——任何帶有固定前綴與數字串的東西。

帳號與訂單號

絕不該逐字抵達第三方模型的客戶帳號參照或合作夥伴訂單格式。

帶校驗的數字

通過 Luhn 校驗的卡號類或會員號——加上校驗以減少在相似數字串上的誤報。

領域特定代碼

保單號、理賠 ID、裝置序號——任何你的產業視為敏感但通用偵測器不認識的權杖。
一個自訂實體在一條 pii 規則內疊加於內建集合之上。它偵測匹配項並套用該規則的動作——mask、block 或 flag——就像一個內建實體所做的那樣。

​
2. 自訂實體的剖析

一個自訂實體是三個小欄位加上一個可選的遮罩標籤。你在 pii 規則編輯器的 Custom entities 下新增它們：
欄位必填作用
name是穩定 ID，例如 employee_id。小寫 ASCII ／數字／_，必須以字母開頭。會流入 Matches 動態與稽核日誌。
pattern是一個 Go RE2 正規表示式（線性時間、無回溯參照）。必須可編譯。
checksum否luhn 會以 Luhn 演算法驗證每個匹配項。只接受 ""（無）或 "luhn"。
mask_with否遮罩動作上的逐字替換。預設為 [<UPPERCASE_NAME>]。
name 遵循與閘道其餘部分相同的鍵約定——小寫、以字母開頭、無空格或連字號。挑一個清楚的（case_number、partner_order_id）；當規則觸發時，它就是你會在 匹配動態 中看到的東西。

​
可選的 Luhn 校驗

許多「數字形狀」的識別碼——支付卡、某些會員與帳號——帶有一個 Luhn（mod-10）校驗位。一個像 \d{16} 這樣的裸正規表示式會匹配任何 16 位數字串，包括電話號碼、時間戳與訂單總額。設定 checksum: "luhn" 會讓偵測器只在匹配到的數字也通過 Luhn 校驗時才觸發，這樣相似的數字串就能乾淨地通過，而你的誤報率保持低位。對於像員工編號這樣無校驗的權杖，讓它留空。

​
你自己的遮罩標籤

在一個 mask 動作上，一個內建電子郵件渲染為 [EMAIL]。一個自訂實體預設渲染為 [<UPPERCASE_NAME>]——一個 employee_id 匹配變成 [EMPLOYEE_ID]。當你想在模型收到的文字中放一個特定的替換權杖時，把 mask_with 設為逐字覆寫它（例如 <id> 或 ***）。各實體類型的渲染規則請見 遮罩格式。

​
3. 一個具體範例

假設你的提示以 EMP 後接六位數字的形式攜帶員工編號，而你想在輸入階段遮罩它們，這樣上游模型就永遠看不到一個真實 ID。在一條 pii 規則上新增一個自訂實體： 
{
  "type": "pii",
  "stage": "input",
  "action": "mask",
  "entities": ["email"],
  "custom_entities": [
    {
      "name": "employee_id",
      "pattern": "EMP\\d{6}",
      "mask_with": "[EMPLOYEE_ID]"
    }
  ]
}
那條規則在同一遍中同時遮罩標準電子郵件與你的員工編號。在綁定金鑰前先在 Test 分頁中測試它： 
Forward EMP482915's note to jane@acme.com

Forward [EMPLOYEE_ID]'s note to [EMAIL]
不會向上游傳送任何東西，也不會計量任何東西。然後把防護欄綁定到一把金鑰（參見 綁定到金鑰）並像以前一樣呼叫 /v1/chat/completions——閘道會在轉送前遮罩請求，無需修改 SDK。
遮罩在兩個階段都會執行：一條輸入規則會在模型看到請求之前遮罩它，而一條輸出規則會遮罩模型的回覆——包括串流回應，其中掃描器會帶內改寫匹配項。封鎖動作在兩個階段也都會強制執行。若要把關模型的回應，參見 輸出階段規則。

​
一個帶校驗的範例

對於一個卡號類的會員號，加上 Luhn 校驗，這樣不是有效號碼的 16 位數字串就不會匹配： 
{
  "name": "member_card",
  "pattern": "\\d{16}",
  "checksum": "luhn",
  "mask_with": "[MEMBER_CARD]"
}

​
4. 限制與驗證

規則建構器會在儲存時驗證每個自訂實體——一個壞偵測器永不抵達熱路徑。
每個自訂實體都是對全文的一次正規表示式掃描，所以每條規則的上限是 25。這個上限讓熱路徑保持線性；已編譯的模式會在跨請求間快取。需要更多形狀？把它們拆分到同一個防護欄中的多條 pii 規則。
pattern 是一個 Go RE2 正規表示式——線性時間、無回溯參照。驗證器會拒絕一個無法編譯的模式，並在錯誤中指名出問題的實體。
只接受 ""（無校驗）和 "luhn"。其他任何內容——"sha256"、"mod10"，甚至 "LUHN"——都會在儲存時被拒絕。
一個 name 必須以字母開頭，且只使用小寫 ASCII、數字與底線。一條規則中的兩個自訂實體不能共用一個名稱。

​
5. 每實體動作覆寫

一個自訂實體參與與內建實體相同的 entity_actions 對應。一條 pii 規則可以遮罩大多數東西，但在一個高敏感度的自訂偵測器上封鎖——以它的 name 引用該實體： 
{
  "type": "pii",
  "stage": "input",
  "action": "mask",
  "entities": ["email", "phone"],
  "custom_entities": [
    { "name": "ssn_internal", "pattern": "ID-\\d{9}", "checksum": "luhn" }
  ],
  "entity_actions": {
    "ssn_internal": "block"
  }
}
entity_actions 中的鍵必須引用該規則上已啟用的一個內建實體，或一個自訂實體的 name；值必須是 block、mask、flag 或 annotate。驗證器會拒絕其他任何內容。

​
6. 下一步去哪裡

PII Shield

自訂實體疊加其上的那條單一遮罩規則——內建偵測器集合與具型別遮罩標籤。

遮罩格式

每個實體在遮罩動作上如何渲染，以及 mask_with 如何覆寫它。

正規表示式偵測器

何時一條普通的 regex 規則比一個具型別的 PII 實體更合適。

調校誤報

使用 Matches 動態與校驗來調整精確度。
閱讀 防護欄參考 以了解完整的 PII 規則——每個欄位、評測工具與完整 API——或閱讀 建立你的第一個防護欄 以從頭走過端到端流程。