AIRI 接入 Amazon Bedrock 实战指南：API Key 配置、模型选择与源码级原理剖析

AIRI 通过提供者（Provider）抽象层统一接入各类 LLM 服务，Amazon Bedrock 是其中被正式支持的一员。本指南以 docs/content/ko/docs/manual/config/providers/consciousness/amazon-bedrock.md 为骨架，完整覆盖从 AWS 侧准备 API Key、在 AIRI 设置页填入配置、触发自动校验，到在“意识（Consciousness）”模块中选中模型并验证对话的完整流程，并结合仓库内提供者实现源码，深入讲解区域参数校验规则、Converse API 调用细节与模型列表拉取策略，帮助你安全、正确地让 AIRI 跑在 AWS Bedrock 之上。

为什么选择 Amazon Bedrock

Amazon Bedrock 通过 Bedrock API Key 与 AWS 区域（Region）来访问账户中被授予访问权限的基础模型。与自建 API 网关或第三方中转不同，Bedrock 的模型访问、区域和计费全部复用 AWS 账户体系：

• 如果你已经在 AWS 上管理模型访问权限、区域和结算，接入 Bedrock 不需要额外的账号体系，同一套账户管理方式可以直接沿用；
• 模型通过 AWS 侧的“模型访问（Model Access）”按账户授权，AIRI 只负责发起请求，无需自行维护凭证之外的任何基础设施；
• 在 AIRI 的提供者体系中，Amazon Bedrock 被归类为付费云服务提供者（见 packages/stage-ui/src/libs/providers/attributes.ts 中 'amazon-bedrock': paidCloud 的标记），这意味着它走的是标准的云 API Key 校验与计费链路。

第一步：在 AWS 侧准备 Bedrock API Key

在接触 AIRI 之前，需要先在 AWS 控制台完成两步准备工作：

1. 打开 Amazon Bedrock 控制台，在“Model access”页面启用你计划使用的目标模型（例如 Amazon Nova 系列或 Anthropic Claude 系列）；
2. 在同一账户、同一区域下创建 Bedrock API Key，供 AIRI 调用使用。

安全提醒：请勿泄露 Bedrock API Key。它应只保存在 AIRI 的提供者配置中，不再需要时应及时在 AWS 侧回收/删除。仓库的 i18n 文案也明确提示该 Key 需要在 AWS Console → Bedrock → API Keys 中生成（见 packages/i18n/src/locales/ko/settings.yaml 中 api-key 的说明）。

第二步：在 AIRI 中配置 Amazon Bedrock

打开 设置 → 提供者 → 聊天 → Amazon Bedrock，在表单中填写两个字段：

字段	说明	默认值 / 约束
Amazon Bedrock API Key	在 AWS Console 生成的 Bedrock API Key	必填，不能为空字符串
AWS Region	Bedrock 已启用的 AWS 区域	默认 us-east-1，需匹配区域命名规范

从源码层面看，这两个字段在 packages/stage-ui/src/libs/providers/providers/amazon-bedrock/index.ts 的配置 Schema 中有着明确的约束：

const amazonBedrockConfigSchema = z.object({
  apiKey: z
    .string('Amazon Bedrock API Key')
    .min(1),
  region: z
    .string('AWS Region')
    .regex(/^[a-z]{2,3}-[a-z]+-\d+$/, 'Must be a valid AWS region (e.g. us-east-1, ap-southeast-1)')
    .optional()
    .default('us-east-1'),
})

值得注意的细节：

• Region 有格式校验：必须形如 us-east-1、ap-southeast-1（[a-z]{2,3}-[a-z]+-\d+），填错会直接提示非法区域；
• Region 可以省略：不填写时默认回落为 us-east-1；
• API Key 必填：至少 1 个字符才会触发校验逻辑；
• 没有自定义端点字段：AIRI 的 Amazon Bedrock 表单只提供 API Key 与 Region 两个输入框（见 packages/stage-pages/src/pages/settings/providers/chat/amazon-bedrock.vue），请求地址由区域参数推导而来，不支持自定义 baseURL。

请求地址的推导逻辑位于同一文件的 createBedrockConverseProvider 与 createProvider 中：

const baseURL = `https://bedrock-runtime.${region}.amazonaws.com/v1/`

也就是说，只要你填写的区域在 AWS 上真实存在且该账户开通了 Bedrock，AIRI 就会自动指向 bedrock-runtime.<region>.amazonaws.com 发起调用。

第三步：等待自动校验通过

填入 API Key 与 Region 后，AIRI 会自动触发提供者校验，无需手动保存或点击测试按钮。

校验器的实现（index.ts）会向 https://bedrock.<region>.amazonaws.com/foundation-models 发起一次只读请求：

const res = await fetch(
  `https://bedrock.${region}.amazonaws.com/foundation-models?byInferenceType=ON_DEMAND&byOutputModality=TEXT&byProvider=Amazon&maxResults=1`,
  { method: 'GET', headers: { authorization: `Bearer ${apiKey}` } },
)
if (res.status === 403 || res.status === 401) {
  errors.push({ error: new Error('Invalid Amazon Bedrock API key or insufficient permissions.') })
}

• 返回 403/401 时判定为 “API Key 无效或权限不足”；
• 网络异常时判定为 “无法连接，请检查区域与网络”。

校验状态会实时反映在设置页上：失败时页面显示红色错误提示，并附有 “继续（Continue Anyway）” 按钮（见 chat/amazon-bedrock.vue），用于在确认配置无误但校验服务不可达时强行继续；成功时显示绿色成功提示，并可直接跳转到模型选择页面。

