在 AWS 上运行 ClaudeAI SDK 的 Claude Platform on AWS Providerai-sdk/anthropic-aws完整指南【免费下载链接】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 SDKThe AI Toolkit for TypeScript中的ai-sdk/anthropic-aws提供方展开讲解如何通过它直接访问托管在 AWS 环境内的 Anthropic Messages API端点aws-external-anthropic.{region}.api.aws并介绍 AWS SigV4 与 API Key 两种认证方式、Provider 全部配置项、IAM 权限要求以及底层的请求签名实现原理。读完本文你将掌握在 TypeScript / Next.js 应用中接入 Claude Platform on AWS 的完整实战方案并能独立排查最常见的配置错误。什么是 Claude Platform on AWS Providerai-sdk/anthropic-aws是 AI SDK 官方提供方之一让你能够在自己的 AWS 账户环境中调用 Anthropic Messages API。与直连 Claude 官方 API 不同Claude Platform on AWS 由 Anthropic 运营底层模型栈但流量入口、身份认证和计费都落在 AWS 侧——请求被发送到aws-external-anthropic.{region}.api.aws并使用AWS SigV4 签名或AWS 预置的 API Key进行认证见 anthropic-aws-provider.ts 中的createAnthropicAws实现。该提供方与一方的ai-sdk/anthropic保持完全一致的线协议wire format与功能集模型 ID、流式输出streaming、提示词缓存prompt caching、工具调用tool use、计算机使用computer use、Agent Skills 以及anthropic-beta头全部与 Claude 官方 API 一一对应。从源码结构看这一点是通过直接复用ai-sdk/anthropic/internal中的AnthropicLanguageModel、AnthropicFiles、AnthropicSkills和anthropicTools实现的ai-sdk/anthropic-aws只负责“换一个入口和认证方式”见 anthropic-aws-provider.ts。与 Amazon Bedrock 的关键区别文档明确区分了 Claude Platform on AWS 与 Amazon Bedrock对应ai-sdk/amazon-bedrock提供方API 形态不同Claude Platform on AWS 直接使用 Anthropic 的 Messages API而不是 Bedrock 的Converse/InvokeModel接口新功能上线节奏不同由于底层就是 Anthropic 运行时新特性在 Claude 官方 API 上线当天即可用无需等待 AWS 侧集成延迟。安装与前置条件安装提供方包npm install ai-sdk/anthropic-aws从 package.json 可以看到该包依赖ai-sdk/anthropic复用其模型实现、ai-sdk/provider、ai-sdk/provider-utils以及aws4fetch用于 SigV4 签名并声明 Node.js22的运行时要求。在调用任何模型之前你的 AWS 账户必须满足以下两个前置条件订阅 Claude Platform on AWS通过 AWS Marketplace 完成订阅开启出站 Web 身份联邦outbound web identity federation这是一次性设置aws iam enable-outbound-web-identity-federation如果缺少这一步每一次请求都会返回Outbound web identity federation is disabled for your account——这是最常见的配置错误。另外你还需要workspace ID。订阅后 AWS 会在所选区域为你的账户预置一个初始工作区可在 Claude Console 的Workspaces页面找到通过 AWS Console 的 Claude Platform on AWS 服务页进入。两种认证方式方式一AWS SigV4生产环境推荐SigV4 与你的现有 AWS IAM 策略、角色和审计体系天然集成支持 AWS 默认凭证链中的任意凭证来源环境变量、共享凭证文件、Web 身份IRSA、ECS 容器凭证、EC2 实例元数据等。典型环境变量配置AWS_REGIONus-west-2 ANTHROPIC_AWS_WORKSPACE_IDwrkspc_… AWS_ACCESS_KEY_ID… AWS_SECRET_ACCESS_KEY… # AWS_SESSION_TOKEN… # 仅临时凭证需要SSO、STS、assume role然后使用默认 Provider 实例import { anthropicAws } from ai-sdk/anthropic-aws;或显式实例化import { createAnthropicAws } from ai-sdk/anthropic-aws; // SigV4 —— 自动读取 AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / AWS_SESSION_TOKEN const anthropicAws createAnthropicAws({ region: us-west-2, workspaceId: wrkspc_…, });如果需要在请求时动态获取凭证例如临时 assume role可以传入credentialProviderconst anthropicAws createAnthropicAws({ region: us-west-2, workspaceId: wrkspc_…, credentialProvider: async () fetchCredentialsFromSTS(), });从源码看credentialProvider返回的凭证会完全替代accessKeyId/secretAccessKey/sessionToken三个静态配置见 anthropic-aws-provider.ts如果它抛出异常SDK 会包装成带指引信息的错误AWS credential provider failed: … Please ensure your credential provider returns valid AWS credentials with accessKeyId and secretAccessKey properties.方式二API Key本地开发 / 脚本 / 从 Claude 官方 API 迁移对于更简单的集成路径可以使用 AWS 预置的 API Key由你的 Anthropic 账户代表签发ANTHROPIC_AWS_API_KEYsk-…import { createAnthropicAws } from ai-sdk/anthropic-aws; const anthropicAws createAnthropicAws({ region: us-west-2, workspaceId: wrkspc_…, apiKey: sk-…, });优先级规则只要设置了apiKey就优先走 API Key 认证环境中的任何 SigV4 凭证都会被忽略。这一点在源码中有明确体现——createAnthropicAws会先读取apiKey命中则用createApiKeyFetchFunction否则才构建createSigV4FetchFunction见 anthropic-aws-provider.ts并在 anthropic-aws-provider.test.ts 中有专门测试用例验证两者同时存在时 API Key 优先、不产生authorization与x-amz-date头。Provider 配置项全表以下配置项来自AnthropicAwsProviderSettings接口见 anthropic-aws-provider.ts配置项说明环境变量回退备注regionClaude Platform on AWS 端点所在 AWS 区域AWS_REGION必填无兜底默认值workspaceId当前 AWS 账户的 Anthropic 工作区 ID每个请求经anthropic-workspace-id头发送ANTHROPIC_AWS_WORKSPACE_ID必填apiKeyAPI Key 认证x-api-key头设置后优先于 SigV4ANTHROPIC_AWS_API_KEY可选accessKeyIdSigV4 用的 AWS Access Key IDAWS_ACCESS_KEY_ID可选secretAccessKeySigV4 用的 AWS Secret Access KeyAWS_SECRET_ACCESS_KEY可选sessionTokenSigV4 会话令牌仅临时凭证AWS_SESSION_TOKEN可选baseURL自定义端点覆盖—默认https://aws-external-anthropic.{region}.api.aws/v1headers附加到每个请求的自定义请求头—与默认头合并fetch自定义 fetch 实现测试 / 中间件拦截—默认globalThis.fetchcredentialProvider返回动态 AWS 凭证的函数覆盖accessKeyId/secretAccessKey/sessionToken—支持异步此外还有内部的generateId选项用于自定义请求 ID 生成。几个值得注意的实现细节默认端点模板getBaseURL()在未传baseURL时用withoutTrailingSlash去掉尾部斜杠后拼出https://aws-external-anthropic.{region}.api.aws/v1而region同样支持从AWS_REGION读取见 anthropic-aws-provider.ts。测试用例验证了us-east-1会生成https://aws-external-anthropic.us-east-1.api.aws/v1/messages且baseURL优先级高于模板见 anthropic-aws-provider.test.ts每个请求必带的默认头anthropic-version: 2023-06-01与anthropic-workspace-id见 anthropic-aws-provider.tsworkspaceId缺失时请求会直接失败region 的解析时机region在模型创建时而非请求时解析缺失会立即抛错而workspaceId在请求时才解析见 anthropic-aws-provider.test.ts。使用语言模型Provider 实例本身是函数式接口直接传入模型 ID 即可创建语言模型import { anthropicAws } from ai-sdk/anthropic-aws; const model anthropicAws(claude-sonnet-4-6);模型 ID 与 Claude 官方 API 完全一致。从ai-sdk/anthropic导出的AnthropicModelId类型见 anthropic-language-model-options.ts可以看到当前支持的 ID 集合例如claude-sonnet-4-5、claude-sonnet-4-6、claude-opus-4-6、claude-opus-5、claude-haiku-4-5等且类型上保留了(string {})以兼容新发布的模型 ID。由于 Claude Platform on AWS 直接使用 Anthropic 运行时官方 API 上的提示词缓存、computer use、Web 搜索、代码执行、Agent Skills 等能力在这里行为完全一致。完整的生成示例与 README 及官方文档保持一致import { createAnthropicAws } from ai-sdk/anthropic-aws; import { generateText } from ai; const anthropicAws createAnthropicAws(); const { text } await generateText({ model: anthropicAws(claude-sonnet-4-6), prompt: Invent a new holiday and describe its traditions., });Provider 暴露的能力面从AnthropicAwsProvider接口见 anthropic-aws-provider.ts看Provider 实例还提供languageModel(modelId)/chat(modelId)/messages(modelId)创建文本生成模型provider标识为anthropic-aws.messagesfiles()返回AnthropicFiles文件上传支持图片与 PDF 的 URL 输入supportedUrls对image/*和application/pdf匹配任意http(s)URL见 anthropic-aws-provider.tsskills()返回AnthropicSkills用于向 Anthropic 上传 Agent Skillstools暴露anthropicTools内置工具集embeddingModel()/imageModel()当前会抛出NoSuchModelError即该提供方不支持 embedding 与图像生成模型见 anthropic-aws-provider.ts。底层原理SigV4 签名与 API Key 请求包装ai-sdk/anthropic-aws的差异化实现集中在 anthropic-aws-fetch.ts它以FetchFunction中间件的形式包装底层 fetchSigV4 路径createSigV4FetchFunction合并原始请求头与init.headers并追加 User-Agent 后缀ai-sdk/anthropic-aws/{VERSION}及运行时环境标识仅当请求为POST且携带 body时才进行签名——GET或无 body 的POST直接透传见 anthropic-aws-fetch.ts通过prepareBodyString将 body 统一转换为字符串支持string、Uint8Array、ArrayBuffer其余类型JSON.stringify使用aws4fetch的AwsV4Signer以service: aws-external-anthropic、当前region与凭证构造签名sessionToken存在时会自动附加x-amz-security-token头见 anthropic-aws-fetch.ts将签名结果头authorization、x-amz-date、x-amz-security-token等与原请求头合并后发出。API Key 路径createApiKeyFetchFunction更简单——仅在合并后的请求头上追加x-api-key头即可不会产生authorization。测试文件 anthropic-aws-fetch.test.ts 对上述行为覆盖非常完整非 POST 跳过签名、Request对象与init头合并、各类 body 类型处理、异步凭证提供者、签名头合并、x-api-key覆盖旧值、globalThis.fetch懒加载运行时替换 fetch 依然生效等均有对应用例。此外流式场景doStream也会穿过同一套 fetch 包装message_start/content_block_delta等 SSE 事件被正确解析为text-delta见 anthropic-aws-provider.test.ts。IAM 权限要求你的 IAM 主体需要获得调用 Claude Platform on AWS 工作区操作的权限。AWS 提供了三个托管策略AnthropicFullAccess授予aws-external-anthropic:*全部资源权限AnthropicInferenceAccess授予读操作以及CreateInference、CreateBatchInference、CancelBatchInference、DeleteBatchInference、CountTokens权限——这是调用模型的最低要求AnthropicReadOnlyAccess授予Get*、List*、CallWithBearerToken权限不足以执行推理。对于仅需文本生成的应用至少应附加AnthropicInferenceAccess策略。常见错误排查现象原因处理Outbound web identity federation is disabled for your account未执行一次性开启步骤运行aws iam enable-outbound-web-identity-federationAWS SigV4 authentication requires AWS credentials…源码会给出 4 条指引SigV4 路径下缺少凭证设置环境变量、显式传accessKeyId/secretAccessKey、提供credentialProvider或改用 API Key请求报 workspace 相关错误workspaceId无法解析设置ANTHROPIC_AWS_WORKSPACE_ID或显式传入workspaceId模型创建即抛 region 错误region缺失且无AWS_REGION显式传入region或设置AWS_REGION403 无权限IAM 策略不足检查是否附加了AnthropicInferenceAccess或AnthropicFullAccess关于排查与迁移更细的说明可继续参考仓库内的 官方文档页、Provider 实现 与 请求包装实现以及 Anthropic 一方提供方文档模型 ID、提示词缓存、computer use 等能力的完整说明。【免费下载链接】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），仅供参考