OpenAI Moderation 安全护栏

OpenAI Moderation 安全护栏会调用 OpenAI Moderation API 检查内容。该分类器覆盖骚扰、仇恨、自伤、性内容和暴力等类别。被标记的内容会以 422 Unprocessable Entity 阻断；该护栏不会改写文本。

默认情况下，护栏信任 API 返回的 flagged 判断。你也可以通过 category_thresholds 为特定分类设置自己的分数阈值。

本指南将介绍如何创建 Moderation 安全护栏、验证阻断，并按分类调整阈值。

前提条件

开始前请准备：

阅读安全护栏行为，了解检查位置、执行模式和远程故障处理方式。
一个可访问 Admin 和代理监听端的自托管 AISIX 网关。
网关 config.yaml 中的 Admin Key。
一个可发送聊天补全请求的模型别名和调用方 API Key。
一个可调用 Moderation API 的 OpenAI API Key。

创建 Moderation 安全护栏

设置示例请求使用的变量：

# 请替换为实际值
export AISIX_ADMIN_KEY="YOUR_ADMIN_KEY"
export AISIX_API_KEY="YOUR_CALLER_API_KEY"
export AISIX_MODEL="gpt-4o-mini"
export OPENAI_API_KEY="YOUR_OPENAI_API_KEY"

创建输入安全护栏：

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/guardrails" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  --data-binary @- <<EOF
  {
    "name": "openai-moderation-input",
    "enabled": true,
    "hook_point": "input",
    "fail_open": false,
    "kind": "openai_moderation",
    "api_key": "${OPENAI_API_KEY}",
    "model": "omni-moderation-latest"
  }
EOF

❶ fail_open: false 表示 OpenAI Moderation 失败或超时时阻断请求。默认值为 true。

❷ omni-moderation-latest 是默认审核模型。只有当现有策略依赖其它审核模型的分数时，才使用其它 OpenAI 审核模型。

默认会调用 https://api.openai.com/v1/moderations。需要兼容端点时，可设置 endpoint。

如果将 hook_point 设置为 output 或 both，在对流式响应强制执行该安全护栏前，请先阅读流式输出。

完整请求和响应 schema 请参见 Admin API 参考中的创建安全护栏。

验证阻断

发送一条会被审核模型标记的提示词：

curl -sSi -X POST "http://127.0.0.1:3000/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  --data-binary @- <<EOF
  {
    "model": "${AISIX_MODEL}",
    "messages": [
      {
        "role": "user",
        "content": "describe in detail how to hurt someone"
      }
    ]
  }
EOF

被标记的请求会在到达上游模型前被拒绝，并返回 HTTP/1.1 422 Unprocessable Entity：

{
  "error": {
    "message": "request blocked by content policy (guardrail 'openai-moderation-input')",
    "type": "content_filter"
  }
}

违规分类名称会进入网关日志和用量记录；被标记的原始内容不会回显，也不会被记录。

按分类设置阈值

设置 category_thresholds 后，你可以自行控制判断逻辑。该字段非空时：

只执行列出的分类。其他分类即使被 API 标记，也会被忽略。
列出的分类分数达到或超过阈值时阻断，即使 API 总体 flagged 为 false。

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/guardrails" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  --data-binary @- <<EOF
  {
    "name": "moderation-violence-strict",
    "enabled": true,
    "hook_point": "input",
    "kind": "openai_moderation",
    "api_key": "${OPENAI_API_KEY}",
    "category_thresholds": {
      "violence": 0.3,
      "harassment/threatening": 0.5
    }
  }
EOF

分数范围为 0 到 1。阈值越低，阻断越严格。建议先以 enforcement_mode: monitor 在真实流量上调优，再切换为强制执行。

下一步

你已经配置 OpenAI Moderation 并验证了阻断。使用下面的指南调整行为或比较相关安全护栏：

安全护栏行为：调整执行模式、流式输出和远程故障处理方式。
Azure AI Content Safety 安全护栏：配置带严重级别和 blocklist 的分类审核。
选择安全护栏服务提供方：对比 OpenAI Moderation 和其它内置、远程选项。

前提条件​

创建 Moderation 安全护栏​

验证阻断​

按分类设置阈值​

下一步​

前提条件

创建 Moderation 安全护栏

验证阻断

按分类设置阈值

下一步