项目标题「lerobot 复现」看起来很短但背后其实是一个相当完整的开源机器人学习项目。LeRobot 这个名字在机器人社区里已经不算陌生了它主打的是把模仿学习、强化学习这些方法落地到真实机器人上整个项目托管的模型仓库、训练脚本和数据格式都是开放的。很多人看到这个项目第一反应是先装起来跑一遍搞清楚它到底是怎么采集数据、怎么训练策略、又怎么部署到机械臂上的。这篇文章我就从复现者的角度把从零开始折腾 LeRobot 的完整过程、踩过的坑、以及每一步背后的原理都梳理清楚给正准备复现的朋友一份可以直接参考的实操记录。复现一个开源项目表面上是在“把别人的代码跑通”实际上是在重建一套完整的技术认知。LeRobot 这类项目尤其值得这样做因为它不是单纯的算法仓库而是把感知、控制、数据采集、模型训练、部署整个链路都串起来了。你把它复现一遍等于把现代机器人学习的主流技术栈从头到尾过了一遍后面想改采集方式、换策略模型、接新硬件都有了具体的抓手。1. 整体设计与拆解LeRobot 到底在解决什么问题先把这个项目的定位说清楚。LeRobot 是一个开源的机器人学习框架核心思路是让机器人通过“观察-动作”数据来学习操作技能。这里的操作技能可以简单理解为给定当前摄像头画面和机械臂关节角度模型预测下一步该输出什么动作。整个过程和自动驾驶里的行为克隆有些相似但应用场景更聚焦在机械臂、灵巧手、移动操作这类真实物理设备上。我最初接触这个项目时最关心的一个问题就是“它凭什么能直接跑起来”。拆开看LeRobot 的架构大致分三层数据处理层负责从真实机械臂上采集演示数据把视频帧、关节角度、动作指令统一封装成标准格式同时支持数据清洗、裁剪、归一化等预处理操作。策略模型层内置了几种经典的模仿学习模型比如 Diffusion Policy 和 Action Chunking TransformerACT用户也可以接入 Hugging Face 上直接分享的预训练权重。部署执行层把训练好的模型导出接到真实机器人如常见的小型机械臂或者仿真环境如 MuJoCo里去做闭环推理。选择从复现切入最划算的路线是先把数据格式和推理流程吃透再去看训练和采集。因为数据格式是整个项目的“通用语言”你把数据部分理解透彻了后面的模型输入输出、部署脚本、甚至新环境适配都会变得非常清晰。1.1 复现前的路径规划复现 LeRobot 不是一条直线走到底而是分成几条可独立验证的路径。我建议按下面的顺序推进先跑通基于已有数据集的推理 demo不做任何采集和训练。用自带或社区公开的演示数据跑一遍完整的训练流程。在仿真环境里部署模型验证闭环控制是否正常。最后再考虑接入真实机械臂采集自己的演示数据训练一个新任务。为什么要先从推理开始因为这一步依赖最少、可预期性最强。只要环境装好了下载一个预训练权重跑一个脚本就能看到模型输出动作整个过程对新手来说是一个非常合理的正反馈。我自己复现的时候顺序就是环境配置、推理试用、数据格式检查、训练测试、仿真部署最后才碰真实硬件。1.2 为什么这个项目值得完整复现LeRobot 和传统的机器人控制项目有一个很明显的区别它把模型训练和机器人硬件解耦了。也就是说你可以先在纯软件环境里把模型训练好、验证好再把模型部署到真实机器人上这中间的数据流和接口设计得非常干净。这种设计带来的实际好处是复现成本被大幅降低了。即使你没有真实的机械臂也可以在 MuJoCo 仿真环境里跑通 LeRobot 的完整流程包括数据采集、模型训练和闭环评估。等到你手里有真实设备了再按官方文档接上标准的机械臂配置即可。我在复现过程中最大的体会就是“开源项目能不能跑通往往不取决于代码本身而取决于你对它数据流的理解。”LeRobot 的数据封装、Hugging Face 数据集接口、以及动作空间的定义环环相扣。把这些关系理清之后遇到问题排查起来就会快很多。2. 硬件与软件环境准备复现 LeRobot 的客观条件任何复现工作的第一步都是环境准备这边需要特别强调“版本一致性”。LeRobot 持续更新对 Python 版本、PyTorch 版本、CUDA 版本都有一定要求。如果版本不匹配很多“疑难杂症”会在训练阶段集中爆发而且看起来完全不相关。比如你可能在训练时遇到 Tensor 维度对不上实际上是 torch 版本更新导致的 API 行为变化。2.1 硬件的最低与推荐配置先谈硬件。LeRobot 的模拟推理和训练其实不算特别吃资源但要跑得舒服至少需要一块支持 CUDA 的 NVIDIA 显卡。我实测下来硬件配置能否完成推理能否完成常规训练能否完成大规模数据训练纯 CPU勉强可以速度极慢不推荐耗时太久基本不可行入门级 NVIDIA 显卡如 8GB 显存流畅可以需要控制 batch size较吃力中高端 NVIDIA 显卡12GB 及以上显存流畅很轻松推荐配置如果你手里只有 CPU也不是完全不能跑但训练一个策略模型可能要花费数倍的时间。尤其是 Diffusion Policy 这类基于扩散模型的策略其训练过程中的多次去噪迭代对算力要求偏高CPU 训练的现实体验很折磨。我的建议是尽量找一块支持 CUDA 的显卡再开始完整复现。内存方面16GB 起步比较保险32GB 会更从容。因为加载数据集、预处理视频帧、缓存特征都需要内存特别是在数据并行训练时内存占用会明显上涨。存储空间也需要注意一个典型的演示数据集大约在几个 GB 规模但训练过程中的 checkpoints 和日志也会累积占用。2.2 环境安装的完整步骤软件层面官方推荐的方案是用 conda 创建独立虚拟环境避免污染系统环境。我复现时用的安装过程和注意事项如下# 创建 Python 3.10 虚拟环境 conda create -n lerobot python3.10 conda activate lerobot # 安装 PyTorch根据自己的 CUDA 版本选择对应命令 pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121 # 克隆并安装 LeRobot git clone https://github.com/huggingface/lerobot.git cd lerobot pip install -e .这里几个细节值得展开说。第一Python 3.10 是一个兼容性很好的折中选择。很多机器人相关依赖库已经适配了 3.10而 3.11、3.12 在某些旧版本库上可能遇到二进制兼容问题。官方文档一般也会标明推荐版本直接照做即可。第二PyTorch 的安装方式直接决定了后面训练能不能调用 GPU。安装完成后务必确认 CUDA 可用python -c import torch; print(torch.cuda.is_available())如果输出False大概率是 PyTorch 版本和本机驱动的 CUDA 版本不匹配需要重新安装对应版本。这一步看起来基础但很多人折腾半天训练跑不起来原因就是把 PyTorch 装成了 CPU 版。第三pip install -e . 会把项目以可编辑模式安装到当前环境这样源码修改能即时生效对学习代码非常有帮助。但这种方式也有副作用如果项目依赖的某个库版本需要升级可能因为已安装的包而冲突。所以遇到依赖冲突时优先查看项目仓库的 issue 区很多环境问题已经有人遇到并给出解法。2.3 关于预训练模型的下载安装完主项目之后LeRobot 通常会从 Hugging Face 拉取预训练模型或数据集。这里有一个实际体验上的提醒国内网络环境下Hugging Face 的下载速度可能不稳定而且偶尔连接失败。这跟代码逻辑无关纯粹是网络链路问题。我的做法是配置镜像站或者使用代理工具这里仅指常规的 HTTP 代理这些细节按个人网络情况处理即可。如果下载始终失败也可以考虑手动下载模型权重文件再放置到本地缓存目录并设置环境变量指向该目录。这个方案在复现时非常有用省去反复重试的时间。3. 数据格式与数据流拆解复现项目的核心认知复现 LeRobot 的过程中最值得花时间去理解的环节就是数据流。整个项目就像一条流水线原始观测图像关节状态进入数据采集器变成标准化数据集训练脚本读取数据集生成策略部署时策略又根据实时观测输出动作。这个闭环里面每一环都对数据的格式有严格要求任何一个环节对不上后面都会报错。3.1 从真实机器人到数据集LeRobot 的数据采集逻辑可以类比为“录屏录操作”。真实机械臂上通常装有多个摄像头同时关节编码器会记录每个时刻的角度。采集一次演示就是同步保存视频帧和关节角度序列。这个过程在代码里被抽象成一个“Episode”的概念每个 Episode 就是一个完整的演示轨迹。一个典型的数据集目录结构包含videos/每个时间步的摄像头画面一般以 MP4 视频的形式存储。observations/每个时间步的关节角度、末端执行器位姿、速度等状态信息。actions/每个时间步的控制指令通常也是关节角度目标值。meta/任务描述、环境参数、采集日期等信息。要理解为什么 LeRobot 采用这种“多个文件索引”的结构而不是一个单一的 HDF5 文件核心原因是平衡读取效率和灵活性。视频帧以压缩视频存储节省空间同时方便可视化状态数据单独保存成 NumPy 数组读取速度快元信息用 JSON 文件保存便于扩展。复现时我强烈建议亲自创建一个“假数据集”来看结构。什么意思呢就是用项目自带的数据集创建脚本或者直接下载一个小型示例数据集然后用 Python 加载它打印每个字段的 shape 和类型。这样你会对“模型输入的到底是什么”有直观感受。3.2 归一化与动作表示LeRobot 对数据做了归一化处理这是复现时最容易忽略但对训练效果影响很大的环节。机械臂的关节角度和图像像素值的数值范围完全不同如果不做归一化直接输进神经网络训练很难收敛。LeRobot 的做法是对图像做标准化对状态/动作数据做均值方差归一化并在训练时统一到接近零均值、单位方差的分布。动作表示方面LeRobot 支持两种常见形式绝对关节位置直接输出目标关节角度简洁直接但需要控制器跟踪。增量动作输出相对于当前状态的变动量平稳性更好但对频率和噪声更敏感。不同策略模型对动作表示的偏好不同比如 ACT 模型常用绝对位置Diffusion Policy 则对增量动作更友好。复现时你不需要一开始就精通这些细节但要知道动作表示的选择会直接影响模型输出头的设计和训练损失函数这属于策略模型的“元参数”。3.3 数据格式的常见认知误区新手最容易犯的错误是把 LeRobot 的数据集简单理解成“一张图一个命令”的监督学习样本。实际上LeRobot 的策略模型是上下文相关的它通常接收一小段历史观测序列然后预测未来若干个动作。也就是说样本不是单个时间步而是“一段观测窗口 一段动作窗口”。我在复现时把这个窗口机制理解透之后再看训练代码里的 DataLoader 就顺畅多了。LeRobot 会在每个 Episode 上做滑窗采样而不是随机抽单个时间步这也是为了保证策略能学到时间连贯性。如果忽略这一点你后续想自己写数据加载逻辑就会踩坑。4. 实操记录从推理到训练再到部署接下来这部分就是完整的实战过程了我按照实际复现顺序把每一步的输入输出、耗时、和容易出错的地方写出来。4.1 第一步加载预训练模型进行推理验证复现的第一个里程碑是让一个已经训练好的模型跑通推理流程。LeRobot 提供了一条非常简洁的命令行入口核心用法是python lerobot/scripts/eval.py \ --model.pretrained_model_name_or_pathlerobot/diffusion_policy \ --env.typemujoco \ --env.taskaloha_insert_pegs这条命令的逻辑是从模型仓库拉取预训练权重在 MuJoCo 仿真环境里加载一个任务然后跑闭环评估。如果一切正常你会看到仿真环境里机械臂在执行操作终端上打印出每个 episode 的成功率或回报均值。值得说明的是eval.py不仅是在做推理它同时还要做“闭环控制”模型基于当前仿真状态输出动作仿真器执行动作环境反馈新的状态再送入模型循环往复。这个过程才是 LeRobot 真正工作的样子。第一次跑这个命令时我建议把--enable_recording这类可视化参数打开把推理过程录下来这样你能直观看到模型的行为质量。成功率不是唯一的指标观察动作的平滑度、任务完成的稳定性你就能对模型水平有个初步判断。4.2 第二步检查数据集并训练一个轻量模型推理验证通过后下面要做的就是完整训练。第一步是下载一个现成的数据集示例任务和数据集在 Hugging Face 上都有对应仓库。下载和加载数据集的代码大概是这样from lerobot.common.datasets.lerobot_dataset import LeRobotDataset dataset LeRobotDataset(lerobot/pusht, local_files_onlyFalse) print(dataset.num_episodes, dataset.num_samples)这里特别注意首次运行会触发数据集下载如果网络状况不佳会长时间卡住。我的建议是先设置 Hugging Face 镜像或者手动下载并把数据集放到本地缓存路径。训练脚本一般长这样python lerobot/scripts/train.py \ --dataset.repo_idlerobot/pusht \ --policy.typediffusion \ --output_diroutputs/pusht_diffusion训练过程中你会看到 loss 逐步下降终端日志会定期输出当前步数、loss 值、学习率等指标。这个过程可能持续数小时取决于显卡性能和数据量。我测试下来一张中端显卡训练一个中等规模的数据集几百个 episode大约需要 2 到 4 小时这个时间范围可以帮你规划实验节奏。训练结束后输出目录里会保存 checkpoint。每个 checkpoint 包含模型权重、优化器状态和训练配置。LeRobot 会在固定间隔保存 checkpoint你可以在训练中途停止然后加载最新的 checkpoint 继续训练或评估。4.3 第三步仿真环境闭环评估训练完成之后用新训练的模型替换预训练模型再次运行 eval 命令就能对比效果python lerobot/scripts/eval.py \ --model.pretrained_model_name_or_pathoutputs/pusht_diffusion/checkpoints/last \ --env.typemujoco \ --env.taskpusht这一步验证的是训练出的模型在闭环环境中是否真的能用。有些模型在训练集上 loss 很低但在闭环测试中表现不佳原因是模仿学习存在分布偏移问题。LeRobot 提供的评估脚本对这个问题进行了量化评估对比成功率是一个很客观的指标。首次评估时成功率低并不一定代表训练失败可能是评估时的随机种子、初始状态与训练分布不一致需要多跑几个 episode 取平均。4.4 第四步仿真环境中的数据采集仿真环境的一个巨大优势是数据采集成本极低。你可以通过脚本控制机械臂完成特定任务自动生成大量演示数据。LeRobot 在 MuJoCo 环境下也提供了数据采集接口这样即便没有真实机械臂也可以完整体验“采集-训练-部署”全流程。在仿真环境采集数据时要特别留意“数据多样性”。如果采集到的演示轨迹都很相似训练出的策略会过拟合无法处理起始位置的微小变化。我建议在仿真环境里加入随机初始状态、随机目标位置和噪声扰动让数据分布更宽泛。这一步对后续真实硬件上的迁移也非常重要。4.5 第五步真实机械臂部署前的最后检查如果你有真实机械臂最后一步就是把模型部署到真实设备上。部署前需要检查连接配置、摄像头标定、控制频率和设备驱动。LeRobot 的代码里对特定机械臂有专门的示例配置但换一个品牌或型号就需要自己写配置文件和坐标转换逻辑了。真实部署时最容易出问题的点有三个观测分布不一致仿真环境的图像和真实摄像头的图像差异较大模型很可能失效。解决办法是尽量在部署前用真实数据做微调或者在采集演示时使用真实摄像头。控制延迟模型推理的延迟会直接影响闭环控制的稳定性。如果单次推理超过几十毫秒机械臂的动态性能会受到明显影响需要优化模型推理速度或降低控制频率。安全机制真实机械臂的力和速度一定要设限防止模型输出异常动作导致设备损坏或安全问题。建议首次测试时在低速低力矩模式下运行。5. 常见问题与排查技巧实录复现过程中我收集整理了一些高频问题。这些问题在 GitHub 讨论区和官方文档里都有迹可循但很多细节需要实际操作才会真正意识到。5.1 环境安装阶段的问题问题现象可能原因解决方法torch.cuda.is_available() 返回 FalsePyTorch 装成了 CPU 版按对应 CUDA 版本重新安装 PyTorchpip install -e . 出现依赖冲突本机已安装库与项目依赖不兼容新建虚拟环境尽量不预装额外包下载预训练模型超时网络链路不稳定手动下载权重并配置本地缓存MuJoCo 无法启动渲染窗口缺少图形依赖库 (libGL)安装对应系统依赖包其中玩一下图形依赖的问题在服务器或无桌面系统上MuJoCo 的渲染往往需要 X11 或虚拟显示服务。如果你只是想跑训练而不看渲染画面可以设置无头模式或者使用虚拟屏幕工具。这里要避免的坑是明明 GPU 正常、数据加载正常结果因为渲染初始化失败报一个完全不相干的错。5.2 数据加载与训练阶段的问题数据加载阶段最常见的问题是因为数据集路径变更或缓存失效导致的加载失败。LeRobot 使用 Hugging Face 数据集库如果之前下载了旧版本数据集而仓库更新了数据结构加载时就会报字段缺失的错误。解决方法是删除本地缓存重新下载。训练阶段的坑相对集中显存不足OOMbatch size 过大或者图像分辨率太高。解决方案是减小 batch size或开启梯度累积还可以降低视频帧采样分辨率。loss 变成 NaN常见于学习率过高或数据中存在异常值。先降低学习率并在训练前检查数据归一化结果是否包含无穷大值。loss 下降但评估不涨模型过拟合训练集或评估环境初始状态分布和训练不一致。可以增加数据增强、引入更多演示数据、或者调整随机种子重新评估。我个人的经验法则是遇到训练不收敛的问题先不要急着调模型架构先把数据归一化、学习率和 batch size 这三个基础项逐一排除。很多项目的训练问题最终都归结为学习率不合理或数据分布异常。5.3 部署阶段的常见坑仿真部署时模型表现不错但真实设备上表现大打折扣这种情况太常见了。核心原因是“仿真到真实的分布偏移”。图像风格、光线条件、摄像角度、关节动力学特性所有这些都在变化。LeRobot 的常见解法是两阶段迁移先在少量真实演示数据上微调模型再部署。这一点几乎适用于所有模仿学习项目建议一开始就纳入计划。另外真实机械臂执行动作频率和仿真完全不是一个量级。仿真中你可以在每个控制周期都调用模型但真实机械臂的控制频率可能只有几十赫兹模型推理策略必须调整。LeRobot 的部署代码里支持对动作执行进行平滑、插值和限幅这些参数需要根据具体机械臂的通信协议调整。6. 复现后的扩展从“跑通”到“改造”复现的终点不是跑通一次而是你能够根据需求去改动它。我整理了几条短期内可以尝试的扩展方向每个方向都不需要重写框架但能极大扩展你对 LeRobot 的理解。第一个方向是替换策略模型。LeRobot 内置的 Diffusion Policy 和 ACT 是两种经典方案你可以试着把同一个数据集分别用两种模型训练对比它们的动作平滑度和任务成功率。这能很好地帮你理解不同模型对任务、数据量和算力的要求差异。第二个方向是修改动作空间。以推物体任务为例模型可以直接输出末端执行器的速度也可以输出关节角度目标。前者控制更平滑后者更容易实现精确位置控制。你自己定义动作空间并调整模型输出头的维度就能验证这种选择对策略学习难度的影响。第三个方向是接入自己的仿真任务。LeRobot 提供了任务接口你可以按照其格式注册新的仿真环境定义观测空间、动作空间和奖励函数。这个过程会让你对环境的抽象有一个更完整的认识也能为后续真实硬件接入铺路。我建议复现时准备一个实验记录本把每个实验的配置参数、数据集路径、模型结构、训练曲线、评估结果都记录下来。这个习惯后期会非常有用因为你一旦开始对比不同配置就会发现记忆并不可靠只有系统记录才能帮你快速定位最优参数组合。7. 最后的一点体会LeRobot 是我见过的最适合完整复现的机器人学习项目之一因为它把“数据-模型-部署”这条主线做得非常清晰而且每一步都有可验证的产出。你从推理开始逐步深入到训练、数据采集和真实部署整个过程就像一次完整的工程实践而不只是读了几篇论文。刚开始复现的时候不必急于把每个原理都搞懂先按照“推理-训练-部署”的路径跑通一遍获得对项目的整体感知然后再回头逐模块深入。这个过程很像组装一台电脑你先装好主机点亮屏幕再去研究每个配件的性能指标和兼容性。这种“先整体后局部”的路径在复现现代机器人项目时效率是最高的。如果你正准备开始复现 LeRobot或者已经在某个环节卡了几天希望这份实操记录能给你一些参考。等你跑通了第一个 demo再回头看那些曾经让你头大的报错信息就会发现一切都值得。