forked from Zakaria/hermes-agent
Hermes-agent
This commit is contained in:
Zakaria
@@ -0,0 +1,170 @@
|
||||
---
|
||||
sidebar_position: 14
|
||||
title: "AWS Bedrock"
|
||||
description: "将 Hermes Agent 与 Amazon Bedrock 配合使用——原生 Converse API、IAM 身份验证、Guardrails 及跨区域推理"
|
||||
---
|
||||
|
||||
# AWS Bedrock
|
||||
|
||||
Hermes Agent 通过 **Converse API** 原生支持 Amazon Bedrock——而非 OpenAI 兼容端点。这让你可以完整访问 Bedrock 生态系统：IAM 身份验证、Guardrails、跨区域推理配置文件以及所有基础模型。
|
||||
|
||||
## 前提条件
|
||||
|
||||
- **AWS 凭证** — [boto3 凭证链](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html)支持的任意来源：
|
||||
- IAM 实例角色（EC2、ECS、Lambda — 零配置）
|
||||
- `AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY` 环境变量
|
||||
- `AWS_PROFILE`（用于 SSO 或命名配置文件）
|
||||
- `aws configure`（用于本地开发）
|
||||
- **boto3** — 通过 `pip install hermes-agent[bedrock]` 安装
|
||||
- **IAM 权限** — 至少需要：
|
||||
- `bedrock:InvokeModel` 和 `bedrock:InvokeModelWithResponseStream`（用于推理）
|
||||
- `bedrock:ListFoundationModels` 和 `bedrock:ListInferenceProfiles`（用于模型发现）
|
||||
|
||||
:::tip EC2 / ECS / Lambda
|
||||
在 AWS 计算环境中，为实例附加带有 `AmazonBedrockFullAccess` 的 IAM 角色即可。无需 API 密钥，无需 `.env` 配置——Hermes 会自动检测实例角色。
|
||||
:::
|
||||
|
||||
## 快速开始
|
||||
|
||||
```bash
|
||||
# 安装并启用 Bedrock 支持
|
||||
pip install hermes-agent[bedrock]
|
||||
|
||||
# 选择 Bedrock 作为提供商
|
||||
hermes model
|
||||
# → 选择 "More providers..." → "AWS Bedrock"
|
||||
# → 选择你的区域和模型
|
||||
|
||||
# 开始对话
|
||||
hermes chat
|
||||
```
|
||||
|
||||
## 配置
|
||||
|
||||
运行 `hermes model` 后，你的 `~/.hermes/config.yaml` 将包含以下内容：
|
||||
|
||||
```yaml
|
||||
model:
|
||||
default: us.anthropic.claude-sonnet-4-6
|
||||
provider: bedrock
|
||||
base_url: https://bedrock-runtime.us-east-2.amazonaws.com
|
||||
|
||||
bedrock:
|
||||
region: us-east-2
|
||||
```
|
||||
|
||||
### 区域
|
||||
|
||||
通过以下任意方式设置 AWS 区域（优先级从高到低）：
|
||||
|
||||
1. `config.yaml` 中的 `bedrock.region`
|
||||
2. `AWS_REGION` 环境变量
|
||||
3. `AWS_DEFAULT_REGION` 环境变量
|
||||
4. 默认值：`us-east-1`
|
||||
|
||||
### Guardrails
|
||||
|
||||
要对所有模型调用应用 [Amazon Bedrock Guardrails](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails.html)：
|
||||
|
||||
```yaml
|
||||
bedrock:
|
||||
region: us-east-2
|
||||
guardrail:
|
||||
guardrail_identifier: "abc123def456" # 来自 Bedrock 控制台
|
||||
guardrail_version: "1" # 版本号或 "DRAFT"
|
||||
stream_processing_mode: "async" # "sync" 或 "async"
|
||||
trace: "disabled" # "enabled"、"disabled" 或 "enabled_full"
|
||||
```
|
||||
|
||||
### 模型发现
|
||||
|
||||
Hermes 通过 Bedrock 控制平面自动发现可用模型。你可以自定义发现行为：
|
||||
|
||||
```yaml
|
||||
bedrock:
|
||||
discovery:
|
||||
enabled: true
|
||||
provider_filter: ["anthropic", "amazon"] # 仅显示这些提供商
|
||||
refresh_interval: 3600 # 缓存 1 小时
|
||||
```
|
||||
|
||||
## 可用模型
|
||||
|
||||
Bedrock 模型使用**推理配置文件 ID** 进行按需调用。`hermes model` 选择器会自动显示这些 ID，并将推荐模型置于顶部：
|
||||
|
||||
| 模型 | ID | 备注 |
|
||||
|-------|-----|-------|
|
||||
| Claude Sonnet 4.6 | `us.anthropic.claude-sonnet-4-6` | 推荐——速度与能力的最佳平衡 |
|
||||
| Claude Opus 4.6 | `us.anthropic.claude-opus-4-6-v1` | 能力最强 |
|
||||
| Claude Haiku 4.5 | `us.anthropic.claude-haiku-4-5-20251001-v1:0` | 最快的 Claude |
|
||||
| Amazon Nova Pro | `us.amazon.nova-pro-v1:0` | Amazon 旗舰模型 |
|
||||
| Amazon Nova Micro | `us.amazon.nova-micro-v1:0` | 最快、最经济 |
|
||||
| DeepSeek V3.2 | `deepseek.v3.2` | 强大的开源模型 |
|
||||
| Llama 4 Scout 17B | `us.meta.llama4-scout-17b-instruct-v1:0` | Meta 最新模型 |
|
||||
|
||||
:::info 跨区域推理
|
||||
以 `us.` 为前缀的模型使用跨区域推理配置文件，可在多个 AWS 区域间提供更好的容量保障和自动故障转移。以 `global.` 为前缀的模型则在全球所有可用区域间路由。
|
||||
:::
|
||||
|
||||
## 会话中途切换模型
|
||||
|
||||
在对话过程中使用 `/model` 命令：
|
||||
|
||||
```
|
||||
/model us.amazon.nova-pro-v1:0
|
||||
/model deepseek.v3.2
|
||||
/model us.anthropic.claude-opus-4-6-v1
|
||||
```
|
||||
|
||||
## 诊断
|
||||
|
||||
```bash
|
||||
hermes doctor
|
||||
```
|
||||
|
||||
诊断工具会检查：
|
||||
- AWS 凭证是否可用（环境变量、IAM 角色、SSO）
|
||||
- `boto3` 是否已安装
|
||||
- Bedrock API 是否可达（ListFoundationModels）
|
||||
- 你所在区域的可用模型数量
|
||||
|
||||
## Gateway（消息平台）
|
||||
|
||||
Bedrock 可与所有 Hermes gateway 平台配合使用（Telegram、Discord、Slack、飞书等）。将 Bedrock 配置为提供商后，正常启动 gateway 即可：
|
||||
|
||||
```bash
|
||||
hermes gateway setup
|
||||
hermes gateway start
|
||||
```
|
||||
|
||||
Gateway 读取 `config.yaml` 并使用相同的 Bedrock 提供商配置。
|
||||
|
||||
## 故障排查
|
||||
|
||||
### "No API key found" / "No AWS credentials"
|
||||
|
||||
Hermes 按以下顺序检查凭证：
|
||||
1. `AWS_BEARER_TOKEN_BEDROCK`
|
||||
2. `AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY`
|
||||
3. `AWS_PROFILE`
|
||||
4. EC2 实例元数据（IMDS）
|
||||
5. ECS 容器凭证
|
||||
6. Lambda 执行角色
|
||||
|
||||
若均未找到，请运行 `aws configure` 或为你的计算实例附加 IAM 角色。
|
||||
|
||||
### "Invocation of model ID ... with on-demand throughput isn't supported"
|
||||
|
||||
请使用**推理配置文件 ID**（以 `us.` 或 `global.` 为前缀），而非裸基础模型 ID。例如：
|
||||
- ❌ `anthropic.claude-sonnet-4-6`
|
||||
- ✅ `us.anthropic.claude-sonnet-4-6`
|
||||
|
||||
### "ThrottlingException"
|
||||
|
||||
你已触及 Bedrock 单模型速率限制。Hermes 会自动进行退避重试。如需提高限额，请在 [AWS Service Quotas 控制台](https://console.aws.amazon.com/servicequotas/)申请配额提升。
|
||||
|
||||
## 一键 AWS 部署
|
||||
|
||||
如需在 EC2 上通过 CloudFormation 进行全自动部署：
|
||||
|
||||
**[sample-hermes-agent-on-aws-with-bedrock](https://github.com/JiaDe-Wu/sample-hermes-agent-on-aws-with-bedrock)** — 自动创建 VPC、IAM 角色、EC2 实例并配置 Bedrock。一键即可在任意区域完成部署。
|
||||
Reference in New Issue
Block a user