版本：Dev

Alibaba Cloud Content Moderation

Alibaba Cloud Content Moderation 通过 TextModerationPlus API 为内容评定风险等级，AISIX 会阻断返回等级达到配置阈值的请求。请求可以在到达上游模型前检查，响应也可以在返回调用方前检查。

它与 Alibaba Cloud AI Guardrails（aliyun_ai_guardrail、MultiModalGuard API）使用不同的审核 API 和 AISIX 安全护栏类型。如果你需要在 AI Guardrails 控制台中管理策略，或执行提示词攻击检测和敏感数据脱敏等组合检查，请使用 AI Guardrails。调用记录能否查询不能仅按这两种 API 区分。

本指南将创建一个 Alibaba Cloud Content Moderation 资源，发送一个允许请求，并发送一个会在到达上游模型前被 AISIX 拒绝的阻断请求。

准备工作

请先准备以下内容：

阅读安全护栏行为，了解钩子点、执行模式和远程故障处理方式。
以下配置路径之一：
- AISIX Enterprise 或 AISIX Cloud，其中包含环境、已接入的网关和具有写权限范围的 Admin Token。对于 AISIX Enterprise，请按照 AISIX Enterprise 快速入门操作。如需申请 AISIX Cloud 访问权限，请联系 API7。
- 加载声明式 resources.yaml 文件的开源 AISIX 网关。
可以发送 Chat Completions 请求的模型别名和调用方 API Key。
已在目标地域开通的 Alibaba Cloud Content Moderation 增强版 API。
一个允许调用 TextModerationPlus API Action 的阿里云 AccessKey ID 和 AccessKey Secret。
curl。控制面路径还会使用 jq。

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

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

创建 Alibaba Cloud Content Moderation 安全护栏

请选择一种配置路径创建安全护栏，再使用通用验证步骤。

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 Content Moderation 资源并获取其 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-review",
    "enabled": false,
    "hook_point": "both",
    "fail_open": false,
    "enforcement_mode": "block",
    "kind": "aliyun_text_moderation",
    "config": {
      "region": "cn-shanghai",
      "access_key_id": "'"${ALIBABA_CLOUD_ACCESS_KEY_ID}"'",
      "access_key_secret": "'"${ALIBABA_CLOUD_ACCESS_KEY_SECRET}"'",
      "output_fail_open": false,
      "risk_level_threshold": "medium",
      "timeout_ms": 3000
    }
  }' | jq -r '.guardrail.id')

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

❷ fail_open: false 表示当 Alibaba Cloud Content Moderation 调用失败或超时时阻断请求。这是默认值。

❸ enforcement_mode: block 表示拒绝命中的内容，这是默认行为。参见执行模式。

❹ output_fail_open: false 表示阿里云服务不可用时阻断未扫描的模型输出，这是默认行为。

❺ risk_level_threshold 会阻断返回风险等级达到或高于配置阈值的内容。

❻ timeout_ms 限制的是每一次调用阿里云的完整耗时，从发送请求直到读完整个响应体，而不是整个检查。AISIX 每次调用最多向 TextModerationPlus 发送 2,000 个字符，并且从不为了满足上限而截断内容：更长的内容会被切分为多个分块，每个分块单独调用一次。这些调用依次执行，分块数量没有上限，也没有整体时限，因此总耗时约为分块数乘以单次调用耗时。阿里云按调用次数计费。

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

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

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-review
    enabled: true
    hook_point: both
    fail_open: false
    enforcement_mode: block
    kind: aliyun_text_moderation
    region: cn-shanghai
    access_key_id: ${ALIBABA_CLOUD_ACCESS_KEY_ID}
    access_key_secret: ${ALIBABA_CLOUD_ACCESS_KEY_SECRET}
    output_fail_open: false
    risk_level_threshold: medium
    timeout_ms: 3000

guardrail_attachments:
  - guardrail_id: aliyun-review
    scope_type: env
    priority: 100

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

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

验证安全护栏

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

通过 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 响应体。

为了让检查结果可重复，请使用会被你的 Alibaba Cloud Content Moderation 配置判定为达到或高于 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": "YOUR_POLICY_VIOLATING_TEXT"
      }
    ]
  }'

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

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

当 Alibaba Cloud Content Moderation 返回阻断风险等级时，AISIX 会在请求被转发到上游模型前阻断它。

调整风险阈值

阿里云会为每次审核判定返回风险等级。该等级由阿里云根据审核结果和配置的分数阈值确定，AISIX 不会重新计算。

AISIX 可以阻断 low、medium 或 high 等级：

阈值	效果
`high`	只阻断高风险判定。这是默认值。
`medium`	阻断中风险和高风险判定。
`low`	阻断低风险、中风险和高风险判定。

当应用需要拒绝更多不确定内容时，可以使用更严格的阈值；当只希望阿里云阻断最强匹配时，可以使用较宽松的阈值。

将被阻止的请求追踪到阿里云

被阻止的响应只会告诉调用方内容策略拒绝了请求。若要了解某个请求被阻止的具体原因，可通过 RequestId 关联阿里云侧可用的审核记录。记录可见性取决于所用的查询功能和记录条件；使用阿里云日志分析前还需单独开通并确认计费。

