从遥操作到自主控制LeRobot 机器人学习框架上手全记录【免费下载链接】lerobot LeRobot: Making AI for Robotics more accessible with end-to-end learning项目地址: https://gitcode.com/GitHub_Trending/le/lerobot想让你的机械臂学会抓东西你大概率走过一条弯路先买臂、再对电机、再写 PID、再录数据、再调训练脚本每一步都在不同代码库之间反复横跳。LeRobot 是 Hugging Face 推出的 PyTorch 机器人学习框架把数据采集 → 策略训练 → 真机部署这三段拼成了同一套接口和同一组 CLI 命令让你少写一半胶水代码。5 分钟跑通第一条链路官方推荐直接装 PyPI 包不建议 clone 源码装——源码装只有你要改框架本身时才值得。最短路径 4 步# 1. 建环境LeRobot 要求 Python 3.12装低版本后面必踩坑 conda create -y -n lerobot python3.12 conda activate lerobot # 2. 装数据集 硬件控制所需依赖 pip install lerobot[dataset] lerobot[hardware] # 3. 验证安装 lerobot-info# 4. 用一行代码摸一下官方数据集确认数据链路通 from lerobot.datasets import LeRobotDatasetMetadata meta LeRobotDatasetMetadata(lerobot/aloha_mobile_cabinet) print(meta.total_episodes, meta.robot_type)第 2 步装 extras 而不是裸pip install lerobot是因为裸包只含核心lerobot-record这类脚本会缺依赖报 ModuleNotFoundError。第 4 步只拉元数据不拉数据几 MB 而已用来快速确认你能访问到数据集生态——LeRobot 数据集托管在 Hugging Face Hub 上直接按 repo_id 引用。SO-100 机械臂 遥操作的典型控制效果按任务找入口你要做什么就进哪个门不用通读源码按任务对号入座训练一个策略主入口lerobot-train命令配置全部走命令行例如lerobot-train --policy.typeact --dataset.repo_id你的数据集适用说明ACT、Diffusion、Pi0/Pi0.5、GR00T N1.7、SmolVLA 等策略都在src/lerobot/policies/下用--policy.type切换每个策略的 README 在docs/source/policy_*_README.md录数据 / 接入自己的硬件主入口lerobot-record命令--robot.type和--teleop.type两个参数决定组合例如--robot.typeso100_follower --teleop.typeso100_leader内置支持 SO-100/SO-101、LeKiwi、Reachy2、Unitree G1 等第三方硬件xArm、UR5e、Franka 等走插件机制装lerobot_robot_name包后 CLI 自动发现不用改框架代码跑评估 / 仿真验证主入口lerobot-eval支持 LIBERO、MetaWorld 等 benchmark例如lerobot-eval --policy.pathlerobot/pi0_libero_finetuned --env.typelibero --env.tasklibero_object --eval.n_episodes10真机回放用lerobot-replay不需要 GPU纯数据回放验证处理数据集主入口examples/dataset/use_dataset_tools.py和lerobot-edit-dataset命令删 episode、切分、合并、加特征都有现成工具可视化lerobot-dataset-viz把推理做快主入口src/lerobot/async_inference/提供策略服务端 机器人客户端的异步推理架构gRPC 传输推理和机器人控制并行延迟敏感任务强烈建议上这套示例在examples/tutorial/async-inf/走通一个小任务SO-100 遥操作 ACT 训练 回放以最常见的单臂抓取场景为例完整链路是遥操作录 2~3 个 episode → 训练 ACT → 回放验证。这条链路里真正需要做决策的只有三个点决策一数据格式选视频流还是纯图片帧。用默认的use_videosTrueMP4 Parquet 的 LeRobotDataset v3 格式。视频编码比逐帧图片省 10 倍存储空间且读取时自动解码LeRobotDataset对上层完全透明。除非你的下游任务有特殊需求不建议自己换格式。# 先确认能发现串口 lerobot-find-port然后按src/lerobot/scripts/lerobot_record.py文件头的示例跑录制核心就是三行lerobot-record \ --robot.typeso100_follower \ --teleop.typeso100_leader \ --dataset.repo_id你的用户名/so100_pick决策二策略选 ACT 还是 Pi0 系。如果你是自己录的几十条量级的小数据集建议 ACT——它小、训练快、对数据量不敏感单卡甚至 CPU 都能跑起来。Pi0/Pi0.5 这类 VLA 模型视觉能力强、支持语言指令但预训练权重本身就几个 G微调对显存和 GPU 要求高数据集没上百条时先别碰。架构上可以参考 VLA 模型的多模态输入到动作输出的完整结构决策三验证先回放还是上真机。建议先lerobot-replay把 checkpoint 的 action 序列叠在原始观测上回放——这一步不接任何硬件10 秒内能看出模型学没学到东西动作轨迹是否合理。回放正常再上lerobot-eval或真机。直接上真机失败率高且失败时你分不清是数据问题还是推理管线问题。训练时两个容易忽略的点--dataset.repo_id指向你录制时上传的数据集相机键名和分辨率必须和录制时一致examples/tutorial/act/act_using_example.py里有完整注释不一致会直接 shape 报错或静默出垃圾动作。踩坑速查现象装依赖直接报 Python 版本错误或import lerobot失败→ 根因LeRobot 要求 Python 3.12conda/venv 里是 3.10 之类的旧版本 → 解法按开头步骤重建 3.12 环境不要试图降版本兼容。现象加载数据集时视频解码报 ffmpeg / TorchCodec 相关错误→ 根因缺 ffmpegTorchCodec 解不了 MP4 → 解法conda install -c conda-forge ffmpeg。注意 macOS Intel、Linux ARM 上 TorchCodec 无 wheel框架会自动回退 pyav这两类平台不用装 ffmpeg。现象lerobot-find-port找不到机械臂串口→ 根因USB 未识别或驱动缺失WSL 用户常见 → 解法WSL 下conda install evdev -c conda-forge裸机先换线/换口再跑一次lerobot-find-port。现象录制后电机行为异常、关节角度漂移→ 根因电机未配置或校准参数过期 → 解法lerobot-setup-motors重配lerobot-calibrate重新校准。现象真机部署时相机输入报错或动作明显不对→ 根因推理时的相机键名/分辨率与训练数据集不一致 → 解法去模型卡片的 info.json 里核对相机键名把OpenCVCameraConfig的 width/height 改一致参考examples/tutorial/pi0/using_pi0_example.py的配置段。现象训练不收敛、loss 不动→ 根因学习率/数据集统计量问题 → 解法先用examples/dataset/use_dataset_tools.py检查数据分布学习率调整逻辑在src/lerobot/optim/schedulers.py。延伸入口docs/source/installation.mdx安装全流程WSL/ARM/macOS 各平台的分支说明装环境卡住先看它examples/每个任务一个可运行脚本act、pi0、diffusion、async 推理、RL改几个常量就能跑自己的docs/source/hardware_guide.mdx各策略的 GPU/显存需求和预期训练时长选策略前先查这个docs/source/bring_your_own_policies.mdx写自定义策略的完整契约说明算法研究背景的人看CONTRIBUTING.md 与 tests/想给框架提 PR 的先读贡献指南tests 目录是各模块正确用法的活文档【免费下载链接】lerobot LeRobot: Making AI for Robotics more accessible with end-to-end learning项目地址: https://gitcode.com/GitHub_Trending/le/lerobot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考