AI SDKai-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/aiai-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 Changese617cba: 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.44CHANGELOG 记录了完整的发布历史可归纳为三个里程碑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/anthropic4.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/provider4.0.2与ai-sdk/provider-utils5.0.5同步发布。实验性意味着 API 形态可能在后续版本调整使用时建议锁定版本并关注 CHANGELOG。2.3 v2.0.0版本线修正2.0.0的 Major Changesa23b676是 CHANGELOG 中最值得注意的一笔它解释了一个版本管理细节该包最初以1.0.0发布是因为其 major changeset 被应用到了包的起始版本0.0.10.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/provider4.0.13、ai-sdk/anthropic4.0.52、ai-sdk/provider-utils5.0.39。版本依赖速查截至 2.0.44来源 CHANGELOG.md 与 package.json项值当前版本2.0.44Node.js 要求22运行时依赖ai-sdk/anthropic、ai-sdk/provider、ai-sdk/provider-utils、aws4fetchpeerDependencieszod^3.25.76 \|\| ^4.1.8典型同步依赖版本ai-sdk/anthropic4.0.52、ai-sdk/provider4.0.13、ai-sdk/provider-utils5.0.39三、安装与前置条件npm install ai-sdk/anthropic-aws使用前需要完成三项 AWS 侧准备详见 07-anthropic-aws.mdxAWS 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 IdentityIRSA、ECS 容器凭据或 EC2 实例元数据。环境变量方式AWS_REGIONus-west-2 ANTHROPIC_AWS_WORKSPACE_IDwrkspc_… AWS_ACCESS_KEY_ID… AWS_SECRET_ACCESS_KEY… # AWS_SESSION_TOKEN… # 仅临时凭据SSO、STS、assumed role需要源码中的认证通道选择逻辑anthropic-aws-provider.tsconst 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的AwsV4Signerservice固定为aws-external-anthropicregion、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_KEYsk-…优先级规则一旦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_KEYanthropic-aws-provider.ts。五、Provider 设置参数全表以下参数定义于 anthropic-aws-provider.ts 的AnthropicAwsProviderSettings并与官方文档 07-anthropic-aws.mdx 保持一致设置项说明环境变量回退regionAWS 区域用于拼接aws-external-anthropic.{region}.api.aws端点。必填无兜底默认值AWS_REGIONworkspaceIdAnthropic 工作区 ID随每个请求通过anthropic-workspace-id请求头发送ANTHROPIC_AWS_WORKSPACE_IDapiKeyAPI Key 认证一旦提供即替代 SigV4ANTHROPIC_AWS_API_KEYaccessKeyIdSigV4 访问密钥 IDAWS_ACCESS_KEY_IDsecretAccessKeySigV4 秘密访问密钥AWS_SECRET_ACCESS_KEYsessionTokenSigV4 会话令牌仅临时凭据AWS_SESSION_TOKENbaseURL端点覆盖默认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-6import { 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的AnthropicLanguageModelprovider 标识为anthropic-aws.messagesfiles()FilesV4文件上传接口skills()SkillsV4Agent Skills 上传接口toolsAnthropic 工具集嵌入与图像模型显式抛出NoSuchModelError表示该 provider 不支持用new关键字调用模型函数会抛出明确错误。由于复用了 Anthropic 运行时第一方 provider 支持的 prompt caching、computer use、web search、code execution、Agent Skills 等能力在这里行为一致。七、IAM 权限调用模型的最低要求AWS 为 Claude Platform on AWS 提供了三个托管策略07-anthropic-aws.mdxAnthropicFullAccess授予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_REGIONbaseURL 优先级显式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.jsonpnpm 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_IDAWS_SECRET_ACCESS_KEY建议配合credentialProvider做动态凭据确认 IAM 主体绑定AnthropicInferenceAccess及以上权限需要流式转录时确认包版本 ≥ 1.0.7并留意其实验性 API 可能变化。相关仓库资源CHANGELOG.md | README.md | provider 实现 | fetch 认证封装 | 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辅助生成（AIGC），仅供参考