AWS上集成Claude从0到1：Bedrock、Lambda与生产实践

很多开发者在把 Claude 集成到 AWS 时，遇到的第一个障碍往往不是模型能力，而是 AWS 这套体系的复杂度：账号权限怎么开、Bedrock 模型访问在哪里申请、IAM 策略怎么写、调用代码和本地调用有什么区别、部署成 API 又要走哪几步。网上资料虽然多，但要么只讲概念，要么只贴一段代码，很少有人把“从开发到生产落地”的完整链路串起来。本文就从 0 到 1 梳理一遍 AWS + Claude 的落地路径，覆盖账号准备、Bedrock 开通、最小调用、重试与日志、Lambda 发布 API、Claude Code 配合使用，以及生产环境最关心的成本与安全注意事项。新手可以按章节顺序阅读，有经验的开发者可以直接跳到第 4、6、7 节对照排查。

1. 为什么要在 AWS 上使用 Claude

1.1 Claude 能解决什么问题

Claude 是 Anthropic 推出的大语言模型系列，核心能力包括文本生成、代码理解、文档摘要、对话推理、复杂任务拆解等。和很多通用大模型相比，Claude 在长文本理解、代码生成、多轮对话稳定性上有自己的优势，因此常被用在智能客服、代码辅助、内容总结、知识库问答、数据分析等场景。

在 AWS 上使用 Claude，本质上是把“模型能力”和“云基础设施”组合在一起。你既可以把它当做一个带鉴权的 API 来调用，也可以把它嵌入到现有的微服务、数据管道、无服务器架构里，由 AWS 承担部署、弹性伸缩、监控和权限治理。对于已经深度使用 AWS 的团队，这样做比单独维护一套模型调用服务更顺手，也更容易通过 CloudTrail、IAM、VPC 等能力满足企业级的安全与合规要求。

1.2 AWS 上接入 Claude 的主要方案对比

目前把 Claude 接入业务，大致有四种常见路径：Anthropic 官方 API、Amazon Bedrock、SageMaker 自托管，以及面向编程场景的 Claude Code。它们解决的是不同层次的问题，选择依据主要看你的账号体系、合规要求和运维成本。

如果你的业务已经运行在 AWS 上，需要 IAM 资源细粒度管控和审计日志，而且不想再单独维护一套 API Key 的生命周期，Bedrock 通常是更合理的选择。SageMaker 自托管虽然灵活，但需要自己管理模型推理服务器，日常的扩容、补丁、监控成本明显更高，一般只有在模型定制或网络隔离需求特别苛刻时才考虑。

1.3 为什么很多企业选择 Bedrock

从工程角度看，Bedrock 的价值不只是“能调用 Claude”，而是把调用入口纳入 AWS 的统一治理体系。第一，权限可以用 IAM 控制到某个具体模型，不需要在代码里埋明文密钥；第二，每次调用的元数据可以写入 CloudTrail，审计和追踪有据可查；第三，账单归属到 AWS 账号，方便按项目、按环境分摊成本；第四，Prompt 和输出内容在传输与存储环节可以结合 KMS 加密，满足更多合规场景。

当然 Bedrock 也有自己的限制，比如模型可用区域、配额上限、延迟波动，这些需要在选型时提前确认。本文偏工程落地方向，会在第 6、7 章同步说明这些边界，避免你上线后才发现问题。

2. 环境准备与账号配置

2.1 开始前需要准备什么

动手之前，建议先把下面的清单准备好，避免做到一半发现缺账号或缺权限。

• 一个 AWS 账号，并且有权限进入 IAM 控制台创建用户和策略。
• 一个用于开发环境的 IAM 用户或角色，具备 programmatic access，也就是可以调用 AWS CLI 的那种访问密钥。
• 本机安装好 AWS CLI，版本建议 2.x。
• Python 3.9 及以上版本，用于运行 boto3 示例。
• Node.js 18 及以上版本，用于安装 Claude Code（如果后面要用）。
• 浏览器能正常访问 AWS 管理控制台，并且目标区域已经开通了 Bedrock 服务。

需要说明的是，不同版本账号、不同区域开放的模型可能不同，本文示例统一使用us-east-1区域，实际以你的环境为准。版本也需要根据你的项目实际情况调整，本文重点演示配置思路和最小可运行链路。

