软学习

软学习是一个用于在连续域中训练最大熵策略的深度强化学习工具箱。该实现较为精简，主要为我们自身的开发目的而优化。它使用 tf.keras 模块来实现大多数模型类（例如策略和价值函数）。我们使用 Ray 进行实验编排。Ray Tune 和 Autoscaler 实现了多项便捷功能，使我们能够无缝地将本地原型设计时使用的实验脚本部署到任何选定的云服务（如 GCP 或 AWS）上，以运行大规模实验，并智能地并行化和分布式训练，从而实现高效的资源分配。

此实现使用 TensorFlow。若需 PyTorch 版本的软演员-评论家算法，请参阅 rlkit。

入门指南

前置条件

该环境既可以在本地通过 Conda 运行，也可以在 Docker 容器内运行。对于 Conda 安装，您需要先安装 Conda。对于 Docker 安装，您需要安装 Docker 和 Docker Compose。此外，目前我们的大多数环境都需要 MuJoCo 许可证。

Conda 安装

1. 从 MuJoCo 官网 下载 并安装 MuJoCo 1.50 和 2.00。我们假设 MuJoCo 文件已解压到默认位置（~/.mujoco/mjpro150 和 ~/.mujoco/mujoco200_{platform}）。遗憾的是，gym 和 dm_control 对 MuJoCo 2.00 的安装路径要求不同，因此您需要同时将其安装在 ~/.mujoco/mujoco200_{platform} 和 ~/.mujoco/mujoco200 目录下。最简单的方法是创建一个符号链接：ln -s ~/.mujoco/mujoco200_{plaftorm} ~/.mujoco/mujoco200。

2. 将您的 MuJoCo 许可证密钥文件（mjkey.txt）复制到 ~/.mujoco/mjkey.txt：

3. 克隆 softlearning：

git clone https://github.com/rail-berkeley/softlearning.git ${SOFTLEARNING_PATH}

4. 创建并激活 Conda 环境，安装 softlearning 以启用命令行界面。

cd ${SOFTLEARNING_PATH}
conda env create -f environment.yml
conda activate softlearning
pip install -e ${SOFTLEARNING_PATH}

至此，环境应已准备就绪。请参阅“示例”部分，了解如何训练和模拟智能体的示例。

最后，要停用并移除 Conda 环境：

conda deactivate
conda remove --name softlearning --all

Docker 安装

docker-compose

构建镜像并运行容器：

export MJKEY="$(cat ~/.mujoco/mjkey.txt)" \
    && docker-compose \
        -f ./docker/docker-compose.dev.cpu.yml \
        up \
        -d \
        --force-recreate

您可以使用标准的 Docker exec 命令进入容器，例如：

docker exec -it softlearning bash

请参阅“示例”部分，了解如何训练和模拟智能体的示例。

最后，清理 Docker 设置：

docker-compose \
    -f ./docker/docker-compose.dev.cpu.yml \
    down \
    --rmi all \
    --volumes

示例

训练与模拟智能体

1. 训练智能体：

softlearning run_example_local examples.development \
    --algorithm SAC \
    --universe gym \
    --domain HalfCheetah \
    --task v3 \
    --exp-name my-sac-experiment-1 \
    --checkpoint-frequency 1000  # 每1000步保存一次检查点，以便后续恢复训练

2. 模拟得到的策略： 首先，找到检查点保存的绝对路径。默认情况下（即未指定 log-dir 参数时），数据会保存在 ~/ray_results/<universe>/<domain>/<task>/<datatimestamp>-<exp-name>/<trial-id>/<checkpoint-id> 目录下。例如：~/ray_results/gym/HalfCheetah/v3/2018-12-12T16-48-37-my-sac-experiment-1-0/mujoco-runner_0_seed=7585_2018-12-12_16-48-37xuadh9vd/checkpoint_1000/。接下来的命令假设该路径已通过环境变量 ${SAC_CHECKPOINT_DIR} 获取。

python -m examples.development.simulate_policy \
    ${SAC_CHECKPOINT_DIR} \
    --max-path-length 1000 \
    --num-rollouts 1 \
    --render-kwargs '{"mode": "human"}'

examples.development.main 包含多个不同的环境，并且 /examples 文件夹中还有更多示例脚本。如需了解更多关于智能体和配置的信息，可在运行脚本时添加 --help 标志：python ./examples/development/main.py --help。

