ACT 纯仿真复现教程（Ubuntu + Conda，无真机ALOHA）

文章标签

ACT ALOHA 机器人模仿学习 MuJoCo仿真 Ubuntu Conda 无真机复现 具身智能

文章简介

本文提供一套无ALOHA真实机器人、仅依靠MuJoCo仿真环境 的ACT完整复现流程，适配Ubuntu服务器/本地台式机，全程使用Conda管理Python环境，覆盖系统依赖安装、仓库部署、仿真数据集生成、模型训练、仿真评估、报错排查全流程，完全基于官方仓库 tonyzhaozh/act 内置仿真任务，新手可一键跟着命令复现。

适用场景：实验室远程服务器、无实体机械臂、仅做算法仿真验证、复现ACT论文基线效果。

一、本方案可复现的仿真任务

无真机环境下仅推荐复现两类脚本控制仿真任务，本地脚本可一键自动采集数据集，无需下载外部文件：

sim_transfer_cube_scripted 方块搬运任务（上手最简单，优先跑通）
sim_insertion_scripted 插销插入任务

仓库另外提供两组human人机交互任务：

sim_transfer_cube_human、sim_insertion_human

⚠️ 注意：本地record_sim_episodes.py脚本无法生成human数据集，必须下载官方云端数据才能运行，初次复现不建议尝试。

二、硬件&系统环境要求

基础系统

Ubuntu 20.04 / 22.04 桌面/无头服务器均可

必备工具

已预装 Miniconda / Anaconda（Conda环境管理器）

服务器可联网下载Python依赖、系统库

GPU（可选但强烈推荐）

NVIDIA显卡 + CUDA环境：训练速度大幅提升

无NVIDIA GPU：可使用osmesa纯软件渲染，速度极慢，仅用于调试环境

三、完整分步复现流程

3.1 安装Ubuntu系统底层依赖

MuJoCo、dm_control、OpenGL渲染、视频存储全部依赖以下系统库，先执行安装：

bash 复制代码

sudo apt update
sudo apt install -y \
    git wget unzip ffmpeg patchelf \
    libglfw3 libglew-dev libgl1-mesa-glx libosmesa6

依赖说明：

libglfw3：仿真窗口渲染底层库
libglew-dev：EGL/OpenGL图形接口依赖
libgl1-mesa-glx / libosmesa6：无头服务器软件渲染核心
ffmpeg：训练/评估时生成仿真回放视频

3.2 克隆ACT官方代码仓库

bash 复制代码

git clone https://github.com/tonyzhaozh/act.git
cd act

3.3 Conda环境搭建（推荐方案A，官方yaml一键构建）

仓库提供两种环境安装方式，优先使用conda_env.yaml，版本统一、依赖冲突最少。

方案A：yaml文件一键创建环境（推荐）

bash 复制代码

# 基于官方配置创建aloha虚拟环境
conda env create -f conda_env.yaml
conda activate aloha

# 编译安装detr模块
cd detr
pip install -e .
cd ..

环境自检命令，验证torch、mujoco、dm_control导入正常：

bash 复制代码

python -c "import torch, mujoco, dm_control; print('torch ok'); print('mujoco ok'); print('dm_control ok')"

方案B：手动pip安装（yaml构建失败时备用）

bash 复制代码

conda create -n aloha python=3.8.10 -y
conda activate aloha
pip install torchvision torch pyquaternion pyyaml rospkg pexpect
pip install mujoco==2.3.7 dm_control==1.0.14
pip install opencv-python matplotlib einops packaging h5py ipython
cd detr
pip install -e .
cd ..

重要提醒：两套安装方式不要混合执行，选一种完整走完，否则版本冲突会持续报错。

3.4 无头服务器配置MuJoCo渲染后端（必做）

远程无显示器服务器、云服务器必须指定渲染方式，否则OpenGL直接崩溃。

有NVIDIA显卡（推荐EGL）

临时生效（当前终端）：

bash 复制代码

export MUJOCO_GL=egl

永久写入环境变量：

bash 复制代码

echo 'export MUJOCO_GL=egl' >> ~/.bashrc
source ~/.bashrc

无NVIDIA显卡/EGL报错（切换软件渲染osmesa）

临时生效：

bash 复制代码

export MUJOCO_GL=osmesa

永久写入：

bash 复制代码

