版本：1.8.0

Alibaba Cloud AI Guardrails

Alibaba Cloud AI Guardrails 将审核策略保存在 AI Guardrails 控制台中，AISIX 通过 MultiModalGuard API 将策略判定应用到网关流量。请求可以在到达上游模型前检查，响应也可以在返回调用方前检查。阿里云侧可通过结果查询或日志分析审计可用记录；记录可见性取决于所开通的查询功能、地域和记录条件，不能假定每次调用都会留下可查询记录。

它与 Alibaba Cloud Content Moderation（aliyun_text_moderation、TextModerationPlus API）使用不同的审核 API 和 AISIX 安全护栏类型：本页的 aliyun_ai_guardrail 集成需要开通相应商品并按其规则计费；其检测与阻断策略在自己的控制台配置。调用记录的可见范围不能仅按这两种 API 区分。如果你在 AI Guardrails 控制台管理策略，或需要在一次调用中组合执行内容合规、提示词攻击检测和敏感数据处理，请使用本安全护栏。

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

准备工作

请先准备以下内容：

阅读安全护栏行为，了解钩子点、执行模式和远程故障处理方式。
以下配置路径之一：
- AISIX Enterprise 或 AISIX Cloud，其中包含环境、已接入的网关和具有写权限范围的 Admin Token。对于 AISIX Enterprise，请按照 AISIX Enterprise 快速入门操作。如需申请 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。控制面路径还会使用 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 Enterprise 或 AISIX Cloud

导出控制面连接参数：

# AISIX_CP 包含 /api，且不含尾部斜杠
# 本地私有化部署快速入门使用 http://localhost:8080/api
export AISIX_CP="YOUR_AISIX_CONTROL_PLANE_API_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 限制的是每一次调用阿里云 API 的完整耗时，从发送请求直到读完整个响应体，而不是整个检查。超过单次调用上限的内容会分块检查，每块一次调用，且没有整体时限，因此总耗时约为分块数乘以单次调用耗时。参见内容大小限制。

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 发送一个正常请求：

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

如该调用满足所使用查询功能的记录条件，可在阿里云侧结合 RequestId 查询判定详情；未查到记录不等于安全护栏未执行。

敏感数据脱敏

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

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

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

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

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

内容大小限制

AISIX 每次调用最多向 MultiModalGuard 发送 2,000 个字符，并且从不为了满足上限而截断内容。对于非流式请求和响应，AISIX 会拼接提取出的文本，将其无损地切分为不超过 2,000 个字符的分块，并检查每一个分块。每个分块都是一次独立的 MultiModalGuard 调用。这些调用依次执行，分块数量没有上限，检查在第一个被阻断或失败的分块处停止。因此，延迟和阿里云调用次数随内容长度线性增长，而阿里云按调用次数计费。当分布在多条消息中的内容需要脱敏时，AISIX 会逐条消息再检查一次，使脱敏后的文本与原消息一一对应，这会增加调用次数。

对于使用 window 模式的流式响应，AISIX 会将内容划分为不超过 2,000 个字符的重叠窗口，并逐个检查。

如果客户端每次调用都重新发送整段对话，每个请求都要为完整历史付出检查成本。要降低这部分负载，请在安全护栏上设置 input_messages: latest_turn：输入检查将只读取最新一轮，而不是整段对话历史。参见选择输入消息窗口。

流式输出

流式响应使用安全护栏行为中介绍的共享流式控制进行增量检查。同一响应的每个窗口使用相同的 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`。使用它查询阿里云侧可用的记录，或提交给阿里云支持；查询结果受相应功能和记录条件限制。
`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`
检查	内容合规、提示词攻击、敏感数据等组合检查	基于风险等级的内容审核
动作	阻断和敏感数据脱敏	阻断
阿里云侧调用记录	日志分析的接口字段包含 `MultiModalGuard`；以功能开通情况和记录条件为准	日志分析的接口字段也包含 `TextModerationPlus`；以功能开通情况和记录条件为准
开通项	`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 Enterprise 或 AISIX Cloud​

开源 AISIX 网关​

AISIX 如何应用建议​

验证安全护栏​

敏感数据脱敏​

内容大小限制​

流式输出​

将判定追踪到阿里云​

排查配置错误​

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

后续步骤​