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 安全护栏，并验证匿名化和阻断行为。

前提条件

开始前请准备：

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

启动 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"
      }
    ],
    // 标注 2
    "default_action": "mask",
    // 标注 3
    "operator": "replace",
    // 标注 4
    "score_threshold": 0.5,
    "language": "en"
  }'

❶ entities 会将检测限制为列出的 Presidio entities。entities 为空时，会使用 Presidio 的完整识别器集合。

❷ default_action: "mask" 会匿名化列出的实体，除非条目覆盖了该动作。本示例通过 action: "block" 阻断美国社会安全号码。

❸ operator: "replace" 会将掩码值替换为 <EMAIL_ADDRESS> 这类实体占位符。当下游系统需要稳定假名而不是占位符时，可使用 hash。

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

由于该安全护栏使用 hook_point: both，AISIX 也会在模型响应返回调用方前应用相同的匿名化。原始请求值不会到达服务提供方，原始响应值不会到达调用方。对于流式模型响应，请参见流式输出。

命中的值也不会写入网关日志和用量记录。用量记录只包含按实体名称统计的脱敏次数。

完整请求和响应 schema 请参见 Admin API 参考中的创建安全护栏。

验证匿名化

发送包含邮箱地址的提示词：

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"
      }
    ]
  }'

如果上游模型调用成功，响应会以 HTTP/1.1 200 OK 开头。AISIX 在调用上游模型前匿名化提示词，因此服务提供方收到的是：

email <EMAIL_ADDRESS> about the order

验证阻断

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

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 开头，并包含标准内容过滤错误：

{
  "error": {
    "message": "request blocked by content policy (guardrail 'presidio-pii-policy')",
    "type": "content_filter"
  }
}

命中的原始值不会回显。

重写限制

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

下一步

你已经配置 Microsoft Presidio 并验证了匿名化和阻断。使用下面的指南调整行为或比较相关安全护栏：

安全护栏行为：调整执行模式、流式输出和远程故障处理方式。
PII 检测与脱敏：当基于规则的匹配已经足够时，使用内置敏感数据检测。
选择安全护栏服务提供方：对比 Microsoft Presidio 和其它内置、远程选项。

前提条件​

启动 Presidio​

创建 Presidio 安全护栏​

验证匿名化​

验证阻断​

重写限制​

下一步​