LeRobot v0.5.0 发布，这是目前规模最大的一次更新。
#机器人 #开源 #LeRobot #HuggingFace #具身智能
> 基于对 c:\GitHub\lerobot 代码库的全面探索整理
> 分析日期：2025年3月
---
LeRobot 是 Hugging Face 开源的真实世界机器人机器学习库，基于 PyTorch，提供：
| 项目 | 说明 |
|---|---|
| 名称 | lerobot |
| 版本 | 0.5.1 |
| 许可证 | Apache-2.0 |
| Python | >=3.12（支持 3.12、3.13） |
| 状态 | Alpha（开发中） |
| 文档 | https://huggingface.co/docs/lerobot/index |
| 源码 | https://github.com/huggingface/lerobot |
| Discord | https://discord.gg/s3KuuzsPFb |
| 目录/文件 | 用途 |
|---|---|
| src/ | 主源码（全部在 src/lerobot/） |
| tests/ | 单元/集成测试，按模块划分 |
| docs/ | 文档源码（MDX），可构建为在线文档 |
| examples/ | 示例与教程代码 |
| docker/ | Docker 相关配置 |
| .github/ | CI/CD 工作流 |
| media/ | README 等媒体资源 |
| README.md | 项目介绍、快速开始、支持的机器人与策略 |
| pyproject.toml | 项目元数据、依赖、可选 extra、所有 CLI 入口 |
| CONTRIBUTING.md | 贡献指南、开发环境、测试与代码风格 |
| LICENSE | Apache-2.0 |
| AI_POLICY.md、CODE_OF_CONDUCT.md | 行为与 AI 使用政策 |
src/lerobot/）| 包/目录 | 职责 |
|---|---|
| policies/ | 策略实现：ACT、Diffusion、VQ-BeT、TDMPC、SAC、Pi0/Pi0.5/Pi0Fast、SmolVLA、Groot、XVLA、Wall-X、SARM、HIL-SERL、RTC 等；含 configuration、modeling、processor |
| robots/ | 机器人接口与具体实现：so_follower、bi_so_follower、koch_follower、openarm_follower、hope_jr、lekiwi、reachy2、unitree_g1、earthrover_mini_plus、omx_follower 等 |
| teleoperators/ | 遥操作设备：so_leader、bi_so_leader、koch_leader、openarm_leader、gamepad、keyboard、phone、reachy2、unitree_g1、homunculus、openarm_mini 等 |
| datasets/ | LeRobotDataset、流式数据集、采样器、视频/图像工具、pipeline features、统计与工具函数 |
| envs/ | 仿真环境：aloha、pusht、libero、metaworld 等；与 EnvHub 集成 |
| cameras/ | 相机抽象与实现：opencv、intelrealsense、reachy2_camera、zmq |
| motors/ | 电机/总线：dynamixel、feetech、damiao、robstride；校准与编码 |
| processor/ | 数据与策略的预处理/后处理管道（normalize、batch、tokenizer、delta_action、gym_action 等） |
| configs/ | 训练/评估/数据等配置解析与类型（parser、train、eval、policies 等） |
| optim/ | 优化器与学习率调度（factory、optimizers、schedulers） |
| rl/ | 强化学习：buffer、actor、learner、queue、process、wandb_utils、reward/crop、joint_observations 等 |
| async_inference/ | 异步推理：policy_server、robot_client、configs |
| data_processing/ | 数据处理（如 sarm_annotations） |
| transport/ | gRPC 等传输（用于 async 等） |
| model/ | 模型相关共用逻辑 |
| utils/ | 通用工具：logging、io、random、control、rotation、hub、constants、errors、decorators、transition 等 |
| scripts/ | 所有 lerobot-* CLI 脚本的实现入口 |
all（聚合大部分 extra；unitree_g1、groot 等部分需单独安装说明）所有入口均在 pyproject.toml 的 [project.scripts] 中定义，实现位于 src/lerobot/scripts/，入口函数为各模块的 main()。
| 命令 | 用途 |
|---|---|
| lerobot-calibrate | 对机器人或遥操作设备进行校准 |
| lerobot-find-cameras | 发现并测试相机设备 |
| lerobot-find-port | 查找与 MotorsBus 对应的 USB 端口 |
| lerobot-record | 录制数据集（遥操作或策略生成动作） |
| lerobot-replay | 在机器人上回放数据集中某条 episode 的动作 |
| lerobot-setup-motors | 设置电机 ID 与波特率 |
| lerobot-teleoperate | 通过遥操作直接控制机器人 |
| lerobot-eval | 在环境/机器人上跑 rollouts 评估策略并计算指标 |
| lerobot-train | 训练策略（解析配置、数据集、环境、策略等） |
| lerobot-train-tokenizer | 训练用于动作编码的 FAST tokenizer |
| lerobot-dataset-viz | 可视化 LeRobotDataset 任意 episode 的所有帧 |
| lerobot-info | 输出系统配置摘要（尽量无额外依赖） |
| lerobot-find-joint-limits | 通过遥操作寻找关节限位与末端执行器边界 |
| lerobot-imgtransform-viz | 可视化给定配置下图像变换效果 |
| lerobot-edit-dataset | 编辑数据集（删 episode、切分、合并、删特征、改任务、图像转视频等） |
| lerobot-setup-can | 配置与调试 Damiao 电机用的 CAN 接口 |
policies/pretrained.py）：所有策略的基类，继承 nn.Module 与 HubMixin。config_class 和 name，并实现：from_pretrained() / _save_pretrained()，与 HF Hub 集成；默认以 safetensors 单文件保存模型。policies/ 下以子包形式存在，通常包含：
configuration_*.py：策略配置modeling_*.py：策略网络与 select_actionprocessor_*.py：观测/动作的预处理与后处理CODEBASE_VERSION = "v3.0"。lerobot-dataset-viz、lerobot-edit-dataset、push_dataset_to_hub 等。connect()、get_observation()、send_action() 等，与具体硬件解耦。docs/source/，主要为 .mdx，导航由 _toctree.yml 定义。doc-builder build lerobot docs/source/ --build_dir ；预览：doc-builder preview lerobot docs/source/（需 docs-requirements.txt 与 Node.js）。src/lerobot 对应，如 tests/datasets/、tests/policies/、tests/robots/、tests/scripts/、tests/envs/、tests/rl/、tests/async_inference/、tests/optim/、tests/configs/、tests/utils/、tests/transport/、tests/training/ 等。tests/fixtures/ 提供 dataset_factories、files、hub、optimizers、constants 等，通过 conftest.py 的 pytest_plugins 注册。tests/artifacts/ 存放测试用数据集、checkpoint、图像等（含 safetensors、bag、png），需 git-lfs（git lfs install 与 git lfs pull）。pytest -sv ./testspytest -sv tests//test_xxx.py pytest -q tests/ -k .github/workflows/（如 fast_tests.yml，使用 UV、Python 3.12）。部分测试依赖 optional extras；串口/相机等硬件不可用时通过 conftest 跳过或报错。__init__.py、wall_x 第三方代码）。lerobot.envs.*、lerobot.configs.*、lerobot.optim.*、lerobot.model.*、lerobot.cameras.*、lerobot.motors.*、lerobot.transport.* 等开启类型检查，其余模块 ignore_errors = true。pre-commit install 与 pre-commit run --all-files。pip install lerobot 后运行 lerobot-info；按需安装 extras（如 lerobot[gamepad]、lerobot[pi]）。lerobot-record、lerobot-edit-dataset、lerobot-dataset-viz。lerobot-train --policy=act --dataset.repo_id=lerobot/aloha_mobile_cabinet 等；评估用 lerobot-eval。Robot/Teleoperator 或继承 PreTrainedPolicy，参见文档 bring_your_own_policies、integrate_hardware、envhub。