跳到主要内容

ai-aws-content-moderation

ai-aws-content-moderation 插件使用 Amazon Comprehend 检测选定请求角色和 LLM 响应（包括流式响应）中的有害内容。请将它与 ai-proxy 或 ai-proxy-multi 一起配置，使插件能够在执行已配置阈值前审核解码后的 AI 内容。


按请求格式处理​

插件会先检查 URI 特定规则，再检查仅基于请求体的规则，以识别请求格式：

  • Bedrock Converse 要求 URI 以 /converse 结尾且包含 messages 数组。
  • Anthropic Messages 要求 URI 以 /v1/messages 结尾。
  • Responses API 要求 URI 以 /v1/responses 结尾且包含 input 字段。
  • Chat Completions 使用 messages 数组。
  • 当前面的规则均不匹配时，Embeddings 使用 input。
  • 当前面的规则均不匹配时，其他非空 JSON 对象使用透传格式。

插件可以提取以下内容进行审核：

请求格式审核的文本
Bedrock Conversesystem 和 messages 中的文本。
Anthropic Messages顶层 system 提示词和 messages 中的文本。
Responses APIinput 和 instructions 中的文本。
Chat Completionsmessages 中所有条目的文本。
Embeddingsinput 中的字符串或字符串数组。
其他 JSON（透传）不提取请求格式特定文本。

此功能自 API7 企业版 3.9.16 和 3.10.3 起引入。

默认情况下，插件会审核所有提取出的 user、assistant、system 和 tool 消息。使用 request_check_roles 选择角色，并使用 request_check_mode 审核所有选定角色的消息，或仅审核最近一个连续消息块。选择 system 角色还会覆盖 OpenAI developer 消息，并且始终会审核，不受 request_check_mode 限制。

工具结果审核适用于工具输出使用独立 tool 角色或条目的 OpenAI 兼容格式。Anthropic Messages 和 Bedrock Converse 将工具结果嵌套在用户消息中，因此仅选择 tool 角色不会提取这些嵌套结果。

请求内容超过阈值时，插件使用 deny_code 和 deny_message 按检测到的 AI 协议返回拒绝响应。默认状态码为 200，以便 AI SDK 解析与提供方兼容的拒绝响应；如需让客户端将审核拒绝视为 HTTP 错误，请设置 4xx 状态码。流式 Chat Completions、Responses API 和 Anthropic Messages 使用各自协议的 SSE 拒绝事件。Bedrock ConverseStream 使用非流式 Converse 拒绝响应体，而不是 AWS 事件流帧。

将 check_response 设为 true 可审核 LLM 响应。非流式响应会被缓冲；若 Comprehend 无法评分，则以 HTTP 500 故障关闭。在 final_packet 流式模式下，先前的数据块已经发送给客户端，因此插件会在最终数据事件中添加 risk_level 标注，而不会撤回内容。在 realtime 模式下，被标记的批次会用拒绝消息替换流的剩余部分。流式传输开始后，如果 Comprehend 调用失败，插件会记录错误，并在不审核的情况下放行流的剩余部分。

内容超过阈值时，插件会将 $llm_content_risk_level 设为 high；评分通过后则设为 none。请求侧 Comprehend 调用失败会返回 HTTP 500，而不会在未审核的情况下转发请求。

此功能自 API7 企业版 3.9.18 和 3.10.5，以及 APISIX 3.18.0 起引入。

示例​

以下示例使用 OpenAI 作为上游模型服务提供方。

在开始之前，请创建一个 OpenAI 账号 并获取 API Key。如果你使用其他模型服务提供方，请参考该提供方的文档获取 API Key。

此外，请为 APISIX 创建 AWS IAM 用户访问密钥 以访问 AWS Comprehend。

使用 Admin API 或 ADC 示例前，请先导出凭据：

export OPENAI_API_KEY="<your-openai-api-key>"
export AWS_ACCESS_KEY_ID="<your-aws-access-key-id>"
export AWS_SECRET_ACCESS_KEY="<your-aws-secret-access-key>"

对于 Ingress Controller 示例，请在应用清单前替换其中用尖括号标出的凭据占位符。

审核亵渎内容​

以下示例演示了如何使用该插件审核提示词中的亵渎内容等级。