2.2 开通 Bedrock 模型访问权限

在网上搜索“AWS Claude 调用失败”的案例里，有很大一部分并不是代码问题，而是 Bedrock 的模型访问没有开通。Bedrock 模型访问开通流程如下：登录 AWS 控制台，切换到目标区域，进入 Amazon Bedrock 服务页面。在左侧菜单里找到 Model access，点击 Manage model access，勾选你要使用的 Anthropic Claude 系列模型，提交后等待状态变为 Access granted。

模型访问权限和 IAM 权限是两回事：模型访问是账号层面的“允许使用该模型”，IAM 权限是“哪个身份能调用”，两者缺一不可。开通后可以进入 Playground 先手动测试一次对话，确认模型本身可用，再回到命令行做程序化调用。

2.3 配置 AWS CLI 与认证

程序化调用 Claude 的第一步是让本机或服务器能通过 AWS 认证。开发环境建议使用 IAM 用户的 Access Key，生产环境则优先使用 IAM Role，通过临时凭证或实例角色访问，不推荐把长期密钥写在配置文件里提交到代码仓库。

aws configure

执行后按提示输入 Access Key ID、Secret Access Key、默认区域us-east-1，输出格式选择json。配置完成后运行下面命令验证身份：

aws sts get-caller-identity

如果返回了类似Arn: arn:aws:iam::123456789012:user/bedrock-dev的内容，说明认证已经可用。接下来需要给这个用户或角色附加一个最小权限策略，核心权限是bedrock:InvokeModel和bedrock:InvokeModelWithResponseStream。下面是一个最小策略示例，资源只限定到某一个模型：

{ "Version": "2012-10-17", "Statement": [ { "Sid": "AllowInvokeClaudeHaiku", "Effect": "Allow", "Action": [ "bedrock:InvokeModel", "bedrock:InvokeModelWithResponseStream" ], "Resource": "arn:aws:bedrock:us-east-1::foundation-model/anthropic.claude-3-haiku-20240307-v1:0" } ] }

策略里把资源限定到具体的模型 ARN，是生产环境推荐的做法。如果为了方便后续切换模型，也可以先使用"Resource": "*"，但权限范围越大，越容易造成误用和数据泄露风险，建议在测试阶段就养成最小权限的习惯。

2.4 验证最小调用

认证配置好以后，先用 boto3 发起一次最简调用，确认整条链路是通的。先安装依赖：

pip install boto3

然后运行下面的 Python 脚本：

# 文件路径：bedrock_quick_test.py import boto3 bedrock_runtime = boto3.client( service_name="bedrock-runtime", region_name="us-east-1" ) model_id = "anthropic.claude-3-haiku-20240307-v1:0" response = bedrock_runtime.converse( modelId=model_id, messages=[ { "role": "user", "content": [{"text": "你好，请用一句话介绍你自己"}] } ], inferenceConfig={ "maxTokens": 200, "temperature": 0.7 } ) answer = response["output"]["message"]["content"][0]["text"] print(answer)

这里使用了converse方法，它是 Bedrock 提供的一种统一对话接口，不需要像早期InvokeModel那样手工拼 Anthropic 格式的请求体。运行脚本后，如果正常输出一段 Claude 的自我介绍文本，说明环境已经就绪；如果报错，可以按第 6 章的排查表逐步定位。

3. 核心概念：模型 ID、推理参数与调用方式

3.1 Bedrock 与 Claude 模型的关系

Amazon Bedrock 可以理解为一个“模型网关”：它本身不训练模型，而是把 Anthropic、Meta、Mistral 等多家模型统一封装成标准 API。对调用方来说，只需要通过 AWS 凭证访问 Bedrock，就能使用背后的 Claude 模型，无需关心模型实际部署在哪个集群。

这种设计带来的好处是切换模型时，如果使用 Converse 这类统一接口，请求结构基本不变，只需要改modelId和对应的参数差异。坏处是 Bedrock 与 Anthropic 官方 API 在某些字段、限流策略和可用性上存在差异，如果你之前接触的是官方 API，迁移到 Bedrock 时要特别注意模型 ID 和错误码的差异。

