Traces 的 PII Redaction

概览

PII Redaction 是 CrewAI AMP 的一项功能，可自动检测并掩码 crew 和 flow 执行轨迹中的 Personally Identifiable Information（PII）。这能确保信用卡号、社会安全号码、电子邮件地址和姓名等敏感数据不会暴露在 CrewAI AMP traces 中。你也可以创建自定义 recognizers 来保护组织特有的数据。

为什么 PII Redaction 很重要

在生产环境中运行 AI agents 时，敏感信息经常会在 crews 中流动：

来自 CRM 集成的客户数据
来自支付处理器的财务信息
来自表单提交的个人信息
内部员工数据

如果没有正确 redaction，这些数据就会出现在 traces 中，使 GDPR、HIPAA 和 PCI-DSS 等法规的合规变得困难。PII Redaction 会在数据被存入 traces 之前自动对其进行 masking。

工作原理

Detect - 扫描 trace 事件数据中的已知 PII 模式
Classify - 识别敏感数据类型（信用卡、SSN、邮箱等）
Mask/Redact - 根据你的配置，用掩码值替换敏感数据

Original: "Contact [email protected] or call 555-123-4567"
Redacted: "Contact <EMAIL_ADDRESS> or call <PHONE_NUMBER>"

启用 PII Redaction

进入 Crew Settings

在 CrewAI AMP 仪表板中，选择你已部署的 crew，并进入其某个部署/自动化，然后导航到 Settings → PII Protection。
启用 PII Protection

打开 PII Redaction for Traces。这会启用对 trace 数据的自动扫描和 redaction。

Info

你需要为每个部署手动启用 PII Redaction。
配置实体类型

选择要检测和 redaction 的 PII 类型。每个实体都可以单独启用或禁用。
保存

保存配置。之后所有新的 crew 执行都会启用 PII redaction，无需重新部署。

支持的实体类型

CrewAI 支持以下按类别组织的 PII 实体类型。

全局实体

Entity	Description	Example
`CREDIT_CARD`	信用卡/借记卡号码	”4111-1111-1111-1111”
`CRYPTO`	加密货币钱包地址	”bc1qxy2kgd…”
`DATE_TIME`	日期和时间	”January 15, 2024”
`EMAIL_ADDRESS`	电子邮件地址	”[email protected]”
`IBAN_CODE`	国际银行账号	”DE89 3704 0044 0532 0130 00”
`IP_ADDRESS`	IPv4 和 IPv6 地址	”192.168.1.1”
`LOCATION`	地理位置	”New York City”
`MEDICAL_LICENSE`	医疗执照号码	”MD12345”
`NRP`	国籍、宗教或政治群体	-
`PERSON`	个人姓名	”John Doe”
`PHONE_NUMBER`	多种格式的电话号码	”+1 (555) 123-4567”
`URL`	网页 URL	”https://example.com”

美国特定实体

Entity	Description	Example
`US_BANK_NUMBER`	美国银行账号	”1234567890”
`US_DRIVER_LICENSE`	美国驾照号码	”D1234567”
`US_ITIN`	个人纳税人识别号	”900-70-0000”
`US_PASSPORT`	美国护照号码	”123456789”
`US_SSN`	社会安全号码	”123-45-6789”

Redaction 动作

对于每个已启用实体，你可以配置数据如何被 redaction：

Action	Description	Example Output
`mask`	用实体类型标签替换	`<CREDIT_CARD>`
`redact`	完全移除文本	(empty)

自定义 Recognizers

除了内置实体之外，你还可以创建 custom recognizers 来检测组织特有的 PII 模式。

Recognizer 类型

你有两种自定义 recognizer 可选：

Type	Best For	Example Use Case
Pattern-based (Regex)	具有可预测格式的结构化数据	薪资金额、员工 ID、项目代码
Deny-list	精确字符串匹配	公司名称、内部代号、特定术语

创建自定义 Recognizer

进入 Custom Recognizers

前往组织 Settings → Organization → Add Recognizer。
配置 Recognizer

配置以下字段：
- Name：该 recognizer 的描述性名称
- Entity Type：会出现在 redacted 输出中的实体标签（例如 EMPLOYEE_ID、SALARY）
- Type：在 Regex Pattern 或 Deny List 之间选择
- Pattern/Values：正则表达式模式或需要匹配的字符串列表
- Confidence Threshold：触发 redaction 所需的最低分数（0.0-1.0）。更高的值（例如 0.8）可减少误报，但可能漏掉部分匹配；更低的值（例如 0.5）会捕获更多匹配，但可能过度 redaction。默认值为 0.8。
- Context Words（可选）：在附近出现时会提升检测置信度的词语
保存

