数据整理与 ACT 模型训练

00课程节奏：五星学习法 · 8 段微课（每段 ≤ 15 min）

本实验按五星学习法组织：先用一个真实故障聚焦问题，再激活旧知（CNN、Transformer、损失函数、VAE），接着示证新知（ACT 的 CNN+Transformer+CVAE 三段结构），然后动手应用新知完成数据整理与训练并读懂日志，最后借排障与超参方法论融会贯通。全程切成 8 段微课、每段不超过 15 分钟，段间停顿 1~2 分钟消化；纯讲授合计约 100 分钟，其余课时用于动手实操与个别辅导。

讲课提示：课段 1/2 以讲授 + 提问为主；课段 3~4 用源码 + 动画；课段 5~6 边讲边演命令行与日志；课段 7 学员独立完成；课段 8 答疑拔高。段间停顿 1~2 分钟。

01实验目标课段 1 · 聚焦问题 · 12 min

02核心原理：ACT 是怎样"学会"一个任务的课段 1 收尾 + 课段 2 · 激活旧知 · 8 min

通俗类比：学做饭时，你一边看食材和锅（图像 / 状态），一边在脑中"放映"老师连贯的切炒动作（示范数据），越看越多就形成了"看到这一步 → 手直接这样做"的肌肉记忆。ACT 就是这套肌肉记忆的数学版，分三步走：

① CNN 编码器（看）——每张摄像头图像过一个预训练 ResNet18（ResNet18_Weights.IMAGENET1K_V1），压成一串特征向量；机器人 6 维关节状态也一起拼进去。相当于把"锅里的画面"压缩成大脑能处理的重点信息。

② Transformer 编码器-解码器（想）——编码器 4 层、解码器 1 层，维度 512、8 头注意力、前馈 3200。关键创新是 动作分块（action chunking）：模型不是一次预测一步，而是一次吐出未来 chunk_size=100 步的动作序列，避免"走一步看一步"导致的抖动与误差累积。

③ CVAE（造多样性的手）——同一个场景，人示范的动作也会有细微差异。CVAE 在训练时往瓶颈层 latent_dim=32 塞一个随机变量 z，强迫模型学会"同场景不同微动作都合理"；损失函数就是指导文件中的核心公式：loss = reconstruction_loss + kl_weight × kld_loss（kl_weight=10）。重建损失管"像不像示范"，KL 损失管"随机变量像不像标准正态"——一个像老师，一个保持即兴的自由度。

自回归 vs 并行：自回归模型（如 GPT 式输出、某些扩散策略）一 token 一 token 地续写动作，序列长了慢；ACT 借解码器一次性并行输出整段动作块，推理快、适合真机实时控制。代价是长程依赖表达弱——两条路线的取舍在 EXP-04 会再次遇到。

03环境与材料课段 3 · 示证新知 · 15 min

• ✓EXP-01 产出的可用数据集（示例：liming/put_cube_plate，num_episodes ≥ 3，正式建议 ≥ 50）
• ✓训练机 LeRobot 0.4.1 + CUDA 可用 GPU（日志 policy.device=cuda）
• ✓源码参考：lerobot-0.4.1/src/lerobot/policies/act/（modeling_act.py、configuration_act.py）与 docs/source/act.mdx
• ✓脚本参考：command/5_train.sh（含数据集命名与 SAVE_FREQ 分段保存逻辑）
• ✓监控工具：终端日志（log_freq=100）+ nvtop 看 GPU 占用
• ✓输出目录：./outputs/put_cube_on_plate_act（每次实验前 rm -rf 清空，避免新旧日志混淆）
• ✓时间口径：命令行 steps=1000 是最小示例，指导文档示例日志跑到 step 5000，正式训练按 ≥5000 步准备
• ✓对照基线：指导文档示例日志起始量级为 loss:8.088、grdn≈10（见 §8 表）——换数据集后绝对值不同属正常，只比下降趋势

