OpenAI Moderation 安全护栏

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

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

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

前提条件

开始前请准备：

阅读安全护栏行为，了解 Hook 点和执行模式。
一个 OpenAI API Key。Moderation API 可免费使用；你已有的模型流量 Key 也可以使用。
一个可访问 Admin 和代理监听端的自托管 AISIX 网关。
网关 config.yaml 中的 Admin Key。
一个可发送聊天补全请求的模型别名和调用方 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" \\
  -d '{
    "name": "openai-moderation-input",
    "enabled": true,
    "hook_point": "input",
    "fail_open": false,
    "kind": "openai_moderation",
    "api_key": "'"\${OPENAI_API_KEY}"'",
    // 标注 1
    "model": "omni-moderation-latest"
  }'

❶ 可选。omni-moderation-latest 是默认模型；text-moderation-latest 是旧版分类器。护栏会调用 https://api.openai.com/v1/moderations；可通过 endpoint 指向兼容部署或测试替身。

验证阻断

发送一条会被审核模型标记的 Prompt：

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

被标记的请求会在到达上游模型前被拒绝，并返回 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" \\
  -d '{
    "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
    }
  }'

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

失败策略

失败	跳过原因
调用超时（`timeout_ms`，默认 `5000`）	`openai_moderation_timeout`
OpenAI 返回 HTTP 429	`openai_moderation_throttled`
HTTP 5xx 或连接错误	`openai_moderation_5xx`
其他 HTTP 4xx（Key、端点或模型配置错误）	`openai_moderation_config_error`

fail_open: true（默认）：调用失败时放行请求，并在用量记录中记录跳过原因。
fail_open: false：调用失败时阻断请求。

输出 Hook 拥有独立的 output_fail_open（默认 false）。

流式响应

当护栏覆盖 output Hook 时，流式响应会先缓冲，完整检查后再释放，确保被标记内容不会在流中提前到达调用方。默认缓冲上限为 262144 字节，超出时默认 fail-closed。

下一步

如果需要按严重级别控制分类审核或使用服务端 blocklist，请参考 Azure AI Content Safety 安全护栏。如需对比所有服务提供方，请阅读选择安全护栏服务提供方。

前提条件​

创建 Moderation 安全护栏​

验证阻断​

按分类设置阈值​

失败策略​

流式响应​

下一步​