Amazon Bedrock 中 Claude Code 的代码部署模式与最佳实践

📢 转载信息

原文链接：https://aws.amazon.com/blogs/machine-learning/claude-code-deployment-patterns-and-best-practices-with-amazon-bedrock/

原文作者：Court Schuett, Gabriel Velazquez, Jawhny Cooke, Karan Lakhwani, and Gabe Levy

Claude Code 是 Anthropic 推出的由 AI 驱动的编码助手，它通过自然语言交互帮助开发人员编写、审查和修改代码。 Amazon Bedrock 是一项全托管服务，通过单个 API 为用户提供领先 AI 公司的基础模型。本文将向您展示如何使用 Amazon Bedrock 部署 Claude Code。您将了解用于安全地以企业规模部署的身份验证方法、基础设施决策和监控策略。

面向大多数企业推荐的方案

我们推荐使用 Amazon Bedrock Claude Code 指南，它实现了经过验证的模式，可以在数小时内部署。

使用以下经过验证的技术栈部署 Claude Code：

• 身份验证：使用 AWS IAM 联合的直接 IdP 集成
• 基础设施：专用的 AWS 账户和公共 Amazon Bedrock 端点
• 监控：使用 OpenTelemetry 结合 CloudWatch 仪表板和分析

该架构提供了安全的访问，具有用户归属、容量管理以及对成本和开发人员生产力的可见性。

身份验证方法

Claude Code 部署始于对 Amazon Bedrock 的身份验证。身份验证的决策会影响下游的安全、监控、操作和开发人员体验。

身份验证方法比较

下文将讨论上表中概述的权衡和实施注意事项。

API 密钥

Amazon Bedrock 支持API 密钥，这是实现概念验证最快的方式。可以通过 AWS 管理控制台、AWS CLI 或 SDK 生成短期（12 小时）和长期（无限期）密钥。

然而，API 密钥存在安全隐患，因为它提供持久访问而没有 MFA、需要手动分发，并有提交到代码库的风险。它们不提供任何用户归属信息用于成本分配或监控。仅用于短期测试（< 1 周，12 小时过期）。

AWS 登录

aws login 命令通过基于浏览器的身份验证流程使用您的 AWS 管理控制台凭证来访问 Amazon Bedrock。它支持快速设置而无需 API 密钥，推荐用于测试和小规模部署。

单点登录 (SSO)

AWS IAM Identity Center 通过 OpenID Connect (OIDC) 与现有企业身份提供商集成，OIDC 是一种身份验证协议，它允许身份提供商验证用户身份并将身份验证信息与应用程序共享，从而实现单点登录。

开发人员使用 aws sso login 命令使用 IAM Identity Center 进行身份验证，该命令生成具有可配置会话时长的临时凭证。这些凭证会自动刷新，减少了凭证管理的运维开销，同时通过临时、有时限的访问提高了安全性。

aws sso login --profile=your-profile-name export CLAUDE_CODE_USE_BEDROCK=1 export AWS_PROFILE=your-profile-name

使用 IAM Identity Center 进行 AWS 访问的组织可以将此模式扩展到 Claude Code。但是，它不会暴露 OIDC JWT 令牌以供 OpenTelemetry 属性提取，从而限制了详细的用户级别监控。

此身份验证方法适用于那些优先考虑快速 SSO 部署而非详细监控，或处于不需要全面指标的初始部署阶段的组织。

直接 IdP 集成

直接与您的身份提供商（Okta、Azure AD、Auth0 或 AWS Cognito 用户池）进行 OIDC 联合是生产环境 Claude Code 部署的推荐方式。此方法将您的企业身份提供商直接连接到 AWS IAM，以生成具有完整用户上下文的临时凭证用于监控。

process credential provider（流程凭证提供程序）协调使用 PKCE（一种有助于防止授权码拦截的安全扩展）的 OAuth2 身份验证。开发人员在浏览器中进行身份验证，将 OIDC 令牌交换为 AWS 临时凭证。

一个辅助脚本使用 AWS 安全令牌服务 (STS) 的 AssumeRoleWithWebIdentity 来承担角色，获取凭证以 InvokeModel 和 InvokeModelWithStreaming 以使用 Amazon Bedrock。直接 IAM 联合支持最长 12 小时的会话时长，并且 JWT 令牌在整个会话期间保持可访问，通过 OpenTelemetry 启用监控，以跟踪诸如电子邮件、部门和团队等用户属性。

Amazon Bedrock Claude Code 指南实现了 Cognito Identity Pool 和直接 IAM 联合模式，但推荐使用直接 IAM 以实现简单性。该解决方案提供了一个交互式设置向导，可配置您的 OIDC 提供商集成、部署必要的 IAM 基础架构，并为 Windows、macOS 和 Linux 构建分发包。

