从 Changelog 到源码：AI SDK 中 @ai-sdk/amazon-bedrock 提供商的完整能力图谱与演进脉络

从 Changelog 到源码：AI SDK 中 @ai-sdk/amazon-bedrock 提供商的完整能力图谱与演进脉络

【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/ai

导读

@ai-sdk/amazon-bedrock是 AI SDK（The AI Toolkit for TypeScript）中对接 Amazon Bedrock 的官方提供商，它基于 Bedrock Converse API 封装了文本生成、嵌入、图像生成与文档重排四类模型能力，并内置 API Key（Bearer Token）与 AWS SigV4 双轨认证。本文以 packages/amazon-bedrock/CHANGELOG.md 的完整变更记录为骨架，结合 provider 工厂源码、认证实现 与 模型选项定义，梳理该包从 0.0.1 到 5.0.81 的功能演进、认证优先级、模型矩阵与 providerOptions 细节，帮助读者在接入 Bedrock 时做出正确的版本与配置决策。

一、包定位：作为 ProviderV4 的 Amazon Bedrock 接入层

从 包入口 可以看到，该包导出了createAmazonBedrock工厂函数、默认实例amazonBedrock（以及保留的旧别名bedrock），并对外暴露AmazonBedrockProviderSettings、AmazonBedrockLanguageModelChatOptions等类型。其核心实现位于 amazon-bedrock-provider.ts，实现了ProviderV4规范，具体包括：

• languageModel(modelId)/ 直接以函数调用bedrock(modelId)：创建聊天语言模型；
• embedding/embeddingModel/ 已废弃的textEmbedding/textEmbeddingModel：创建文本嵌入模型；
• image/imageModel：创建图像生成模型（如 Amazon Nova Canvas）；
• reranking/rerankingModel：创建文档重排模型；
• tools：透出@ai-sdk/anthropic的 Anthropic 专属工具。

从 Changelog 可以看到 API 命名的演进轨迹：textEmbeddingModel在 AI SDK 6（4.0.0-beta.88，commit8d9e8ad）中因移除EmbeddingModelV3泛型而被统一为embeddingModel，旧名称保留为废弃别名；ImageModelV1也曾被重命名为ImageModelV2（9301f86）。这也解释了为什么 provider 源码 中同时存在多组新旧方法。

二、演进主线：从 v0.0.1 到 v5.0.81 的四次关键跃迁

CHANGELOG 完整记录了该包与 AI SDK 主版本同步的演进历史，其核心脉络如下：

1. 初创期（v0.0.x）：功能补全

• 0.0.1（02f6a088）：首次加入 Amazon Bedrock provider，此时仍依赖 AWS SDK；
• 随后快速补齐会话令牌（d67fa9c）、Guardrails（01fc6c0）、多个前置系统消息（c434799）、并行工具调用流式支持（8f080f4）、Titan 嵌入模型（59d1abf）、provider 自定义工具（3b1b69a）、文件内容块（bc0ffc5）等能力。

2. v2.0.0：摆脱 AWS SDK 重依赖

3ff4ef8是一个架构分水岭——移除对 AWS SDK Bedrock 客户端库的依赖。从此请求由 amazon-bedrock-sigv4-fetch.ts 中的createSigV4FetchFunction直接基于aws4fetch完成签名，包的体积与启动成本显著下降。该阶段同时引入了 cache points（d1475de）、Nova Canvas 图像生成（58c3411）、推理支持（cf7d818）、budgetTokens（a841484）与 AWS 凭证提供器（d65df9d）。

3. v3.x / AI SDK 5：认证重构与 providerOptions 化

3.0.0版本（AI SDK 5，d5f588f）集中发生了多项破坏性变更：

• 314edb2：新增API Key 认证（Bearer Token）并自动回退 SigV4，这是当前默认推荐路径；
• 97ea26f：全面转向providerOptions且使用 camelCase 命名；
• a89add7：为 Claude 模型补齐结构化输出；
• 3593385：正确解析文档与图片的 MIME 类型；
• 89eaf5e：Nova Canvas 图像生成支持style参数；
• c87b7e4/109fb4d/3aeb791：持续接入 Claude 4 系列新模型。

4. v5.x / AI SDK 7：ESM-only、Mantle 与工作流序列化

