跳到主要内容

Local PII Redact

Aidy 的 local-pii-redact 插件用于本地化部署场景：请求发往上游 LLM 前先做 PII 脱敏，上游响应返回客户端前再按本次请求内保存的 restore plan 还原。

它不替代 SaaS 形态的 guard 检测能力。两者建议二选一：SaaS 场景继续使用 plugins.guard，本地化 PII 脱敏场景使用 plugins.local_pii_redact。

启用条件​

插件只有同时满足以下条件才会进入 chat 请求链路：

  1. 静态配置 plugins.local_pii_redact.enable = true
  2. 静态配置 plugins.local_pii_redact.recognize_url 非空
  3. 当前 route 配置 plugin_config.local_pii_redact.enabled = true

插件 ID 为 local-pii-redact，静态配置 key 与 route plugin_config key 均为 local_pii_redact。

静态配置​

[plugins.local_pii_redact]
enable = true
recognize_url = "http://127.0.0.1:9015"
timeout_ms = 1500
max_recognize_chars = 0
internal_recognizer = ["cn_id_card", "email"]

[[plugins.local_pii_redact.patterns]]
name = "employee_id"
regex_pattern = "EMP-[0-9]{6}"
validator = ""

字段说明：

  • enable：全局开关。
  • recognize_url：本地 PII 服务 base URL，插件会调用 {recognize_url}/pii/recognize。
  • timeout_ms：识别服务超时，默认 1500ms；服务异常时 fail-open，不阻断业务请求。
  • max_recognize_chars：识别文本字符数告警阈值。0 表示使用默认 512；当前实现只写风险摘要，不分段、不阻断。
  • internal_recognizer：传给本地 PII 服务的内置识别器列表；未设置时省略该字段，显式空数组表示关闭内置识别器。
  • patterns：传给本地 PII 服务的自定义 pattern。validator 可为 luhn_check、chinese_id_check、chinese_phone_check、email_check 或空字符串。

Route 配置​

route 级配置用于指定当前 route 是否启用本地 PII 脱敏，plugin_key 为 local_pii_redact，配置值使用以下 proto：

运行时行为​

请求阶段，插件会从 RequestIR 中收集文本并调用本地 PII 服务：

POST /pii/recognize

请求体示例：

{
  "message": "待识别文本",
  "patterns": [],
  "internal_recognizer": ["cn_id_card", "email"]
}

当服务返回 status=unsafe 且包含 replacements 时，插件会复制 RequestIR，仅改写 canonical 文本字段，然后通过 SetRequestIR 写回。上游 LLM 看到的是占位符，例如 [证件号_1]。

响应阶段，插件使用本次请求上下文内的 restore plan 还原：

  • 非流式响应在 ResponseIR 层还原后再输出。
  • 流式响应在 StreamEventIR 层按 item / tool call 维度跨 chunk 还原。

日志​

插件不会直接写 Kafka，只会写请求日志扩展字段 ext_fields.local_pii_redact，随后由现有 plugins.log 输出。

ext_fields.local_pii_redact 使用以下 proto：

安全约束：

  • 不写 restore plan 明细。
  • 不写原始 PII。
  • 不改变 plugins.log 的 Kafka body 行为。