版本：1.4.0

AWS Bedrock

Amazon Bedrock 是一项 AWS 服务，可通过托管 API 访问 Amazon 及其他服务提供方的基础模型。AISIX 为应用提供统一的 OpenAI 兼容接口，用于访问由 Bedrock 托管的 Claude、Llama、Mistral、Amazon Nova、Cohere 等模型。

此配置适用于需要使用 AISIX 身份验证、模型允许列表、限流和用量核算的 Bedrock 托管模型。AISIX 使用 AWS SigV4 对出站 Bedrock 调用进行签名。

准备工作

开始前，请准备以下内容：

一套 AISIX 环境：
- 对于 AISIX Cloud，需要一个已关联网关的环境和具有写入作用域的 Admin Token。对于 On-Premises，请按照 AISIX Cloud 快速入门操作。如需申请 Hybrid Cloud 访问权限，请联系 API7。
- 对于开源 AISIX 网关，请准备本地 AISIX 安装，或使用开源 AISIX 网关快速入门中的 Docker 环境。配置网关以加载声明式资源文件。
对目标模型具有 bedrock:InvokeModel 权限的 AWS Access Key ID 和 Secret Access Key；使用临时凭证时还可提供 STS Session Token。
对于跨区域推理，需要对推理配置文件 ARN、源区域以及每个目标区域中的基础模型 ARN 拥有 bedrock:InvokeModel 权限。具体要求参见 AWS 的地理区域和全球推理配置文件说明。
对所选区域中目标 Bedrock 模型的访问权限，以及该模型的模型 ID 或推理配置文件 ID。
curl 和 jq。

使用 AISIX Cloud 配置

导出 AISIX Cloud 连接信息：

# AISIX_CP 是 Admin API 基础 URL；应包含 /api，且不含尾部斜杠
# 本地私有化部署快速入门使用 http://localhost:8080/api
export AISIX_CP="YOUR_AISIX_CLOUD_ADMIN_API_URL"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"

使用 Bedrock 目录服务提供方和结构化 config 凭证创建服务提供方密钥：

PROVIDER_KEY_ID=$(curl -sS -X POST "$AISIX_CP/provider_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "bedrock-prod",
    "provider": "amazon-bedrock",
    "api_key": "",
    "api_base": "https://bedrock-runtime.us-west-2.amazonaws.com",
    "config": {
      "access_key_id": "YOUR_AWS_ACCESS_KEY_ID",
      "secret_access_key": "YOUR_AWS_SECRET_ACCESS_KEY",
      "region": "us-west-2"
    },
    "allowed_environments": ["'"$ENV_ID"'"]
  }' | jq -r '.provider_key.id')

api_key 留空是有意为之。即使 config 提供了结构化 Bedrock 凭证，创建请求仍要求包含此字段。更新 config 时应省略 api_key，不要再次发送空字符串。

开源网关可以推导标准 AWS 端点，但 AISIX Cloud 当前要求为 Bedrock 显式设置 api_base。主机名和 config 中的区域必须设置为相同值。Dashboard 会显示 Access Key ID、Secret Access Key 和区域字段。如果通过 AISIX Cloud Admin API 使用临时 STS 凭证，还需在 config 中添加 session_token。

为 Claude Sonnet 5 创建别名。该模型不支持在 us-west-2 区域内推理，因此示例使用其美国地理区域推理配置文件：

MODEL_ID=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/models" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "claude-bedrock",
    "model_name": "us.anthropic.claude-sonnet-5",
    "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
  }' | jq -r '.model.id')

创建可访问该模型的调用方 API Key：

BEDROCK_CALLER_KEY=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/api_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "bedrock-caller",
    "allowed_models": ["'"${MODEL_ID}"'"]
  }' | jq -r '.plaintext')

使用开源 AISIX 网关配置

导出 AWS 凭证，并选择应用将发送给 AISIX 的调用方 API Key：

