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

前提条件

开始前请准备：

阅读安全护栏行为，了解钩子点、执行模式和远程故障处理方式。
以下配置路径之一：
- AISIX Cloud，其中包含环境、已接入的网关和具有写权限范围的 Admin Token。对于 On-Premises，请按照 AISIX Cloud 快速入门操作。如需申请混合云访问权限，请联系 API7。
- 加载声明式 resources.yaml 文件的开源 AISIX 网关。
可以发送 Chat Completions 请求的模型别名和调用方 API Key。
Docker，用于运行本指南中的 Presidio analyzer 和 anonymizer 容器。
curl。AISIX Cloud 路径还会使用 jq。

启动 Presidio

对于本地 Docker 评估，请创建网络并在其中启动两个 Presidio 服务：

docker network create aisix-guardrails
docker run -d --name presidio-analyzer --network aisix-guardrails \
  -p 5002:3000 mcr.microsoft.com/presidio-analyzer:latest
docker run -d --name presidio-anonymizer --network aisix-guardrails \
  -p 5001:3000 mcr.microsoft.com/presidio-anonymizer:latest

把网关容器连接到 aisix-guardrails，或在部署中提供等效网络连通性。开源快速入门使用以下命令：

docker network connect aisix-guardrails aisix-quickstart

从主机确认 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 安全护栏

以下示例会在两个钩子点匿名化邮箱和人名，但阻断美国社会安全号码。请选择一种配置路径，再使用通用验证步骤。

导出两种路径都会使用的网关参数：

# AISIX_PROXY 末尾不包含斜杠或端点路径。
# 本地快速入门使用 http://127.0.0.1:3000。
export AISIX_PROXY="YOUR_AISIX_GATEWAY_URL"
export AISIX_API_KEY="YOUR_CALLER_API_KEY"
export AISIX_MODEL="gpt-4o-mini"

AISIX Cloud

导出控制平面连接参数：

# AISIX_CP 包含 /api，末尾不包含斜杠。
# 本地 On-Premises 快速入门使用 http://localhost:8080/api。
export AISIX_CP="YOUR_AISIX_CLOUD_ADMIN_API_BASE_URL"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"

创建安全护栏并获取其 ID：

export GUARDRAIL_ID=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/guardrails" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "presidio-pii-policy",
    "enabled": false,
    "hook_point": "both",
    "fail_open": false,
    "kind": "presidio",
    "config": {
      "analyzer_url": "http://presidio-analyzer:3000",
      "anonymizer_url": "http://presidio-anonymizer:3000",
      "entities": [
        {
          "type": "EMAIL_ADDRESS"
        },
        {
          "type": "PERSON"
        },
        {
          "type": "US_SSN",
          "action": "block"
        }
      ],
      "default_action": "mask",
      "operator": "replace",
      "score_threshold": 0.5,
      "language": "en"
    }
  }' | jq -r '.guardrail.id')

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

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

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

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

安全护栏只有附加到 Scope 后才会生效。将其附加到整个环境：

curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/guardrails/$GUARDRAIL_ID/attachments" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scope_type": "env"
  }'

env Scope 会将安全护栏应用到环境中的所有流量，不需要 scope_id。如需缩小范围，请将 scope_type 设置为 model、api_key 或 team，并通过 scope_id 传入对应资源 ID。

Attachment 存在后启用安全护栏：

curl -sS -X PATCH "$AISIX_CP/environments/$ENV_ID/guardrails/$GUARDRAIL_ID" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

启用后的配置会自动投射到已接入的网关。

开源 AISIX 网关

在已定义示例模型和调用方 API Key 的资源文件中添加安全护栏：

resources.yaml
guardrails:
  - name: presidio-pii-policy
    enabled: true
    hook_point: both
    fail_open: false
    kind: presidio
    analyzer_url: http://presidio-analyzer:3000
    anonymizer_url: http://presidio-anonymizer:3000
    entities:
      - type: EMAIL_ADDRESS
      - type: PERSON
      - type: US_SSN
        action: block
    default_action: mask
    operator: replace
    score_threshold: 0.5
    language: en

模型服务提供方字段直接位于安全护栏条目下，而不是 config 下。请使用网关进程可以访问的 analyzer 和 anonymizer URL。资源文件中每个已启用安全护栏都会应用于该网关处理的所有请求。

请验证完整文件，然后重新加载网关。可运行的 Docker 工作流参见重新加载资源文件。

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

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

验证匿名化

AISIX Cloud 投射是异步的。如果第一个请求尚未体现安全护栏，请等待网关应用最新修订后重试。收敛检查参见资源投射。

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

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

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

email <EMAIL_ADDRESS> about the order

验证阻断

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

curl -sSi -X POST "$AISIX_PROXY/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  --data-binary @- <<EOF
  {
    "model": "${AISIX_MODEL}",
    "messages": [
      {
        "role": "user",
        "content": "my ssn is 123-45-6789"
      }
    ]
  }
EOF

响应以 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 安全护栏​

AISIX Cloud​

开源 AISIX 网关​

验证匿名化​

验证阻断​

重写限制​

下一步​