ACT模仿学习 安装与部署：环境、数据格式与训练启动
二、安装与部署：环境、数据格式与训练启动
ACT 的官方实现是 Python 项目，训练依赖 PyTorch。安装本身不复杂，真正的成本在数据格式对齐与显存规划上。
- 创建 Python 环境。ACT 的训练脚本对 Python 与 PyTorch 版本有一定要求，建议按仓库 README 注明版本创建：
conda create -n act python=3.10 -y conda activate act - 安装 PyTorch。按显卡情况选择 CUDA 版本，命令以 PyTorch 官网当前给出的为准：
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121 - 拉取代码并安装依赖。仓库根目录下通常有
conda_env.yaml或requirements.txt：git clone https://github.com/tonyzhaoshi/learning-from-human-demonstrations.git cd learning-from-human-demonstrations pip install -r requirements.txt - 准备演示数据。官方示例数据以 HDF5 组织，每条演示一个文件，文件内至少包含观测图像与关节位置两组字段。典型结构如下：
数据字段命名必须与代码里的读取逻辑一致，改名会导致训练时报键不存在的错误。episode_0.hdf5 /observations/images/cam_high # 全局相机图像序列 /observations/images/cam_wrist # 腕部相机图像序列 /observations/qpos # 关节位置与夹爪状态 /action # 期望动作序列 - 确认任务与数据目录的对应关系。训练脚本通过
--task_name找数据，通过--ckpt_dir决定权重保存位置，两者都要与目录结构对齐：mkdir -p data/sim_transfer_cube_scripted ckpt/act_demo - 启动训练。下面是一条典型的 ACT 训练命令，参数含义在后文表格里展开：
python imitate_episodes.py \ --task_name sim_transfer_cube_scripted \ --ckpt_dir ckpt/act_demo \ --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 - 评估。评估时
--policy_class与--chunk_size等结构参数必须与训练时一致，否则加载权重会因形状不匹配而失败。评估模式要显式加--eval：python imitate_episodes.py \ --task_name sim_transfer_cube_scripted \ --ckpt_dir ckpt/act_demo \ --policy_class ACT \ --kl_weight 10 --chunk_size 100 --hidden_dim 512 \ --dim_feedforward 3200 --batch_size 8 \ --eval --temporal_agg
常见报错与排查。
| 报错现象 | 根因 | 处理方式 |
|---|---|---|
| 读取数据时报键不存在 | HDF5 内的字段路径与代码不一致 | 用 h5ls -r 打印真实结构，对齐字段名 |
CUDA out of memory | batch size 或图像分辨率过大 | 下调 batch size；必要时降低输入图像分辨率 |
| 评估时权重加载失败，形状不匹配 | 评估参数与训练参数不一致 | 核对 chunk_size hidden_dim dim_feedforward |
| 训练 loss 一直在 0 附近不动 | KL 权重过大，隐变量退化为常数 | 适当下调 kl_weight |
| 动作整体幅度偏大或偏小 | 动作归一化的统计量不一致 | 用同一份统计量做训练与推理的归一化 |
| 机器人在目标附近高频抖动 | 隐变量采样噪声过大，或未开启时间集成 | 开启 --temporal_agg，或降低采样随机性 |
| 图像通道或色彩空间不对导致效果差 | 训练与推理的图像预处理不一致 | 把预处理写死在流水线里，避免两处各写一份 |
| 显存够但训练极慢 | 数据加载成为瓶颈 | 把数据放本地 SSD，提高 DataLoader 工作进程数 |
硬件方面，ACT 的采集通常用主从臂：人拖动主臂，从臂跟随并记录自身关节位置与动作。相机一般是两路或多路，一路看全局、一路看腕部特写。这里有一条重要经验：训练时的相机位置、数量、视野，与推理时必须完全一致。少一路相机、相机挪了位置、视野被遮挡，模型的表现都会明显下降，因为它是从固定视角的图像分布里学出来的。