echo 'export MUJOCO_GL=osmesa' >> ~/.bashrc
source ~/.bashrc

3.5 环境最小自检

渲染配置完成后先执行导入测试，出现图形相关报错先解决渲染问题，不要直接训练：

bash 复制代码

python -c "import mujoco; import dm_control; print('imports ok')"

3.6 仿真数据集准备（两种方式，方式1优先）

方式1：本地脚本自动生成数据集（最稳，无网络依赖）

创建数据存储根目录：

bash 复制代码

mkdir -p ~/act_data/sim_transfer_cube_scripted
mkdir -p ~/act_data/sim_insertion_scripted

生成方块搬运数据集（50条轨迹）：

bash 复制代码

python record_sim_episodes.py \
  --task_name sim_transfer_cube_scripted \
  --dataset_dir ~/act_data/sim_transfer_cube_scripted \
  --num_episodes 50

生成插入任务数据集（50条轨迹）：

bash 复制代码

python record_sim_episodes.py \
  --task_name sim_insertion_scripted \
  --dataset_dir ~/act_data/sim_insertion_scripted \
  --num_episodes 50

参数补充：本地台式机带显示器可加 --onscreen_render 实时看仿真画面；服务器无头环境禁止添加该参数。

方式2：下载官方Human仿真数据集（备用）

官方谷歌云盘数据集地址：

https://drive.google.com/drive/folders/1gPR03v05S1xiInoVJn7G7VJ9pDCnxq9O?usp=share_link

命令行下载工具：

bash 复制代码

pip install gdown
gdown --folder https://drive.google.com/drive/folders/1gPR03v05S1xiInoVJn7G7VJ9pDCnxq9O?usp=share_link

下载完成后目录规范：

复制代码

~/act_data/
├── sim_transfer_cube_scripted/
│   ├── episode_0.hdf5
│   ├── episode_1.hdf5
├── sim_insertion_scripted/
├── sim_transfer_cube_human/
└── sim_insertion_human/

3.7 修改全局数据路径 constants.py

仓库根目录constants.py存在默认占位路径，必须修改，否则训练找不到数据集：

原代码：

python 复制代码

DATA_DIR = '<put your data dir here>'

修改为你的本地数据根目录（替换用户名）：

python 复制代码

DATA_DIR = '/home/你的用户名/act_data'

3.8 数据集可视化校验

生成/下载数据后，可视化单条轨迹，校验HDF5文件完整性：

bash 复制代码

python visualize_episodes.py \
  --dataset_dir ~/act_data/sim_transfer_cube_scripted \
  --episode_idx 0

运行成功会在数据集目录生成回放视频episode_0_video.mp4与轨迹曲线图，代表数据无损坏。

3.9 ACT模型训练

训练方块搬运任务 sim_transfer_cube_scripted

bash 复制代码

mkdir -p ~/act_ckpts/transfer_cube_act

python imitate_episodes.py \
  --task_name sim_transfer_cube_scripted \
  --ckpt_dir ~/act_ckpts/transfer_cube_act \
  --policy_class ACT \
  --kl_weight 10 \
  --chunk_size 100 \
  --hidden_dim 512 \
  --batch_size 8 \
  --dim_feedforward 3200 \
  --num_epochs 2000 \
  --lr 1e-5 \
  --seed 0

训练插销插入任务 sim_insertion_scripted

bash 复制代码

mkdir -p ~/act_ckpts/insertion_act

python imitate_episodes.py \
  --task_name sim_insertion_scripted \
  --ckpt_dir ~/act_ckpts/insertion_act \
  --policy_class ACT \
  --kl_weight 10 \
  --chunk_size 100 \
  --hidden_dim 512 \
  --batch_size 8 \
  --dim_feedforward 3200 \
  --num_epochs 2000 \
  --lr 1e-5 \
  --seed 0

参数说明：全部为官方默认超参，初次复现不建议修改。

3.10 仿真模型评估

训练完成后，在训练命令末尾添加--eval开启仿真rollout评估：

bash 复制代码

python imitate_episodes.py \
  --task_name sim_transfer_cube_scripted \
  --ckpt_dir ~/act_ckpts/transfer_cube_act \
  --policy_class ACT \
  --kl_weight 10 \
  --chunk_size 100 \
  --hidden_dim 512 \
  --batch_size 8 \
  --dim_feedforward 3200 \
  --num_epochs 2000 \
  --lr 1e-5 \
  --seed 0 \
  --eval