3.2 模型 ID 与推理参数

Bedrock 调用 Claude 时必须指定模型 ID，模型 ID 的格式通常是anthropic.claude-版本-日期:0这样的命名方式。下面列出几个常见的模型 ID 作为参考：

模型 ID 会随新模型发布而增加，同一款模型在不同区域可能 ID 不同，因此最稳妥的方式是登录 Bedrock 控制台，在模型列表中查看当前区域可用的模型 ID。不要在网上复制一段旧代码就长期固定模型 ID，尤其是跨区域部署时，优先从配置项读取。

推理参数方面，常用的是maxTokens、temperature、topP。maxTokens控制生成的最大 token 数，直接影响成本和响应时间；temperature控制随机性，值越小输出越稳定，适合结构化输出；topP控制核采样范围，与temperature通常建议只调整其中一个，而不是同时大幅修改。对稳定性要求高的生产场景，建议把temperature设在 0.2 到 0.5 之间，避免输出飘忽不定。

3.3 InvokeModel 与 Converse API 的区别

Bedrock 提供了多组调用接口，最常接触的是InvokeModel和Converse。InvokeModel是更底层的接口，请求体必须按照各模型的原始格式编写，Claude 系列的格式主要参考 Anthropic Messages API。而Converse是一个统一了消息结构的高级接口，无论底层是哪个厂商的模型，请求格式都保持一致，更加适合新项目。

对于新开发的项目，优先使用Converse。它内置了system、messages、inferenceConfig这些语义明确的字段，写起来更直观。如果后续需要从 Claude 切换到其他模型，改动成本也更小。需要流式输出时，可以对应使用converse_stream或InvokeModelWithResponseStream，本文后面会围绕converse展开实战。

4. 从开发到落地：完整实战案例

4.1 项目设计与目录结构

下面我们实现一个“文本总结助手”：调用方传入一段文本，服务端调用 Claude 生成摘要，并以 JSON 形式返回。这个案例体量不大，但覆盖了调用封装、重试、日志、发布 API 等生产必备环节，可以直接作为模板扩展成其他业务。

项目目录如下：

claude-demo/ ├── claude_client.py ├── lambda_function.py ├── requirements.txt └── README.md

其中claude_client.py是核心调用模块，负责与 Bedrock 交互，包含重试和日志；lambda_function.py是无服务器入口，接收 API Gateway 的 HTTP 请求并返回响应；requirements.txt声明运行时依赖。

4.2 编写带重试和日志的调用服务

直接把 boto3 调用散落在业务代码里，短期内没问题，但一旦出现限流、超时、模型切换，维护成本会迅速上升。更合理的方式是封装成一个独立客户端，把模型 ID、区域、重试策略、日志输出统一收口。

下面是一个完整的claude_client.py示例：

# 文件路径：claude-demo/claude_client.py import boto3 import logging import time from botocore.exceptions import ClientError logger = logging.getLogger(__name__) class ClaudeBedrockClient: def __init__(self, region_name, model_id, retry_times=3, retry_base_seconds=1.0): self.region_name = region_name self.model_id = model_id self.retry_times = retry_times self.retry_base_seconds = retry_base_seconds self.client = boto3.client( service_name="bedrock-runtime", region_name=region_name, ) def invoke(self, prompt, max_tokens=1024, temperature=0.7, system_prompt=None): messages = [ { "role": "user", "content": [{"text": prompt}], } ] payload = { "modelId": self.model_id, "messages": messages, "inferenceConfig": { "maxTokens": max_tokens, "temperature": temperature, }, } if system_prompt: payload["system"] = [{"text": system_prompt}] last_error = None for attempt in range(1, self.retry_times + 1): try: response = self.client.converse(**payload) output_text = response["output"]["message"]["content"][0]["text"] usage = response.get("usage", {}) logger.info( "model=%s input_tokens=%s output_tokens=%s attempt=%s", self.model_id, usage.get("inputTokens"), usage.get("outputTokens"), attempt, ) return output_text except ClientError as e: error_code = e.response.get("Error", {}).get("Code", "") if error_code in ( "ThrottlingException", "InternalServerException", "ServiceUnavailable", ): last_error = e sleep_seconds = self.retry_base_seconds * (2 ** (attempt - 1)) logger.warning( "retry after %.2f seconds, attempt=%s, error=%s", sleep_seconds, attempt, error_code, ) time.sleep(sleep_seconds) else: logger.exception("bedrock invoke failed, error_code=%s", error_code) raise except Exception as exc: logger.exception("unexpected error when invoking bedrock") last_error = exc break raise RuntimeError( f"invoke failed after {self.retry_times} retries: {last_error}" )