# 请替换为实际值
export BEDROCK_CREDENTIALS='{"access_key_id":"YOUR_AWS_ACCESS_KEY_ID","secret_access_key":"YOUR_AWS_SECRET_ACCESS_KEY","region":"us-west-2"}'
export BEDROCK_CALLER_KEY="YOUR_CALLER_API_KEY"

对于新网关，请使用此完整资源文件。对于现有网关，请将这些条目合并到其当前文件中，并保留其他资源。

resources.yaml
_format_version: "1"

provider_keys:
  - display_name: bedrock-prod
    provider: amazon-bedrock
    adapter: bedrock
    api_key: ${BEDROCK_CREDENTIALS}

models:
  - display_name: claude-bedrock
    provider: amazon-bedrock
    model_name: us.anthropic.claude-sonnet-5
    provider_key: bedrock-prod

api_keys:
  - display_name: bedrock-caller
    key_env: BEDROCK_CALLER_KEY
    allowed_models: ["claude-bedrock"]

❶ provider 用于标记上游。

❷ adapter 选择 Bedrock。

❸ api_key 是包含 access_key_id、secret_access_key 和 region 的 JSON 字符串。Bedrock 端点按区域确定，例如 bedrock-runtime.us-west-2.amazonaws.com，因此区域为必填项。对于标准 AWS，应不设置 api_base；如果使用私有 Bedrock 端点，则将其设置为该端点。

❹ model_name 是 Bedrock 模型 ID 或完整的推理配置文件 ID。示例中的 us. 配置文件可从 us-west-2 使用，并将推理限制在美国和加拿大境内。

❺ provider_key 通过服务提供方密钥的 display_name 将模型关联到凭证。模型的 provider 使用与服务提供方密钥相同的上游标签。

要在示例文件中使用 Meta Llama，请替换 claude-bedrock 模型条目，并更新 bedrock-caller 以允许新别名。保留 bedrock-prod 和其他资源不变：

resources.yaml（Meta Llama 模型访问）
models:
  - display_name: llama-bedrock
    provider: amazon-bedrock
    model_name: us.meta.llama3-3-70b-instruct-v1:0
    provider_key: bedrock-prod

api_keys:
  - display_name: bedrock-caller
    key_env: BEDROCK_CALLER_KEY
    allowed_models: ["llama-bedrock"]

对于 Amazon Nova，请使用 Bedrock 模型或推理配置文件 ID，例如从 us-west-2 使用的 Nova 2 Lite 配置文件 us.amazon.nova-2-lite-v1:0。与 Claude 和 Llama 示例一样，us. 前缀选择美国地理区域推理配置文件。网关会从 BEDROCK_CALLER_KEY 读取明文调用方 Key，并且只存储其哈希。

下面的验证使用 claude-bedrock。如果应用了 Meta Llama 配置块，请改为发送 llama-bedrock，并预期响应中出现该别名。

使用临时 STS 凭证时，请在凭证 JSON 中包含 session_token；使用长期静态密钥时则省略该字段。服务提供方密钥 Secret 遵循服务提供方密钥中说明的凭证处理方式。

验证并加载配置

如果 AISIX 安装在本地，请在加载前验证完整文件：

aisix validate --resources resources.yaml

验证后，在网关进程环境中提供文件引用的环境变量，再启动网关。仅当这些变量已经可供进程使用时，才重新加载现有网关；否则，请使用更新后的环境重启网关。

如果使用 Docker，请调整开源 AISIX 网关快速入门中的验证和启动命令。挂载此 resources.yaml 文件，并在两条命令中使用 -e 传入它引用的每个环境变量。

验证服务提供方连接

导出 AISIX 网关 Origin：

# AISIX_PROXY 不含尾部斜杠或端点路径
# 本地快速入门使用 http://127.0.0.1:3000
export AISIX_PROXY="YOUR_AISIX_GATEWAY_URL"

通过 AISIX 代理发送 Chat Completions 请求：

