AIRI 接入 Amazon Bedrock 聊天模型实战：凭据、区域配置与 Converse API 实现原理-育师

人工智能
AI Agent
MCP 服务
工具调用
GUI 自动化
语音
数字人
交互助手

【免费下载链接】airi

💖🧸 自托管、归你拥有的 Grok 风格 AI 伴侣与 waifu / 赛博生命灵魂容器，目标是接近 Neuro-sama 的高度；支持实时语音聊天、Minecraft 和 Factorio 游玩，支持 Web / macOS / Windows。

项目地址：https://gitcode.com/moeru-ai/airi

点击查看免费下载

本文基于 AIRI 仓库中的官方手册 Amazon Bedrock 配置文档，讲解如何在 AIRI 中使用 AWS 凭据与区域配置接入 Amazon Bedrock 聊天模型，并结合 provider 实现源码深入剖析消息转换、非流式 Converse 调用的 SSE 重放策略、模型列表拉取逻辑与配置校验链路。读完本文，你不仅能完成凭据准备、配置填写与 Ping 验证的完整接入流程，还能理解 AIRI 底层是如何把一个 Bearer Token 认证的 AWS 端点适配进统一的 xsai 聊天管道。

为什么选择 Amazon Bedrock？

Amazon Bedrock 使用 AWS 凭据和区域来访问已获授权的基础模型。如果你已经在 AWS 中管理模型访问权限、区域和计费，Bedrock 可沿用这一套账户管理方式，无需为 AIRI 单独申请第三方的 API 平台账号。

在 AIRI 的 provider 体系中，amazon-bedrock被归类为云端付费服务商。可以在 provider 属性表中看到'amazon-bedrock': paidCloud的登记，这意味着它属于需要外部网络访问与账户授权的云端推理服务，与本地推理类 provider 的管理方式不同。

第一步：准备 AWS 凭据

打开并登录 AWS Management Console（Bedrock 控制台），创建具备 Bedrock 权限的访问凭据。
在控制台的 Bedrock → API Keys 中生成 API Key，并在 Bedrock 已启用的区域中申请目标模型的访问权限。

AWS 凭据安全：不要公开 AWS 访问密钥。请使用权限最小化的凭据，并在不再使用时撤销。

AIRI 界面中对该字段的中文说明（见 zh-Hans 文案文件）也明确提示：Bedrock API 密钥需在「AWS 控制台 → Bedrock → API Keys」中生成；AWS 区域需填写 Bedrock 已激活的区域，例如us-east-1、us-west-2。

第二步：在 AIRI 中配置

打开设置 → 服务商 → 聊天 → Amazon Bedrock，填写 AWSAPI Key，并选择区域；默认区域为us-east-1。
确认该 AWS 账户已在对应区域获得目标模型的访问权限。只有在使用自定义 Bedrock Endpoint 时才填写自定义地址。

配置项与校验规则

对应的聊天配置页由 amazon-bedrock.vue 实现，页面上暴露两个字段：apiKey（必填，密码型输入框）与region（文本输入框，占位符为us-east-1）。这两项的配置约束在 provider 定义的 zod schema 中（schema 定义）：

配置项	类型	必填	校验规则	默认值
`apiKey`	string	是	非空（`.min(1)`），界面以密码框展示	无
`region`	string	否	正则`^[a-z]{2,3}-[a-z]+-\d+$`（如`us-east-1`、`ap-southeast-1`）	`us-east-1`

从源码结构看，region的取值直接参与拼接请求域名：所有运行时请求发往https://bedrock-runtime.{region}.amazonaws.com，元数据请求发往https://bedrock.{region}.amazonaws.com。因此区域写错不会导致"格式校验失败"，而是表现为请求打到错误的区域端点——这也是排查时需要重点关注凭据、区域、模型权限三者是否属于同一账户同一区域的原因。

第三步：验证配置（Ping API）

Ping API：点击此按钮测试凭据、区域和网络是否正确。
选择模型：测试成功后，选择账户已授权的模型，再到设置 → 意识启用。

AIRI 中这一步由 provider 注册时的validators.validateProvider完成（校验器实现），其行为可以从源码中精确读出：

请求：GET https://bedrock.{region}.amazonaws.com/foundation-models?byInferenceType=ON_DEMAND&byOutputModality=TEXT&byProvider=Amazon&maxResults=1，请求头携带authorization: Bearer {apiKey}；
返回401或403时，报Invalid Amazon Bedrock API key or insufficient permissions.；
网络层失败（如区域端点不可达）时，报Failed to connect to Amazon Bedrock. Check your region and network.。

校验是否被触发由validationRequiredWhen决定：只有apiKey去除空白后非空时才要求校验（相关逻辑），这在测试用例中有明确覆盖——有 key 返回true，空 key 或仅有 region 时返回false。

配置页的交互同样值得注意：验证失败时页面会展示红色 Alert 与错误信息，并额外提供一个"继续"按钮（forceValid），允许在确认误判时强行通过；验证成功后则出现绿色 Alert，点击即可跳转到设置 → 意识进行模型选择（见配置页模板与goToModelSelection）。

底层原理：AIRI 如何调用 Bedrock Converse API