每个 AISIX 代理响应都包含 x-aisix-request-id 响应头，上述 422 响应也不例外：

HTTP/1.1 422 Unprocessable Entity
x-aisix-request-id: 12179fb5-5c3c-4a2a-a411-d73746379cc6

向调用方获取该 ID，然后在网关日志中搜索：

grep 12179fb5-5c3c-4a2a-a411-d73746379cc6 /path/to/aisix.log

审核决定以 info 级别记录。两个 ID 出现在同一条日志中，因此一次搜索即可找到。为适应页面宽度，以下示例进行了换行；实际日志中为一行：

INFO request{request_id=12179fb5-5c3c-4a2a-a411-d73746379cc6}: aisix_guardrails::aliyun:
aliyun text moderation blocked content row=aliyun-review service="llm_query_moderation"
aliyun_request_id=019F6EF3-6F9A-5A25-9EED-256CB0E26448 aliyun_code=200
aliyun_risk_level=high aliyun_labels=inappropriate_oral,violent_incidents

这里有两个不同且不可互换的 ID：

字段	含义
`request_id`	网关请求 ID，与调用方收到的 `x-aisix-request-id` 相同。
`aliyun_request_id`	阿里云为审核调用生成的 `RequestId`。使用它查询阿里云侧可用的记录，或向阿里云支持提交工单；查询结果受相应功能和记录条件限制。
`aliyun_risk_level`	阿里云返回并用于与阈值比较的风险等级。
`aliyun_labels`	阿里云匹配的类别。一个请求通常会匹配多个类别。

通过审核的请求会以 debug 级别记录相同字段。如果需要获取未被阻止请求的阿里云 RequestId，请将网关 log_level 提升为 debug。

如果网关在取得阿里云响应前超时或连接失败，aliyun_request_id 会记录为空，因为网关未取得该 ID；这并不证明阿里云没有受理该调用。随附的 failure 字段会指出失败类别。以下示例同样进行了换行：

WARN request{request_id=...}: aisix_guardrails::aliyun: aliyun text moderation call failed
row=aliyun-review aliyun_request_id= failure=Timeout fail_open=false elapsed_ms=3001

failure 之后的字段给出底层原因。http_status 是响应的状态码，只在收到响应时出现，例如响应头已返回、但响应体卡住超过了 timeout_ms。error 是底层错误及其完整的原因链，例如 DNS 解析失败或连接被拒绝；error_kind 将其归类为 connect、timeout、request、body、decode 或 other。如果调用是被网关自身的 timeout_ms 计时器终止的（如本例），这两个字段都不会出现。elapsed_ms 是从发送请求到失败所经过的时间。

阿里云会在 HTTP 200 响应中报告自身的配额限流和超时，即响应体 Code 588（EXCEED_QUOTA）和 Code 581（TIMEOUT）。AISIX 将它们归类为 aliyun_throttled 和 aliyun_timeout，与 HTTP 429 以及 timeout_ms 耗尽使用相同的失败标记。这些调用已经到达阿里云，因此 aliyun_request_id 有值，并且之前会有一条指明错误码的警告，例如 Code 581 TIMEOUT。参见各安全护栏类型发起的失败标记。

422 表示配置错误的情况

当 fail_open: false 时，无法从阿里云获得决定的安全护栏会阻止请求。因此，错误凭证和真实的策略命中都会以相同的 422 content_filter 返回给调用方。日志可区分二者：配置错误以 error 级别记录，aliyun_code 会指出具体原因。

`aliyun_code`	原因
`SignatureDoesNotMatch`	`access_key_secret` 错误。
`InvalidAccessKeyId.NotFound`	`access_key_id` 错误，或密钥已禁用。
`InvalidAction.NotFound`	`region` 或 `endpoint` 不提供此 API。

阿里云还会为其他失败返回其他代码；可在错误诊断中按名称查询任意代码。

AISIX 会记录错误代码，但不会记录阿里云随代码返回的响应体。签名错误的响应体会引用整个已签名请求，其中包含调用方的提示词和你的 AccessKey ID；将其写入日志会同时泄露这两类信息。

此流程会刻意排除以下两项内容：

阿里云的 RequestId 永远不会返回给调用方。调用方只会收到 x-aisix-request-id，其余信息由你从日志中解析。
永远不会记录阿里云匹配的文本。阿里云会在 RiskWords 和 RiskPositions 字段中返回违规词，但 AISIX 只记录类别标签，因此网关日志不会泄露调用方内容。

下一步

你已经通过 AISIX 执行了 Alibaba Cloud Content Moderation 策略。使用下面的指南调整行为或比较相关安全护栏：

安全护栏行为：调整检查位置、执行模式、流式输出或远程故障处理方式。
Alibaba Cloud AI Guardrails：使用 MultiModalGuard、在 AI Guardrails 控制台中配置策略并支持敏感数据脱敏的安全护栏。
选择安全护栏服务提供方：对比 Alibaba Cloud Content Moderation 与其他内置和远程选项。

准备工作​

创建 Alibaba Cloud Content Moderation 安全护栏​

AISIX Enterprise 或 AISIX Cloud​

开源 AISIX 网关​

验证安全护栏​

调整风险阈值​

将被阻止的请求追踪到阿里云​

422 表示配置错误的情况​

下一步​