跳转到主要内容
当你需要脱敏 LLM 提示词携带的敏感数据——email、卡号、 国民身份证、密钥——时，网关会在模型看到之前就地改写每个 匹配项。一个被脱敏的值会变成一个带类型的标签 （jane@acme.com → [EMAIL]），因此模型仍然读到一个连贯的 提示词，而原始值永远不离开你的工作区。 本页专注于脱敏渲染成什么、如何更改标签，以及如何在一条 规则上脱敏某些实体而拦截另一些。完整的引擎——每种规则 类型、阶段和路由——请见防护栏参考， 专门针对请求上脱敏的内容见 输入阶段规则。

​
1. 用带类型的标签脱敏 LLM 提示词携带的敏感数据

带 mask 动作的 pii 规则会检测一个实体，并把每个匹配项 替换为一个带类型的编辑标签——一个方括号中的大写标签，它 指明什么被移除了，而不透露值：
实体渲染标签
email[EMAIL]
credit_card[CREDIT_CARD]
ssn[SSN]
完整的内置检测器集合——email、phone、credit_card、ssn、 ip、iban、mac_address、jwt、aws_access_key、api_key_openai、 bitcoin_address，再加上区域性的 jp_mynumber、kr_rrn 和 cn_resident_id——每一个都渲染它自己的方括号标签（[PHONE]、 [IBAN]、[JP_MYNUMBER] 等）。标签是确定性的：同一个实体总是 渲染同一个标签，因此下游提示词保持稳定，你的日志读起来也 干净。
对于模型质量，带类型的标签胜过一刀切的 [REDACTED]。模型仍然 知道它看的是一个 email 还是一个账号还是一个电话号码，因此它 可以继续推理数据的形态——“reply to [EMAIL]”仍然是一条可 执行的指令——而永远不持有真实值。
输入脱敏完全上线——网关在提示词到达模型之前改写它，无论 是否流式。输出脱敏在非流式响应上也已上线：输出阶段的 mask 规则会在补全返回之前改写它。只有流式输出脱敏在规划路线图上； 在流式回复上，输出阶段优先用 block。确切的阶段/流矩阵见 流式覆盖。

​
2. 一个具体示例

在控制台中你自己的会话下编写规则——防护栏配置需要 Developer+，而不是中继密钥。给一个名为 pii-shield 的防护栏 添加单条 pii 规则： 
{
  "type": "pii",
  "stage": "input",
  "action": "mask",
  "entities": ["email", "phone", "ssn"]
}
把它绑定到一个密钥（设置 guardrail_id，或将它标记为工作区 默认值——参见绑定到密钥）， 然后用那个 sk-orca-... 中继密钥调用网关： 
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 about her SSN 123-45-6789"}
    ]
  }'
网关会在转发前把提示词改写为 “Reply to [EMAIL] about her SSN [SSN]”。上游模型永远看不到该地址或号码。先在编辑器的 Test 标签页中证明确切的渲染（无上游调用，无配额）——参见 测试与 eval。

​
3. 用 mask_with 覆盖标签

内置实体渲染一个固定的标签。自定义实体——你自己叠加在内置 集合之上的正则检测器——让你用 mask_with 自己设置替换文本： 
{
  "type": "pii",
  "stage": "input",
  "action": "mask",
  "custom_entities": [
    {
      "name": "employee_id",
      "pattern": "EMP-[0-9]{6}",
      "mask_with": "[STAFF_ID]"
    }
  ]
}
mask_with 是该实体匹配项的逐字替换字符串。EMP-004217 变成 [STAFF_ID]。把它留空，匹配项就渲染默认标签 [<UPPERCASE_NAME>]——这里是 [EMPLOYEE_ID]——因此即使没有 覆盖，自定义检测器也总是产生可读的、带类型的编辑结果。
name（小写 ASCII / 数字 / 下划线，必须以字母开头）、pattern （一个 Go RE2 正则——线性时间，无反向引用）、可选的 checksum （luhn 校验类卡号），以及可选的 mask_with。每条规则最多 25 个自定义实体——每个都是对全文的一次扫描，因此该上限 让热路径保持线性。参见 自定义 PII 实体。
name 会以未加引号的形式流入审计日志和 Matches 信息流，因此 把它保持为小写 ASCII 字母、数字和下划线，以字母开头（例如 employee_id、internal_ticket）。校验器会拒绝其他任何内容。

​
4. 脱敏某些实体，拦截另一些——entity_actions

单条 pii 规则可以通过 entity_actions 对不同实体应用不同 动作，而不必堆叠三条互相重叠的规则。经典形态：脱敏低 敏感度的联系数据，但直接拦截高敏感度字段。 
{
  "type": "pii",
  "stage": "input",
  "action": "mask",
  "entities": ["email", "phone", "ip", "credit_card", "ssn"],
  "entity_actions": {
    "credit_card": "block",
    "ssn": "block"
  }
}
这里 email、phone 和 ip 遵循规则的顶层 mask 并渲染 [EMAIL] / [PHONE] / [IP]；而一个 credit_card 或 ssn 匹配 则以 HTTP 400 guardrail_blocked 拦截整个请求。
字段规则
键必须是规则上声明的实体（内置或自定义）。
值block、mask、flag 或 annotate。
被拦截的请求不消耗配额——输入阶段拦截在计量之前触发。 被脱敏的请求带着净化后的文本通过。所以一条规则可以悄悄脱敏 常规字段并硬性阻止受监管的字段，只需一次绑定，无需修改应用。

​
5. Mask vs. block vs. flag

脱敏是规则（或按实体覆盖）可以采取的动作之一。按你想干扰 流量的程度来选择：

mask

把匹配项脱敏为一个带类型的标签，并带着净化后的文本放行 请求。模型永远看不到原始值。

block

以 HTTP 400 guardrail_blocked 拒绝整个请求。什么都不到达 模型。用它处理绝不能传输的数据。

flag

不改变流量的任何方面——只记录一条匹配。在执行某条规则之前 衡量它会触发的频率。
一个好的上线节奏是 flag → mask → block：flag 以衡量影响， 信任检测器后改为 mask，并把 block 留给那些你完全不能放行的 字段。参见动作和 调优误报。

​
6. 验证什么被脱敏了

每条触发的规则都会在工作区 Matches 信息流中记录一条 匹配——规则类型、动作、阶段和一个详情字符串。匹配的子串 本身（原始 email、实际卡号）仅在开启 Log raw content 时才记录，而它默认关闭——隐私保守的姿态，因为整个重点就是 让原始值不进入你的日志。
只有在你确实需要子串进行分诊时才开启 Log raw content，并且 只按防护栏开启。关闭它时，信息流证明一个 [CREDIT_CARD] 被脱敏 了，而永不存储号码。该开关不可追溯。参见 日志与隐私。

​
7. 接下来去哪里

  • PII Shield 预设——你可以一键 应用的单规则、全脱敏起点。
  • 自定义 PII 实体——用 mask_with 和可选的 luhn 编写你自己的正则检测器。
  • 输入阶段规则——脱敏今天 实时运行的地方，在模型之前、计量之前。
  • 拦截密钥——对于凭证， 拦截（而不是脱敏）才是正确选择。
  • 流式覆盖——今天哪些 阶段/流组合是脱敏 vs. 拦截。
阅读防护栏参考以了解完整引擎，或阅读 PII 暴露和 密钥泄露以了解脱敏专为 遏制的威胁。