版本：Dev

AWS Bedrock Guardrails

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

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

准备工作

请先准备以下内容：

阅读安全护栏行为，了解钩子点、执行模式和远程故障处理方式。
以下配置路径之一：
- AISIX Enterprise 或 AISIX Cloud，其中包含环境、已接入的网关和具有写权限范围的 Admin Token。对于 AISIX Enterprise，请按照 AISIX Enterprise 快速入门操作。如需申请 AISIX Cloud 访问权限，请联系 API7。
- 加载声明式 resources.yaml 文件的开源 AISIX 网关。
可以发送 Chat Completions 请求的模型别名和调用方 API Key。
位于受支持区域的 AWS Bedrock Guardrail，并配置一个会阻断唯一测试 Token（例如 confidential-codename）的词过滤器。
允许对该 Guardrail 调用 bedrock:ApplyGuardrail 的 AWS 凭证，采用凭证模式之一。
curl。AISIX Enterprise 或 AISIX Cloud 路径还会使用 jq。

创建 Bedrock 安全护栏

以下示例使用 Bedrock 安全护栏检查请求和响应。请选择一种配置路径，再使用通用验证步骤。

导出两种路径都会使用的网关参数：

# 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 AWS_ACCESS_KEY_ID="YOUR_AWS_ACCESS_KEY_ID"
export AWS_SECRET_ACCESS_KEY="YOUR_AWS_SECRET_ACCESS_KEY"

AISIX Enterprise 或 AISIX Cloud

导出控制面连接参数：

# AISIX_CP 包含 /api，且不含尾部斜杠
# 本地私有化部署快速入门使用 http://localhost:8080/api
export AISIX_CP="YOUR_AISIX_CONTROL_PLANE_API_URL"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"

在 AISIX 中创建 Bedrock 安全护栏，并获取其 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": "bedrock-review",
    "enabled": false,
    "hook_point": "both",
    "fail_open": false,
    "enforcement_mode": "block",
    "kind": "bedrock",
    "config": {
      "guardrail_id": "YOUR_BEDROCK_GUARDRAIL_ID",
      "guardrail_version": "DRAFT",
      "region": "us-east-1",
      "aws_credentials": {
        "kind": "static",
        "access_key_id": "'"${AWS_ACCESS_KEY_ID}"'",
        "secret_access_key": "'"${AWS_SECRET_ACCESS_KEY}"'"
      },
      "output_fail_open": false,
      "latency_mode": {
        "kind": "timed",
        "timeout_ms": 2000
      }
    }
  }' | jq -r '.guardrail.id')

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

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

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

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

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

安全护栏只有附加到 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"
  }'

env Scope 会将安全护栏应用到环境中的所有流量，不需要 scope_id。如需缩小范围，请将 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}'

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

开源 AISIX 网关

在已定义示例模型和调用方 API Key 的资源文件中添加安全护栏。示例从 AWS_ACCESS_KEY_ID 和 AWS_SECRET_ACCESS_KEY 读取凭证。已经运行的快速入门容器不会继承之后才在主机上导出的变量。

resources.yaml（Bedrock 安全护栏）
guardrails:
  - name: bedrock-review
    enabled: true
    hook_point: both
    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: ${AWS_ACCESS_KEY_ID}
      secret_access_key: ${AWS_SECRET_ACCESS_KEY}
    output_fail_open: false
    latency_mode:
      kind: timed
      timeout_ms: 2000

guardrail_attachments:
  - guardrail_id: bedrock-review
    scope_type: env
    priority: 100

模型服务提供方字段直接位于安全护栏条目下，而不是 config 下。安全护栏只在 Attachment 指定的范围内生效：请添加 guardrail_attachments 条目引用它，否则它虽然会被加载，但不会检查任何流量。

重新加载或重建网关前，请验证完整文件。扩展开源快速入门时，请按照重新加载资源文件操作，只在验证成功后重建容器，并传入额外凭证变量。

选择安全护栏凭证

aws_credentials.kind 决定 AISIX 调用 ApplyGuardrail 时如何认证。region 在所有模式下都是安全护栏的顶层字段。

`kind`	字段	认证方式
`static`	`access_key_id` 和 `secret_access_key`，使用临时凭证时另加 `session_token`	使用这组密钥进行 SigV4 签名。
`api_key`	`api_key`，即 Bedrock API Key	以 Bearer Token 发送，不做 SigV4 签名。
`default_chain`	不带凭证字段	使用网关自身的 AWS 凭证进行 SigV4 签名：环境变量、Web Identity（例如 EKS 上的 IRSA）、ECS 容器凭证端点或 EC2 实例配置文件。

在 static 或 default_chain 模式下，role_arn 会通过 sts:AssumeRole 用这组凭证换取该角色的凭证；external_id 和 role_session_name 可选，且都要求同时设置 role_arn。临时凭证会在过期前刷新。例如，使用网关自身的凭证调用安全护栏：

resources.yaml（安全护栏凭证）
aws_credentials:
  kind: default_chain
  role_arn: arn:aws:iam::123456789012:role/bedrock-guardrail

在 AISIX Enterprise 和 AISIX Cloud 中，密钥字段只写不读。PATCH 时密钥留空表示保留已存储的密钥，但仅在 kind 不变时成立；更换 kind 必须提供新 kind 的密钥。替换 static 的 secret_access_key 时，Session Token 也会一并替换，请求未提供时则被移除，因为临时凭证是成套签发的。

api_key 和 default_chain 两种 kind，以及 static 凭证上的 session_token 或角色字段，都需要 1.7.0 或更高版本的网关。只要目标环境中注册了更早版本的网关，AISIX Enterprise 和 AISIX Cloud 就会拒绝保存此类安全护栏，并返回 422 DP_INCOMPATIBLE。

验证安全护栏

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

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

curl -sSi -X POST "$AISIX_PROXY/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"${AISIX_MODEL}"'",
    "messages": [
      {
        "role": "user",
        "content": "What is the capital of France?"
      }
    ]
  }'

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

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

curl -sSi -X POST "$AISIX_PROXY/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"${AISIX_MODEL}"'",
    "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 "$AISIX_PROXY/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"${AISIX_MODEL}"'",
    "messages": [
      {
        "role": "user",
        "content": "Draft a reply to alice@example.com about the invoice."
      }
    ]
  }'

请求成功，上游模型收到的是 Draft a reply to {EMAIL} about the invoice.。在此示例中，上游模型不会收到原始地址；原始文本仍会发送给 AWS Bedrock Guardrails 进行审核。该请求的用量事件只会记录被掩码的实体类型名称，绝不记录命中的值。

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

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

下一步

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

安全护栏行为：调整检查位置、执行模式、流式输出或远程故障处理方式。
选择安全护栏服务提供方：对比 AWS Bedrock Guardrails 和其它内置、远程安全护栏。
Azure AI Content Safety 安全护栏：在 Azure 中配置分类审核或 Prompt Shield 检查。

准备工作​

创建 Bedrock 安全护栏​

AISIX Enterprise 或 AISIX Cloud​

开源 AISIX 网关​

选择安全护栏凭证​

验证安全护栏​

PII 匿名化（掩码）​

下一步​