跳到主要内容

Alibaba Cloud AI Guardrails

Alibaba Cloud AI Guardrails 将审核策略保存在 AI Guardrails 控制台中，AISIX 通过 MultiModalGuard API 将策略判定应用到网关流量。请求可以在到达上游模型前检查，响应也可以在返回调用方前检查。每次调用还会显示在 AI Guardrails 控制台自身的记录中，便于在阿里云侧审计判定。

它与 Alibaba Cloud Content Moderation（aliyun_text_moderation、TextModerationPlus API）是不同的阿里云产品：两者需单独开通和计费，检测与阻断策略在各自的控制台配置，调用也只会出现在对应产品的控制台中。如果你在 AI Guardrails 控制台管理策略，或需要在一次调用中组合执行内容合规、提示词攻击检测和敏感数据处理，请使用本安全护栏。

本指南将创建一个 Alibaba Cloud AI Guardrails 资源，发送一个允许请求，并观察由控制台策略驱动的阻断和敏感数据脱敏。

准备工作​

请先准备以下内容：

  • 阅读安全护栏行为，了解钩子点、执行模式和远程故障处理方式。
  • 以下配置路径之一：
    • AISIX Cloud，其中包含环境、已接入的网关和具有写权限范围的 Admin Token。对于 On-Premises，请按照 AISIX Cloud 快速入门操作。如需申请混合云访问权限，请联系 API7。
    • 加载声明式 resources.yaml 文件的开源 AISIX 网关。
  • 可以发送 Chat Completions 请求的模型别名和调用方 API Key。
  • 已在账号中开通 Alibaba Cloud AI Guardrails 服务（商品 lvwang_guardrail_public_cn，按量付费）。如果未开通，每次调用都会以业务代码 408 失败，并在消息中指出该商品。
  • 一个允许调用 MultiModalGuard API Action 的阿里云 AccessKey（RAM 权限 yundun-greenweb:MultiModalGuard）。
  • 已在 AI Guardrails 控制台启用检测和阻断策略。结果由控制台策略而非 AISIX 决定：设置为阻断的检查模块返回 block，设置为脱敏的模块返回 mask，仅观察的模块返回 watch（AISIX 会放行）。未启用的模块不会运行。例如，敏感数据脱敏需要启用敏感数据检查并选择脱敏动作；在此之前，此类请求会返回 pass，且不含 sensitiveData 结果。
  • curl。AISIX Cloud 路径还会使用 jq。

创建 Alibaba Cloud AI Guardrail​

以下示例使用 pro 服务层级检查请求和响应。请选择一种配置路径，再使用通用验证步骤。

导出两种路径都会使用的网关和模型服务提供方参数：

# 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"
export ALIBABA_CLOUD_ACCESS_KEY_ID="YOUR_ALIBABA_CLOUD_ACCESS_KEY_ID"
export ALIBABA_CLOUD_ACCESS_KEY_SECRET="YOUR_ALIBABA_CLOUD_ACCESS_KEY_SECRET"

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"

在环境中创建 Alibaba Cloud AI Guardrails 资源并获取其 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": "aliyun-ai-guard",
    "enabled": false,
    "hook_point": "both",
    "fail_open": false,
    "kind": "aliyun_ai_guardrail",
    "config": {
      "region": "cn-shanghai",
      "access_key_id": "'"${ALIBABA_CLOUD_ACCESS_KEY_ID}"'",
      "access_key_secret": "'"${ALIBABA_CLOUD_ACCESS_KEY_SECRET}"'",
      "output_fail_open": false,
      "service_level": "pro",
      "timeout_ms": 3000
    }
  }' | jq -r '.guardrail.id')

❶ both 同时检查调用方请求和模型响应。参见安全护栏检查位置。

❷ fail_open: false 表示当 Alibaba Cloud AI Guardrails 失败或超时时阻断请求。默认值为 true。

❸ output_fail_open: false 表示阿里云服务中断时阻断未经扫描的模型输出。这是默认值。

❹ service_level 选择 API 层级：pro（默认值）调用 query_security_check_pro 和 response_security_check_pro；basic 调用 query_security_check 和 response_security_check。该值必须与账号中开通的层级一致。

