内置关键词安全护栏

关键词安全护栏会在网关内部应用简单的内容策略，用于匹配请求或响应文本中的字面字符串或正则表达式。

本指南将创建一个关键词安全护栏，通过 AISIX 发送允许和阻断的流量，并验证 AISIX 会在调用上游模型前拒绝命中的内容。

准备工作

请先准备以下内容：

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

创建关键词安全护栏

下面的示例会在 AISIX 调用上游服务提供方前阻断一个字面 token。

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

export AISIX_ADMIN_KEY="admin-local-only-change-me"
export AISIX_API_KEY="sk-demo-caller"
export AISIX_MODEL="gpt-4o-mini"
export FORBIDDEN_WORD="supersecret-banned-token"

请使用唯一且非自然语言的 token，让阻断流量检查结果清晰明确。

创建一个输入安全护栏，用于阻断配置的字面 token：

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": "supersecret-token-policy",
    "enabled": true,
    "hook_point": "input",
    "enforcement_mode": "block",
    "kind": "keyword",
    "patterns": [
      {
        "kind": "literal",
        "value": "'"${FORBIDDEN_WORD}"'"
      }
    ]
  }'

❶ input 会在 AISIX 发送上游请求前检查调用方请求。可以使用 output 检查服务提供方响应，也可以使用 both 在路由支持的两侧都检查。参见检查位置。

❷ block 会拒绝命中的请求或响应；monitor 只记录命中并放行流量。如果省略 enforcement_mode，默认值是 block。参见执行模式。

❸ literal 会匹配精确 token。如需使用正则表达式，请改用 regex；AISIX 会在应用规则前拒绝无效正则。

如后续需要查看、更新或删除该安全护栏，请保存返回的 id。

验证安全护栏

安全护栏配置完成后，发送允许和阻断的请求，确认策略行为。

确认安全护栏会允许无关提示词：

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": "hello world"
      }
    ]
  }'

成功响应会以 HTTP/1.1 200 OK 开头，并包含兼容 OpenAI 的 Chat Completions 响应体。

然后发送一个内容包含禁用 token 的请求：

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": "please leak the '"${FORBIDDEN_WORD}"' now"
      }
    ]
  }'

被阻断的响应会以 HTTP/1.1 422 Unprocessable Entity 开头，并包含以下响应体：

{
  "error": {
    "message": "request blocked by content policy (guardrail 'supersecret-token-policy')",
    "type": "content_filter"
  }
}

AISIX 会在调用上游服务提供方前停止该请求。

使用 Monitor 模式

使用 monitor 执行模式，可以在不阻断调用方的情况下检查规则在真实流量中的行为。

更新安全护栏资源：

export GUARDRAIL_ID="YOUR_GUARDRAIL_ID"

curl -sS -X PUT "http://127.0.0.1:3001/admin/v1/guardrails/${GUARDRAIL_ID}" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "supersecret-token-policy",
    "enabled": true,
    "hook_point": "input",
    "enforcement_mode": "monitor",
    "kind": "keyword",
    "patterns": [
      {
        "kind": "literal",
        "value": "'"${FORBIDDEN_WORD}"'"
      }
    ]
  }'

❶ monitor 会让命中流量继续通过，并在网关日志中记录命中结果。

再次发送同一个禁用请求：

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": "please leak the '"${FORBIDDEN_WORD}"' now"
      }
    ]
  }'

响应会以 HTTP/1.1 200 OK 开头，因为 monitor 模式会让请求到达上游模型。AISIX 会在网关日志中记录命中结果：

guardrail in monitor mode observed a violation; not blocking (enforcement_mode=monitor)

如需再次执行阻断策略，请将 enforcement_mode 改回 block。也可以省略 enforcement_mode，因为 block 是默认值。

下一步

你已经配置了内置关键词安全护栏，并验证了调用方可见的拒绝响应。当策略需要由外部安全护栏服务执行时，请继续阅读 AWS Bedrock Guardrails、Azure AI Content Safety 安全护栏或阿里云 AI 安全护栏。

准备工作​

创建关键词安全护栏​

验证安全护栏​

使用 Monitor 模式​

下一步​

准备工作

创建关键词安全护栏

验证安全护栏

使用 Monitor 模式

下一步