CleanRL 云基础设施安装指南：基于 Terraform 与 AWS Batch 的规模化强化学习实验部署

CleanRL 云基础设施安装指南：基于 Terraform 与 AWS Batch 的规模化强化学习实验部署

【免费下载链接】cleanrlHigh-quality single file implementation of Deep Reinforcement Learning algorithms with research-friendly features (PPO, DQN, C51, DDPG, TD3, SAC, PPG)项目地址: https://gitcode.com/GitHub_Trending/cl/cleanrl

CleanRL 的云集成方案将训练代码打包为 Docker 容器，借助 AWS Batch 服务并发运行成百上千个强化学习实验，从而支撑大规模超参数搜索与基准测试。本文以 CleanRL 官方云部署文档为主线，结合仓库内的 Terraform 基础设施定义与submit_exp提交脚本源码，完整讲解从零搭建 AWS Batch 计算环境、提交实验到清理资源的全流程，读完即可上手搭建属于自己的分布式 RL 实验平台。

云集成的总体思路

CleanRL 云集成的核心思想非常简单：把代码打包进 Docker 容器，然后使用 AWS Batch 并发运行数千个实验（"The rough idea behind the cloud integration is to package our code into a docker container and use AWS Batch to run thousands of experiments concurrently"）。

这套思路落地为三个环节：

1. Docker 镜像：仓库根目录的 Dockerfile 基于nvidia/cuda:11.4.2-runtime-ubuntu20.04构建，安装 Python、uv、xvfb、ffmpeg 等运行依赖，并将cleanrl/目录整体拷贝进镜像，确保任意训练脚本（如 cleanrl/ppo.py）在任何节点上行为一致；
2. 基础设施定义：cloud/目录下的 Terraform 配置定义 AWS Batch 的计算环境（Compute Environments）与作业队列（Job Queues），通过terraform apply一键创建；
3. 实验提交：cleanrl_utils/submit_exp.py脚本把--command中的训练命令逐条包装成 AWS Batch 作业提交，并自动注入 W&B API Key 用于实验跟踪。

其中第二、三步分别对应docs/cloud/installation.md（本文主体）与docs/cloud/submit-experiments.md（配套实战文档），下文依次展开。

前置条件

安装云基础设施前需要准备以下环境：

• Terraform CLI：仓库使用 Terraform 定义 AWS Batch 基础设施。cloud/main.tf声明了版本约束required_version = ">= 0.14.9"，并要求 AWS provider 版本~> 3.27，安装时需保证 Terraform 版本满足该要求（具体安装步骤参考 HashiCorp 官方 CLI 安装教程）；
• Python 环境与 uv：CleanRL 项目本身基于 pyproject.toml 管理依赖，其中cloud可选依赖组包含boto3>=1.24.70,<2与awscli>=1.31.0,<2（见pyproject.toml第 70-73 行），用于 AWS 交互；
• AWS 账号与默认 Profile：需要配置好 AWS 访问凭证（Access Key / Secret Key），Terraform 与提交脚本默认使用defaultprofile。

安装并部署 AWS Batch 基础设施

在 CleanRL 项目根目录下依次执行以下命令：

# 1. 安装 cloud 可选依赖（boto3、awscli 等） uv pip install ".[cloud]" # 2. 进入 cloud 基础设施目录 cd cloud # 3. 配置 AWS 凭证（交互式输入 Access Key / Secret Key / Region / 输出格式） python -m awscli configure # 4. 初始化 Terraform（下载 AWS provider 插件） terraform init # 5. 导出当前 AWS 区域，供后续 terraform apply/destroy 使用 export AWS_DEFAULT_REGION=$(aws configure get region --profile default) # 6. 应用基础设施（预览变更后输入 yes 确认） terraform apply

整个流程的每一步都对应明确的产物：

关于成本的重要说明

官方文档特别提醒：创建 AWS Batch 计算环境和作业队列本身完全免费，只有在提交实验并实际占用计算资源（EC2 实例）时才会产生费用。这意味着你可以放心地反复执行terraform apply搭建基础设施，而不必担心产生持续支出。

验证部署结果

部署完成后，打开 AWS 管理控制台的 AWS Batch 页面，即可看到 Terraform 创建的计算环境与作业队列，其形态与本文开头的aws_batch1.png截图一致：左侧导航包含 Jobs、Job definitions、Job queues、Compute environments 等入口，主区域展示各作业队列（如c5a-large、c5a-large-spot）的状态与作业统计（RUNNABLE / RUNNING / SUCCEEDED / FAILED）。

基础设施剖析：Terraform 到底创建了什么

terraform apply并不是黑盒操作——仓库中的 Terraform 源码清晰地展示了它创建的全部资源。入口配置 cloud/main.tf 定义了 AWS provider 并调用./modules/cleanrl模块：

