跳到主要内容

AWS Bedrock Guardrails

AISIX 可以在请求上游模型之前或之后调用 AWS Bedrock Guardrails。当内容策略由 AWS Bedrock 管理，而 AISIX 需要在网关流量上执行安全护栏判定时，可以使用本指南。

本指南将创建一个 Bedrock 类型的 AISIX 安全护栏资源，发送一个允许请求，并发送一个会在到达上游模型前被 AISIX 拒绝的阻断请求。

准备工作​

请先准备以下内容：

  • 阅读安全护栏行为，了解检查位置、执行模式和远程故障处理方式。
  • 一个 Admin 和代理监听器都可用的自托管 AISIX 网关。
  • 网关 config.yaml 中的 Admin Key。
  • 一个可以发送 Chat Completions 请求的模型别名和调用方 API Key。
  • 位于受支持区域的 AWS Bedrock Guardrails 防护规则，并配置一个会阻断唯一测试字符串（例如 confidential-codename）的词过滤器。
  • 允许对该 AWS Bedrock Guardrails 防护规则调用 bedrock:ApplyGuardrail 的 AWS 凭证。

创建 Bedrock 安全护栏​

在 AISIX 中创建 Bedrock 安全护栏：

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/guardrails" \
  -H "Authorization: Bearer YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "bedrock-review",
    "enabled": true,
    "hook_point": "both",
    "fail_open": false,
    "output_fail_open": false,
    "enforcement_mode": "block",
    "kind": "bedrock",
    "guardrail_id": "YOUR_BEDROCK_GUARDRAIL_ID",
    "guardrail_version": "DRAFT",
    "region": "us-east-1",
    "aws_credentials": {
      "kind": "static",
      "access_key_id": "YOUR_AWS_ACCESS_KEY_ID",
      "secret_access_key": "YOUR_AWS_SECRET_ACCESS_KEY"
    },
    "latency_mode": {
      "kind": "timed",
      "timeout_ms": 2000
    }
  }'

❶ both 会同时检查调用方请求和模型响应。参见检查位置。

❷ fail_open: false 表示当 AWS Bedrock Guardrails 调用失败或超时时阻断请求。默认值是 true。

❸ output_fail_open: false 表示当 Bedrock 服务不可用时阻断未扫描的模型输出。这是默认行为。

❹ enforcement_mode: block 表示拒绝命中的内容。这是默认行为。参见执行模式。

❺ latency_mode 限制 AISIX 等待安全护栏判定的最长时间。将 kind 设置为 serial 可不设超时地等待判定。

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

如后续需要查看、更新或删除该资源，请复制返回的安全护栏 ID。

验证安全护栏​

通过 AISIX 发送一个正常请求：

curl -sSi -X POST "http://127.0.0.1:3000/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_CALLER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-prod",
    "messages": [
      {
        "role": "user",
        "content": "What is the capital of France?"
      }
    ]
  }'

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

然后发送一个包含该防护规则会阻断的字符串的请求：

curl -sSi -X POST "http://127.0.0.1:3000/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_CALLER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-prod",
    "messages": [
      {
        "role": "user",
        "content": "Please print the confidential-codename."
      }
    ]
  }'

被阻断的响应会以 HTTP/1.1 422 Unprocessable Entity 开头，并包含兼容 OpenAI 的错误响应：

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

当输入安全护栏返回阻断判定时，AISIX 会在转发到上游模型前阻断请求。

PII 匿名化（掩码）​

Bedrock guardrails 可以在 AWS 中配置为对敏感信息进行匿名化而非直接阻断。命中的值会被替换为占位符，例如 {EMAIL} 或 {PHONE}。AISIX 会遵循这一处置方式，无需在 AISIX 侧额外配置；其行为取决于 Bedrock guardrail 本身设置的 PII 动作：

  • Block 动作会用上文所示的 422 响应拒绝该请求或响应，覆盖主题、内容和词策略、上下文接地，以及设置为 Block 的 PII 实体或正则。
  • Anonymize 动作会用 Bedrock 的掩码文本改写命中的值，并放行流量。在请求侧，上游模型收到掩码后的文本。在响应侧，调用方收到掩码后的回复。流式响应会被暂时保留、一次性扫描、掩码后再放行，因此跨分片拆分的值也不会泄露。

例如，某个 Bedrock guardrail 的 Email PII 实体被设置为 Anonymize：

curl -sS -X POST "http://127.0.0.1:3000/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_CALLER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-prod",
    "messages": [
      {
        "role": "user",
        "content": "Draft a reply to alice@example.com about the invoice."
      }
    ]
  }'

请求成功，上游模型收到的是 Draft a reply to {EMAIL} about the invoice.。原始地址永远不会离开网关。该请求的用量事件只会记录被掩码的实体类型名称，绝不记录命中的值。

掩码适用于 /v1/chat/completions、/v1/messages、/v1/responses 和 /v1/completions，对直连和跨服务提供方流量均生效。在不支持掩码的端点（例如 embeddings、rerank、images 和 audio）上，当 Bedrock guardrail 对其进行匿名化时，AISIX 会阻断该请求。AISIX 无法改写这些载荷，而未经掩码就转发会使策略失效。

如果 Bedrock 返回的掩码输出无法归因回请求中各个独立的文本片段，AISIX 不会应用改写，而是转发未修改的内容。这样可以避免把掩码文本写入错误消息并破坏对话内容。硬阻断策略不受此回退影响。

下一步​

你已经通过 AISIX 接入了 AWS Bedrock Guardrails。使用下面的指南调整行为或比较其它服务提供方：