可选参数：
  -h, --help            显示帮助信息并退出
  --universe {robosuite,dm_control,gym}
  --domain DOMAIN
  --task TASK
  --checkpoint-replay-pool CHECKPOINT_REPLAY_POOL
                        是否将回放缓冲区一同保存为检查点。若设置，则优先于 variant['run_params']['checkpoint_replay_pool']。请注意，回放缓冲区是逐步保存（并构建）的，因此每条经验仅被保存一次。
  --algorithm ALGORITHM
  --policy {gaussian}
  --exp-name EXP_NAME
  --mode MODE
  --run-eagerly RUN_EAGERLY
                        是否以 eager 模式运行 TensorFlow。
  --local-dir LOCAL_DIR
                        用于保存训练结果的本地目标文件夹。
  --confirm-remote [CONFIRM_REMOTE]
                        远程运行时是否提示确认。
  --video-save-frequency VIDEO_SAVE_FREQUENCY
                        视频保存频率。
  --cpus CPUS           分配给 Ray 进程的 CPU 数量。传递给 `ray.init`。
  --gpus GPUS           分配给 Ray 进程的 GPU 数量。传递给 `ray.init`。
  --resources RESOURCES
                        分配给 Ray 进程的资源。传递给 `ray.init`。
  --include-webui INCLUDE_WEBUI
                        布尔标志，指示是否启动 Web UI（即 Jupyter Notebook）。传递给 `ray.init`。
  --temp-dir TEMP_DIR   若提供，则指定 Ray 进程的根临时目录。传递给 `ray.init`。
  --resources-per-trial RESOURCES_PER_TRIAL
                        每次试验分配的资源。传递给 `tune.run`。
  --trial-cpus TRIAL_CPUS
                        每次试验分配的 CPU 数量。注意：这仅用于 Ray 的内部调度管理，而非实际的 CPU 硬性限制。传递给 `tune.run`。
  --trial-gpus TRIAL_GPUS
                        每次试验分配的 GPU 数量。同样，这仅用于 Ray 的内部调度管理，而非实际的 GPU 硬性限制。传递给 `tune.run`。
  --trial-extra-cpus TRIAL_EXTRA_CPUS
                        预留的额外 CPU，以备试验需要启动使用 CPU 的其他 Ray Actor 时使用。
  --trial-extra-gpus TRIAL_EXTRA_GPUS
                        预留的额外 GPU，以备试验需要启动使用 GPU 的其他 Ray Actor 时使用。
  --num-samples NUM_SAMPLES
                        每次试验重复执行的次数。传递给 `tune.run`。
  --upload-dir UPLOAD_DIR
                        可选的 URI 地址，用于将训练结果同步到远程存储（例如 s3://<bucket> 或 gs://<bucket>)。传递给 `tune.run`。
  --trial-name-template TRIAL_NAME_TEMPLATE
                        试验名称的可选模板字符串。例如：'{trial.trial_id}-seed={trial.config[run_params][seed]}'。传递给 `tune.run`。
  --checkpoint-frequency CHECKPOINT_FREQUENCY
                        检查点之间的训练迭代次数。值为 0（默认）时表示禁用检查点保存。若设置，则优先于 variant['run_params']['checkpoint_frequency']。传递给 `tune.run`。
  --checkpoint-at-end CHECKPOINT_AT_END
                        是否在实验结束时保存检查点。若设置，则优先于 variant['run_params']['checkpoint_at_end']。传递给 `tune.run`。
  --max-failures MAX_FAILURES
                        尝试从上次检查点恢复试验的最大次数。仅在启用检查点保存时生效。传递给 `tune.run`。
  --restore RESTORE     检查点路径。仅在运行单个试验时有意义。默认为 None。传递给 `tune.run`。
  --server-port SERVER_PORT
                        用于启动 TuneServer 的端口号。传递给 `tune.run`。

从已保存的检查点恢复训练

此功能目前存在缺陷！

要从之前的检查点恢复训练，需运行原始示例主脚本，并添加 --restore 标志。例如，可以按如下方式恢复之前的示例：

softlearning run_example_local examples.development \
    --algorithm SAC \
    --universe gym \
    --domain HalfCheetah \
    --task v3 \
    --exp-name my-sac-experiment-1 \
    --checkpoint-frequency 1000 \
    --restore ${SAC_CHECKPOINT_PATH}

参考文献

这些算法基于以下论文：

软演员-评论家算法及其应用。
图奥马斯·哈尔诺亚*、奥里克·周*、克里斯蒂安·哈蒂凯宁*、乔治·塔克尔、世勋·哈、杰·谭、维卡什·库马尔、亨利·朱、阿比谢克·古普塔、皮特·阿贝尔和谢尔盖·列文。 arXiv 预印本，2018年。
论文 | 视频

用于层次强化学习的潜在空间策略。
图奥马斯·哈尔诺亚*、克里斯蒂安·哈蒂凯宁*、皮特·阿贝尔和谢尔盖·列文。 国际机器学习会议（ICML），2018年。
论文 | 视频