5.0.0是一次面向未来的大版本：

• ef992f8：移除全部 CommonJS 导出，所有包 ESM-only（package.json 中"type": "module"佐证），require()用户必须切换为 ESMimport；
• 7fc6bd6：最低 Node.js 版本提升到 22（官方支持 22/24/26）；
• cd27bca：新增Mantle 提供商子路径（@ai-sdk/amazon-bedrock/mantle，见 package.json exports）；
• c29a26f：支持 provider 引用与按提供商能力上传文件；
• 3887c70：在规范中加入顶层reasoning参数并支持generateText/streamText；
• 6d8716c：支持推理服务 tier（serviceTier）；
• b3976a2：所有 provider 模型类加入WORKFLOW_SERIALIZE/WORKFLOW_DESERIALIZE静态方法，可跨工作流步骤边界序列化。

三、安装与初始化

根据 包 README 与 package.json，安装与最小使用如下：

npm i @ai-sdk/amazon-bedrock

import { bedrock } from '@ai-sdk/amazon-bedrock'; import { generateText } from 'ai'; const { text } = await generateText({ model: bedrock('anthropic.claude-3-haiku-20240307-v1:0'), prompt: 'Write a vegetarian lasagna recipe for 4 people.', });

注意两点环境前提：该包engines.node >= 22；自5.0.0起为 ESM-only，不支持require()。

四、认证机制：API Key 优先，SigV4 兜底

这是该包最值得注意的工程特性之一。从 provider 工厂源码 与 认证实现 可以确认完整的认证优先级：

1. 直接配置的apiKey（withSettings()/createAmazonBedrock({ apiKey })）；
2. 环境变量AWS_BEARER_TOKEN_BEDROCK；
3. SigV4 签名回退（AWS 标准凭证链）。

API Key 认证（推荐）

export AWS_BEARER_TOKEN_BEDROCK=your-api-key-here

