AI SDK `@ai-sdk/anthropic-aws` 深度解读：Claude Platform on AWS Provider 的版本演进、认证机制与源码实现-育师

AI SDK`@ai-sdk/anthropic-aws`深度解读：Claude Platform on AWS Provider 的版本演进、认证机制与源码实现

【免费下载链接】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/anthropic-aws是 AI SDK（本仓库即其开源实现）中用于接入Claude Platform on AWS的官方 provider 包：它把 Anthropic Messages API 托管到 AWS 环境中，用 AWS SigV4 或 AWS 分配的 API Key 完成认证，而 API 表面与第一方 Claude API 完全一致。本文以该包 CHANGELOG.md 为骨架，梳理其版本演进脉络与依赖结构，并结合 README.md、provider 实现、fetch 认证封装与测试用例逐层拆解认证机制、配置项与使用方式，读完即可在 AWS 环境中正确接入并排查常见问题。

一、包的定位：在 AWS 中运行的第一方 Claude API

从 CHANGELOG 首条 Major Changes（e617cba: feat(anthropic-aws): add Claude Platform on AWS provider）可以看出，该包的核心使命是新增Claude Platform on AWS provider。与第一方@ai-sdk/anthropic相比，它的差异不在 API 表面，而在接入环境：

同一套 wire format 与功能集：模型 ID、流式输出、prompt caching、tool use、computer use、Agent Skills、anthropic-beta请求头等，与第一方 Claude API 完全一致（见 README.md）。
AWS 原生认证与计费：请求发往https://aws-external-anthropic.{region}.api.aws/v1，通过 AWS Marketplace 计费。
与 Amazon Bedrock 的本质区别：Claude Platform on AWS 直接使用 Anthropic 的 Messages API（而非 Bedrock 的Converse/InvokeModel），因此新特性与第一方 Claude API 同日上线，不存在 AWS 集成延迟（见 07-anthropic-aws.mdx）。

从 package.json 的依赖声明可以印证它的"薄封装"定位：核心逻辑复用@ai-sdk/anthropic（工作区依赖workspace:*），认证与请求适配层使用aws4fetch（^1.0.20），底层接口契约依赖@ai-sdk/provider与@ai-sdk/provider-utils。这正是 CHANGELOG 中大量 Patch Changes 仅包含依赖更新的原因——包本身功能稳定，版本随上层 SDK 同步演进。

二、版本演进主线：从 1.0.0 到 2.0.44

CHANGELOG 记录了完整的发布历史，可归纳为三个里程碑：

2.1 v1.0.0-canary / beta：发布前通道

1.0.0-canary.0至1.0.0-canary.7、1.0.0-beta.8至1.0.0-beta.10展示了标准的 canary → beta 预发布流程，期间依赖跟随@ai-sdk/anthropic@4.0.0-canary.x / beta.x持续更新，最终在1.0.0通过b8396f0触发首个 beta 发布。

2.2 v1.0.0：正式发布

1.0.0的 Major Changes 即新增 Claude Platform on AWS provider，标志该包正式可用。其后的1.0.1~1.0.8均为 Patch Changes，除依赖升级外，1.0.7引入了一项实质功能：

5c5c0f5: Add experimental streaming transcription support for transcription models, including OpenAI gpt-realtime-whisper and xAI WebSocket STT.

该条目说明包在转录模型（含 OpenAIgpt-realtime-whisper与 xAI WebSocket STT）上增加了实验性流式转录支持，随@ai-sdk/provider@4.0.2与@ai-sdk/provider-utils@5.0.5同步发布。实验性意味着 API 形态可能在后续版本调整，使用时建议锁定版本并关注 CHANGELOG。

2.3 v2.0.0：版本线修正

2.0.0的 Major Changes（a23b676）是 CHANGELOG 中最值得注意的一笔，它解释了一个版本管理细节：

该包最初以1.0.0发布，是因为其 major changeset 被应用到了包的起始版本0.0.1（0.0.1→1.0.0），而不是预期的首次稳定版1.0.0；此次 major bump 将版本修正为2.0.0，以反映预期的 v2 线。

换句话说，这是对发布管线版本号计算的修正，而非破坏性 API 变更。2.0.0之后（2.0.1~2.0.44）全部为 Patch Changes，每个版本均同步更新@ai-sdk/anthropic、@ai-sdk/provider、@ai-sdk/provider-utils三者中若干依赖，例如最新2.0.44同时更新了@ai-sdk/provider@4.0.13、@ai-sdk/anthropic@4.0.52、@ai-sdk/provider-utils@5.0.39。

版本依赖速查（截至 2.0.44，来源 CHANGELOG.md 与 package.json）：

项	值
当前版本	`2.0.44`
Node.js 要求	`>=22`
运行时依赖	`@ai-sdk/anthropic`、`@ai-sdk/provider`、`@ai-sdk/provider-utils`、`aws4fetch`
peerDependencies	`zod@^3.25.76 \\|\\| ^4.1.8`
典型同步依赖版本	`@ai-sdk/anthropic@4.0.52`、`@ai-sdk/provider@4.0.13`、`@ai-sdk/provider-utils@5.0.39`