这个类有几个设计要点。其一是重试策略：只有遇到限流和服务端异常才重试，遇到权限、参数类的客户端错误直接抛出，避免无意义的重复调用。其二是退避算法：首次等待 1 秒，之后按 2 的幂次增长，降低对 Bedrock 的二次冲击。其三是日志记录：每次调用成功都记录模型 ID 和 token 消耗，方便后续核算成本和分析调用量。

4.3 封装为 Lambda 函数并通过 API Gateway 暴露

调用服务写好后，下一步是把它放到 AWS 无服务器环境里，通过 API Gateway 对外提供 HTTP 接口。先看入口文件：

# 文件路径：claude-demo/lambda_function.py import json import logging from claude_client import ClaudeBedrockClient logger = logging.getLogger() logger.setLevel(logging.INFO) MODEL_ID = "anthropic.claude-3-haiku-20240307-v1:0" REGION_NAME = "us-east-1" client = ClaudeBedrockClient(region_name=REGION_NAME, model_id=MODEL_ID) def lambda_handler(event, context): try: body = json.loads(event.get("body", "{}")) prompt = body.get("prompt", "请用一句话介绍你自己") max_tokens = int(body.get("max_tokens", 512)) answer = client.invoke(prompt, max_tokens=max_tokens) return { "statusCode": 200, "headers": {"Content-Type": "application/json"}, "body": json.dumps({"answer": answer}, ensure_ascii=False), } except Exception as exc: logger.exception("lambda handler failed") return { "statusCode": 500, "headers": {"Content-Type": "application/json"}, "body": json.dumps({"error": str(exc)}, ensure_ascii=False), }

Lambda 在冷启动时会执行模块顶层的ClaudeBedrockClient初始化，因此客户端可以复用，只有首次调用或容器回收时才重新创建，能明显减少启动开销。函数逻辑本身很简单：解析请求体、调用模型、统一返回 JSON。

接下来要创建 Lambda 函数。可以直接在控制台创建，也可以使用 AWS CLI 或 SAM 打包上传。部署时需要给执行角色附加权限，策略可以复用 2.3 节的最小权限示例，再把Resource换成你实际使用的模型 ARN。最后创建一个 API Gateway 的 REST API，将POST /summarize路由指向该 Lambda 函数。如果使用控制台创建触发器，系统会自动生成调用授权；如果使用 Terraform 或 SAM 等 IaC 工具，需要额外补充lambda:InvokeFunction的资源策略，否则 API 调用会返回 403。

配置完成后，用 curl 验证一次：

curl -X POST https://your-api-id.execute-api.us-east-1.amazonaws.com/prod/summarize \ -H "Content-Type: application/json" \ -d '{"prompt": "用一句话总结：AWS 上使用 Claude 的完整流程"}'

正常返回结果类似：

{ "answer": "在 AWS 上使用 Claude 的完整流程包括开通 Bedrock 模型访问、配置 IAM 权限、通过 SDK 调用模型，以及结合 Lambda 和 API Gateway 发布为对外接口。" }

到这里，“从开发到落地”的最小闭环已经完成。本地开发时有 Python 客户端可以直接调试，线上则通过 API Gateway 暴露标准 HTTP 接口，前后端调用方式完全统一。

4.4 本地测试与进一步扩展

如果不想每次都打包部署到 Lambda，也可以先在本地跑通整个调用流程。只需要在本地配置好 AWS 凭证，然后直接调用ClaudeBedrockClient：

# 文件路径：claude-demo/local_test.py import logging from claude_client import ClaudeBedrockClient logging.basicConfig(level=logging.INFO) client = ClaudeBedrockClient( region_name="us-east-1", model_id="anthropic.claude-3-haiku-20240307-v1:0", ) result = client.invoke( system_prompt="你是一个严谨的文档助理。", prompt="请用 3 个要点总结本文介绍的生产环境注意事项。", max_tokens=300, ) print(result)