terraform { required_providers { aws = { source = "hashicorp/aws" version = "~> 3.27" } } required_version = ">= 0.14.9" } provider "aws" { profile = "default" } module "cleanrl" { source = "./modules/cleanrl" spot_bid_percentage = "50" instance_types = [ "g4dn.4xlarge", # 16 vCPU, 64GB, $1.204, GPU "g4dn.xlarge", # 4 vCPU, 16GB, $0.526, GPU "r5ad.large", # 2 vCPU, 16GB, $0.131 "c5a.large", # 2 vCPU, 4GB, $0.077 # ARM 架构实例 "c6g.medium", # 1 vCPU, 2GB, $0.034 "m6gd.medium", # 1 vCPU, 4GB, $0.0452 ] }

模块内部 cloud/modules/cleanrl/main.tf 通过count = length(var.instance_types)为每种实例类型同时创建两套资源：

• On-demand 计算环境 + 作业队列：类型为EC2，min_vcpus = 0、max_vcpus = var.max_vcpus，作业队列名与实例类型一致（如c5a-large、g4dn-xlarge）；
• Spot 计算环境 + 作业队列：类型为SPOT，额外设置bid_percentage = var.spot_bid_percentage与spot_iam_fleet_role，作业队列名带-spot后缀（如c5a-large-spot、g4dn-xlarge-spot）。

队列命名规则为replace(instance_type, ".", "-")，即c5a.large对应队列c5a-large——这正是后续提交实验时--job-queue参数直接引用的名字。

可调变量

cloud/modules/cleanrl/variables.tf 定义了模块的全部可调参数：

此外，cloud/modules/cleanrl/setups.tf 负责创建配套的基础设施，包括：

• IAM 角色：ecs_instance_role（EC2 容器服务角色）、aws_batch_service_role（Batch 服务角色）、AWS_EC2_spot_fleet_role（Spot Fleet 角色）；
• 安全组：aws_batch_compute_environment_security_group，放行全部出站流量（egress0.0.0.0/0）；
• 默认 VPC 与子网：通过aws_default_vpc与aws_subnet_ids数据源获取当前账号的默认子网，作为计算环境挂载目标。

从源码结构可以推断：部署这套基础设施约需要三类云资源——计算环境（含按需/Spot 两种）、作业队列，以及一组 IAM 角色/安全组/VPC 依赖，全部资源在terraform destroy时会被一并清理。

提交实验到 AWS Batch

基础设施就绪后，即可通过cleanrl_utils.submit_exp提交训练实验。该脚本的完整实现位于 cleanrl_utils/submit_exp.py，其核心逻辑为：

1. 生成多 seed 命令：对--num-seed个 seed，为--command依次追加--seed N后缀；
2. 本地 dry-run 输出：生成对应的docker run -d --cpuset-cpus="N" ...命令并写入<exp-script>.docker.sh文件，便于先在本地确认容器调用方式；
3. AWS 批量提交（--provider aws时）：通过 boto3 依次调用register_job_definition、submit_job、deregister_job_definition，把每个 seed 实验作为一个独立 Batch 作业提交到指定队列，并注入WANDB_API_KEY、WANDB_RESUME=allow、WANDB_RUN_ID（自动生成）三个环境变量，同时按--num-hours设置作业超时（attemptDurationSeconds）、按--aws-num-retries设置重试次数。

第一步：dry run 检查生成的 Docker 命令

提交前先用 dry-run 模式（不带--provider）检查脚本生成的容器命令是否正确：

uv run python -m cleanrl_utils.submit_exp \ --docker-tag vwxyzjn/cleanrl:latest \ --command "uv run python cleanrl/ppo.py --env-id CartPole-v1 --total-timesteps 100000 --track --capture_video" \ --num-seed 1

输出应类似：

docker run -d --cpuset-cpus="0" -e WANDB_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx vwxyzjn/cleanrl:latest /bin/bash -c "uv run python cleanrl/ppo.py --env-id CartPole-v1 --total-timesteps 100000 --track --capture_video --seed 1"

对照 cleanrl_utils/submit_exp.py 的源码可以看到：脚本用multiprocessing.cpu_count()获取本机核数，将多个实验的容器按--cpuset-cpus轮流绑定到不同 CPU 核心，从而在本地也能利用多核并发跑多个 seed。

第二步：提交到 AWS 各类计算实例

按需选择以下四类提交方式之一（均需指定--provider aws）：

1. 计算优化型 Spot 实例（CPU 任务，推荐）

uv run python -m cleanrl_utils.submit_exp \ --docker-tag vwxyzjn/cleanrl:latest \ --command "uv run python cleanrl/ppo.py --env-id CartPole-v1 --total-timesteps 100000 --track --capture_video" \ --job-queue c5a-large-spot \ --num-seed 1 \ --num-vcpu 1 \ --num-memory 2000 \ --num-hours 48.0 \ --provider aws

2. 加速计算型 Spot 实例（GPU 任务，如 Atari）

uv run python -m cleanrl_utils.submit_exp \ --docker-tag vwxyzjn/cleanrl:latest \ --command "uv run python cleanrl/ppo_atari.py --env-id BreakoutNoFrameskip-v4 --track --capture_video" \ --job-queue g4dn-xlarge-spot \ --num-seed 1 \ --num-vcpu 1 \ --num-gpu 1 \ --num-memory 4000 \ --num-hours 48.0 \ --provider aws

3. 计算优化型按需实例（CPU 任务）

uv run python -m cleanrl_utils.submit_exp \ --docker-tag vwxyzjn/cleanrl:latest \ --command "uv run python cleanrl/ppo.py --env-id CartPole-v1 --total-timesteps 100000 --track --capture_video" \ --job-queue c5a-large \ --num-seed 1 \ --num-vcpu 1 \ --num-memory 2000 \ --num-hours 48.0 \ --provider aws

4. 加速计算型按需实例（GPU 任务）

uv run python -m cleanrl_utils.submit_exp \ --docker-tag vwxyzjn/cleanrl:latest \ --command "uv run python cleanrl/ppo_atari.py --env-id BreakoutNoFrameskip-v4 --track --capture_video" \ --job-queue g4dn-xlarge \ --num-seed 1 \ --num-vcpu 1 \ --num-gpu 1 \ --num-memory 4000 \ --num-hours 48.0 \ --provider aws

提交参数速查表

以上命令中的参数均对应 cleanrl_utils/submit_exp.py 中的 argparse 定义：

提交后的效果

作业提交成功后，AWS Batch 控制台会出现对应的作业列表与 EC2 实例（可对照docs/cloud/aws_batch2.png查看实际拉起实例的类型与状态），而 W&B 项目中会同步出现一批CartPole-v1、BreakoutNoFrameskip-v4等任务名的运行记录（见docs/cloud/wandb.png），训练曲线、视频与超参数均可直接在 W&B 仪表盘对比分析。注意训练命令中的--track --capture_video分别负责启用 W&B 跟踪与视频录制。

自定义 Docker 容器

如果官方镜像不满足需求（例如需要安装额外依赖），可以基于仓库根目录的 Dockerfile 自行构建镜像。首先准备 Dockerbuildx并登录镜像仓库：

docker buildx create --use docker login

随后使用--build与--push标志，让submit_exp基于当前目录的 Dockerfile 构建并推送镜像：

uv run python -m cleanrl_utils.submit_exp \ --docker-tag vwxyzjn/cleanrl:latest \ --command "uv run python cleanrl/ppo.py --env-id CartPole-v1 --total-timesteps 100000 --track --capture_video" \ --build --push

对应 cleanrl_utils/submit_exp.py 的实现：构建时执行docker buildx build --output=type=registry（或 type=docker） --platform <archs> -t <docker-tag> .，其中--push决定输出类型是推送 registry 还是仅本地 docker。

构建多架构镜像

要同时支持 ARM 与 X86 架构，使用--archs指定多平台：

uv run python -m cleanrl_utils.submit_exp \ --docker-tag vwxyzjn/cleanrl:latest \ --command "uv run python cleanrl/ppo.py --env-id CartPole-v1 --total-timesteps 100000 --track --capture_video" \ --archs linux/arm64,linux/amd64 \ --build --push

需要注意的取舍（官方文档明确提示）：

• 多架构镜像构建较慢，但可解锁m6gd.medium等 ARM 实例，这类实例通常比 X86 实例便宜 20%-70%；
• 然而目前没有云厂商提供带 Nvidia GPU 的 ARM 实例，因此若实验依赖 GPU，多架构方案的价值有限；
• 若坚持多架构，可以接入一台原生 ARM 服务器加速构建，把它挂到本机buildx实例上：

docker -H ssh://costa@gpu info docker buildx create --name remote --use docker buildx create --name remote --append ssh://costa@gpu docker buildx inspect --bootstrap python -m cleanrl_utils.submit_exp -b --archs linux/arm64,linux/amd64

清理基础设施

实验全部跑完后，删除基础设施同样简单直接：

export AWS_DEFAULT_REGION=$(aws configure get region --profile default) terraform destroy

terraform destroy会按依赖顺序回收cloud/modules/cleanrl/下定义的所有资源——包括按需/Spot 计算环境、作业队列、IAM 角色与安全组。由于未提交作业时计算环境min_vcpus = 0、不占用任何实例，销毁过程通常很快且不会产生额外费用。

小结与延伸阅读

至此，你已经掌握了 CleanRL 云部署的完整闭环：用terraform apply一键拉起 AWS Batch 计算环境与作业队列，用cleanrl_utils.submit_exp把训练命令批量封装为容器作业提交到按需或 Spot 队列，用--build --push定制 Docker 镜像，最后用terraform destroy一键清理。

如果想进一步了解实验提交的更多参数组合与大规模基准测试的组织方式，可继续阅读配套文档 docs/cloud/submit-experiments.md 与仓库根目录的 Dockerfile；benchmark/目录下的各类*.sh脚本（如 benchmark/ppo.sh、benchmark/ppo_atari.sh）也提供了按算法批量提交基准实验的现成范例，可与本文的提交命令对照使用。

【免费下载链接】cleanrlHigh-quality single file implementation of Deep Reinforcement Learning algorithms with research-friendly features (PPO, DQN, C51, DDPG, TD3, SAC, PPG)项目地址: https://gitcode.com/GitHub_Trending/cl/cleanrl