软演员-评论家：带有随机演员的离策略最大熵深度强化学习。
图奥马斯·哈尔诺亚、奥里克·周、皮特·阿贝尔和谢尔盖·列文。 国际机器学习会议（ICML），2018年。
论文 | 视频

用于机器人操作的可组合深度强化学习。
图奥马斯·哈尔诺亚、维奇尔·庞格、奥里克·周、穆尔塔扎·达拉尔、皮特·阿贝尔、谢尔盖·列文。 国际机器人与自动化会议（ICRA），2018年。
论文 | 视频

基于深度能量函数策略的强化学习。
图奥马斯·哈尔诺亚*、唐浩然*、皮特·阿贝尔、谢尔盖·列文。 国际机器学习会议（ICML），2017年。
论文 | 视频

如果 Softlearning 对您的学术研究有所帮助，请您引用我们的论文。以下是一个 BibTeX 示例：

@techreport{haarnoja2018sacapps,
  title={Soft Actor-Critic Algorithms and Applications},
  author={Tuomas Haarnoja and Aurick Zhou and Kristian Hartikainen and George Tucker and Sehoon Ha and Jie Tan and Vikash Kumar and Henry Zhu and Abhishek Gupta and Pieter Abbeel and Sergey Levine},
  journal={arXiv preprint arXiv:1812.05905},
  year={2018}
}

Softlearning 快速上手指南

Softlearning 是一个用于在连续域中训练最大熵策略的深度强化学习工具箱，基于 TensorFlow 和 Ray 构建，核心算法为软演员 - 评论家（SAC）。

环境准备

系统要求

• 操作系统: Linux 或 macOS (Windows 需通过 WSL 或 Docker)
• Python: 推荐通过 Conda 管理环境
• 依赖工具:
  • Conda (推荐) 或 Docker
  • MuJoCo: 大多数环境需要 MuJoCo 1.50 和 2.00 的许可证。

前置依赖配置

在使用前，请确保已下载并安装 MuJoCo，并配置好许可证密钥：

1. 下载 MuJoCo 1.50 和 2.00 并解压到默认位置 (~/.mujoco/mjpro150 和 ~/.mujoco/mujoco200_{platform})。
2. 由于 gym 和 dm_control 对路径要求不同，需创建软链接：

   ln -s ~/.mujoco/mujoco200_{platform} ~/.mujoco/mujoco200
   

3. 将许可证文件 mjkey.txt 复制到 ~/.mujoco/mjkey.txt。

提示：国内用户若下载 MuJoCo 困难，可尝试寻找国内镜像源或联系社区获取资源。

安装步骤

推荐使用 Conda 方式进行安装，以便更好地管理依赖。

方法一：Conda 安装（推荐）

1. 克隆仓库

   git clone https://github.com/rail-berkeley/softlearning.git ${SOFTLEARNING_PATH}
   cd ${SOFTLEARNING_PATH}
   

2. 创建并激活环境

   conda env create -f environment.yml
   conda activate softlearning
   

3. 安装工具包 以可编辑模式安装，以便启用命令行接口：

   pip install -e ${SOFTLEARNING_PATH}
   

方法二：Docker 安装

如果你偏好容器化部署，可以使用 docker-compose：

export MJKEY="$(cat ~/.mujoco/mjkey.txt)" \
    && docker-compose \
        -f ./docker/docker-compose.dev.cpu.yml \
        up \
        -d \
        --force-recreate

进入容器：

docker exec -it softlearning bash

基本使用

安装完成后，你可以立即开始训练智能体。以下是在 Gym 环境的 HalfCheetah 任务上训练 SAC 算法的最简示例。

1. 训练智能体

运行以下命令开始训练，并设置每 1000 次迭代保存一次检查点：

softlearning run_example_local examples.development \
    --algorithm SAC \
    --universe gym \
    --domain HalfCheetah \
    --task v3 \
    --exp-name my-sac-experiment-1 \
    --checkpoint-frequency 1000

注：训练结果默认保存在 ~/ray_results/ 目录下。

2. 模拟策略（可视化）

训练完成后，找到生成的检查点绝对路径（例如：~/ray_results/gym/HalfCheetah/v3/.../checkpoint_1000/），将其赋值给环境变量 ${SAC_CHECKPOINT_DIR}，然后运行：

python -m examples.development.simulate_policy \
    ${SAC_CHECKPOINT_DIR} \
    --max-path-length 1000 \
    --num-rollouts 1 \
    --render-kwargs '{"mode": "human"}'

这将弹出一个窗口展示训练好的智能体在环境中的表现。

更多选项

查看完整的参数配置帮助信息：

python ./examples/development/main.py --help

支持指定 GPU/CPU 资源、上传结果到云存储（S3/GCS）、调整采样次数等高级功能。