const { text } = await generateText({ model: bedrock('anthropic.claude-3-haiku-20240307-v1:0'), prompt: 'Write a vegetarian lasagna recipe for 4 people.', // API key 自动从 AWS_BEARER_TOKEN_BEDROCK 加载 });

也可直接传入配置：

const bedrockWithApiKey = bedrock.withSettings({ apiKey: process.env.AWS_BEARER_TOKEN_BEDROCK, region: 'us-east-1', // 可选 });

SigV4 认证（回退路径）

未提供 API Key 时自动走 SigV4，需要标准 AWS 环境变量：

• AWS_REGION（必填，region）
• AWS_ACCESS_KEY_ID
• AWS_SECRET_ACCESS_KEY
• AWS_SESSION_TOKEN（可选，临时凭证）

源码细节（createSigV4FetchFunction）显示：只有 POST 且带 body 的请求才走AwsV4Signer签名；同时每次调用使用globalThis.fetch而不缓存，避免第三方遥测库（如 OpenTelemetry、Datadog）在 provider 创建后 patchfetch被静默忽略——这正是5.0.0中d0dbd96修复的问题。此外5.0.0的6732c16修复了显式传入accessKeyId/secretAccessKey时仍误用AWS_SESSION_TOKEN环境变量的行为（源码第 243-249 行）。d65df9d（v2.1.4）还支持传入credentialProvider函数动态获取凭证。

五、模型矩阵：四类模型全覆盖

1. 聊天模型（Converse API）

模型 ID 联合类型 覆盖了 Anthropic Claude 全系（含claude-sonnet-5、claude-fable-5、Opus 4.x、Sonnet 4.6/4.5、Haiku 4.5、3.x 系列）、Amazon Titan/Nova、Meta Llama 3/3.1/3.2/3.3/4、Mistral、Cohere Command、DeepSeek R1、OpenAI gpt-oss 等，并支持us./eu.前缀的跨区域推理配置 ARN 形式。Changelog 中的相关能力包括：

• 推理配置：budgetTokens（a841484）、自适应思考与 reasoning effort（632ab10）、Nova 2 的maxReasoningEffort（f65d7df）、推理预算用于应用推理配置 ARN（051a41d）；
• ARRN 处理：应用推理配置 ARN 支持（76db5e3）、ARN 模型 ID 中斜杠编码（ce56626）、跨区域推理配置下的 Cohere 嵌入模型识别（9eda693）；
• 停止序列：通过additionalModelResponseFieldPaths请求/stop_sequence并暴露providerMetadata.bedrock.stopSequence（9ab6ebe）；
• 推理元数据：performanceConfig、serviceTier、cacheDetails（08f54fc）。

2. 嵌入模型

支持 Titan、Cohere、Amazon Nova 等嵌入模型：

• Nova 需要发送taskType与singleEmbeddingParams（151c4aa）；
• Cohere 需要发送input_type并解析 Cohere 风格响应（6ece44c），支持outputDimension（256/512/1024/1536，0df64d6），并提升了单请求嵌入条数上限（1daf48b）；
• Cohere 嵌入 token 用量从响应头提取（9fa4e9d）；
• 5.0.67（5d2229e）新增modelFamily 设置以支持 ARN 形式的嵌入模型。

3. 图像模型

支持 Amazon Nova Canvas 图像生成（58c3411）与编辑（9061dc0），并支持style参数（89eaf5e）；5.0.15（5cd0e38）为 Bedrock 图像模型请求新增了独立的providerOptionsschema 与类型。

4. 重排模型

d1bdadb引入重排模型，随后补充简写命名（9524761）；85a80fc修复了重排请求键应为bedrockRerankingConfiguration的问题。重排模型走的是bedrock-agent-runtime服务端点（见 provider 源码）。

六、providerOptions：模型级微调的核心入口

Changelog 记录了多次 providerOptions 相关的规范化（97ea26f转为 providerOptions、6f231db统一为 optional 而非 nullish 混用、242696c/99fbed8规范化并导出类型名）。当前 聊天模型选项 schema 提供以下关键项：

此外，文件 part 支持citations.enabled（文档引用生成），文本 part 支持guardContent与guardContentQualifiers（grounding_source/query/guard_content），图像 part 支持guardContent——对应 Changelog 中df45e67的 GuardrailConverseContentBlock 消息级防护能力。

七、工具调用与结构化输出：Agent 能力的底层保障

工具调用相关修复贯穿整个 CHANGELOG，反映出多模型混合下的兼容性工程：

• 并行工具调用：流式模式支持（8f080f4）；
• 工具调用 ID 规范化：Bedrock 生成的 ID 可能含非法字符，重放对话历史前需净化（8fcb72c）；Mistral 模型要求工具调用 ID 恰好 9 位字母数字（d5466df）；空字符串工具调用 ID 处理（e6087c9）；
• 工具参数健壮性：无效工具输入包装为对象（cf06314）、流式无参工具调用发送{}（ef9d7d6）、空工具描述优雅处理（2a2e17d）；
• strict 模式：工具级 strict mode（1bd7d32）、Claude Opus 4.7/4.8 在 Bedrock Messages API 拒绝strict字段时予以省略（bc8ed78、b555b23、ebd31b8的警告与回退路由）；
• 工具 + 结构化输出组合（88b2c7e）：移除阻止工具与 JSON 响应格式并用的错误警告，工具选择改为{ type: 'required' }，JSON 工具响应正确转文本并将 finish reason 从tool_use映射为stop，从而支持"工具调用 + 结构化最终输出"的多步 Agent 工作流；
• provider 工具透传：Anthropic provider 定义的工具（f418dd7）与标准函数工具可混用（aebbebd移除了误导性警告）；
• 禁用并行工具调用：透传 Anthropic 选项且不发送冲突的 tool choice 字段（9921a2f）；
• 工具搜索 beta：1921625为 Anthropic 增加 tool search beta。

结构化输出本身也有精细调整：d98d9ba将废弃的output_format迁移为output_config.format并启用 Bedrock Anthropic 原生结构化输出；5.0.71（bd74b49、6aa2401）为 Claude Sonnet 4.6 / Haiku 4.5 默认启用 JSON 工具回退并新增structuredOutputMode选项；b72fc7c会净化原生 Anthropic 结构化输出中不支持的 JSON Schema 约束。

八、推理、引用与多模态内容

推理（Reasoning）链路

• a10bf62修复使用推理时 "Extra inputs are not permitted" 错误；cc24427修复additionalModelRequestFields与推理并用的问题；
• 推理文本与签名：b0c59e8在存在签名时保留推理文本；bcbaae6跳过无签名的推理内容；aabc617支持 Converse 的reasoningContent.redactedContent并在后续轮次重放；030b4e1/a4ecd1c在过滤掉无签名推理后省略空的 assistant 消息；9c78e5d保留消息内容块上的 cache points；24ac76f在存在推理内容时保留空文本块。

引用（Citations）

c5e2a7c引入引用支持；1ee6b1f从引用内容响应中返回文本；b2eb608在 Bedrock 流式响应中接受引用增量。

多模态

• 52e22a7：Converse 消息支持视频输入；
• 1f92bdb：s3://图片 URL 直接作为 S3 image source 透传而非下载；
• 9d5a299：工具结果支持文档文件；5463d0d/ff5eba1统一image-*与file-*输出类型；9bd6512将文件 part 数据属性打上类型标签并移除 image part 类型；
• 08336f1与770c214：净化文件名（去除扩展名 / 非法字符）以保证 prompt cache 生效与请求合法。

九、流式传输与事件流可靠性

Converse 流式（ConverseStream）在该包中占据大量维护工作：

• afe9730修复/delta/stop_sequence流式事件；
• 1ac9af8：拒绝以不完整缓冲帧结束的事件流，而非静默返回部分输出；
• e0776b9：表面化事件流帧解码与处理失败，而非静默完成；
• 8ca1352：表面化带模型的 event-stream 异常；
• 35841f5：将各提供商的中流错误事件规范化为公共StreamProviderError，并保留 type/code/status/retry/raw payload 元数据；
• 68c5081：工具使用 schema 中input标记为可选，以兼容 Zod >= 4.4.0 下的contentBlockStart事件解析；
• 测试方面，仓库提供了完整的 事件流解码测试、流式响应处理器测试 以及 聊天模型事件流测试，并有大量 流式 chunk 夹具 佐证。

十、用量统计与响应元数据

• 9ab6ebe：通过additionalModelResponseFields.stop_sequence暴露停止序列；
• fd49828：在原始 usage 元数据中保留完整的 Bedrock Converse usage 对象；
• 61d25a9：从 API 响应头提取响应元数据；
• 3bd2689：扩展 token 用量；
• e89fc99：修正输入 token 计算逻辑；
• 5fc7da5：在 provider-utils 中集中创建空的语言模型用量；
• dee4c16：对 CRIS 前缀的 OpenAI GPT-5.x 发送嵌套 reasoning effort，同时保留 gpt-oss 的扁平格式；
• 43fc411：从生成与流式调用中返回 Bedrock Converse 请求体。

十一、升级与运维注意事项

综合 CHANGELOG 各 Major 版本，迁移时需要特别关注：

1. AI SDK 7 / v5.0.0：ESM-only（ef992f8），require()需改为import；Node 最低 22（7fc6bd6）；部分导出符号改名但保留废弃别名（04e9009）；
2. AI SDK 6 / v4.0.0：textEmbeddingModel改名为embeddingModel（8d9e8ad）；
3. AI SDK 5 / v3.0.0：providerOptions 化（97ea26f）；新增 API Key 认证（314edb2）；删除模型简写废弃警告（eb173f1）；
4. v2.0.0：移除 AWS SDK 依赖（3ff4ef8），自定义凭证需改用credentialProvider；
5. 版本号与依赖对应关系可参考 package.json：依赖@ai-sdk/provider、@ai-sdk/provider-utils、@ai-sdk/anthropic、@ai-sdk/openai工作区包，以及aws4fetch、@smithy/eventstream-codec、@smithy/util-utf8。

结语

透过@ai-sdk/amazon-bedrock的 CHANGELOG，可以清晰看到一条从"AWS SDK 薄封装"到"自带 SigV4 签名 + API Key 双轨认证 + 四类模型 + 深度兼容各厂商模型方言"的演进曲线。每一次 Patch 背后都是对 Converse API 边缘语义（事件流帧、工具调用 ID、推理签名、缓存点）的精细化处理。对于开发者而言，理解这份变更日志的语义，等价于掌握了 Bedrock 上跨 Claude、Nova、Llama、Cohere、Mistral 等模型的最佳实践边界——尤其是 providerOptions schema 与 认证源码 中体现的优先级与回退逻辑，值得作为接入 Bedrock 时的第一手参考。

【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/ai