1. 复现之前先把“复现目标”说清楚最近一直在折腾 lerobot 这个开源机器人学习框架的复现从环境搭建到训练出自己的一个模仿学习策略整个过程踩了不少坑也把很多文档里没写明白的细节摸清楚了。如果你正准备复现这个项目或者你只是想看看现在机器人操作策略训练到底怎么跑通这篇东西应该能帮你省下至少一周的调研时间。先说说 lerobot 到底是干嘛的。它本质上是一套面向机器人操作学习的训练和评估工具链核心是把模仿学习、强化学习里的主流算法比如扩散策略、ACT、VQ-BeT 等集成到一个统一框架里让研究者可以在仿真环境或者真实机器人上采集数据、训练策略、评估效果。复现它其实就是把官方给出的示例流程在自己的机器上完整跑一遍从环境配置、数据准备、模型训练到最终看到策略能控制机器人完成某个具体操作。在动手之前我强烈建议你先想清楚一个问题你要的“复现”是哪一种我身边不少人是看了论文或视频之后热血上头直接下载代码开始跑结果卡在环境依赖或者数据集下载上最后不了了之。我根据自己的实践把复现目标分成三类目标 A能跑通官方示例。这要求最低主要目的是理解整个流程怎么流转结果是否达到论文展示的效果其实不重要。目标 B换到自己的数据/场景上训练出新策略。这个你需要在数据采集、标注、训练配置上多花精力对硬件和实验设计也有更高要求。目标 C二次开发或接入自家机器人平台。这个就不仅仅是复现了还要理解源码中的传感器接口、策略推理逻辑、坐标变换等内部机制工作量最大。目标不同后面每一步的做法和容错标准都不一样。比如目标 A 的话你用普通的游戏显卡勉强也能跑最多慢一些目标 C 的话你可能需要先在仿真环境里把逻辑吃透再考虑真实硬件。硬件这块我直接说结论复现的瓶颈通常在显存和存储而不是 CPU。lerobot 默认采用的扩散策略在训练时会同时加载图像观测、关节状态和动作序列batch size 稍微调大一点显存占用就往上蹿。官方推荐的 GPU 显存不低于 8GB但我实测下来如果不想频繁调整 batch size12GB 以上会更从容。存储方面单个仿真数据集动辄几十 GB真实机器人采集的数据更大所以你需要留出至少 200GB 的可用磁盘空间并且最好是 SSD否则数据加载会成为瓶颈。对绝大多数人来说最稳妥的复现路线是先在仿真环境里跑通再考虑真实机器人。原因有两个一是仿真环境的数据获取成本低你可以脚本化地批量生成训练数据二是仿真出问题时定位更方便摄像头、机械臂的状态都能可视化查看不用对着真实硬件束手无策。1.1 lerobot 的核心组件与工作流程lerobot 的代码结构不算复杂但刚开始容易看得眼花缭乱。我用一个不太严谨但很好理解的类比它像一个“机器人训练车间”。车间里有四个核心工位——数据仓库、模型库、训练流水线、评估与控制接口。数据仓库负责管理各种格式的演示数据官方会提供一个命令行工具把原始数据转换成统一的存储格式模型库里预置了多个策略网络结构你不需要自己从零写模型训练流水线封装了数据加载、batch 采样、损失计算和日志记录评估与控制接口则负责把训练好的策略部署到仿真环境或真实机器人上让模型输出动作指令去驱动机器人完成目标。整个工作流程是先准备数据下载或自己采集然后定义实验配置哪套模型、什么训练参数启动训练最后加载训练好的 checkpoint 做评估和部署。复现的核心就是把这个链路完整走通理解每一步的数据流转和接口约定。1.2 版本选择比你想的重要我复现时最头大的不是算法而是版本兼容问题。lerobot 对 Python、PyTorch、CUDA 的版本组合比较敏感。官方文档会给出建议版本但如果你照着“最新版”盲目安装极大概率会碰到冲突。下面这个表格是我整理过的一套相对稳定的组合供参考组件推荐版本备注Python3.103.11 及以上有些依赖没跟上CUDA11.8 或 12.1需与 PyTorch 匹配PyTorch2.1.x2.2 以上部分算子兼容性有变操作系统Ubuntu 20.04 / 22.04Windows 也可以跑但仿真可视化体验差一些主要依赖以官方 requirements 为准不要轻易升级小版本特别提醒PyTorch 版本和 CUDA 版本的匹配关系一定要先确认好不要先装了 PyTorch 再回头纠结 CUDA。稳妥的做法是先装好 CUDA 驱动然后用pip install torch安装对应的预编译包让 PyTorch 自己去搞定底层库。2. 从零搭建运行环境我的完整步骤记录我的做法是在一台 Ubuntu 22.04 服务器上进行复现用的是一张 24GB 显存的显卡。这个环境配置过程前后花了两天其中真正有效操作的时间其实只有两个小时剩下的时间全部花在排查依赖冲突和下载数据集上。下面我把自己的操作步骤完整写出来每个步骤都附带原因解释希望你能顺着这个思路走不要照搬命令就以为是万能答案。2.1 用 conda 创建干净的 Python 环境我习惯先用 conda 创建一个独立的虚拟环境避免把系统 Python 搞乱。这一步没什么技术含量但非常重要。如果你直接复用 base 环境装到后面你会发现某个依赖需要 Python 3.9另一个又要求 3.11互相打架直接崩溃。创建环境命令如下conda create -n lerobot python3.10 conda activate lerobot创建完环境之后我建议先升级一遍 pip 和 setuptools因为有些老旧的工具链会解析出奇怪的依赖组合pip install --upgrade pip setuptools wheel2.2 安装依赖时最容易踩的坑lerobot 仓库里的requirements.txt是官方给出的依赖清单但这里有个坑直接pip install -r requirements.txt经常会出现版本冲突尤其是huggingface_hub、torch、numpy这三个库之间历史版本兼容性很混乱。我的做法是分两步安装第一步先安装 PyTorch 及其配套组件指定版本和 CUDA 版本。以 CUDA 12.1 为例pip install torch2.1.2 torchvision0.16.2 --index-url https://download.pytorch.org/whl/cu121第二步再安装其余依赖。这里我给个建议不要一次装完所有依赖再测试最好装一批验一批。否则后面报错时你根本不知道是哪一个库引入的问题。我用到的安装顺序是pip install einops gdown h5py omegaconf pip install timm hydra-core pip install wandb其中wandb是训练日志工具官方示例中默认会尝试连接云端如果你不想用可以通过环境变量WANDB_MODEoffline切到离线模式否则第一次训练时会卡在登录环节这算是新手最容易遇到的“假卡死”之一。2.3 验证环境是否跑通的小实验环境装完后不要急着下载数据集先做一个小实验用随机输入跑一遍模型的前向推理确认整个链路能通。我写段简单的 Python 代码来验证import torch from lerobot.models import DiffusionPolicy model DiffusionPolicy.from_pretrained(lerobot/diffusion_policy) dummy_obs torch.randn(1, 3, 96, 96) dummy_state torch.randn(1, 2) action model.predict(dummy_obs, dummy_state) print(action.shape)如果这一步能顺利输出动作张量的形状说明模型组件、张量计算、依赖加载都正常。如果在这里就报错那就先别继续往下走了一定是环境没搭对。这个验证方法是我强烈推荐的标准操作它把成千上万个潜在问题压缩到一个极小的范围内不用等到训练时才触发一堆奇怪的异常。3. 数据从哪里来下载官方数据集 vs 自己采集数据是机器人模仿学习里面最容易被低估的环节。很多人以为复现的核心是跑训练脚本实际上从数据下载、格式理解到数据装载都可能成为卡脖子的地方。lerobot 官方提供了多个仿真数据集和真实机器人数据集它们都存放在开源模型托管平台上可以通过项目中的命令行工具直接下载。我复现时用的是官方指定的推箱子任务数据集它生成自一个仿真环境包含大量人机交互演示。3.1 官方数据集的下载流程下载数据集的命令在官方文档里有但不同版本的命令参数格式会有变化我以自己下载时的命令为例python lerobot/scripts/download_dataset.py \ --dataset-id lerobot/aloha_mobile_pick_place \ --output-dir ./data这里要提醒一下下载速度可能会非常不稳定尤其是数据集文件涉及多个分片。如果你的网络环境一般建议用带断点续传能力的下载工具或者多试几次不要中途放弃。我下载时前两次都失败在第 8 个分片上第三次才完整拉下来。下载完成后数据集目录结构大致如下data/ aloha_mobile_pick_place/ metadata.json episodes/ ep_0.h5 ep_1.h5 ... videos/ ep_0.mp4 ep_1.mp4 ...meta 文件描述了传感器标定信息、动作维度、坐标空间等视频文件主要用于可视化查看演示过程真正训练时主要用到的是episodes里面的 HDF5 文件。3.2 数据格式里最容易忽视的细节每个 HDF5 文件保存一个 episode 的数据里面通常包含图像序列、机器人关节状态、动作指令、时间戳等。你不需要手动解析它但至少得清楚“动作”和“状态”之间的区别因为后续训练时它们是分开处理的。状态state观测到的环境信息比如机械臂关节角度、夹爪开合度。动作action在某个状态下机械臂执行的控制指令通常是关节角度目标或末端速度。模仿学习的目标就是学习一个从观测状态到动作的映射函数。这个映射在训练阶段被反复拟合在评估阶段则被用来实时决策。我在查看数据时发现一个很有意思的点即便是在仿真数据集里同一个任务的不同 episode 之间动作节奏、轨迹平滑度也有明显差异。这其实是好事因为多样性的数据能提升策略的泛化能力。如果你训练出的策略表现不佳先别急着调模型参数检查一下训练集是不是太过单一。3.3 自制数据采集的硬件配置建议如果你不想只用官方数据而是想采集自己的操作数据那你需要一套能够记录机器人状态和图像的硬件方案。官方的采集方案通常要求机械臂具备高精度编码器外接摄像头或者腕部相机来录制图像。以常见的六轴机械臂搭配一个夹爪为例你需要采集这些信号信号类型获取方式保存格式关节角度机械臂控制器实时读取一维数值数组关节速度差分计算或控制器输出一维数值数组夹爪开合夹爪电机反馈标量或向量第一视角图像腕部相机图像数组外置视角图像固定机位相机图像数组采集频率越高数据越精细但数据量也越大。我建议动作指令和状态使用 50Hz 以上采样图像使用 30~50Hz这样训练出来的策略在推理时才不会感觉到“一顿一顿”的卡顿。这里有一个很反直觉的经验真实采集的数据里偶尔保留一些“不完美”的示范例如夹取时轻微抖动几毫米然后调整成功对策略鲁棒性有正面效果。但如果你希望学到的动作更精准则需要人为筛选掉明显失败的轨迹。到底怎么取舍取决于你最终想让机械臂达到什么样的表现。4. 训练一个模仿学习策略配置解读与启动细节数据准备好之后就进入整个复现过程中最核心、也最消耗计算资源的部分模型训练。lerobot 支持多种模仿学习算法我复现时主要跑的是扩散策略Diffusion Policy原因很简单它在多种机械臂任务上的鲁棒性都很好代码实现也相对清晰。4.1 训练配置文件的逐项拆解lerobot 使用 YAML 文件管理训练配置其中关键参数分布在数据、模型、优化器和训练循环几个模块里。我打开默认配置文件时第一眼看到几十个参数会有点懵但真正需要手动调整的其实不多。我挑几个最容易影响结果的参数解释一下batch_size每次训练迭代送入模型的样本数。显存不足时优先降低它默认值在面对大模型时容易爆显存。num_epochs训练轮数。不是越多越好需要结合验证误差判断。learning_rate初始学习率。使用默认值一般不会有问题但如果 loss 震荡剧烈可以适当降低。num_frames一个训练样本中包含的连续帧数。扩散策略依赖上下文信息太小会看不清动作趋势太大则增加显存占用。delta_timestamps定义每个输入帧与当前帧的时间偏移量这决定了策略能看到“过去多久”的信息对快速运动任务影响很大。默认配置通常能在通用场景下跑出不错的效果但如果你想迁移到自己的数据集上这些参数都需要重新审视不能指望一把通吃。4.2 启动训练命令与日志观察启动训练的官方命令差不多长这样python lerobot/scripts/train.py \ --config-dir lerobot/configs \ --config-name diffusion_policy.yaml \ hydra.run.diroutputs/diffusion_policy_debug \ dataset_repo_idlerobot/aloha_mobile_pick_place训练开始后控制台会输出若干条基本信息包括数据集规模、batch 数量、模型参数量等。看到参数量动辄几千万时不要慌这是扩散模型的正常规模。随后每隔固定步数日志会打印 loss 值和学习率。我习惯把wandb打开因为图表比命令行输出的文字直观得多。这里我总结一下训练早期阶段的典型曲线走势大概前几百步 loss 会快速下降之后进入缓慢的下坡期中间会有小幅波动这很正常。如果 loss 完全没有下降趋势或者初期就出现 NaN那基本可以断定是数据异常、学习率过高、或模型初始化出了问题不是“多训练一会儿”能解决的。4.3 训练过程中的监控指标与问题判断监控指标看起来简单但很多人只盯 loss容易错判模型的真实状态。建议同时关注这几个指标loss整体训练误差越低越好但不能单独依赖它判断模型质量。action_mse_loss动作预测的均方误差如果这个值持续偏高说明策略输出的动作和演示动作差异大可能导致实际执行时阶段性地“走样”。state_loss部分算法会额外引入状态上的监督这个指标过高可能说明观测状态编码不够充分。data_loading_time数据加载耗时。如果这个值过大模型吃的都是老旧数据训练过程就会忽快忽慢看起来 loss 波动很大。训练过程中我特别强调要定期存 checkpoint。lerobot 的默认配置会周期性保存但你最好在训练脚本里显式设置一个保存间隔更短的 backup 目录。因为有一次我训练到第 300 轮时机器意外断电默认保存间隔是 50 轮我损失了整整 50 轮的结果重新跑花了好几个小时真的很痛苦。5. 评估与部署让策略在仿真/真实环境里动起来训练结束只是复现的一半另一半是在评估环境里真正看到策略执行任务。这个环节最容易产生“训练时分数很高实际动起来却拉胯”的落差原因是训练和评估之间存在很多容易被忽略的差异。5.1 评估脚本与可视化lerobot 提供了评估命令加载训练好的 checkpoint 并让策略在环境中执行一定数量的 episode统计成功率或任务得分。常见的运行方式如下python lerobot/scripts/eval.py \ --config-name diffusion_policy.yaml \ --pretrained-checkpoint outputs/diffusion_policy_debug/checkpoints/010000.pt \ --dataset-repo-id lerobot/aloha_mobile_pick_place评估时有一个很关键的细节策略输出的是动作序列而环境要求每一步执行一个动作。你需要在“执行整个动作序列”和“每步重新预测”之间做取舍。默认配置会在固定时间窗口内执行同一串预测动作这称为 receding horizon control滚动时域控制。如果你发现实际动作用力过猛或者抖动频繁可以尝试减小动作序列的执行长度让策略更频繁地重新规划。可视化的价值不只是“看个热闹”。通过观察机械臂动作你能够快速判断策略是不是学到了有意义的特征比如夹爪在接近目标时会不会预先张开手臂在移动时是不是沿着平滑轨迹。这些信息比数字更能揭示模型的决策行为。5.2 真实机器人部署前的安全检查如果你打算在真实机器人上部署我有几条来自自己教训的安全建议先空跑测试。不连接真实硬件只把策略输出发送给仿真环境验证动作幅值和频率在安全范围内。加动作限幅。在策略输出和真实执行器之间加一个低通滤波或动作限幅模块防止模型输出瞬时异常大动作。准备急停开关。无论你的模型训练得多好都要做好随时切断动力的准备这不是信不信任模型的问题而是安全底线。从小范围目标开始。让机械臂先完成一个范围很小的接近动作确认可行后再逐步扩大任务区域。这四条建议听起来简单但绝大多数“机器人学习事故”都是因为跳过其中某一条而发生的。我自己就吃过动作限幅没加的亏——模型在仿真里表现完美真实部署时一个瞬间的异常输出差点把机械臂怼到桌面上。5.3 策略性能优化的方向评估之后如果策略和目标表现还有差距优化的优先级应当明确。我总结下来性价比最高的几个方向依次是检查数据质量问题是否存在错误标注、时间对齐偏移、图像模糊数据问题不解决调什么参数都是白费。调整动作预测窗口长度窗口太短会让策略缺乏远见太长则容易让简单任务变得犹豫需要反复试验。增加上下文帧数如果任务依赖历史状态例如需要记得此前是否已经抓取成功这一点尤其有效。对图像观测做增强包括亮度扰动、平移裁剪、旋转等有助于提升泛化能力。不要一开始就扎进模型结构改动里那是最耗时且最难见效的方向。先把你手里的数据和评测流程优化到可靠可信的程度再考虑“魔改网络”。6. 我复现过程中遇到的三类坑和解决办法走完整轮复现最耗时间的一定是踩坑和排错阶段。这些坑在文档里未必写得很清楚但实际碰到的概率接近百分之百。我把最有代表性的三类坑记录在这里希望能帮你少走弯路。6.1 环境依赖冲突最容易被拖垮的环节第一次装依赖的时候我一直卡在一个报错信息上ModuleNotFoundError: No module named torch._six。这个报错的原因是某些视觉库的新版本不再兼容旧版 torch 的内部工具函数而 lerobot 里的部分模块还沿用旧写法。我当时的解决办法是把einops和timm降到与 torch 2.1 兼容的版本同时将torchvision对齐到 torch 版本。这里给出一个判断逻辑遇到torch._six或类似内部 API 报错时优先怀疑某个库版本的隐性 API 变化不要急着修改源码。另外还有一个隐藏依赖问题如果同时安装了系统包里的 OpenCV 和 pip 安装的 OpenCV很可能出现二进制冲突表现是加载视频时经常莫名其妙崩溃。建议在 conda 环境内明确指定opencv-python-headless并且在导入时确认到底加载的是哪一个。6.2 训练不收敛的排查链路训练不收敛的具体表现是 loss 在前几千步不下降或者在某个高位附近来回震荡。我踩过的一次就是数据加载异常导致的“伪不收敛”——数据加载器把图像和动作的时间戳错位了模型在每个 step 都在学习错误的对应关系loss 当然下不去。排查链路应该按这个顺序来可视化一批训练样本确认图像内容和对应动作是否合理。检查时间戳对齐图像帧的时间戳和动作指令的时间戳应该在同一个坐标系里尤其是自制数据。检查归一化图像像素范围是否归一化到[-1, 1]或[0, 1]关节角度是否被标准化尺度差异过大会让优化器很不稳定。检查学习率和 batch size 的匹配关系batch size 越小学习率一般也要相应调小否则一个 batch 的噪声会干扰更新方向。这个顺序不是随意的它是从“数据本身是否正确”逐步过渡到“模型训练机制是否合理”的排查思路能最快锁定问题区间。6.3 硬件资源不足时的降级方案很多人复现 lerobot 用的不是顶配显卡资源不足是常态。如果你在训练时遭遇显存爆掉不要立刻想着再买一张卡有几个可以先试的方案调小batch_size这是最简单有效的办法。batch size 从 8 降到 4显存占用能减少接近一半。开启梯度累积通过多个小 batch 累积梯度等效于大 batch 的训练效果但显存压力小得多。减小输入图像分辨率把图像从 256x256 降低到 128x128模型推理和训练都会快很多我实测对任务成功率影响不大。使用混合精度训练PyTorch 自带的自动混合精度机制能显著减小显存占用同时训练速度更快代价是轻微的数值精度损失。这些方案合在一起可以让你在 8GB 显存的卡上勉强跑通默认规模的训练。当然如果追求更好的效果硬件升级还是最终解但在那之前这些办法值得先试。最后再分享一点个人体会整个 lerobot 复现做下来我的最大感受是这个项目真正的门槛并不在算法原理而在环境兼容和数据链路。只要把这两块稳住训练和评估都只是时间问题。如果你之前没接触过机器人学习框架强烈建议先从官方数据集和仿真评估开始不要一上来就接真实机器人那样只会把变量搅在一起出了问题根本不知道从哪里查。另外如果你在复现时发现了和官方示例不一致的行为先检查你的版本号再检查数据集有没有完整下载最后再怀疑代码本身。这几类问题在新手期占了我排查时间的九成。希望这篇记录能帮你在复现 lerobot 的路上少踩一点坑。有什么我没提到但你觉得值得补充的细节也欢迎留言讨论。
1. 复现之前先把“复现目标”说清楚最近一直在折腾 lerobot 这个开源机器人学习框架的复现从环境搭建到训练出自己的一个模仿学习策略整个过程踩了不少坑也把很多文档里没写明白的细节摸清楚了。如果你正准备复现这个项目或者你只是想看看现在机器人操作策略训练到底怎么跑通这篇东西应该能帮你省下至少一周的调研时间。先说说 lerobot 到底是干嘛的。它本质上是一套面向机器人操作学习的训练和评估工具链核心是把模仿学习、强化学习里的主流算法比如扩散策略、ACT、VQ-BeT 等集成到一个统一框架里让研究者可以在仿真环境或者真实机器人上采集数据、训练策略、评估效果。复现它其实就是把官方给出的示例流程在自己的机器上完整跑一遍从环境配置、数据准备、模型训练到最终看到策略能控制机器人完成某个具体操作。在动手之前我强烈建议你先想清楚一个问题你要的“复现”是哪一种我身边不少人是看了论文或视频之后热血上头直接下载代码开始跑结果卡在环境依赖或者数据集下载上最后不了了之。我根据自己的实践把复现目标分成三类目标 A能跑通官方示例。这要求最低主要目的是理解整个流程怎么流转结果是否达到论文展示的效果其实不重要。目标 B换到自己的数据/场景上训练出新策略。这个你需要在数据采集、标注、训练配置上多花精力对硬件和实验设计也有更高要求。目标 C二次开发或接入自家机器人平台。这个就不仅仅是复现了还要理解源码中的传感器接口、策略推理逻辑、坐标变换等内部机制工作量最大。目标不同后面每一步的做法和容错标准都不一样。比如目标 A 的话你用普通的游戏显卡勉强也能跑最多慢一些目标 C 的话你可能需要先在仿真环境里把逻辑吃透再考虑真实硬件。硬件这块我直接说结论复现的瓶颈通常在显存和存储而不是 CPU。lerobot 默认采用的扩散策略在训练时会同时加载图像观测、关节状态和动作序列batch size 稍微调大一点显存占用就往上蹿。官方推荐的 GPU 显存不低于 8GB但我实测下来如果不想频繁调整 batch size12GB 以上会更从容。存储方面单个仿真数据集动辄几十 GB真实机器人采集的数据更大所以你需要留出至少 200GB 的可用磁盘空间并且最好是 SSD否则数据加载会成为瓶颈。对绝大多数人来说最稳妥的复现路线是先在仿真环境里跑通再考虑真实机器人。原因有两个一是仿真环境的数据获取成本低你可以脚本化地批量生成训练数据二是仿真出问题时定位更方便摄像头、机械臂的状态都能可视化查看不用对着真实硬件束手无策。1.1 lerobot 的核心组件与工作流程lerobot 的代码结构不算复杂但刚开始容易看得眼花缭乱。我用一个不太严谨但很好理解的类比它像一个“机器人训练车间”。车间里有四个核心工位——数据仓库、模型库、训练流水线、评估与控制接口。数据仓库负责管理各种格式的演示数据官方会提供一个命令行工具把原始数据转换成统一的存储格式模型库里预置了多个策略网络结构你不需要自己从零写模型训练流水线封装了数据加载、batch 采样、损失计算和日志记录评估与控制接口则负责把训练好的策略部署到仿真环境或真实机器人上让模型输出动作指令去驱动机器人完成目标。整个工作流程是先准备数据下载或自己采集然后定义实验配置哪套模型、什么训练参数启动训练最后加载训练好的 checkpoint 做评估和部署。复现的核心就是把这个链路完整走通理解每一步的数据流转和接口约定。1.2 版本选择比你想的重要我复现时最头大的不是算法而是版本兼容问题。lerobot 对 Python、PyTorch、CUDA 的版本组合比较敏感。官方文档会给出建议版本但如果你照着“最新版”盲目安装极大概率会碰到冲突。下面这个表格是我整理过的一套相对稳定的组合供参考组件推荐版本备注Python3.103.11 及以上有些依赖没跟上CUDA11.8 或 12.1需与 PyTorch 匹配PyTorch2.1.x2.2 以上部分算子兼容性有变操作系统Ubuntu 20.04 / 22.04Windows 也可以跑但仿真可视化体验差一些主要依赖以官方 requirements 为准不要轻易升级小版本特别提醒PyTorch 版本和 CUDA 版本的匹配关系一定要先确认好不要先装了 PyTorch 再回头纠结 CUDA。稳妥的做法是先装好 CUDA 驱动然后用pip install torch安装对应的预编译包让 PyTorch 自己去搞定底层库。2. 从零搭建运行环境我的完整步骤记录我的做法是在一台 Ubuntu 22.04 服务器上进行复现用的是一张 24GB 显存的显卡。这个环境配置过程前后花了两天其中真正有效操作的时间其实只有两个小时剩下的时间全部花在排查依赖冲突和下载数据集上。下面我把自己的操作步骤完整写出来每个步骤都附带原因解释希望你能顺着这个思路走不要照搬命令就以为是万能答案。2.1 用 conda 创建干净的 Python 环境我习惯先用 conda 创建一个独立的虚拟环境避免把系统 Python 搞乱。这一步没什么技术含量但非常重要。如果你直接复用 base 环境装到后面你会发现某个依赖需要 Python 3.9另一个又要求 3.11互相打架直接崩溃。创建环境命令如下conda create -n lerobot python3.10 conda activate lerobot创建完环境之后我建议先升级一遍 pip 和 setuptools因为有些老旧的工具链会解析出奇怪的依赖组合pip install --upgrade pip setuptools wheel2.2 安装依赖时最容易踩的坑lerobot 仓库里的requirements.txt是官方给出的依赖清单但这里有个坑直接pip install -r requirements.txt经常会出现版本冲突尤其是huggingface_hub、torch、numpy这三个库之间历史版本兼容性很混乱。我的做法是分两步安装第一步先安装 PyTorch 及其配套组件指定版本和 CUDA 版本。以 CUDA 12.1 为例pip install torch2.1.2 torchvision0.16.2 --index-url https://download.pytorch.org/whl/cu121第二步再安装其余依赖。这里我给个建议不要一次装完所有依赖再测试最好装一批验一批。否则后面报错时你根本不知道是哪一个库引入的问题。我用到的安装顺序是pip install einops gdown h5py omegaconf pip install timm hydra-core pip install wandb其中wandb是训练日志工具官方示例中默认会尝试连接云端如果你不想用可以通过环境变量WANDB_MODEoffline切到离线模式否则第一次训练时会卡在登录环节这算是新手最容易遇到的“假卡死”之一。2.3 验证环境是否跑通的小实验环境装完后不要急着下载数据集先做一个小实验用随机输入跑一遍模型的前向推理确认整个链路能通。我写段简单的 Python 代码来验证import torch from lerobot.models import DiffusionPolicy model DiffusionPolicy.from_pretrained(lerobot/diffusion_policy) dummy_obs torch.randn(1, 3, 96, 96) dummy_state torch.randn(1, 2) action model.predict(dummy_obs, dummy_state) print(action.shape)如果这一步能顺利输出动作张量的形状说明模型组件、张量计算、依赖加载都正常。如果在这里就报错那就先别继续往下走了一定是环境没搭对。这个验证方法是我强烈推荐的标准操作它把成千上万个潜在问题压缩到一个极小的范围内不用等到训练时才触发一堆奇怪的异常。3. 数据从哪里来下载官方数据集 vs 自己采集数据是机器人模仿学习里面最容易被低估的环节。很多人以为复现的核心是跑训练脚本实际上从数据下载、格式理解到数据装载都可能成为卡脖子的地方。lerobot 官方提供了多个仿真数据集和真实机器人数据集它们都存放在开源模型托管平台上可以通过项目中的命令行工具直接下载。我复现时用的是官方指定的推箱子任务数据集它生成自一个仿真环境包含大量人机交互演示。3.1 官方数据集的下载流程下载数据集的命令在官方文档里有但不同版本的命令参数格式会有变化我以自己下载时的命令为例python lerobot/scripts/download_dataset.py \ --dataset-id lerobot/aloha_mobile_pick_place \ --output-dir ./data这里要提醒一下下载速度可能会非常不稳定尤其是数据集文件涉及多个分片。如果你的网络环境一般建议用带断点续传能力的下载工具或者多试几次不要中途放弃。我下载时前两次都失败在第 8 个分片上第三次才完整拉下来。下载完成后数据集目录结构大致如下data/ aloha_mobile_pick_place/ metadata.json episodes/ ep_0.h5 ep_1.h5 ... videos/ ep_0.mp4 ep_1.mp4 ...meta 文件描述了传感器标定信息、动作维度、坐标空间等视频文件主要用于可视化查看演示过程真正训练时主要用到的是episodes里面的 HDF5 文件。3.2 数据格式里最容易忽视的细节每个 HDF5 文件保存一个 episode 的数据里面通常包含图像序列、机器人关节状态、动作指令、时间戳等。你不需要手动解析它但至少得清楚“动作”和“状态”之间的区别因为后续训练时它们是分开处理的。状态state观测到的环境信息比如机械臂关节角度、夹爪开合度。动作action在某个状态下机械臂执行的控制指令通常是关节角度目标或末端速度。模仿学习的目标就是学习一个从观测状态到动作的映射函数。这个映射在训练阶段被反复拟合在评估阶段则被用来实时决策。我在查看数据时发现一个很有意思的点即便是在仿真数据集里同一个任务的不同 episode 之间动作节奏、轨迹平滑度也有明显差异。这其实是好事因为多样性的数据能提升策略的泛化能力。如果你训练出的策略表现不佳先别急着调模型参数检查一下训练集是不是太过单一。3.3 自制数据采集的硬件配置建议如果你不想只用官方数据而是想采集自己的操作数据那你需要一套能够记录机器人状态和图像的硬件方案。官方的采集方案通常要求机械臂具备高精度编码器外接摄像头或者腕部相机来录制图像。以常见的六轴机械臂搭配一个夹爪为例你需要采集这些信号信号类型获取方式保存格式关节角度机械臂控制器实时读取一维数值数组关节速度差分计算或控制器输出一维数值数组夹爪开合夹爪电机反馈标量或向量第一视角图像腕部相机图像数组外置视角图像固定机位相机图像数组采集频率越高数据越精细但数据量也越大。我建议动作指令和状态使用 50Hz 以上采样图像使用 30~50Hz这样训练出来的策略在推理时才不会感觉到“一顿一顿”的卡顿。这里有一个很反直觉的经验真实采集的数据里偶尔保留一些“不完美”的示范例如夹取时轻微抖动几毫米然后调整成功对策略鲁棒性有正面效果。但如果你希望学到的动作更精准则需要人为筛选掉明显失败的轨迹。到底怎么取舍取决于你最终想让机械臂达到什么样的表现。4. 训练一个模仿学习策略配置解读与启动细节数据准备好之后就进入整个复现过程中最核心、也最消耗计算资源的部分模型训练。lerobot 支持多种模仿学习算法我复现时主要跑的是扩散策略Diffusion Policy原因很简单它在多种机械臂任务上的鲁棒性都很好代码实现也相对清晰。4.1 训练配置文件的逐项拆解lerobot 使用 YAML 文件管理训练配置其中关键参数分布在数据、模型、优化器和训练循环几个模块里。我打开默认配置文件时第一眼看到几十个参数会有点懵但真正需要手动调整的其实不多。我挑几个最容易影响结果的参数解释一下batch_size每次训练迭代送入模型的样本数。显存不足时优先降低它默认值在面对大模型时容易爆显存。num_epochs训练轮数。不是越多越好需要结合验证误差判断。learning_rate初始学习率。使用默认值一般不会有问题但如果 loss 震荡剧烈可以适当降低。num_frames一个训练样本中包含的连续帧数。扩散策略依赖上下文信息太小会看不清动作趋势太大则增加显存占用。delta_timestamps定义每个输入帧与当前帧的时间偏移量这决定了策略能看到“过去多久”的信息对快速运动任务影响很大。默认配置通常能在通用场景下跑出不错的效果但如果你想迁移到自己的数据集上这些参数都需要重新审视不能指望一把通吃。4.2 启动训练命令与日志观察启动训练的官方命令差不多长这样python lerobot/scripts/train.py \ --config-dir lerobot/configs \ --config-name diffusion_policy.yaml \ hydra.run.diroutputs/diffusion_policy_debug \ dataset_repo_idlerobot/aloha_mobile_pick_place训练开始后控制台会输出若干条基本信息包括数据集规模、batch 数量、模型参数量等。看到参数量动辄几千万时不要慌这是扩散模型的正常规模。随后每隔固定步数日志会打印 loss 值和学习率。我习惯把wandb打开因为图表比命令行输出的文字直观得多。这里我总结一下训练早期阶段的典型曲线走势大概前几百步 loss 会快速下降之后进入缓慢的下坡期中间会有小幅波动这很正常。如果 loss 完全没有下降趋势或者初期就出现 NaN那基本可以断定是数据异常、学习率过高、或模型初始化出了问题不是“多训练一会儿”能解决的。4.3 训练过程中的监控指标与问题判断监控指标看起来简单但很多人只盯 loss容易错判模型的真实状态。建议同时关注这几个指标loss整体训练误差越低越好但不能单独依赖它判断模型质量。action_mse_loss动作预测的均方误差如果这个值持续偏高说明策略输出的动作和演示动作差异大可能导致实际执行时阶段性地“走样”。state_loss部分算法会额外引入状态上的监督这个指标过高可能说明观测状态编码不够充分。data_loading_time数据加载耗时。如果这个值过大模型吃的都是老旧数据训练过程就会忽快忽慢看起来 loss 波动很大。训练过程中我特别强调要定期存 checkpoint。lerobot 的默认配置会周期性保存但你最好在训练脚本里显式设置一个保存间隔更短的 backup 目录。因为有一次我训练到第 300 轮时机器意外断电默认保存间隔是 50 轮我损失了整整 50 轮的结果重新跑花了好几个小时真的很痛苦。5. 评估与部署让策略在仿真/真实环境里动起来训练结束只是复现的一半另一半是在评估环境里真正看到策略执行任务。这个环节最容易产生“训练时分数很高实际动起来却拉胯”的落差原因是训练和评估之间存在很多容易被忽略的差异。5.1 评估脚本与可视化lerobot 提供了评估命令加载训练好的 checkpoint 并让策略在环境中执行一定数量的 episode统计成功率或任务得分。常见的运行方式如下python lerobot/scripts/eval.py \ --config-name diffusion_policy.yaml \ --pretrained-checkpoint outputs/diffusion_policy_debug/checkpoints/010000.pt \ --dataset-repo-id lerobot/aloha_mobile_pick_place评估时有一个很关键的细节策略输出的是动作序列而环境要求每一步执行一个动作。你需要在“执行整个动作序列”和“每步重新预测”之间做取舍。默认配置会在固定时间窗口内执行同一串预测动作这称为 receding horizon control滚动时域控制。如果你发现实际动作用力过猛或者抖动频繁可以尝试减小动作序列的执行长度让策略更频繁地重新规划。可视化的价值不只是“看个热闹”。通过观察机械臂动作你能够快速判断策略是不是学到了有意义的特征比如夹爪在接近目标时会不会预先张开手臂在移动时是不是沿着平滑轨迹。这些信息比数字更能揭示模型的决策行为。5.2 真实机器人部署前的安全检查如果你打算在真实机器人上部署我有几条来自自己教训的安全建议先空跑测试。不连接真实硬件只把策略输出发送给仿真环境验证动作幅值和频率在安全范围内。加动作限幅。在策略输出和真实执行器之间加一个低通滤波或动作限幅模块防止模型输出瞬时异常大动作。准备急停开关。无论你的模型训练得多好都要做好随时切断动力的准备这不是信不信任模型的问题而是安全底线。从小范围目标开始。让机械臂先完成一个范围很小的接近动作确认可行后再逐步扩大任务区域。这四条建议听起来简单但绝大多数“机器人学习事故”都是因为跳过其中某一条而发生的。我自己就吃过动作限幅没加的亏——模型在仿真里表现完美真实部署时一个瞬间的异常输出差点把机械臂怼到桌面上。5.3 策略性能优化的方向评估之后如果策略和目标表现还有差距优化的优先级应当明确。我总结下来性价比最高的几个方向依次是检查数据质量问题是否存在错误标注、时间对齐偏移、图像模糊数据问题不解决调什么参数都是白费。调整动作预测窗口长度窗口太短会让策略缺乏远见太长则容易让简单任务变得犹豫需要反复试验。增加上下文帧数如果任务依赖历史状态例如需要记得此前是否已经抓取成功这一点尤其有效。对图像观测做增强包括亮度扰动、平移裁剪、旋转等有助于提升泛化能力。不要一开始就扎进模型结构改动里那是最耗时且最难见效的方向。先把你手里的数据和评测流程优化到可靠可信的程度再考虑“魔改网络”。6. 我复现过程中遇到的三类坑和解决办法走完整轮复现最耗时间的一定是踩坑和排错阶段。这些坑在文档里未必写得很清楚但实际碰到的概率接近百分之百。我把最有代表性的三类坑记录在这里希望能帮你少走弯路。6.1 环境依赖冲突最容易被拖垮的环节第一次装依赖的时候我一直卡在一个报错信息上ModuleNotFoundError: No module named torch._six。这个报错的原因是某些视觉库的新版本不再兼容旧版 torch 的内部工具函数而 lerobot 里的部分模块还沿用旧写法。我当时的解决办法是把einops和timm降到与 torch 2.1 兼容的版本同时将torchvision对齐到 torch 版本。这里给出一个判断逻辑遇到torch._six或类似内部 API 报错时优先怀疑某个库版本的隐性 API 变化不要急着修改源码。另外还有一个隐藏依赖问题如果同时安装了系统包里的 OpenCV 和 pip 安装的 OpenCV很可能出现二进制冲突表现是加载视频时经常莫名其妙崩溃。建议在 conda 环境内明确指定opencv-python-headless并且在导入时确认到底加载的是哪一个。6.2 训练不收敛的排查链路训练不收敛的具体表现是 loss 在前几千步不下降或者在某个高位附近来回震荡。我踩过的一次就是数据加载异常导致的“伪不收敛”——数据加载器把图像和动作的时间戳错位了模型在每个 step 都在学习错误的对应关系loss 当然下不去。排查链路应该按这个顺序来可视化一批训练样本确认图像内容和对应动作是否合理。检查时间戳对齐图像帧的时间戳和动作指令的时间戳应该在同一个坐标系里尤其是自制数据。检查归一化图像像素范围是否归一化到[-1, 1]或[0, 1]关节角度是否被标准化尺度差异过大会让优化器很不稳定。检查学习率和 batch size 的匹配关系batch size 越小学习率一般也要相应调小否则一个 batch 的噪声会干扰更新方向。这个顺序不是随意的它是从“数据本身是否正确”逐步过渡到“模型训练机制是否合理”的排查思路能最快锁定问题区间。6.3 硬件资源不足时的降级方案很多人复现 lerobot 用的不是顶配显卡资源不足是常态。如果你在训练时遭遇显存爆掉不要立刻想着再买一张卡有几个可以先试的方案调小batch_size这是最简单有效的办法。batch size 从 8 降到 4显存占用能减少接近一半。开启梯度累积通过多个小 batch 累积梯度等效于大 batch 的训练效果但显存压力小得多。减小输入图像分辨率把图像从 256x256 降低到 128x128模型推理和训练都会快很多我实测对任务成功率影响不大。使用混合精度训练PyTorch 自带的自动混合精度机制能显著减小显存占用同时训练速度更快代价是轻微的数值精度损失。这些方案合在一起可以让你在 8GB 显存的卡上勉强跑通默认规模的训练。当然如果追求更好的效果硬件升级还是最终解但在那之前这些办法值得先试。最后再分享一点个人体会整个 lerobot 复现做下来我的最大感受是这个项目真正的门槛并不在算法原理而在环境兼容和数据链路。只要把这两块稳住训练和评估都只是时间问题。如果你之前没接触过机器人学习框架强烈建议先从官方数据集和仿真评估开始不要一上来就接真实机器人那样只会把变量搅在一起出了问题根本不知道从哪里查。另外如果你在复现时发现了和官方示例不一致的行为先检查你的版本号再检查数据集有没有完整下载最后再怀疑代码本身。这几类问题在新手期占了我排查时间的九成。希望这篇记录能帮你在复现 lerobot 的路上少踩一点坑。有什么我没提到但你觉得值得补充的细节也欢迎留言讨论。
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