开发人员收到配置了 AWS CLI 配置文件以使用凭证流程的安装包。身份验证通过公司凭证进行，凭证刷新通过自动打开浏览器完成。凭证流程处理令牌缓存、凭证刷新和错误恢复。

对于需要详细使用监控、按开发人员分配成本以及全面审计跟踪的组织，通过 IAM 联合进行直接 IdP 集成为稍后讨论的高级监控功能奠定了基础。

组织决策

除了身份验证之外，架构决策决定了 Claude Code 如何与您的 AWS 基础架构集成。这些选择会影响操作复杂性、成本管理和使用策略的执行。

公共端点

Amazon Bedrock 在多个 AWS 区域提供托管的、公共 API 端点，运维开销极低。AWS 负责管理基础设施、扩展、可用性和安全补丁。开发人员通过 AWS CLI 配置文件或环境变量使用标准的 AWS 凭证。结合直接 IdP 集成中的 OpenTelemetry 指标，您可以按单个开发人员、部门或成本中心跟踪公共端点的使用情况，并且可以在 AWS IAM 级别执行。例如，实施按开发人员的速率限制需要观察 CloudWatch 指标或 CloudTrail 日志并采取自动化措施的基础设施。需要基于自定义业务逻辑进行即时、请求级别阻止的组织可能需要额外的组件，例如 LLM（大型语言模型）网关模式。公共 Amazon Bedrock 端点足以满足大多数组织的需求，因为它们在简单性、AWS 托管的可靠性、成本警报和适当的控制机制之间取得了平衡。

LLM 网关

LLM 网关在开发人员和 Amazon Bedrock 之间引入了一个中介应用程序层，通过自定义基础设施路由请求。 AWS 上的多提供商生成式 AI 网关指南描述了此模式，它部署了一个带有负载均衡和集中式凭证管理的容器化代理服务。

此架构最适用于以下情况：

• 多提供商支持：根据可用性、成本或能力在 Amazon Bedrock、OpenAI 和 Azure OpenAI 之间路由
• 自定义中间件：在请求级别进行专有提示工程、内容过滤或提示注入检测
• 请求级别策略执行：即时阻止超出自定义业务逻辑的请求，超越 IAM 的能力

网关提供统一的 API 和实时跟踪，但会增加运维开销：Amazon 弹性容器服务 (Amazon ECS)/Amazon 弹性 Kubernetes 服务 (Amazon EKS) 基础设施、弹性负载均衡 (ELB) 应用程序负载均衡器、Amazon ElastiCache、Amazon 关系数据库服务 (Amazon RDS) 管理、延迟增加，以及一种新的故障模式，即网关问题会阻止 Claude Code 的使用。网关非常适合以编程方式调用 LLM 的应用程序，提供集中监控、按用户可见性和统一的控制访问提供商。

对于传统 API 访问场景，组织可以部署网关以获得监控和归属能力。Claude Code 指南解决方案已经通过直接 IdP 身份验证、OpenTelemetry 指标、IAM 策略和 CloudWatch 仪表板提供了监控和归属功能。向指南解决方案添加 LLM 网关会重复现有功能。仅当需要多提供商支持、自定义中间件或超出 IAM 的请求级别策略执行时，才考虑使用网关。

单账户实施

我们建议将编码助手推理集中在单个专用账户中，与您的开发和生产工作负载分开。此方法提供了五个主要优势：

1. 简化的操作： 通过统一的仪表板管理配额并监控跨多个账户的使用情况。只需申请一次配额增加，而不是为每个账户申请。
2. 清晰的成本可见性： AWS Cost Explorer 和 成本和使用情况报告直接显示 Claude Code 的费用，无需复杂的标记。OpenTelemetry 指标支持按部门和团队级别的分配。
3. 集中式安全： CloudTrail 日志流向一个位置，用于监控和合规性。只需部署一次监控堆栈即可收集开发人员的指标。
4. 生产保护： 账户级别的隔离有助于防止 Claude Code 的使用耗尽配额并限制生产应用程序。生产流量高峰不会影响开发人员的生产力。
5. 实施： 跨账户 IAM 配置允许开发人员通过联合到受限角色的身份提供商进行身份验证，仅授予模型调用权限，并附带适当的护栏。

此策略与直接 IdP 身份验证和 OpenTelemetry 监控集成。身份提供商处理身份验证，专用账户处理推理，开发账户专注于应用程序。

推理配置文件

Amazon Bedrock 推理配置文件通过资源标记提供成本跟踪，但无法扩展到按开发人员的粒度。虽然您可以创建应用程序配置文件进行成本分配，但为 1000 多个独立开发人员管理配置文件在操作上会变得繁琐。推理配置文件最适合需要隔离成本跟踪的 10-50 个不同团队的组织，或在使用跨区域推理（其中托管的路由将请求分配到 AWS 区域）时。它们非常适合需要基本成本分配而非全面监控的场景。

