a6-plugin-ai-content-moderation

概览

Apache APISIX提供两个内容安全审核插件，用于过滤有害内容，覆盖 LLM 请求和响应：

插件	服务提供方	请求	响应	流式传输
`ai-aws-content-moderation`	AWS Comprehend	✅	✅	✅
`ai-aliyun-content-moderation`	Aliyun Moderation Plus	✅	✅	✅

两者都必须与 ai-proxy 或 ai-proxy-multi 一起使用，以便插件审核已解码的 AI 内容。自 APISIX 3.18.0 起，AWS 支持响应与流式审核，并提供 fail_mode、角色选择以及默认值为 200 的 deny_code。字段表和协议详情请参阅 ai-aws-content-moderation 和 ai-aliyun-content-moderation。

适用场景

在内容到达 LLM 前拦截有毒、仇恨或色情内容
审核有害的 LLM 响应。非流式响应可在交付前被拒绝；流式检查无法撤回已发送的分块
通过可配置阈值执行内容策略
直接在服务或路由上应用一致的审核策略

插件执行顺序

ai-prompt-template           (priority 1071)
ai-prompt-decorator          (priority 1070)
ai-proxy                     (priority 1040)
ai-aws-content-moderation    (priority 1031) ← runs AFTER ai-proxy
ai-aliyun-content-moderation (priority 1029) ← runs AFTER ai-proxy

优先级数值越大，执行越早。两个审核插件都在 ai-proxy 或 ai-proxy-multi 之后运行，以读取已解码的 AI 请求；但它们仍会在请求调用上游 LLM 前拦截命中审核规则的请求。

插件 1：ai-aws-content-moderation

使用 AWS Comprehend DetectToxicContent API 对请求和响应内容进行评分。

配置参考

字段	类型	必填	默认	描述
`comprehend.access_key_id`	字符串	是	—	AWS 访问密钥ID
`comprehend.secret_access_key`	字符串	是	—	AWS 秘密访问密钥
`comprehend.region`	字符串	是	—	AWS区域(如`us-east-1`)
`comprehend.endpoint`	字符串	否	自动	自定义Comprehend 端点
`comprehend.ssl_verify`	布尔	否	`true`	验证 SSL 证书
`check_request`	布尔	否	`true`	启用请求审核
`check_response`	布尔	否	`false`	启用响应审核
`request_check_roles`	数组	否	`user`、`tool`、`system`、`assistant`	要审核的请求角色
`request_check_mode`	字符串	否	`all`	`all` 或 `last`（最近的连续消息块）。选中时始终检查 `system`
`request_check_length_limit`	整数	否	`1000`	每个 Comprehend 请求文本段的最大字节数
`response_check_length_limit`	整数	否	`1000`	每个 Comprehend 响应文本段的最大字节数
`stream_check_mode`	字符串	否	`final_packet`	当 `check_response` 为 true 时，可为 `realtime` 或 `final_packet`
`stream_check_cache_size`	整数	否	`128`	`realtime` 模式中每个审核批次的最大字符数
`stream_check_interval`	数字	否	`3`	审核批次之间的秒数
`fail_mode`	字符串	否	`skip`	对非 AI 或无法识别流量采用 `skip`、`warn` 或 `error`
`deny_code`	数字	否	`200`	在响应头发送前拒绝请求时的 HTTP 状态码
`deny_message`	字符串	否	—	自定义拒绝消息
`moderation_categories`	对象	否	—	每类阈值(0-1)
`moderation_threshold`	数字	否	`0.5`	总毒性阈值(0-1)

审核类别

类别	描述
`PROFANITY`	亵渎上帝的语言
`HATE_SPEECH`	仇恨内容
`INSULT`	侮辱性语言
`HARASSMENT_OR_ABUSE`	骚扰或辱骂内容
`SEXUAL`	色情内容
`VIOLENCE_OR_THREAT`	暴力或威胁性内容

每个类别接受来自0的分数阈值（最严格，屏蔽几乎 1（最宽松）。如果设置了1，每个类别都是单独检查的。否则， moderation_threshold 用作总体毒性检查。

分步操作： AWS 内容审核

a6 route create -f - <<'EOF'
{
  "id": "moderated-chat",
  "uri": "/v1/chat/completions",
  "methods": ["POST"],
  "plugins": {
    "ai-aws-content-moderation": {
      "comprehend": {
        "access_key_id": "AKIAIOSFODNN7EXAMPLE",
        "secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
        "region": "us-east-1"
      },
      "moderation_categories": {
        "HATE_SPEECH": 0.3,
        "VIOLENCE_OR_THREAT": 0.2,
        "SEXUAL": 0.5
      }
    },
    "ai-proxy": {
      "provider": "openai",
      "auth": {
        "header": {
          "Authorization": "Bearer sk-your-key"
        }
      },
      "options": {
        "model": "gpt-4"
      }
    }
  }
}
EOF