04实操步骤课段 5~6 · 应用新知 · 2×15 min

整条链路按"看数据 → 打包（可选）→ 清输出 → 起训练 → 盯日志 → 收检查点"六步推进，每步都有可核验的产出物：

05关键命令随课段 5 / 6 对照使用

四段命令依次完成"数据就位 → 启动训练 → 读日志 → 看卡"，参数均取自第 10 章原文：

# ── 1) 查看与打包数据（第 10 章）
cd ~/.cache/huggingface/lerobot/liming/put_cube_plate/
zip -r put_cube_plate.zip ~/.cache/huggingface/lerobot/liming/put_cube_plate

# ── 2) ACT 训练（第 10 章原文命令）
rm -rf /home/lz-xl01/lerobot-0.4.1/outputs/put_cube_on_plate_act
lerobot-train --dataset.repo_id=liming/put_cube_plate --policy.type=act --policy.repo_id=put_cube_on_plate_act --policy.push_to_hub=false --batch_size=8 --steps=1000 --output_dir=./outputs/put_cube_on_plate_act --policy.device=cuda --num_workers=4 --wandb.enable=false --log_freq=100 --save_freq=1000 --eval_freq=1000

# ── 3) 健康日志长这样（step 涨、loss 降）
step:100 smpl:3K ep:7 epch:2.23 loss:8.088 grdn:133.488 lr:1.0e-05 updt_s:0.969 data_s:0.048
… loss 持续下降 → Checkpoint policy after step 5000 → End of training

# ── 4) GPU 监控
nvtop

• ✓grdn（梯度范数）：受 grad_clip_norm=10.0 约束，长期贴着 10 说明学习不稳定。
• ✓lr：1e-5 AdamW，随调度缓慢变化；data_s 是取数耗时，持续偏大要减 num_workers 或查 IO。
• ✓epch：数据集小的时候很快 >10 是正常现象，关注 loss 而非 epoch。
• ✓smpl：已消耗的样本计数（3K = 3072），配合 step 判断数据吞吐是否正常。
• ✓updt_s：单步更新耗时，突然变大先查是否有别的进程抢 GPU。

06动画演示：ACT 编码器-解码器（CNN + Transformer + CVAE）课段 4 · 示证新知 · 12 min

把三段连起来读：看（CNN）→ 想（Transformer）→ 带一点即兴（CVAE）→ 连贯出手（chunk）。训练就是不断微调这三段的权重，让输出的动作块在"重建损失 + KL 损失"的合力下越来越像人类示范。

07互动练习：超参滑杆看训练曲线模拟课段 7 · 应用新知 · 10 min

说明：曲线为教学模拟，用于建立"lr / batch / steps 与收敛形态"的直觉；真实曲线以终端 loss 日志为准。

08常见问题课段 8 · 融会贯通 · 13 min

• ✓显存不足（OOM / CUDA out of memory）：优先降 batch_size（8 → 4），再关无关程序、确认没有别的训练占卡（nvtop）。
• ✓数据集读不到 / episode 数为 0：检查 --dataset.repo_id 是否与缓存目录名一致（liming/put_cube_plate）、上一实验是否留下空目录（先 rm -rf 重建）。
• ✓loss 不降：看 lr 是否被改大、数据是否其实是 reset 期垃圾片段、steps 是否太短（< 1000 看不出趋势）。
• ✓data_s 持续很大：磁盘慢或 num_workers 过高，调回 4 或把数据集移到本机 SSD。
• ✓找不到检查点：确认 --output_dir 与 save_freq，最终应有 checkpoints/last/pretrained_model（含 config.json、weights、processor）。
• ✓磁盘被检查点写满：分段检查点按 save_freq 持续累积，跑长训练前先看剩余空间，旧实验的 output 目录及时归档清理。

09拓展阅读课段 8 · 融会贯通

10思考题课段 8 · 融会贯通