❺ timeout_ms 限制 AISIX 等待安全护栏判定的最长时间。

AISIX 根据 region 推导端点（green-cip.<region>.aliyuncs.com）。只有需要覆盖该主机时，才在 config 中将 endpoint 设置为完整 URL。

无需配置本地风险阈值。AI Guardrails 控制台会根据已配置策略计算总体建议，AISIX 会遵循该建议。

将安全护栏附加到环境，使其应用到所有流量：

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 的资源文件中添加安全护栏。示例从 ALIBABA_CLOUD_ACCESS_KEY_ID 和 ALIBABA_CLOUD_ACCESS_KEY_SECRET 读取凭证。已经运行的快速入门容器不会继承之后才在主机上导出的变量。

resources.yaml
guardrails:
  - name: aliyun-ai-guard
    enabled: true
    hook_point: both
    fail_open: false
    kind: aliyun_ai_guardrail
    region: cn-shanghai
    access_key_id: ${ALIBABA_CLOUD_ACCESS_KEY_ID}
    access_key_secret: ${ALIBABA_CLOUD_ACCESS_KEY_SECRET}
    output_fail_open: false
    service_level: pro
    timeout_ms: 3000

模型服务提供方字段直接位于安全护栏条目下，而不是 config 下。AISIX 根据 region 推导端点；只有网关需要使用其他完整 URL 时才设置 endpoint。

资源文件中每个已启用安全护栏都会应用于该网关处理的所有请求。重新加载或重建网关前，请验证完整文件。扩展开源快速入门时，请按照重新加载资源文件操作，只在验证成功后重建容器，并传入额外凭证变量。

AISIX 如何应用建议​

每个 MultiModalGuard 响应都包含由控制台策略基于所有检测维度（内容合规、提示词攻击、敏感数据等）计算的建议。AISIX 将其映射为网关判定：

建议AISIX 行为
pass请求或响应不经修改并继续处理。
watch内容不经修改并继续处理；检测详情会记录到网关日志。
blockAISIX 以 422 content_filter 拒绝请求（或在监控模式下记录本应阻断）。
mask当请求路径和流式模式支持替换时，AISIX 会改写内容；否则会阻断内容。参见敏感数据脱敏。

验证安全护栏​

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

通过 AISIX 发送一个正常请求：

curl -sSi -X POST "$AISIX_PROXY/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"${AISIX_MODEL}"'",
    "messages": [
      {
        "role": "user",
        "content": "What is the capital of France?"
      }
    ]
  }'

成功响应以 HTTP/1.1 200 OK 开头，并返回兼容 OpenAI 的 Chat Completions 响应体。

为了让检查结果可重复，请使用控制台策略已配置为阻断的内容，例如启用提示词攻击策略时使用攻击探测内容，或使用合规策略会拒绝的内容。然后发送该内容：

curl -sSi -X POST "$AISIX_PROXY/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"${AISIX_MODEL}"'",
    "messages": [
      {
        "role": "user",
        "content": "YOUR_POLICY_VIOLATING_TEXT"
      }
    ]
  }'

被阻断的响应以 HTTP/1.1 422 Unprocessable Entity 开头，并包含兼容 OpenAI 的错误：

{
  "error": {
    "message": "request blocked by content policy (guardrail 'aliyun-ai-guard')",
    "type": "content_filter"
  }
}

该调用也会显示在 AI Guardrails 控制台的记录中，可查看同一判定在各检测维度上的详情。

敏感数据脱敏​

当控制台中的敏感数据策略设置为脱敏时，阿里云会返回已替换敏感片段的内容，AISIX 再将改写结果写回请求或响应：

  • 在输入检查位置，上游模型收到脱敏后的提示词。
  • 在输出检查位置，调用方收到脱敏后的响应。

对流式响应执行脱敏需要先暂存完整响应。因此，需要脱敏流式输出的安全护栏应设置 stream_processing_mode: "buffer_full"。在 AISIX Cloud 中把该字段添加到 config 内；在开源资源文件中直接添加到安全护栏条目下。