系统定义的跨区域推理配置文件会自动将请求路由到多个 AWS 区域，分配负载以提高吞吐量和可用性。当您调用跨区域配置文件（例如 us.anthropic.claude-sonnet-4）时，Amazon Bedrock 会选择一个可用区域来处理您的请求。

应用程序推理配置文件是您在账户中明确创建的配置文件，通常包装在系统定义的配置文件或某个区域中的特定模型周围。您可以向应用程序配置文件添加自定义键值对标记，如 team:data-science 或 project:fraud-detection，这些标记会流入 AWS 成本和使用情况报告，用于成本分配分析。要创建应用程序配置文件：

aws bedrock create-inference-profile \
 --inference-profile-name team-data-science \
 --model-source arn:aws:bedrock:us-west-2::foundation-model/anthropic.claude-sonnet-4 \
 --tags team=data-science costcenter=engineering

标记会出现在 AWS 成本和使用情况报告中，因此您可以查询：

“数据科学团队上个月在 Amazon Bedrock 上花费了多少？”

必须在 API 调用中明确引用每个配置文件，这意味着开发人员的凭证配置必须指定其唯一的配置文件，而不是共享的端点。

有关推理配置文件的更多信息，请参阅Amazon Bedrock 推理配置文件文档。

监控

有效的监控策略将 Claude Code 从一个生产力工具转变为一项可衡量的投资，方法是跟踪使用情况、成本和影响。

渐进式增强路径

监控层是互补的。组织通常从基本可见性开始，并随着投资回报率 (ROI) 要求的合理化而增加功能。

让我们探讨每个级别以及它何时适合您的部署。

注意： 基础架构成本会逐步增加——每个级别都保留了前一个级别的组件，并添加了新组件。

CloudWatch

Amazon Bedrock 会自动向 Amazon CloudWatch 发布指标，跟踪调用计数、限制错误和延迟。CloudWatch 图表显示总体趋势，例如总请求数、平均延迟和配额利用率，部署工作量极少。此基线监控包含在 CloudWatch 的标准定价中，只需要最少的部署工作。您可以创建 CloudWatch 警报，以便在调用率激增、错误率超过阈值或延迟下降时通知您。

调用日志记录

Amazon Bedrock 调用日志记录会捕获有关每次 API 调用的详细信息到 Amazon S3 或 CloudWatch Logs，保留单个请求记录，包括调用元数据以及完整的请求/响应数据。使用 Amazon Athena 处理日志，加载到数据仓库，或使用自定义工具进行分析。日志显示了使用模式、按模型的调用、高峰利用率以及 Amazon Bedrock 访问的审计跟踪。

OpenTelemetry

Claude Code 支持 OpenTelemetry，这是一个用于收集应用程序遥测数据的开源可观察性框架。当配置了 OpenTelemetry 收集器端点时，Claude Code 会为其操作发出详细指标——包括 Amazon Bedrock API 调用和更高级别的开发活动。

遥测捕获了 Amazon Bedrock 默认日志中不包含的详细代码级别指标，例如：添加/删除的代码行数、修改的文件数、使用的编程语言以及开发人员对 Claude 建议的接受率。它还跟踪关键操作，包括文件编辑、代码搜索、文档请求和重构任务。

指南解决方案在 Amazon ECS Fargate 上部署 OpenTelemetry 基础架构。应用程序负载均衡器通过 HTTP(S) 接收遥测数据，并将指标转发到 OpenTelemetry 收集器。收集器将数据导出到 Amazon CloudWatch 和 Amazon S3。

仪表板

指南解决方案包含一个 CloudWatch 仪表板，它持续显示关键指标，跟踪按小时、天或周的活跃用户数，以揭示采用和使用趋势，从而实现按用户成本计算。令牌消耗按输入、输出和缓存令牌细分，高缓存命中率表明上下文重用效率高，按用户视图可识别重度用户。代码活动指标跟踪添加和删除的行数，与令牌使用情况相关联，以显示效率和使用模式。

操作细分显示了文件编辑、代码搜索和文档请求的分布情况，而用户排行榜则按令牌、代码行数或会话时长显示顶级消费者。

仪表板近乎实时地更新，并与 CloudWatch 警报集成，以便在指标超出阈值时触发通知。指南解决方案通过 CloudFormation 和自定义 Lambda 函数进行部署，用于复杂的聚合。

分析

虽然仪表板在实时监控方面表现出色，但长期趋势和复杂的用户行为分析需要分析工具。指南解决方案的可选分析堆栈使用 Amazon Data Firehose 将指标流式传输到 Amazon S3。AWS Glue 数据目录定义了架构，使数据可通过 Amazon Athena 查询。