三、安装与前置条件

npm install @ai-sdk/anthropic-aws

使用前需要完成三项 AWS 侧准备（详见 07-anthropic-aws.mdx）：

AWS Marketplace 订阅：AWS 账户需订阅 Claude Platform on AWS。
启用出站 Web 身份联合（一次性步骤）：
```
aws iam enable-outbound-web-identity-federation
```
若未启用，每个请求都会返回Outbound web identity federation is disabled for your account，这是最常见的配置错误。
获取 workspace ID：订阅后 AWS 会在所选区域预置一个初始工作区，在 AWS 控制台的 Claude Platform on AWS 服务页进入 Claude Console 的Workspaces可找到 ID。

四、认证机制：SigV4 与 API Key 双通道

Provider 支持两种认证方式，二选一即可（见 anthropic-aws-provider.ts 的createAnthropicAws实现）：只要设置了apiKey（或环境变量ANTHROPIC_AWS_API_KEY），就走 API Key 通道；否则走 SigV4 通道。

4.1 方式一：AWS SigV4（生产环境推荐）

SigV4 与既有 AWS IAM 策略、角色与审计体系集成。凭据可通过 AWS 默认凭据链的任意方式提供——环境变量、共享凭据文件、Web Identity（IRSA）、ECS 容器凭据或 EC2 实例元数据。环境变量方式：

AWS_REGION=us-west-2 ANTHROPIC_AWS_WORKSPACE_ID=wrkspc_… AWS_ACCESS_KEY_ID=… AWS_SECRET_ACCESS_KEY=… # AWS_SESSION_TOKEN=… # 仅临时凭据（SSO、STS、assumed role）需要

源码中的认证通道选择逻辑（anthropic-aws-provider.ts）：