这个案例扩展方向很多：把prompt换成系统人设和用户输入拼接，就能变成智能客服；把返回值接入 S3 或 DynamoDB，就能做异步任务；加上converse_stream，就能实现打字机效果。核心架构不变，变的只是业务编排逻辑。

5. Claude Code 在 AWS 场景下的配合使用

5.1 Claude Code 是什么

Claude Code 是 Anthropic 推出的命令行编程助手，主要运行在终端环境里，可以读取项目文件、执行命令、生成和修改代码。它通常通过 npm 安装，需要一个可以作为后端服务的 Claude 版本，Anthropic 官方账号或受支持的云模型通道都可以作为认证来源。在开发者的实际使用中，最常见的问题集中在安装和环境变量上，而不是模型能力本身。

如果你已经有一个可以访问的 Claude 模型通道，但没有配置对应的环境变量或认证信息，Claude Code 启动时就会提示无法连接。此时不要盲目修改系统配置，先确认两点：Node.js 是否安装成功，以及当前账号是否有权访问目标模型通道。

5.2 在 AWS 环境中的使用思路

Claude Code 本身并不依赖 AWS，但如果你的团队已经统一使用 IAM 凭证管理，想让它与 AWS 上的模型通道配合，思路是先确保 AWS 凭证可用，再确认当前 Claude Code 版本是否支持对应的云厂商提供商配置。由于不同版本支持的配置方式差异较大，建议先运行：

claude --help

查看当前版本的 provider 和认证参数，并按官方文档和 README 的要求填写。一个通用的环境准备示例是：

export AWS_REGION=us-east-1 export AWS_PROFILE=bedrock-dev npm install -g @anthropic-ai/claude-code claude

在实际团队中，更推荐给 Claude Code 单独准备一个开发用的 IAM 身份，而不是直接使用管理员账号。这样做的好处是：即使终端环境变量被意外提交到仓库或共享到聊天工具中，也不会把整个云账号暴露出去；同时可以针对不同项目控制不同的模型访问范围，离职或换人时只需要回收对应的 IAM 身份，不需要改动业务代码。

5.3 常见安装报错

在 Windows 的 PowerShell 中安装 Claude Code 后，不少用户会遇到无法将“claude”项识别为 cmdlet、函数、脚本文件或可运行程序的名称的报错。这个提示的含义是系统在 PATH 中找不到claude命令，常见原因是 Node.js 全局安装目录没有加入 PATH，或者安装过程中断。解决方案有两种：第一种是把 npm 全局 bin 目录加入 PATH，然后重新打开终端；第二种是暂时绕过 PATH，直接用 npx 运行：

npx @anthropic-ai/claude-code

在 Linux 和 macOS 上，如果遇到zsh: command not found: claude，处理思路类似，优先检查 npm 全局路径。如果安装时提示权限不足，可以考虑使用 Node 版本管理器重新安装 Node，而不是用 sudo 强行修改全局目录。还有一种情况是官方账号在部分区域提示服务当前不可用，这种通常属于账号接入条件限制，建议改用团队已开通的云模型通道，或等待官方开放后再使用；不要轻信来路不明的安装脚本和代理配置，避免凭据泄露。

6. 常见问题与排查清单

6.1 高频错误速查表

6.2 三个典型排查案例

第一个案例是 IAM 权限不足。现象是本地使用管理员凭证可以调用，切换到新创建的 IAM 用户后立刻返回 AccessDeniedException。排查步骤是先确认 IAM 用户附加的策略，再确认策略中的Resource是否指向了正在调用的模型 ARN，最后检查默认区域是否与策略中的区域一致。很多权限问题是跨区域造成的：策略写的是us-east-1，实际代码却连到了ap-southeast-1，自然找不到对应的模型资源。

第二个案例是模型访问未开通。现象是调用任何 Claude 模型都返回类似的“模型不可用”错误。这时候不要急着改代码，先登录 Bedrock 控制台，在 Model access 页面查看模型状态是否已经变成 Access granted。模型访问开通后有时需要等待几分钟生效，刚开通就立刻调用报错可以先稍等再试。