分析层支持诸如按部门划分的月度令牌消耗、按编程语言划分的代码接受率以及团队间令牌效率变化等查询。成本分析通过将令牌指标与 Amazon Bedrock 定价相结合来计算每个用户的确切成本，然后按部门汇总进行内部计费，从而变得复杂。时间序列分析显示成本如何随着团队增长而扩展，用于预算预测。 SQL 接口与商业智能工具集成，支持导出到电子表格、机器学习模型或项目管理系统。

例如，要查看按部门划分的月度成本分析：

SELECT department, SUM(input_tokens) * 0.003 / 1000 as input_cost, SUM(output_tokens) * 0.015 / 1000 as output_cost, COUNT(DISTINCT user_email) as active_users FROM claude_code_metrics WHERE year = 2024 AND month = 1 GROUP BY department ORDER BY (input_cost + output_cost) DESC;

基础架构会增加中等成本：Data Firehose 按摄取收费，S3 按保留收费，Athena 按扫描数据量收费。

当您需要历史分析、复杂查询或与商业智能工具集成时，请启用分析。虽然对于小型部署或主要关注实时监控的组织来说，仪表板可能就足够了，但对于在 Claude Code 上进行重大投资的企业应实施分析层。这提供了展示投资回报率和随着时间推移优化使用所需的可见性。

配额

配额允许组织通过为单个开发人员或团队设置使用限制来控制和管理令牌消耗。在实施配额之前，我们建议首先启用监控以了解自然使用模式。使用数据通常显示高令牌消耗与高生产力相关，表明重度用户带来了相应的价值。

配额系统将限制存储在 DynamoDB 中，其中包含如下条目：

{ "userId": "jane@example.com", "monthlyLimit": 1000000, "currentUsage": 750000, "resetDate": "2025-02-01" }

由 CloudWatch Events 触发的 Lambda 函数每 15 分钟聚合一次令牌消耗，更新 DynamoDB 并在超过阈值时发布到 SNS。

监控比较

下表总结了不同监控方法的权衡：

整合

本节将身份验证方法、组织架构和监控策略综合成推荐的部署模式，并提供了随着部署成熟度演进的实施优先级的指导。该架构平衡了安全性、操作简便性和全面的可见性。开发人员每天使用公司凭证进行一次身份验证，管理员在仪表板中实时查看使用情况，安全团队拥有 CloudTrail 审计日志和通过 OpenTelemetry 获得的全面用户归属指标。

实施路径

指南解决方案通过交互式设置过程支持快速部署，身份验证和监控在几小时内即可运行。首先将完整堆栈部署到一个试点组，收集实际使用数据，然后根据经过验证的模式进行扩展。

1. 部署 – 克隆 Amazon Bedrock Claude Code 指南存储库并运行交互式 poetry run ccwb init 命令向导。该向导会配置您的身份提供商、联合类型、AWS 区域和可选的监控。部署 CloudFormation 堆栈（通常需要 15-30 分钟），构建分发包，并在分发给用户之前在本地测试身份验证。

1. 分发 – 从不同团队确定一个由 5 到 20 名开发人员组成的试点组。该组将验证身份验证、监控，并提供使用数据以进行全面推广规划。如果启用了监控，CloudWatch 仪表板会立即显示活动。您可以监控令牌消耗、代码接受率和操作类型，以估算容量需求、识别培训需求并证明更广泛推广的价值。

1. 扩展 – Claude Code 经验证后，按团队或部门扩展采用。添加分析堆栈（通常需要 1-2 小时）以进行历史趋势分析，以了解采用率、高性能团队和成本预测。

1. 优化 – 通过与开发领导层的定期审查周期，利用监控数据持续改进。监控数据可以证明价值、识别培训需求并指导容量调整。

何时偏离推荐模式

尽管上述架构适用于大多数企业部署，但在特定情况下可能会证明采用不同的方法是合理的。

1. 如果您需要除 Amazon Bedrock 之外的多个 LLM 提供商、用于提示处理或响应过滤的自定义中间件，或者在需要超出 AWS IAM 功能的请求级别策略执行的监管环境中运行，请考虑使用 LLM 网关。
2. 如果您有少于 50 个需要单独成本跟踪的团队，并且更喜欢原生的 AWS 计费分配而不是遥测指标，请考虑使用推理配置文件。推理配置文件非常适合基于项目的成本分配，但无法扩展到按开发人员跟踪。
3. 考虑从... [内容被截断]

🚀 想要体验更好更全面的AI调用？

欢迎使用青云聚合API，约为官网价格的十分之一，支持300+全球最新模型，以及全球各种生图生视频模型，无需翻墙高速稳定，文档丰富，小白也可以简单操作。