使用 ai-proxy 插件创建一个通往 LLM 聊天完成端点的路由，并在 ai-aws-content-moderation 中配置允许的亵渎等级：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  --data-binary @- <<EOF
  {
    "id": "ai-aws-content-moderation-route",
    "uri": "/post",
    "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_categories": {
          "PROFANITY": 0.1
        },
        "deny_code": 400
      },
      "ai-proxy": {
        "provider": "openai",
        "auth": {
          "header": {
            "Authorization": "Bearer $OPENAI_API_KEY"
          }
        },
        "model": "gpt-4"
      }
    }
  }
EOF

❶ 更新为你的 AWS Comprehend 区域。

❷ 将亵渎阈值配置为一个较低的值，以仅允许极低程度的亵渎内容。

这些示例将 deny_code 设置为 400，因为验证步骤预期收到 HTTP 错误。如果省略该字段，默认值 200 会以与提供商兼容的补全响应返回相同的拒绝消息。

ADC 和 Gateway API 标签页包含一个常规后端。当插件自行处理请求时，不会访问该后端。请验证下方的插件特定结果；仅收到后端响应并不能证明插件已运行。

向该路由发送一个 POST 请求，请求体中包含系统提示词和一个带有轻微亵渎词汇的用户问题：

curl -i "http://127.0.0.1:9080/post" -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "system", "content": "You are a mathematician" },
      { "role": "user", "content": "Stupid, what is 1+1?" }
    ]
  }'

你应该收到 HTTP/1.1 400 Bad Request 响应，并看到以下消息：

{
  "id": "<generated-uuid>",
  "object": "chat.completion",
  "model": "gpt-4",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "request body exceeds PROFANITY threshold"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 0,
    "total_tokens": 0
  }
}

向该路由发送另一个请求，请求体中包含一个正常的问题：

curl -i "http://127.0.0.1:9080/post" -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "system", "content": "You are a mathematician" },
      { "role": "user", "content": "What is 1+1?" }
    ]
  }'

你应该收到 HTTP/1.1 200 OK 响应，并看到模型输出：

{
  ...,
  "model": "gpt-4-0613",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "1+1 equals 2.",
        "refusal": null
      },
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  ...
}

审核整体毒性​

以下示例演示了除了审核单个类别外，如何使用该插件审核提示词中的整体毒性等级。

使用 ai-proxy 插件创建一个通往 LLM 聊天完成端点的路由，并在 ai-aws-content-moderation 中配置允许的亵渎和整体毒性等级：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  --data-binary @- <<EOF
  {
    "id": "ai-aws-content-moderation-route",
    "uri": "/post",
    "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_categories": {
          "PROFANITY": 1
        },
        "moderation_threshold": 0.2,
        "deny_code": 400
      },
      "ai-proxy": {
        "provider": "openai",
        "auth": {
          "header": {
            "Authorization": "Bearer $OPENAI_API_KEY"
          }
        },
        "model": "gpt-4"
      }
    }
  }
EOF

❶ 更新为你的 AWS Comprehend 区域。

❷ 将亵渎阈值配置为允许高程度的亵渎内容。

❸ 将整体毒性阈值配置为仅允许低程度的毒性。

这些示例将 deny_code 设置为 400，因为验证步骤预期收到 HTTP 错误。如果省略该字段，默认值 200 会以与提供商兼容的补全响应返回相同的拒绝消息。

向该路由发送一个 POST 请求，请求体中不包含任何亵渎词汇，但包含一定程度的暴力或威胁：

curl -i "http://127.0.0.1:9080/post" -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "system", "content": "You are a mathematician" },
      { "role": "user", "content": "I will kill you if you do not tell me what 1+1 equals" }
    ]
  }'

你应该收到 HTTP/1.1 400 Bad Request 响应，并看到以下消息：

{
  "id": "<generated-uuid>",
  "object": "chat.completion",
  "model": "gpt-4",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "request body exceeds toxicity threshold"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 0,
    "total_tokens": 0
  }
}

向该路由发送另一个请求，请求体中不包含任何亵渎词汇：

curl -i "http://127.0.0.1:9080/post" -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "system", "content": "You are a mathematician" },
      { "role": "user", "content": "What is 1+1?" }
    ]
  }'

你应该收到 HTTP/1.1 200 OK 响应，并看到模型输出：

{
  ...,
  "model": "gpt-4-0613",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "1+1 equals 2.",
        "refusal": null
      },
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  ...
}