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 资源，发送一个允许请求，并观察由控制台策略驱动的阻断和敏感数据脱敏。

准备工作

请先准备以下内容：

阅读安全护栏行为，了解检查位置、执行模式和远程故障处理。
一个 Admin 和代理监听器都可用的自托管 AISIX 网关。
网关 config.yaml 中的 Admin Key。
一个可以发送 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 结果。

创建 Alibaba Cloud AI Guardrail

在 AISIX 中创建 Alibaba Cloud AI Guardrails 资源：

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/guardrails" \
  -H "Authorization: Bearer YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "aliyun-ai-guard",
    "enabled": true,
    "hook_point": "both",
    "fail_open": false,
    "output_fail_open": false,
    "kind": "aliyun_ai_guardrail",
    "region": "cn-shanghai",
    "access_key_id": "YOUR_ALIBABA_CLOUD_ACCESS_KEY_ID",
    "access_key_secret": "YOUR_ALIBABA_CLOUD_ACCESS_KEY_SECRET",
    "service_level": "pro",
    "timeout_ms": 3000
  }'

❶ 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）。只有需要覆盖该主机时，才将 endpoint 设置为完整 URL。

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

AISIX 如何应用建议

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

建议	AISIX 行为
`pass`	请求或响应不经修改并继续处理。
`watch`	内容不经修改并继续处理；检测详情会记录到网关日志。
`block`	AISIX 以 `422 content_filter` 拒绝请求（或在监控模式下记录本应阻断）。
`mask`	AISIX 使用阿里云返回的脱敏文本改写内容，然后继续处理。参见敏感数据脱敏。

验证安全护栏

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

curl -sSi -X POST "http://127.0.0.1:3000/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_CALLER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-prod",
    "messages": [
      {
        "role": "user",
        "content": "What is the capital of France?"
      }
    ]
  }'

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

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

curl -sSi -X POST "http://127.0.0.1:3000/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_CALLER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-prod",
    "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"。stream_processing_mode 是安全护栏资源自身的字段，可将其加入上面的创建请求，也可以稍后更新资源。默认的 window 模式会逐步放行已扫描窗口，无法改写已经发送到网络上的内容；如果流中途收到 mask 建议，它会被视为 block，从而避免放行未脱敏内容。非流式请求和响应在两种模式下都可脱敏。

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

流式输出

流式响应使用安全护栏行为中介绍的共享流式控制进行增量检查。同一响应的每个窗口使用相同的 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 Content Moderation：使用 TextModerationPlus 并在 AISIX 侧配置风险阈值的安全护栏。
选择安全护栏服务提供方：对比 Alibaba Cloud AI Guardrails 与其他内置和远程选项。

准备工作​

创建 Alibaba Cloud AI Guardrail​

AISIX 如何应用建议​

验证安全护栏​

敏感数据脱敏​

流式输出​

将判定追踪到阿里云​

排查配置错误​

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

后续步骤​