保存 recognizer。它之后就可以在你的部署中启用。

理解实体类型

Entity Type 决定了匹配到的内容在 redacted traces 中如何显示：

Entity Type: SALARY
Pattern: salary:\s*\$\s*\d+
Input: "Employee salary: $50,000"
Output: "Employee <SALARY>"

使用上下文词

上下文词会在匹配模式附近出现特定术语时提升置信度，从而提高准确性：

Context Words: "project", "code", "internal"
Entity Type: PROJECT_CODE
Pattern: PRJ-\d{4}

当 “project” 或 “code” 出现在 “PRJ-1234” 附近时，recognizer 会更有把握认为这是一个真实匹配，从而减少误报。

查看已 redacted 的 traces

一旦启用 PII redaction，你的 traces 就会用 redacted 值替换敏感数据：

Task Output: "Customer <PERSON> placed order #12345.
Contact email: <EMAIL_ADDRESS>, phone: <PHONE_NUMBER>.
Payment processed for card ending in <CREDIT_CARD>."

redacted 值会以尖括号和实体类型标签（例如 <EMAIL_ADDRESS>）清晰标记，这样你既能知道哪些数据被保护了，也能继续调试和监控 crew 行为。

最佳实践

性能考虑

只启用需要的实体

每个已启用实体都会增加处理开销。只启用与你数据相关的实体。
使用更具体的模式

对于自定义 recognizers，请使用更具体的模式，以减少误报并提升性能。Regex 模式最适合识别 traces 中的特定模式，例如 salary、employee id、project code 等。Deny-list recognizers 最适合识别 traces 中的精确字符串，例如公司名称、内部代号等。
利用上下文词

上下文词通过仅在周围文本匹配时才触发检测，从而提高准确性。

故障排查

PII Not Being Redacted

可能原因：

配置中未启用该实体类型
模式与数据格式不匹配
自定义 recognizer 有语法错误

解决办法：

验证实体已在 Settings → Security 中启用
使用示例数据测试正则表达式模式
查看日志中的配置错误

Too Much Data Being Redacted

可能原因：

启用了过于宽泛的实体类型（例如 DATE_TIME 会抓取到所有日期）
自定义 recognizer 模式过于宽泛

解决办法：

禁用会产生误报的实体
让自定义模式更具体
添加上下文词以提升准确性

Performance Issues

可能原因：

启用了过多实体
基于 NLP 的实体（PERSON、LOCATION、NRP）计算开销较大，因为它们使用机器学习模型

解决办法：

只启用你实际需要的实体
在可行时考虑使用基于模式的替代方案
在仪表板中监控 trace 处理时间

实际示例：薪资模式匹配

这个示例演示如何创建一个自定义 recognizer，用于检测并掩码 traces 中的薪资信息。

用例

你的 crew 处理包含薪资信息的员工或财务数据，格式例如：

salary: $50,000
salary: $125,000.00
salary:$1,500.50

你希望自动掩码这些值，以保护敏感的薪酬数据。

配置

Field	Value
Name	`SALARY`
Entity Type	`SALARY`
Type	Regex Pattern
Regex Pattern	`salary:\s\$\s\d{1,3}(,\d{3})*(\.\d{2})?`
Action	Mask
Confidence Threshold	`0.8`
Context Words	`salary, compensation, pay, wage, income`

正则表达式拆解

Pattern Component	Meaning
`salary:`	匹配字面文本 “salary:“
`\s*`	匹配零个或多个空白字符
`\|	匹配美元符号（已转义）
`\s*`	匹配 `$` 后的零个或多个空白字符
`\d{1,3}`	匹配 1-3 位数字（例如 “1”、“50”、“125”）
`(,\d{3})*`	匹配千位分隔的逗号（例如 “,000”、“,500,000”）
`(\.\d{2})?`	可选匹配 cents（例如 “.00”、“.50”）

示例结果

Original: "Employee record shows salary: $125,000.00 annually"
Redacted: "Employee record shows <SALARY> annually"

Original: "Base salary:$50,000 with bonus potential"
Redacted: "Base <SALARY> with bonus potential"

为你的部署启用 recognizer

创建自定义 recognizer 后，请为每个部署启用它：

进入你的部署

前往你的部署/自动化，并打开 Settings → PII Protection。
选择 Custom Recognizers

在 Mask Recognizers 下方，你会看到组织定义的 recognizers。勾选你想启用的 recognizers。
保存配置

保存更改。该 recognizer 将在此部署后续的所有执行中生效。