> 原始 Markdown 孪生体（构建期从源 Markdown 生成）。渲染页：https://docs.gatellm.io/zh-CN/quickstart/aws-bedrock · 文档索引：https://docs.gatellm.io/zh-CN/llms.txt


# 接入 AWS Bedrock 上游

AWS Bedrock 是上游侧协议——网关**不暴露** Bedrock 形态的客户端端点。客户端用 OpenAI / Anthropic / Gemini 等协议端点（经网关翻译）访问 Bedrock 模型，或用 `/v3/{model}/{*rest}` 透传。本章教你建一个 AWS Bedrock 上游 + 模型，并用 OpenAI SDK 调用。

## 前置

- 网关已运行（`http://localhost:7890`），能登录控制台
- 已设 `ENCRYPTION_KEY`——下面要保存的上游 API key 与访问密钥都落库前加密，没设会在保存时报 `encryption_key not set in config`。见 [Docker 单机跑通 → 前置](/zh-CN/quickstart/docker-single-node.md#prereq)
- Bedrock API key（在 Amazon Bedrock 控制台 →「API 密钥」签发，长期或短期均可）
- 知道要调用的 Bedrock 模型 ID（如 `anthropic.claude-3-5-sonnet-...`、`zai.glm-5` 等）
- 知道区域（如 `us-west-2`、`us-east-1`）

## 1. 建 AWS Bedrock 上游

控制台 → **上游服务** → **新建**：

| 字段 | 值 | 说明 |
|------|-----|------|
| 名称 | `aws-global` | 上游唯一标识 |
| 协议 | `aws_converse` | Bedrock Converse API；如走 InvokeModel 路径用 `aws_invoke` |
| 基础 URL | `https://bedrock-runtime.us-west-2.amazonaws.com` | Bedrock runtime 端点 |
| API Key | Bedrock API key 原文 | 直接粘贴 Bedrock API key 一个值。**不要**填 `access_key_id` / `secret_access_key`，也不要拼成 `id:secret:region` 之类的组合串 |
| 启用 | ✓ | |

保存。

> 网关以 `Authorization: Bearer <API Key>` 访问 Bedrock runtime，因此这里要填的是 **Bedrock API key**，不是 IAM 的 access key ID / secret。区域由基础 URL 决定（`https://bedrock-runtime.<region>.amazonaws.com`），换区域就换上游的基础 URL。

## 2. 建 Bedrock 模型

在上游 `aws-global` 行点 **展开** → 模型子表 → **新建模型**：

| 字段 | 值 | 说明 |
|------|-----|------|
| 名称 | `glm-5` | 对外暴露给客户端的模型名 |
| 上游 | `aws-global` | 选刚建的上游 |
| 上游模型 ID | `zai.glm-5` | Bedrock 真实模型 ID |
| 启用 | ✓ | |

保存。

### 用 inference_profile 覆盖模型 ID

如果 Bedrock 用应用推理配置（inference profile）路由流量，把 `inference_profile` 字段填上 ARN，覆盖 `upstream_model_id` 作为发往上游的真实 ID：

```json
{
  "name": "glm-5",
  "upstream": ["aws-global"],
  "upstream_model_id": "zai.glm-5",
  "upstream_inference_profile": "arn:aws:bedrock:us-west-2:123456789012:inference-profile/abcd1234"
}
```

设置后，该值在所有请求中作为上游模型 ID 使用，`upstream_model_id` 作为备用。

### 协议覆盖（OpenAI 兼容）

如果想用 OpenAI 协议端点访问 Bedrock 模型，让上游协议仍是 `aws_converse`，但模型层用 `protocol` 覆盖为 `openai`：

```json
{
  "name": "glm-5",
  "upstream": ["aws-global"],
  "upstream_model_id": "zai.glm-5",
  "protocol": "openai",
  "base_url": "https://bedrock-runtime.us-west-2.amazonaws.com/openai/v1"
}
```

凭证仍来自上游配置，仅改变请求的目标端点与协议格式。`base_url` 结尾不带 `/`（与全站约定一致；即便带了，网关也会在拼接前自动去掉）。

## 3. 配密钥组放行

控制台 → **访问密钥** → **密钥组** 页签 → **新建**：

| 字段 | 值 | 说明 |
|------|-----|------|
| 名称 | `default` | 分组名 |
| 模型 | 选 `glm-5`，或 `*`（全部） | 决定该组密钥能调哪些模型 |
| 启用 | ✓ | |

## 4. 签发访问密钥

控制台 → **访问密钥** → **新建**：

| 字段 | 值 | 说明 |
|------|-----|------|
| 名称 | `my-app-key` | 密钥的标识，用于管理与审计 |
| API 密钥 | 点「生成」 | 自动生成一串，客户端调用时带的凭证 |
| 分组 | `default` | 决定这把密钥能访问哪些模型 |
| 启用 | ✓ | |

## 5. 用 OpenAI SDK 调用

```python
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:7890/v1",
    api_key="<你的访问密钥>",
)

resp = client.chat.completions.create(
    model="glm-5",
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)
```

网关收到 OpenAI 格式请求，按模型配置翻译成 Bedrock 协议（`aws_converse` 或 `aws_invoke`），发给 Bedrock runtime，响应翻译回 OpenAI 格式返回。

## 6. 或用透传

当客户端协议与该模型配置的目标协议相同时，可以用 `/v3/{model}/{*rest}` 透传，请求体原样转发。`{*rest}` 会以 nginx 反代风格拼到上游 `base_url` 之后——对 Bedrock Converse，`{*rest}` 就是 `/model/<上游模型 ID>/converse`。一个最小 converse 请求：

```bash
curl http://localhost:7890/v3/glm-5/model/zai.glm-5/converse \
  -H "Authorization: Bearer <你的访问密钥>" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": [{"text": "你好"}]}
    ]
  }'
```

网关把 `model/zai.glm-5/converse` 拼到上游 `https://bedrock-runtime.us-west-2.amazonaws.com` 之后，请求体（Bedrock 原生 converse 格式）原样转发。流式用 `.../converse-stream`。

## 跨协议细节

- AWS Bedrock 是上游侧协议：客户端用 OpenAI / Anthropic / Gemini 等协议端点访问，网关做协议互译
- 客户端协议与上游协议相同时走 identity（请求体原样转发）；其中 `Anthropic→Anthropic` 是同协议非透传翻译器
- 完整互通矩阵见 [协议互通矩阵](/zh-CN/reference/protocol-matrix.md)
- 跨协议工具调用时，`tool_call_id` 在跨协议往返中必须保留原值

## 常见问题

**Q：客户端报 400 unsupported_feature？**
该「客户端协议 → 上游协议」组合没有翻译器。检查 [协议互通矩阵](/zh-CN/reference/protocol-matrix.md)。

**Q：客户端报 403？**
- 403 model_access_denied：密钥组「模型」列表没包含 `glm-5`
- 403 ip_banned：你的 IP 被封禁（连续登录失败触发）

**Q：客户端报 502 bad_gateway？**
上游不通。检查 Bedrock runtime URL、API key、区域。

**Q：能用 IAM access key / secret 或 EC2 IAM Role 吗？**
不能。网关只用 `Authorization: Bearer` 携带 Bedrock API key，不做 SigV4 签名、不读 EC2 实例元数据。请在 Bedrock 控制台签发 API key 后填入上游的 API Key 字段。

**下一步**：[上游与模型字段](/zh-CN/reference/upstreams-models-fields.md) 看上游/模型完整字段；[端点 · 认证 · 协议互通](/zh-CN/reference/endpoints.md) 看完整端点清单；[协议互通矩阵](/zh-CN/reference/protocol-matrix.md) 看 Bedrock 与其他协议的互通情况。