第三个案例是高并发下的限流。现象是压测时大量请求返回 ThrottlingException，业务方把重试时间设置成固定 1 秒，反而加剧了请求堆积。更合理的做法是指数退避加抖动，并且把可异步处理的请求转成队列任务，错峰调用。如果业务对延迟要求很高，可以考虑申请 Provisioned Throughput 预留推理容量，而不是一味加大重试次数。

7. 生产环境最佳实践

7.1 安全与权限最小化

生产环境的第一原则是权限最小化。IAM 策略只允许必要身份调用必要的模型；Lambda、EC2 等计算资源尽量使用角色而不是长期密钥；包含密钥、Token 的环境变量不要写入代码仓库，优先使用 AWS Secrets Manager 或 Systems Manager Parameter Store。对于涉及个人信息的内容，调用大模型前要经过脱敏处理，并在日志中避免记录完整 Prompt。

Bedrock 的数据合规能力也需要提前了解：通过 Bedrock 调用时，输入输出内容默认不会被 AWS 用于模型训练，但这个承诺要以你企业与 AWS 签订的最新协议为准。涉及数据出境、行业监管的场景，建议提前与安全团队确认所选区域和数据留存策略。

7.2 成本控制

Claude 系列不同型号的价格差异很大，Haiku 相比 Sonnet 和 Opus 便宜很多。实际项目中不要所有请求都用同一个强模型，简单分类、翻译、格式化任务可以优先使用小模型，复杂推理再升级到大模型。系统提示词尽量精简，Prompt 中重复出现的固定内容可以考虑使用提示词缓存类能力，降低输入 token 成本。

关于降本还有一个容易忽略的点：很多团队会把 Auto Scaling Group 的 Desired 数量设为 0，以为这样环境就不再产生费用。这个操作确实会停止 EC2 实例，但环境里如果还挂着弹性 IP、独立的 EBS 卷、NAT Gateway、应用负载均衡器等资源，这些资源依然会继续计费。也就是说，Desired=0 只是让计算节点缩容，不代表整条链路都免费，停机前要检查一遍配套资源。

预算控制方面，建议在 AWS 账单服务里设置预算告警，并按模型调用量、Lambda 执行次数等维度拆分成本标签，让每个业务方都能看到自己的模型消耗。

7.3 可观测性与稳定性

生产级调用必须做好可观测性。Bedrock 控制台可以开启 Model Invocation Logging，把调用日志写入 CloudWatch Logs 或 S3，记录请求 ID、模型、token 用量等信息。业务侧也建议在统一封装层输出结构化日志，便于按天、按模型维度统计分析。对于不要求实时返回的场景，尽量使用异步架构：请求进来先写入队列，再由 worker 调用 Claude，完成后写回结果，这样即使模型侧波动，也不会阻塞用户请求。

降级策略同样是稳定性的一部分。当 Bedrock 可用性出现波动时，可以考虑在主区域外再配置一个备用区域，或者准备一个规则简单的兜底模型。需要注意的是，多区域切换会改变模型 ID 和网络延迟，切换逻辑要提前压测，而不是故障发生时临时改配置。

7.4 数据合规与内容安全

内容安全在生成式 AI 应用里是绕不开的话题。Bedrock 提供了 Guardrails 服务，可以针对 Prompt 和模型输出做敏感信息过滤、有害内容拦截、关键词屏蔽等处理。即使没有接入 Guardrails，业务侧也应该对输入长度、输出长度、敏感字段做基础校验，防止异常输入消耗大量 token 或泄露内部信息。上线前建议整理一份内容安全 checklist，覆盖输入过滤、输出过滤、日志脱敏三个环节。

8. 总结与学习路线

到这里，一条从零开始在 AWS 上接入 Claude 的完整链路已经串起来了：账号与模型访问、最小调用、带重试的客户端、Lambda 发布 API、Claude Code 配合使用，每一环都能对照你的项目实际调整。如果下一步要往生产级 Agent 方向走，建议优先研究流式输出、Tool Use 和 Guardrails，这三块是绕不开的进阶点。实践过程中如果遇到上面没覆盖到的报错，欢迎在评论区带上你的区域、模型 ID 和错误码一起讨论。