默认情况下，命中审核规则的请求会以 HTTP 200 和与服务提供方兼容的拒绝响应返回，以便 AI SDK 能解析响应正文。若客户端必须将审核视作 HTTP 错误，请设置 deny_code: 400：

request body exceeds HATE_SPEECH threshold

总体阈值（不按类别筛选）

{
  "plugins": {
    "ai-aws-content-moderation": {
      "comprehend": {
        "access_key_id": "AKIA...",
        "secret_access_key": "secret...",
        "region": "us-east-1"
      },
      "moderation_threshold": 0.7
    }
  }
}

插件 2：ai-aliyun-content-moderation

使用阿里云内容安全增强版，支持请求审核、响应审核和实时流式审核。

配置参考

字段	类型	必填	默认	描述
`endpoint`	字符串	是	—	阿里云服务端点 URL
`region_id`	字符串	是	—	阿里云地区(如`cn-shanghai`)
`access_key_id`	字符串	是	—	Aliyun 访问密钥ID
`access_key_secret`	字符串	是	—	阿里云访问密钥
`check_request`	布尔	否	`true`	启用请求审核
`check_response`	布尔	否	`false`	启用响应审核
`stream_check_mode`	字符串	否	`final_packet`	`realtime`或`final_packet`
`stream_check_cache_size`	整数	否	`128`	每批最大字符( 实时)
`stream_check_interval`	数字	否	`3`	批次检查之间的秒数(实时)
`request_check_service`	字符串	否	`llm_query_moderation`	Aliyun 请求检查服务
`request_check_length_limit`	数字	否	`2000`	每个请求块的最大字符
`response_check_service`	字符串	否	`llm_response_moderation`	Aliyun响应检查服务
`response_check_length_limit`	数字	否	`5000`	每个响应块的最大字符
`request_check_mode`	字符串	否	`last`	`last`（最近的连续选中消息）或 `all`
`request_check_roles`	数组	否	`["user"]`	`user`、`tool` 或 `system`；不能选择 assistant 历史消息
`fail_mode`	字符串	否	`skip`	对非 AI 或无法识别流量采用 `skip`、`warn` 或 `error`
`risk_level_bar`	字符串	否	`high`	阈值值:`none`、`low`、`medium`、`high`、`max`
`deny_code`	数字	否	`200`	拒绝内容的 HTTP 状态代码
`deny_message`	字符串	否	—	自定义拒绝消息
`timeout`	整数	否	`10000`	请求超时( 毫秒)
`ssl_verify`	布尔	否	`true`	验证 SSL 证书

风险等级系统

当其风险水平达到或超过risk_level_bar时，内容被阻止：

none (0) < low (1) < medium (2) < high (3) < max (4)

设置risk_level_bar: "high"阻止分级为high或max的内容。设置risk_level_bar: "low"会阻止所有额定值为low或以上的东西。

流式传输模式

模式	表现
`final_packet`	在结尾检查已组装的响应，并将 `risk_level` 标记添加到最终流式数据包；无法撤回更早发送的分块
`realtime`	在流式传输过程中分批检查内容，并可在违规后替换流的剩余部分；无法撤回更早发送的分块

分步操作：阿里云请求与响应审核

a6 route create -f - <<'EOF'
{
  "id": "aliyun-moderated-chat",
  "uri": "/v1/chat/completions",
  "methods": ["POST"],
  "plugins": {
    "ai-proxy": {
      "provider": "openai",
      "auth": {
        "header": {
          "Authorization": "Bearer sk-your-key"
        }
      },
      "options": {
        "model": "gpt-4"
      }
    },
    "ai-aliyun-content-moderation": {
      "endpoint": "https://green.cn-shanghai.aliyuncs.com",
      "region_id": "cn-shanghai",
      "access_key_id": "your-aliyun-key-id",
      "access_key_secret": "your-aliyun-key-secret",
      "check_request": true,
      "check_response": true,
      "risk_level_bar": "high",
      "deny_code": 400,
      "deny_message": "Content policy violation"
    }
  }
}
EOF

实时流式审核

