Alibaba Cloud Content Moderation

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

它与 Alibaba Cloud AI Guardrails（aliyun_ai_guardrail、MultiModalGuard API）是不同的阿里云产品。如果你需要在 AI Guardrails 控制台中管理策略、执行提示词攻击检测和敏感数据脱敏等组合检查，或希望在该控制台的记录中查看调用，请使用 AI Guardrails。

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

准备工作

请先准备以下内容：

阅读安全护栏行为，了解检查位置、执行模式和远程故障处理方式。
一个 Admin 和代理监听器都可用的自托管 AISIX 网关。
网关 config.yaml 中的 Admin Key。
一个可以发送 Chat Completions 请求的模型别名和调用方 API Key。
已在目标地域开通的 Alibaba Cloud Content Moderation 增强版 API。
一个允许调用 TextModerationPlus API action 的阿里云 AccessKey ID 和 AccessKey Secret。

创建 Alibaba Cloud Content Moderation 安全护栏

在 AISIX 中创建 Alibaba Cloud Content Moderation 资源：

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-review",
    "enabled": true,
    "hook_point": "both",
    "fail_open": false,
    "output_fail_open": false,
    "enforcement_mode": "block",
    "kind": "aliyun_text_moderation",
    "region": "cn-shanghai",
    "access_key_id": "YOUR_ALIBABA_CLOUD_ACCESS_KEY_ID",
    "access_key_secret": "YOUR_ALIBABA_CLOUD_ACCESS_KEY_SECRET",
    "risk_level_threshold": "medium",
    "timeout_ms": 3000
  }'

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

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

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

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

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

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

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

如后续需要查看、更新或删除该资源，请复制返回的安全护栏 ID。

验证安全护栏

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

为了让检查结果可重复，请使用会被你的 Alibaba Cloud Content Moderation 配置判定为达到或高于 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": "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`	阻断低风险、中风险和高风险判定。

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

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

被阻止的响应只会告诉调用方内容策略拒绝了请求。若要了解某个请求被阻止的具体原因，请将其与阿里云控制台中的审核记录关联起来。

每个 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

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 安全护栏​

验证安全护栏​

调整风险阈值​

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

422 表示配置错误的情况​

下一步​