跳转到主要内容
内置 pii 检测器覆盖了常见实体——email、电话、信用卡、SSN、 IBAN、JWT、云密钥。但你的敏感数据是你的：员工 ID、内部 案件编号、客户账号引用、合作伙伴的订单格式。自定义 PII 实体让你教会同一条脱敏规则识别那些形态，这样网关就能在 模型——或任何下游工具——看到它们之前把它们脱敏。 本页涵盖自定义实体在 PII 检测规则之上增加的那一件 事：你自己的检测器。完整的引擎——每种规则类型、阶段和路由—— 请见防护栏参考。
这里的每一步都是托管网关（api.orcarouter.ai）上的控制台 操作。你在自己的会话下编写防护栏；只有最后的 /v1/* 调用使用 sk-orca-... 中继密钥。创建和编辑防护栏需要工作区中的 Developer+。

​
1. 你何时需要一个自定义 LLM PII 检测器防护栏

内置实体集合是封闭的，由引擎、校验器和规则构建器共享。它是 标准标识符的正确工具。当你想脱敏的数据具有没有任何内置项 覆盖的可预测形态时，使用自定义实体：

内部标识符

员工 ID（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否mask 动作上的逐字替换。默认为 [<UPPERCASE_NAME>]。
name 遵循网关其余部分相同的键约定——小写、以字母开头、没有 空格或连字符。选一个清晰的（case_number、partner_order_id）； 当规则触发时它就是你在 Matches 信息流中看到的内容。

​
可选的 Luhn 校验

许多”数字形态”的标识符——支付卡、某些会员号和账号——带有 一个 Luhn（mod-10）校验位。一个裸正则如 \d{16} 会匹配任意 16 位数字串，包括电话号码、时间戳和订单总额。设置 checksum: "luhn" 让检测器仅在匹配的数字也通过 Luhn 校验时 才触发，这样相似的数字串会干净地通过，你的误报率保持很低。 对于像员工 ID 这样不带校验和的词项，把它留空。

​
你自己的脱敏标签

在 mask 动作上，内置 email 渲染为 [EMAIL]。自定义实体 默认渲染为 [<UPPERCASE_NAME>]——一个 employee_id 匹配变成 [EMPLOYEE_ID]。当你想在模型收到的文本中要一个特定的替换 词项时，设置 mask_with 来逐字覆盖它（例如 <id> 或 ***）。 跨实体类型的渲染规则见 脱敏格式。

​
3. 一个具体示例

假设你的提示词以 EMP 后跟六位数字的形式携带员工 ID，而你想 在输入阶段把它们脱敏，让上游模型永远看不到一个真实的 ID。 给一条 pii 规则添加单个自定义实体： 
{
  "type": "pii",
  "stage": "input",
  "action": "mask",
  "entities": ["email"],
  "custom_entities": [
    {
      "name": "employee_id",
      "pattern": "EMP\\d{6}",
      "mask_with": "[EMPLOYEE_ID]"
    }
  ]
}
那条规则在同一遍中脱敏标准 email 和你的员工 ID。在绑定密钥 之前先在 Test 标签页中测试它： 
Forward EMP482915's note to jane@acme.com

Forward [EMPLOYEE_ID]'s note to [EMAIL]
不会向上游发送任何内容，也不计量。然后把防护栏绑定到一个 密钥（参见绑定到密钥）并 像以前一样调用 /v1/chat/completions——网关会在转发前脱敏 请求，无需修改 SDK。
脱敏在两个阶段都运行：输入规则在模型看到请求之前脱敏它， 输出规则脱敏模型的回复——包括流式响应，扫描器在那里带内 改写匹配。Block 动作在两个阶段也都会执行。要把关模型的 响应，参见输出阶段规则。

​
一个带校验和的示例

对于一个类卡号的会员号，添加 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 动作上如何渲染，以及 mask_with 如何覆盖它。

正则检测器

当一条普通 regex 规则比一个带类型的 PII 实体更合适时。

调优误报

使用 Matches 信息流和校验和来调准精度。
阅读防护栏参考 以了解完整的 PII 规则——每个字段、eval 工具，以及完整的 API—— 或阅读创建你的第一个防护栏 从头走完端到端的流程。