Microsoft Presidio 安全护栏

Presidio 安全护栏使用 Microsoft Presidio 检测和匿名化敏感数据。Presidio 是开源 PII 引擎，需要由你自行运行。AISIX 会为每个请求或响应调用 Presidio analyzer；检测到的实体可以被阻断，也可以按你选择的 operator 匿名化后继续转发。

与内置 pii 安全护栏相比，Presidio 增加了：

NER/ML 实体：可识别正则难以表达的 PERSON、LOCATION、NRP 等 Presidio 识别器实体。
匿名化 operator：可替换为实体占位符、用星号 mask、用 SHA-256 hash，或直接 redact 删除片段。
自托管部署：内容在你自己的网络内分析，不需要外部服务提供方 Key。

本指南将介绍如何在本地运行 Presidio，创建带有按实体动作配置的 Presidio 安全护栏，并验证匿名化和阻断行为。

前提条件

开始前请准备：

阅读安全护栏行为，了解 Hook 点和执行模式。
Docker，用于运行 Presidio analyzer 和 anonymizer 容器。
一个可访问 Admin 和代理监听端的自托管 AISIX 网关。
网关 config.yaml 中的 Admin Key。
一个可发送聊天补全请求的模型别名和调用方 API Key。

运行 Presidio

启动两个 Presidio 服务：

docker run -d --name presidio-analyzer -p 5002:3000 mcr.microsoft.com/presidio-analyzer:latest
docker run -d --name presidio-anonymizer -p 5001:3000 mcr.microsoft.com/presidio-anonymizer:latest

两个容器都必须能被网关访问。确认 analyzer 可响应：

curl -sS -X POST "http://127.0.0.1:5002/analyze" \\
  -H "Content-Type: application/json" \\
  -d '{ "text": "my email is alice@example.com", "language": "en" }'

响应会列出检测到的 EMAIL_ADDRESS 实体及其 offset 和 score。

创建 Presidio 安全护栏

设置示例请求使用的变量：

export AISIX_ADMIN_KEY="YOUR_ADMIN_KEY"
export AISIX_API_KEY="YOUR_CALLER_API_KEY"
export AISIX_MODEL="gpt-4o-mini"

创建一个同时作用于输入和输出的安全护栏：邮箱和人名匿名化，美国 SSN 阻断。

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/guardrails" \\
  -H "Authorization: Bearer \${AISIX_ADMIN_KEY}" \\
  -H "Content-Type: application/json" \\
  -d '{
    "name": "presidio-pii-policy",
    "enabled": true,
    "hook_point": "both",
    "fail_open": false,
    "kind": "presidio",
    "analyzer_url": "http://127.0.0.1:5002",
    "anonymizer_url": "http://127.0.0.1:5001",
    // 标注 1
    "entities": [
      { "type": "EMAIL_ADDRESS" },
      { "type": "PERSON" },
      { "type": "US_SSN", "action": "block" }
    ],
    "default_action": "mask",
    // 标注 2
    "operator": "replace",
    "language": "en",
    "score_threshold": 0.5
  }'

❶ 每个条目指定一个 Presidio entity。没有单独设置 action 的条目使用 default_action：mask 表示匿名化后继续，block 表示以 422 拒绝。entities 为空时，会使用 Presidio 的完整识别器集合，并对所有命中应用 default_action。

❷ 控制被 mask 的实体如何改写：replace（默认）替换为 <ENTITY_TYPE>，mask 替换为 *，hash 替换为原值的 SHA-256 十六进制摘要，redact 删除该片段。

score_threshold 会丢弃置信度低于阈值的 analyzer 结果；省略时接受 analyzer 返回的所有结果。

验证匿名化

发送包含邮箱地址的 Prompt：

curl -sSi -X POST "http://127.0.0.1:3000/v1/chat/completions" \\
  -H "Authorization: Bearer \${AISIX_API_KEY}" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "'"\${AISIX_MODEL}"'",
    "messages": [
      { "role": "user", "content": "email alice@example.com about the order" }
    ]
  }'

请求会成功。AISIX 在调用上游模型前匿名化 Prompt，因此服务提供方收到的是：

email <EMAIL_ADDRESS> about the order

使用 hook_point: both 时，模型响应也会在返回调用方前以同样方式匿名化。原始值不会到达服务提供方、调用方、网关日志或用量记录；用量记录只保存每类实体的脱敏次数。

使用 "operator": "hash" 时，同一 Prompt 中的邮箱会替换为 SHA-256 十六进制摘要。下游系统需要稳定假名而不是占位符时，这种方式更适合。

验证阻断

包含被阻断实体的请求会被拒绝：

curl -sSi -X POST "http://127.0.0.1:3000/v1/chat/completions" \\
  -H "Authorization: Bearer \${AISIX_API_KEY}" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "'"\${AISIX_MODEL}"'",
    "messages": [
      { "role": "user", "content": "my ssn is 123-45-6789" }
    ]
  }'

响应以 HTTP/1.1 422 Unprocessable Entity 开头，并使用标准 content_filter 错误信封。命中的原始值不会回显。

对于无法就地改写请求文本的端点（音频、图像、透传），可 mask 的命中也会改为阻断；AISIX 不会放行策略要求匿名化但无法匿名化的内容。如果 analyzer 找到 PII，但 anonymizer 调用失败，会执行下方失败策略，而不是放行未匿名化文本。

失败策略

失败	跳过原因
调用超时（`timeout_ms`，默认 `5000`，分别作用于 analyzer/anonymizer 调用）	`presidio_timeout`
Presidio 返回 HTTP 429	`presidio_throttled`
HTTP 5xx 或连接错误	`presidio_5xx`
其他 HTTP 4xx（URL、language 或 entity list 配置错误）	`presidio_config_error`

fail_open: true（默认）：调用失败时放行请求，但内容不会被匿名化，并记录跳过原因。严格 PII 策略应像示例一样设置为 false。
fail_open: false：调用失败时阻断请求。

输出 Hook 拥有独立的 output_fail_open（默认 false）。

流式响应

对流式响应做输出匿名化时，AISIX 会先缓冲响应，完整匿名化后再释放改写后的结果，因为 PII 片段可能跨越 chunk 边界。max_buffer_bytes（默认 262144）限制缓冲大小；on_buffer_exceeded（默认 fail_closed，也可设置为 fail_open）控制溢出行为。

下一步

如果基于规则的检测已经足够，进程内 pii 安全护栏可以避免运行额外服务。新实体策略建议先以 enforcement_mode: monitor 运行，审查命中率后再强制执行，详见安全护栏行为。如需对比所有服务提供方，请阅读选择安全护栏服务提供方。

前提条件​

运行 Presidio​

创建 Presidio 安全护栏​

验证匿名化​

验证阻断​

失败策略​

流式响应​

下一步​