默认的 window 模式会逐步放行已扫描窗口，无法改写已经发送到网络上的内容；如果流中途收到 mask 建议，它会被视为 block，从而避免放行未脱敏内容。非流式请求和响应在两种模式下都可脱敏。

如果阿里云建议 mask 却未返回脱敏文本，AISIX 会阻断请求，不会放行策略要求脱敏的内容。

内容大小限制​

AISIX 每次调用最多向 MultiModalGuard 发送 2,000 个字符。对于非流式请求和响应，AISIX 会拼接提取出的文本，并发送前 2,000 个字符用于决策。对于使用 window 模式的流式响应，AISIX 会将内容划分为不超过 2,000 个字符的重叠窗口，并逐个检查。

流式输出​

流式响应使用安全护栏行为中介绍的共享流式控制进行增量检查。同一响应的每个窗口使用相同的 sessionId 和 chatId，因此阿里云会在控制台中将这些窗口归为同一条会话记录。

将判定追踪到阿里云​

每个 AISIX 响应都包含 x-aisix-request-id 请求头。在网关日志中搜索该值；审核判定与阿里云自身的 RequestId 会记录在同一条日志中：

INFO request{request_id=12179fb5-5c3c-4a2a-a411-d73746379cc6}: aisix_guardrails::aliyun_ai_guardrail:
aliyun AI guardrail blocked content row=aliyun-ai-guard service="query_security_check_pro"
aliyun_request_id=019F6EF3-6F9A-5A25-9EED-256CB0E26448 aliyun_code=200 aliyun_suggestion=block
aliyun_dimensions=promptAttack:high/block,contentModeration:none/pass aliyun_labels=prompt_injection
字段含义
request_id网关请求 ID，与调用方收到的 x-aisix-request-id 相同。
aliyun_request_id阿里云为该调用生成的 RequestId。使用它在 AI Guardrails 控制台中查找记录，或提交给阿里云支持。
aliyun_suggestionAISIX 实际执行的总体建议。
aliyun_dimensions所有已运行的检测维度，格式为 type:level/suggestion。大多数维度使用 none/low/medium/high 等级；敏感数据维度使用 S0–S3。
aliyun_labels检测到内容的类别。干净扫描不会记录此字段。

放行请求会以 debug 级别记录相同字段。日志永远不会记录匹配到的文本，只记录类别标签，因此网关日志不会泄露调用方内容。

排查配置错误​

当 fail_open: false 时，无法获得判定的安全护栏会阻断请求。因此，配置错误和策略命中都会以相同的 422 content_filter 返回调用方。日志会以 error 级别区分它们：

日志信号原因
业务代码 408，消息中提到 lvwang_guardrail_public_cn账号未开通 AI Guardrails 服务，或 service_level 指定了账号尚未开通的层级。请在阿里云控制台开通该商品。
aliyun_code=SignatureDoesNotMatchaccess_key_secret 错误。
aliyun_code=InvalidAccessKeyId.NotFoundaccess_key_id 错误，或该密钥已禁用。
提到 RAM 策略的身份认证或权限错误RAM 用户缺少 yundun-greenweb:MultiModalGuard 权限。

与 Content Moderation 安全护栏一样，AISIX 会记录错误代码，但不会记录错误响应体。签名错误的响应体会向发送方引用完整的已签名请求，其中包括调用方提示词。

在两种阿里云安全护栏之间选择​

aliyun_ai_guardrail（本页）aliyun_text_moderation
阿里云产品AI Guardrails（MultiModalGuard）Content Moderation（TextModerationPlus）
策略位置AI Guardrails 控制台策略根据返回的风险等级使用 AISIX 侧 risk_level_threshold
检查内容合规、提示词攻击、敏感数据等组合检查基于风险等级的内容审核
动作阻断和敏感数据脱敏阻断
控制台调用记录有，位于 AI Guardrails 控制台没有 AI Guardrails 记录（属于 Content Moderation 产品）
开通项lvwang_guardrail_public_cn 商品Content Moderation 增强版 API

后续步骤​

你已经配置 Alibaba Cloud AI Guardrails，并验证了由策略驱动的判定。可使用以下指南调整行为或比较相关服务：