另外注意 validationRequiredWhen 的逻辑（index.ts）：只有填入了 API Key 才要求校验。对应的单元测试也覆盖了三种情况（index.test.ts）：

• 有 Key + Region：需要校验；
• Key 为空：不需要校验；
• 只填了 Region、没有 Key：不需要校验。

第四步：在“意识”模块中选用模型

校验通过后，进入 设置 → 模块 → 意识（Consciousness）：

1. 将“提供者”切换为 Amazon Bedrock；
2. 从模型列表中选中一个已授权可用的模型；
3. 发送一条消息验证整个链路（Key → Region → 模型访问 → 对话）是否通畅。

模型列表的加载由“意识”模块 Store 驱动（packages/stage-ui/src/stores/modules/consciousness.ts）：当 activeProvider 被设为 amazon-bedrock 且该提供者支持模型列举时，Store 会调用 fetchModelsForProvider 拉取模型目录；切换提供者时旧的模型选择会被自动清空，避免跨提供者使用不存在的模型 ID 导致 model_not_found。

AIRI 拉取 Bedrock 模型列表的方式也值得展开（index.ts）：

1. 并行请求 foundation-models 接口，过滤出 Amazon、Anthropic、Moonshot、Minimax、DeepSeek 五类按需（ON_DEMAND）文本模型的摘要；
2. 再拉取系统定义的推理配置文件（inference-profiles，SYSTEM_DEFINED），解析出 global./us. 前缀的跨区域 ID；
3. 为每个基础模型优先选择 global. 前缀、其次 us. 前缀的推理配置 ID 作为最终模型 ID（跨区域 ID 在多数区域可用性更广）；
4. 对未出现在基础模型列表中的新模型（如仅以 profile 形式存在的更新型号）做补充；
5. 如果 API 完全不可用，则回落到一个静态模型列表（index.ts），其中包含 Amazon Nova Pro / Lite / Micro、Claude Sonnet 3.5 v2、Claude Sonnet 3.7 等常见模型，保证设置页始终有模型可选。

对应的测试（index.test.ts）通过 stub 掉全局 fetch 并返回 401，验证了“API 不可用时回落到包含 nova 的静态模型列表”这一兜底行为。

请求是如何真正发到 Bedrock 的

AIRI 在浏览器端直接与 Bedrock 通信，走的路径是 Converse API（非流式）。由于 Bearer Token 鉴权不支持 /converse-stream 所需的二进制事件流协议，源码中的自定义 fetch 拦截器（index.ts）做了这样几件事：

1. 解析 xsai 聊天请求体，把 system 消息与普通消息分离；
2. 将消息内容转换为 Converse 的 content 块格式，并把连续相同角色的消息合并（Converse API 要求角色交替出现）；
3. 构造 inferenceConfig，其中 maxTokens 默认 4096，temperature 仅在显式传入时才写入；
4. POST 到 https://bedrock-runtime.<region>.amazonaws.com/model/<modelId>/converse；
5. 拿到完整响应后，将其重新包装成 SSE 流（三个 chat.completion.chunk + [DONE]），让 xsai 管线其余部分仍按标准流式响应处理。

这意味着即使底层是非流式 API，AIRI 的对话界面依然能呈现逐段输出的体验，而对上层业务透明。

问题排查

如果校验失败或对话不通，按以下顺序逐一核对：

1. API Key 是否正确：是否在 AWS Console 的 Bedrock API Keys 中生成，复制时是否有空格或换行；
2. 区域是否一致：AIRI 中填写的 Region 与创建 Key、启用模型访问的区域必须相同，且符合 us-east-1 这类命名规范（可用 us-west-2、ap-southeast-1 等替换）；
3. 模型访问是否同一账户：Key、Region、模型访问权限必须归属于同一个 AWS 账户；
4. 模型列表为空/选不到模型：到 Bedrock 控制台确认该账户在当前区域确实开通了目标模型的访问权限。如果列表始终为空，可确认是否为 API 临时不可用——此时 AIRI 会回落到内置的静态模型列表，你仍可手动选择其中的模型 ID 继续使用。

补充：视觉（Vision）模块同样支持 Bedrock

除聊天（Chat）外，AIRI 的视觉模块也有一个对应的 Bedrock 配置页（packages/stage-pages/src/pages/settings/providers/vision/amazon-bedrock.vue），其内部 providerId 为 vision-amazon-bedrock，字段（API Key + Region）与校验流程和聊天模块完全一致。如果你在“意识”模块之外还需要视觉能力，可以在 设置 → 提供者 → 视觉 → Amazon Bedrock 中复用同一份 AWS 配置。

小结

把 AIRI 接到 Amazon Bedrock 的本质，是完成“AWS 账户侧授权”与“AIRI 侧填两个字段”的对接：

• AWS 侧：启用模型访问、生成 Bedrock API Key，并确保账户与区域一致；
• AIRI 侧：在 设置 → 提供者 → 聊天 → Amazon Bedrock 填入 API Key 与 Region（默认 us-east-1），等待自动校验，再到 设置 → 模块 → 意识 选择模型即可对话。

整个过程没有自定义端点、没有额外代理，AIRI 会依据 Region 自动推导 Bedrock Runtime 地址、自动拉取或回落模型列表，并通过封装 Converse API 的方式保持对话体验一致。核心实现可继续深入阅读 packages/stage-ui/src/libs/providers/providers/amazon-bedrock/index.ts 及其测试 index.test.ts，设置页源码见 chat/amazon-bedrock.vue。