AIRI 的 Bedrock provider 没有直接调用 AWS SDK，而是通过一个自定义fetch拦截器把 xsai 聊天请求重写成 Bedrock Converse API 请求。核心实现在 createBedrockConverseProvider，整体链路如下。

请求改写：从 OpenAI 风格消息到 Converse 消息

分离 system 消息：从messages中过滤出role === 'system'的消息放入converseBody.system数组，其余消息进入messages数组。
内容块转换：toConverseContent将字符串内容包成[{ text }]，将内容数组中type === 'text'的条目映射为{ text }块（转换逻辑）。
合并连续同角色消息：Converse API 要求 user/assistant 角色交替出现，mergeConsecutiveRoles会把相邻的同类消息内容合并到一条中（合并逻辑）。例如连续两条 user 消息会被拼成一条 user 消息的多个内容块。
推理参数映射：max_tokens映射为inferenceConfig.maxTokens（缺省 4096），temperature映射为temperature，top_p映射为topP；未设置的参数不会出现在请求体中（参数构建）。

非流式调用 + SSE 重放

一个关键设计点值得展开：provider 显式使用/converse（非流式）端点，而不是/converse-stream。源码注释给出了原因——Bearer Token 认证不支持/converse-stream所需的二进制事件流协议（端点注释）。请求发往：

POST https://bedrock-runtime.{region}.amazonaws.com/model/{modelId}/converse

拿到完整响应后，拦截器把output.message.content中所有text块拼接为fullText，再将结果封装成一个text/event-stream响应，按 OpenAI chat completion chunk 格式依次 enqueue：先 role 块、再 content 块、最后携带finish_reason的收尾块和data: [DONE]。stopReason为end_turn时映射为stop（SSE 重放实现）。

从源码结构看，这意味着上层 xsai 管道始终"看到"一个标准的流式响应，但对 Bedrock 而言实际是整包返回——Bedrock 通道的体验不会出现逐 token 流式输出，这是 Bearer 认证形态下的实现取舍。

provider 组装与任务能力

createProvider将上述聊天 provider 与一个createModelProvider（使用https://bedrock-runtime.{region}.amazonaws.com/v1/作为 baseURL 占位）合并后返回（组装逻辑）。该 provider 在注册表中声明id: 'amazon-bedrock'、order: 18、tasks: ['chat']，即面向聊天任务。

模型列表是怎么来的

点击"选择模型"时看到的列表来自extraMethods.listModels（模型列表实现），其拉取策略分为五步：

并行拉取基础模型：对Amazon、Anthropic、Moonshot、Minimax、DeepSeek五个供应商，分别请求GET {base}/foundation-models?byInferenceType=ON_DEMAND&byOutputModality=TEXT&byProvider={供应商}，只保留按需推理（ON_DEMAND）且文本输出的模型；
拉取系统推理配置：GET {base}/inference-profiles?type=SYSTEM_DEFINED&maxResults=1000，获取global./us.前缀的跨区域推理 profile；
建立映射：将 profile id 拆为前缀（global/us）与基础模型 id（如amazon.nova-pro-v1:0），形成查找表；
择优展示：对每个基础模型，优先选global.前缀的 profile id，其次us.前缀，最后回退为原始模型 id；
补充 profile 独有模型：某些较新模型只存在于 inference profiles 中而不在 foundation-models 列表里，代码会按amazon.、anthropic.、moonshot.、minimax.、deepseek.前缀过滤后追加进来，且同一模型在global与usprofile 并存时只保留global。

如果以上请求全部失败（网络不通、凭据无效等），listModels会返回一份静态兜底列表fallbackModels，包括 Amazon Nova Pro / Lite / Micro、Claude Sonnet 3.5 v2、Claude Sonnet 3.7（兜底列表）。测试用例专门用 mock 的 401 响应验证了这条兜底路径：列表非空且包含 nova 模型。

需要注意的是，兜底列表只是保证界面可用；实际能否调用某个模型，仍取决于该 AWS 账户在所选区域的真实授权情况。

排查

验证失败时，检查 AWS 凭据、所选区域与模型访问权限是否属于同一账户。模型无法选择时，先在 Bedrock 控制台为该区域申请并启用对应模型。

结合源码，可以把排查清单再细化一层：

现象	对应错误/原因	检查点
凭据无效	`Invalid Amazon Bedrock API key or insufficient permissions.`（HTTP 401/403）	API Key 是否过期、是否具备 Bedrock 读取权限
无法连接	`Failed to connect to Amazon Bedrock. Check your region and network.`	区域端点是否可达、区域格式是否为`xx-xxx-N`
模型列表为空或不全	foundation-models / inference-profiles 请求失败时回退静态列表	该区域是否启用了 ON_DEMAND 文本模型
对话报模型错误	`converse`请求 4xx/5xx 原样透传	模型 id 是否写全（含前缀与版本号，如`us.amazon.nova-lite-v1:0`），区域是否匹配

另外需要说明：AIRI 同时提供了 Bedrock 的视觉配置页（provider id 为vision-amazon-bedrock，见 vision 配置页），其凭据与区域填写方式与聊天页一致；但上文讨论的 provider 实现面向tasks: ['chat']，本文聚焦聊天模型接入。