curl -sS -X POST "$AISIX_PROXY/v1/chat/completions" \
  -H "Authorization: Bearer ${BEDROCK_CALLER_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-bedrock",
    "messages": [
      {
        "role": "user",
        "content": "Say hello from Bedrock."
      }
    ]
  }'

网关会返回 OpenAI 兼容响应，其中包含面向调用方的别名：

{
  "id": "msg_01example",
  "object": "chat.completion",
  "model": "claude-bedrock",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello from Bedrock!"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 5,
    "total_tokens": 14
  }
}

在 Bedrock 调用指标、CloudTrail 或服务提供方侧日志中检查测试请求。如果 AISIX 返回上游身份验证或授权错误，请检查 AWS 凭证、区域、IAM 权限和 Bedrock 模型访问权限。

结构化输出

携带 JSON schema 的 response_format——直接发送到 /v1/chat/completions，或由 Responses 的 text.format、Anthropic Messages 的 output_config.format 转换而来——在 Bedrock 上会被传达给模型。具体形状取决于模型：

Claude 4.5 及更新的模型能够约束自己的解码，因此 schema 以原生方式上送。AISIX 会先从 Bedrock 模型 ID 中读出 Claude 模型名，因此裸 ID（anthropic.claude-sonnet-4-5-...）、跨区域 ID（us.anthropic.claude-...）以及推理配置文件 ARN 都能识别。非流式的 Claude 请求走 Anthropic Messages 协议，schema 放在 output_config.format；Converse 和 ConverseStream 则放在 outputConfig.textFormat，其中 schema 是一个 JSON 字符串，schema 名称在调用方指定时沿用调用方自己的名称。
其余 Converse 实现支持工具调用的模型——Amazon Nova、Meta、Mistral、Cohere，以及更早的 Claude 系列——走合成工具路径：一个入参即为答案的 json_tool_call 工具，回复会被翻译回常规内容，流式请求以模拟流式返回。AISIX 只在 Converse 认可显式工具选择的发布方上添加强制调用，即 Anthropic Claude 和 Amazon Nova；其他发布方只提供该工具，由模型自行选择这唯一一个工具。
Converse 实现完全不支持工具调用的模型——Amazon Titan Text、DeepSeek，以及 AISIX 未归类的发布方——不处理该字段，作答方式与以前一致。给它们附加工具配置会让整个请求失败，包括本身并不携带任何工具的请求。

无论哪种模型，调用方自己发送的工具都会照常转发：发布方不支持的工具是调用方显式要求的，理应由调用方看到上游的拒绝。{"type": "json_object"} 没有指定 schema，在两条路径上都不会写入任何内容。

Bedrock 记载的 JSON Schema 子集与 Anthropic 相同，因此 schema 的密封和收窄方式也一致，参见 AISIX 如何调整 schema。

准备生产环境

如果应用使用流式传输，请在 AWS 权限中添加 bedrock:InvokeModelWithResponseStream，并确认目标模型的流式传输行为。

请至少发送一条用户或助手消息。Bedrock Converse 不接受仅包含系统消息的请求，因此 AISIX 会在调用服务提供方之前拒绝此类请求。该检查覆盖走 Converse 路径的每个请求：所有非 Claude 模型，以及流式 Claude 请求。只有非流式 Claude 请求改走 invoke 路径，response_format 走合成工具路线的流式 Claude 请求也是如此。

面向调用方的错误会隐去 AWS 返回的上游错误详情，避免泄露 ARN、区域和账户 ID 等 AWS 标识符。

后续步骤

你已将 AISIX 连接到 AWS Bedrock，并验证了模型别名。接下来可阅读以下指南：

Anthropic：改为通过 Anthropic API 配置 Claude。
模型别名：为别名配置路由、重试行为或成本元数据。
服务提供方兼容性：查看支持的代理端点和服务提供方特定边界。

准备工作​

使用 AISIX Cloud 配置​

使用开源 AISIX 网关配置​

验证并加载配置​

验证服务提供方连接​

结构化输出​

准备生产环境​

后续步骤​