{
  "plugins": {
    "ai-aliyun-content-moderation": {
      "endpoint": "https://green.cn-shanghai.aliyuncs.com",
      "region_id": "cn-shanghai",
      "access_key_id": "key-id",
      "access_key_secret": "key-secret",
      "check_request": true,
      "check_response": true,
      "stream_check_mode": "realtime",
      "stream_check_cache_size": 256,
      "stream_check_interval": 2,
      "risk_level_bar": "medium"
    }
  }
}

一体化模式

模式A ：仅请求过滤（ AWS ）

Client → ai-proxy [sets context] → [AWS Comprehend blocks toxic] → LLM → Response → Client

plugins:
  ai-aws-content-moderation:
    comprehend:
      access_key_id: "${AWS_ACCESS_KEY_ID}"
      secret_access_key: "${AWS_SECRET_ACCESS_KEY}"
      region: us-east-1
    moderation_threshold: 0.5
  ai-proxy:
    provider: openai
    auth:
      header:
        Authorization: "Bearer ${OPENAI_API_KEY}"

模式B ：请求+响应过滤（阿里云）

Client → ai-proxy [sets context] → [Aliyun checks request] → LLM
       → [Aliyun checks response] → Client

plugins:
  ai-proxy:
    provider: openai
    auth:
      header:
        Authorization: "Bearer ${OPENAI_API_KEY}"
  ai-aliyun-content-moderation:
    endpoint: "https://green.cn-shanghai.aliyuncs.com"
    region_id: cn-shanghai
    access_key_id: "${ALIYUN_KEY_ID}"
    access_key_secret: "${ALIYUN_KEY_SECRET}"
    check_request: true
    check_response: true
    risk_level_bar: high

Secret 管理

两个插件都支持使用 APISIX Secret 管理凭证：

plugins:
  ai-aws-content-moderation:
    comprehend:
      access_key_id: "$secret://vault/aws_key_id"
      secret_access_key: "$secret://vault/aws_secret_key"
      region: us-east-1

配置同步示例

version: "1"
routes:
  - id: moderated-chat
    uri: /v1/chat/completions
    methods:
      - POST
    plugins:
      ai-aws-content-moderation:
        comprehend:
          access_key_id: AKIAIOSFODNN7EXAMPLE
          secret_access_key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
          region: us-east-1
        moderation_categories:
          HATE_SPEECH: 0.3
          VIOLENCE_OR_THREAT: 0.2
        moderation_threshold: 0.5
      ai-proxy:
        provider: openai
        auth:
          header:
            Authorization: Bearer sk-your-key
        options:
          model: gpt-4

故障排查

症状	原因	解决方法
“no ai instance picked”	使用审核插件时未配置 `ai-proxy`	始终在同一路由上配置 `ai-proxy` 或 `ai-proxy-multi`
AWS 拒绝响应为 HTTP 200	默认 `deny_code` 为 `200`	如果客户端需要 HTTP 错误，请设置 `deny_code: 400`
AWS 插件未拦截内容	阈值过于宽松，或 `request_check_roles` 未包含相应角色	降低阈值；AWS 默认检查所有角色并使用 `request_check_mode: all`
阿里云响应审核未生效	`check_response` 默认为 `false`	显式设置 `check_response: true`
“指定签名不匹配”	阿里云访问凭证错误	检查 `access_key_id` 和 `access_key_secret`
延迟较高	同时启用了两个内容审核插件	每条路由只使用一个内容审核提供商
流式响应中途断开	审核插件在 `realtime` 模式检测到违规内容	这是预期行为；调整审核阈值，或使用 `final_packet` 模式

本文根据 api7/a6 仓库中的 a6-plugin-ai-content-moderation/SKILL.md 生成。可在 AI Agent Skills 页面浏览全部 Skill。

概览​

适用场景​

插件执行顺序​

插件 1：ai-aws-content-moderation​

配置参考​

审核类别​

分步操作： AWS 内容审核​

总体阈值（不按类别筛选）​

插件 2：ai-aliyun-content-moderation​

配置参考​

风险等级系统​

流式传输模式​

分步操作：阿里云请求与响应审核​

实时流式审核​

一体化模式​

模式A ：仅请求过滤（ AWS ）​

模式B ：请求+响应过滤（阿里云）​

Secret 管理​

配置同步示例​

故障排查​

概览

适用场景

插件执行顺序

插件 1：ai-aws-content-moderation

配置参考

审核类别

分步操作： AWS 内容审核

总体阈值（不按类别筛选）

插件 2：ai-aliyun-content-moderation

配置参考

风险等级系统

流式传输模式

分步操作：阿里云请求与响应审核

实时流式审核

一体化模式

模式A ：仅请求过滤（ AWS ）

模式B ：请求+响应过滤（阿里云）

Secret 管理

配置同步示例

故障排查