const fetchFunction = apiKey ? createApiKeyFetchFunction(apiKey, options.fetch) : createSigV4FetchFunction(async () => { const region = loadSetting({ settingValue: options.region, settingName: 'region', environmentVariableName: 'AWS_REGION', description: 'AWS region', }); // …读取 accessKeyId / secretAccessKey / sessionToken }, options.fetch);

SigV4 签名封装位于 anthropic-aws-fetch.ts：

使用aws4fetch的AwsV4Signer，service固定为aws-external-anthropic，region、accessKeyId、secretAccessKey、sessionToken取自凭据解析结果；
签名前会把请求体统一字符串化（prepareBodyString处理 string /Uint8Array/ArrayBuffer/ 对象），并对 POST 请求签名；
每次请求自动追加ai-sdk/anthropic-aws/${VERSION}User-Agent 后缀，便于服务端审计。

4.2 方式二：API Key（简化接入）

适合本地开发、脚本或从第一方 Claude API 迁移的场景。API Key 由你的 Anthropic 客户代表为 Claude Platform on AWS 预置：

ANTHROPIC_AWS_API_KEY=sk-…

优先级规则：一旦apiKey生效，它会覆盖环境中任何 SigV4 凭据（测试用例prefers the API-key path when both apiKey and AWS SigV4 creds are present明确验证了这一点）。API Key 通道的封装在 anthropic-aws-fetch.ts：仅向请求头追加x-api-key，不做签名。

4.3 动态凭据：credentialProvider

需要请求时动态取凭据（如临时 AssumeRole）时，可传入credentialProvider异步函数。源码中它的返回值会覆盖accessKeyId、secretAccessKey、sessionToken三个静态设置；若该函数 reject，会包装为带引导提示的错误（"Please ensure your credential provider returns valid AWS credentials…"）。同时，若 SigV4 凭据缺失，源码会抛出分层的引导错误，分别提示"需要 AWS 凭据（四种解决途径）"与"需要同时提供 ACCESS_KEY_ID 与 SECRET_ACCESS_KEY"（anthropic-aws-provider.ts）。

五、Provider 设置参数全表

以下参数定义于 anthropic-aws-provider.ts 的AnthropicAwsProviderSettings，并与官方文档 07-anthropic-aws.mdx 保持一致：

设置项	说明	环境变量回退
`region`	AWS 区域，用于拼接`aws-external-anthropic.{region}.api.aws`端点。必填，无兜底默认值	`AWS_REGION`
`workspaceId`	Anthropic 工作区 ID，随每个请求通过`anthropic-workspace-id`请求头发送	`ANTHROPIC_AWS_WORKSPACE_ID`
`apiKey`	API Key 认证；一旦提供即替代 SigV4	`ANTHROPIC_AWS_API_KEY`
`accessKeyId`	SigV4 访问密钥 ID	`AWS_ACCESS_KEY_ID`
`secretAccessKey`	SigV4 秘密访问密钥	`AWS_SECRET_ACCESS_KEY`
`sessionToken`	SigV4 会话令牌（仅临时凭据）	`AWS_SESSION_TOKEN`
`baseURL`	端点覆盖；默认`https://aws-external-anthropic.{region}.api.aws/v1`（源码通过`withoutTrailingSlash`去除末尾斜杠）	—
`headers`	附加到每个请求的自定义请求头	—
`fetch`	自定义 fetch 实现，可用于测试或中间件拦截	—
`credentialProvider`	返回动态 AWS 凭据的异步函数，覆盖静态三项凭据	—
`generateId`	自定义 ID 生成函数	—

getBaseURL与getHeaders的实现细节（anthropic-aws-provider.ts）值得注意：

const getBaseURL = (): string => withoutTrailingSlash(options.baseURL) ?? `https://aws-external-anthropic.${loadSetting({ …region… })}.api.aws/v1`; const getHeaders = () => ({ 'anthropic-version': '2023-06-01', 'anthropic-workspace-id': loadSetting({ …workspaceId… }), ...options.headers, });

即：每个请求都会携带anthropic-version: 2023-06-01与anthropic-workspace-id两个固定头，且workspaceId缺失时会直接抛错（loadSetting而非loadOptionalSetting）。

六、模型使用与完整示例

Provider 实例可直接以模型 ID 调用（模型 ID 与第一方 Anthropic API 完全一致，如claude-sonnet-4-6）：

import { createAnthropicAws } from '@ai-sdk/anthropic-aws'; import { generateText } from 'ai'; const anthropicAws = createAnthropicAws({ region: 'us-west-2', workspaceId: 'wrkspc_…', }); const { text } = await generateText({ model: anthropicAws('claude-sonnet-4-6'), prompt: 'Invent a new holiday and describe its traditions.', });

也支持直接使用默认实例（凭据全部来自环境变量）：

import { anthropicAws } from '@ai-sdk/anthropic-aws';

Provider 接口（index.ts 与 anthropic-aws-provider.ts）除语言模型外还提供：

languageModel(modelId)/ 直接调用：创建对话模型（底层复用@ai-sdk/anthropic的AnthropicLanguageModel，provider 标识为anthropic-aws.messages）；
files()：FilesV4文件上传接口；
skills()：SkillsV4Agent Skills 上传接口；
tools：Anthropic 工具集；
嵌入与图像模型：显式抛出NoSuchModelError，表示该 provider 不支持；
用new关键字调用模型函数会抛出明确错误。

由于复用了 Anthropic 运行时，第一方 provider 支持的 prompt caching、computer use、web search、code execution、Agent Skills 等能力在这里行为一致。

七、IAM 权限：调用模型的最低要求

AWS 为 Claude Platform on AWS 提供了三个托管策略（07-anthropic-aws.mdx）：

AnthropicFullAccess：授予aws-external-anthropic:*全部资源权限；
AnthropicInferenceAccess：授予读取类操作以及CreateInference、CreateBatchInference、CancelBatchInference、DeleteBatchInference、CountTokens——调用模型所需的最低权限；
AnthropicReadOnlyAccess：仅授予Get*、List*、CallWithBearerToken，不足以执行推理。

生产环境建议为应用 IAM 主体绑定AnthropicInferenceAccess，避免使用全量权限。

八、测试验证：行为有据可查

包内测试 anthropic-aws-provider.test.ts 与 anthropic-aws-fetch.test.ts 对本篇涉及的关键行为给出了可复现的断言：

默认端点拼接：region: 'us-east-1'时请求 URL 为https://aws-external-anthropic.us-east-1.api.aws/v1/messages；省略 region 时读取AWS_REGION；
baseURL 优先级：显式baseURL优先于默认模板；
API Key 通道：设置apiKey后请求头携带x-api-key，且ANTHROPIC_AWS_API_KEY环境变量同样生效；
SigV4 通道：未提供 apiKey 时x-api-key不存在，请求经AwsV4Signer签名（测试中以 mock signer 断言x-amz-date与authorization头）；缺失凭据时抛出引导错误；credentialProvider被调用并采用其返回值；
双通道共存：apiKey 与 SigV4 凭据同时存在时优先 apiKey；
流式输出：doStream经 fetch 封装转发并产出流式事件（对应 CHANGELOG 中的流式能力）。

运行测试的方式（package.json）：

pnpm test:node # Node 环境 vitest pnpm test:edge # Edge 环境 vitest

九、小结与排查清单

@ai-sdk/anthropic-aws的 CHANGELOG 揭示了一条清晰的演进路径：v1 线完成 Claude Platform on AWS provider 落地并加入实验性流式转录，v2 线修正版本号后进入以依赖同步为主的稳定迭代。使用该包时建议按以下顺序排查：

确认已完成aws iam enable-outbound-web-identity-federation（否则报Outbound web identity federation is disabled）；
确认设置了region/AWS_REGION与workspaceId/ANTHROPIC_AWS_WORKSPACE_ID（两者缺失都会在请求构建阶段抛错）；
二选一配置凭据：ANTHROPIC_AWS_API_KEY（或apiKey）或AWS_ACCESS_KEY_ID+AWS_SECRET_ACCESS_KEY（建议配合credentialProvider做动态凭据）；
确认 IAM 主体绑定AnthropicInferenceAccess及以上权限；
需要流式转录时确认包版本 ≥ 1.0.7，并留意其实验性 API 可能变化。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

AI SDK `@ai-sdk/anthropic-aws` 深度解读：Claude Platform on AWS Provider 的版本演进、认证机制与源码实现