跳到主要内容

OpenAI Moderation 安全护栏

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

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

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

前提条件​

开始前请准备：

  • 阅读安全护栏行为，了解钩子点、执行模式和远程故障处理方式。
  • 以下配置路径之一：
    • AISIX Cloud，其中包含环境、已接入的网关和具有写权限范围的 Admin Token。对于 On-Premises，请按照 AISIX Cloud 快速入门操作。如需申请混合云访问权限，请联系 API7。
    • 加载声明式 resources.yaml 文件的开源 AISIX 网关。
  • 可以发送 Chat Completions 请求的模型别名和调用方 API Key。
  • 一个可调用 Moderation API 的 OpenAI API Key。
  • curl。AISIX Cloud 路径还会使用 jq。

创建 Moderation 安全护栏​

以下示例根据审核模型的 flagged 判定阻断内容。请选择一种配置路径，再使用通用验证步骤。

导出两种路径都会使用的网关和模型服务提供方参数：

# AISIX_PROXY 末尾不包含斜杠或端点路径。
# 本地快速入门使用 http://127.0.0.1:3000。
export AISIX_PROXY="YOUR_AISIX_GATEWAY_URL"
export AISIX_API_KEY="YOUR_CALLER_API_KEY"
export AISIX_MODEL="gpt-4o-mini"
export OPENAI_API_KEY="YOUR_OPENAI_API_KEY"

AISIX Cloud​

导出控制平面连接参数：

# AISIX_CP 包含 /api，末尾不包含斜杠。
# 本地 On-Premises 快速入门使用 http://localhost:8080/api。
export AISIX_CP="YOUR_AISIX_CLOUD_ADMIN_API_BASE_URL"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"

在环境中创建一个输入安全护栏并获取其 ID：

export GUARDRAIL_ID=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/guardrails" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "openai-moderation-input",
    "enabled": false,
    "hook_point": "input",
    "fail_open": false,
    "kind": "openai_moderation",
    "config": {
      "api_key": "'"${OPENAI_API_KEY}"'",
      "model": "omni-moderation-latest"
    }
  }' | jq -r '.guardrail.id')

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

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

该安全护栏默认调用 https://api.openai.com/v1/moderations。如有需要，可设置 config.endpoint 指向兼容端点。

安全护栏只会在附加的 Scope 中运行。将其附加到整个环境，使其应用到所有流量：

curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/guardrails/$GUARDRAIL_ID/attachments" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scope_type": "env"
  }'

如需缩小范围，请将 scope_type 设置为 model、api_key 或 team，并通过 scope_id 传入目标 ID。

Attachment 存在后启用安全护栏：

curl -sS -X PATCH "$AISIX_CP/environments/$ENV_ID/guardrails/$GUARDRAIL_ID" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

启用后的配置会自动投射到已接入的网关。

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

开源 AISIX 网关​

让网关进程可以访问 OPENAI_API_KEY，然后在已定义示例模型和调用方 API Key 的资源文件中添加安全护栏：

resources.yaml（OpenAI 审核安全护栏）
guardrails:
  - name: openai-moderation-input
    enabled: true
    hook_point: input
    fail_open: false
    kind: openai_moderation
    api_key: ${OPENAI_API_KEY}
    model: omni-moderation-latest

guardrail_attachments:
  - guardrail_id: openai-moderation-input
    scope_type: env
    priority: 100

模型服务提供方字段直接位于安全护栏条目下，而不是 config 下。默认端点为 https://api.openai.com/v1；网关需要调用其他兼容服务时，请设置 endpoint。

安全护栏只在 Attachment 指定的范围内生效：请添加 guardrail_attachments 条目引用它，否则它虽然会被加载，但不会检查任何流量。请验证完整文件，然后重新加载网关。可运行的 Docker 工作流参见重新加载资源文件。

验证阻断​

AISIX Cloud 投射是异步的。如果第一个请求尚未体现安全护栏，请等待网关应用最新修订后重试。收敛检查参见资源投射。

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

curl -sSi -X POST "$AISIX_PROXY/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。

AISIX Cloud​

使用明确的分类阈值替换现有安全护栏的模型服务提供方配置。现有 Attachment 会继续保留：

curl -sS -X PATCH "$AISIX_CP/environments/$ENV_ID/guardrails/$GUARDRAIL_ID" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "api_key": "'"${OPENAI_API_KEY}"'",
      "category_thresholds": {
        "violence": 0.3,
        "harassment/threatening": 0.5
      }
    }
  }'

开源 AISIX 网关​

在现有安全护栏条目中添加 category_thresholds，以替换其判定规则：

resources.yaml（分类阈值）
guardrails:
  - name: openai-moderation-input
    enabled: true
    hook_point: input
    fail_open: false
    kind: openai_moderation
    api_key: ${OPENAI_API_KEY}
    category_thresholds:
      violence: 0.3
      harassment/threatening: 0.5

guardrail_attachments:
  - guardrail_id: openai-moderation-input
    scope_type: env
    priority: 100

测试新阈值前，请验证完整文件并重新加载网关。

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

下一步​

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