开启时序聚合策略（提升评估成功率）追加参数 --temporal_agg

评估逻辑：自动读取最优权重与dataset_stats.pkl，在ckpt文件夹生成仿真执行视频。

四、预期仿真基线效果

官方仿真环境经验成功率（随机种子、硬件不同会小幅波动）：

sim_transfer_cube_scripted 方块搬运：约90%任务成功率
sim_insertion_scripted 插销插入：约50%任务成功率

五、高频报错与解决方案

1. FileNotFoundError 找不到数据集

排查顺序：

constants.py 的 DATA_DIR 是否修改为真实路径
文件夹名称与task_name完全匹配，无拼写错误
文件夹内存在episode_*.hdf5数据文件

2. OpenGL / EGL / GLFW 渲染崩溃

无头服务器优先执行 export MUJOCO_GL=egl
NVIDIA显卡异常切换 export MUJOCO_GL=osmesa 软件渲染
确认系统依赖 libosmesa6、libglfw3 已完整安装

3. 添加--onscreen_render直接程序闪退

服务器无桌面显示设备，删除该参数，仅本地台式机可使用实时画面渲染。

4. human数据集无法运行

本地采集脚本不支持生成human交互数据，必须下载谷歌云盘官方数据集。

5. 训练正常、评估任务成功率极低

训练、评估task_name保持完全一致
评估使用和训练同一ckpt_dir权重文件夹
检查权重目录中dataset_stats.pkl未被误删
确认数据集路径无大小写、字符拼写错误

六、最简复现执行顺序（推荐新手流程）

安装Ubuntu系统底层依赖
conda_env.yaml一键构建aloha环境，编译detr
配置MUJOCO_GL渲染后端
本地生成sim_transfer_cube_scripted数据集
visualize_episodes.py校验数据文件
启动ACT模型训练
--eval执行仿真评估
流程跑通后再尝试sim_insertion_scripted任务

七、一键复制完整最小命令流

适合新建服务器快速验证环境是否全部通畅：

bash 复制代码

git clone https://github.com/tonyzhaozh/act.git
cd act

sudo apt update
sudo apt install -y \
    git wget unzip ffmpeg patchelf \
    libglfw3 libglew-dev libgl1-mesa-glx libosmesa6

conda env create -f conda_env.yaml
conda activate aloha

cd detr
pip install -e .
cd ..

export MUJOCO_GL=egl

mkdir -p ~/act_data/sim_transfer_cube_scripted

python record_sim_episodes.py \
  --task_name sim_transfer_cube_scripted \
  --dataset_dir ~/act_data/sim_transfer_cube_scripted \
  --num_episodes 50

# 此处手动修改constants.py中DATA_DIR = "/home/你的用户名/act_data"

python visualize_episodes.py \
  --dataset_dir ~/act_data/sim_transfer_cube_scripted \
  --episode_idx 0

mkdir -p ~/act_ckpts/transfer_cube_act

python imitate_episodes.py \
  --task_name sim_transfer_cube_scripted \
  --ckpt_dir ~/act_ckpts/transfer_cube_act \
  --policy_class ACT \
  --kl_weight 10 \
  --chunk_size 100 \
  --hidden_dim 512 \
  --batch_size 8 \
  --dim_feedforward 3200 \
  --num_epochs 2000 \
  --lr 1e-5 \
  --seed 0

八、参考资料

ACT官方代码仓库：https://github.com/tonyzhaozh/act
ALOHA项目主页：https://tonyzhaozh.github.io/aloha/
MuJoCo Python官方文档：https://mujoco.readthedocs.io/en/stable/python.html
dm_control仓库（渲染配置说明）：https://github.com/google-deepmind/dm_control

九、复现优化建议

如果仅目标为跑通ACT算法基线，不建议一开始就折腾human数据集、真机机械臂接口，最优路线：

优先复现sim_transfer_cube_scripted简单搬运任务
完整跑通训练+仿真评估流程，验证环境、数据、模型链路无问题
再拓展难度更高的sim_insertion_scripted插入任务
最后按需下载human交互数据集做对比实验

该流程分层验证，能快速区分报错来源是环境、数据集还是模型算法，大幅节约调试时间。