AIRI 接入 Amazon Bedrock：API Key 配置、Region 校验与 Converse 适配原理

AIRI 接入 Amazon BedrockAPI Key 配置、Region 校验与 Converse 适配原理【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airiAmazon Bedrock 是 AWS 托管的模型访问服务AIRI自托管 AI 伴侣项目将其作为Consciousness意识模块的 Chat 模型供应商之一。本文围绕 amazon-bedrock.md 这份配置指南完整讲解在 AIRI 中接入 Bedrock 的前置准备、表单填写、自动校验与故障排查全流程并结合仓库源码深入剖析其底层实现Bedrock Converse API 的适配方式、Region 格式校验、模型清单拉取逻辑与兜底策略。读完你既能独立完成配置也能理解该供应商在 AIRI 内的调用链路与边界。为什么选择 Amazon Bedrock如果你的团队或项目已经在 AWS 上管理模型访问、Region 和账单那么 Bedrock 可以直接复用这套账户管理方式无需在 AIRI 之外另建一套密钥体系。AIRI 将 Bedrock 归类为付费云供应商paidCloud该分类定义在 attributes.ts 中意味着它需要真实的云端凭据才能工作。从源码注册信息看该供应商的标识为amazon-bedrock负责chat任务在全部供应商中排序为 18见 index.ts。同时它也是 AIRI 首次启动 Onboarding 引导中推荐的热门供应商之一见 onboarding.vue。前置准备启用模型并创建 Bedrock API Key在进入 AIRI 设置之前需要先在 AWS 侧完成两件事打开 Amazon Bedrock 控制台在所选Region下启用你需要使用的目标模型Model access。在同一个 AWS 账户、同一个 Region下创建 Bedrock API Key供 AIRI 调用。::: warning 凭据安全 Bedrock API Key 一旦泄露等同于把模型调用权限交给他人。请只把 Key 保存在 AIRI 的供应商设置中不再使用时及时吊销。 :::从 AIRI 的 i18n 文案en/settings.yaml可以看到表单对 Key 的提示为 Amazon Bedrock API key (generate in AWS Console → Bedrock → API Keys)占位符为bedrock-...即 Bedrock 专属生成的 Key 形式。在 AIRI 中配置 Amazon Bedrock配置入口为Settings → Providers → Chat → Amazon Bedrock需要填写两个字段字段说明默认值Amazon Bedrock API Key在 AWS 控制台生成的 Bedrock API Key必填无AWS RegionBedrock 已启用且拥有模型访问权限的 Regionus-east-1需要注意两点约束Region 默认值为us-east-1。AIRI 表单中没有自定义 Endpoint 字段所有请求都基于该 Region 自动拼接出 Bedrock 的 API 地址。Region 并非任意字符串。底层配置 Schema 通过正则/^[a-z]{2,3}-[a-z]-\d$/校验格式见 index.ts例如us-east-1、ap-southeast-1是合法格式错误格式会在前端校验阶段被拦截。对应的设置页面由 chat/amazon-bedrock.vue 实现API Key 使用密码型输入框ProviderApiKeyInputRegion 使用账户 ID 型输入框ProviderAccountIdInput并绑定到全局的供应商配置存储useProviderConfigStore。此外仓库还提供了一份视觉模块版本 vision/amazon-bedrock.vue其供应商 ID 为vision-amazon-bedrock字段与校验逻辑完全一致。配置验证与模型选择填写完 Key 和 Region 后AIRI 会自动触发校验无需手动提交自动校验只要apiKey非空供应商就进入需要校验状态validationRequiredWhen返回true见 index.test.ts。校验器会向https://bedrock.{region}.amazonaws.com/foundation-models发送一次 GET 请求若返回403或401则判定为 Invalid Amazon Bedrock API key or insufficient permissions网络失败则提示检查 Region 与网络见 index.ts。模型选择校验通过后进入Settings → Modules → Consciousness将供应商切换为 Amazon Bedrock 并选择一个已授权模型然后发送一条消息即可验证端到端可用性。切换供应商时会自动清空之前选中的模型 ID避免跨供应商引用失效见 stores/modules/consciousness.ts。若校验失败但坚持继续设置页也提供Continue Anyway仍然继续按钮forceValid把是否可用的判断交给后续实际请求。源码透视AIRI 如何调用 Bedrock Converse API了解配置后再来看 AIRI 底层是怎么把标准 Chat 请求转成 Bedrock 调用的。核心实现在 packages/stage-ui/src/libs/providers/providers/amazon-bedrock/index.ts。请求地址与认证配置中的baseURL为https://bedrock-runtime.{region}.amazonaws.com/v1/但源码注释明确它是占位符实际请求全部通过自定义 fetch 拦截器发出。真正的调用地址是https://bedrock-runtime.{region}.amazonaws.com/model/{modelId}/converse请求头携带authorization: Bearer {apiKey}与content-type: application/json见 index.ts。这正是文档中Bedrock API Key Region两项配置在底层的落点。消息格式转换Bedrock 的 Converse API 要求 user/assistant 消息交替出现且 system 消息独立成字段。因此 AIRI 做了三层转换拆分 system 消息把对话中 role 为system的消息提取为system字段数组形式。内容块化toConverseContent把 xsai 的字符串或内容块统一转为{ text }块。合并连续同角色消息mergeConsecutiveRoles将相邻的相同 role 消息合并以满足 Converse 的交替约束见 index.ts。请求体还包含inferenceConfigmaxTokens默认4096temperature仅在显式传入时写入见 index.ts。流式响应的模拟一个值得注意的实现细节是由于 Bearer Token 认证不支持 Bedrock 的二进制事件流协议/converse-streamAIRI 只能调用非流式/converse。为让上层 xsai 管线仍然按标准 SSE 流处理源码在拿到完整 JSON 响应后将其重新包装成data: {...}形式的 SSE 分块角色块 → 内容块 → finish_reason 块 →data: [DONE]见 index.ts。因此实际体验是整段生成完毕后一次性呈现而非逐 token 流式输出这是接入 Bedrock 时的预期行为。模型清单拉取与兜底listModels通过两路并行获取模型清单见 index.ts对Amazon、Anthropic、Moonshot、Minimax、DeepSeek五家供应商并行查询foundation-models限定ON_DEMAND推理类型与TEXT输出模态并按global.us. 原始 modelId 的优先级挑选跨区域推理 Profile ID拉取SYSTEM_DEFINED类型的 inference profiles把不在基础模型列表中的新模型如较新的 Claude、Nova 系列也纳入可选清单。当 API 不可用时会退回一份静态模型列表index.ts包含 Amazon Nova Pro / Lite / Micro 与 Claude Sonnet 3.5 v2、Claude Sonnet 3.7。这一点已被单元测试覆盖当fetch返回 401 时listModels仍能返回非空且包含 Nova 模型的结果见 index.test.ts。故障排查文档给出了最常见的三类失败原因结合源码可以更精确地定位现象可能原因排查建议校验提示 Invalid key 或权限不足API Key 无效或账户对该 Region 无访问权限校验器对403/401直接报错确认 Key、Region、模型访问归属同一个 AWS 账户校验提示无法连接Region 填写错误或网络不通确认 Region 格式符合us-east-1这类格式且该 Region 已开通 Bedrock模型列表中找不到目标模型该模型未在当前 Region 授权在 Bedrock 控制台确认模型访问已启用若列表为空可检查是否触发了静态兜底清单核心原则始终是API Key、所选 AWS Region、模型访问权限三者必须属于同一个账户。另外由于 AIRI 的 Bedrock 表单没有自定义 Endpoint 字段所有请求都硬编码指向bedrock-runtime.{region}.amazonaws.com因此任何自定义网关、代理或非标准部署都无法通过该供应商接入需要走其他兼容供应商方案。小结在 AIRI 中启用 Amazon Bedrock 只需三步AWS 控制台启用模型并创建同 Region 的 API Key → 在Settings → Providers → Chat → Amazon Bedrock填入 Key 与 Region默认us-east-1→ 在Settings → Modules → Consciousness选择模型并发送消息验证。底层实现上AIRI 通过自定义 fetch 拦截器把标准 Chat 请求转换为 Bedrock Converse 调用处理了消息角色合并、SSE 流模拟、跨区域推理 Profile 与模型清单兜底等细节这让 Bedrock 供应商在体验一致性上与其他云端供应商保持对齐同时其非流式 整段返回与无自定义 Endpoint两点边界需要在使用时知晓。【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考