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 失败或超时时阻断请求。这是默认值。

❸ 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（阿里云 AI 安全护栏）
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

guardrail_attachments:
  - guardrail_id: aliyun-ai-guard
    scope_type: env
    priority: 100

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

安全护栏只在 Attachment 指定的范围内生效：请添加 guardrail_attachments 条目引用它，否则它虽然会被加载，但不会检查任何流量。重新加载或重建网关前，请验证完整文件。扩展开源快速入门时，请按照重新加载资源文件操作，只在验证成功后重建容器，并传入额外凭证变量。

AISIX 如何应用建议

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

建议	AISIX 行为
`pass`	请求或响应不经修改并继续处理。
`watch`	内容不经修改并继续处理；检测详情会记录到网关日志。
`block`	AISIX 以 `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_suggestion`	AISIX 实际执行的总体建议。
`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=SignatureDoesNotMatch`	`access_key_secret` 错误。
`aliyun_code=InvalidAccessKeyId.NotFound`	`access_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，并验证了由策略驱动的判定。可使用以下指南调整行为或比较相关服务：

安全护栏行为：调整检查位置、执行模式、流式输出或远程故障处理。
Alibaba Cloud Content Moderation：使用 TextModerationPlus 并在 AISIX 侧配置风险阈值的安全护栏。
选择安全护栏服务提供方：对比 Alibaba Cloud AI Guardrails 与其他内置和远程选项。

准备工作​

创建 Alibaba Cloud AI Guardrail​

AISIX Cloud​

开源 AISIX 网关​

AISIX 如何应用建议​

验证安全护栏​

敏感数据脱敏​

内容大小限制​

流式输出​

将判定追踪到阿里云​

排查配置错误​

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

后续步骤​