LeRobot 框架的开发指南 （上）

本文给想要贡献或扩展 LeRobot 框架的开发者提供全面的指南。它涵盖开发环境、测试流程、持续集成工作流程以及贡献指南。

开发环境设置

本地开发环境

为 LeRobot 设置本地开发环境需要 Python 3.10 和包管理工具。建议使用 Poetry 或 uv 进行依赖管理。

设置步骤：
克隆代码库并创建 Python 环境
使用以下方法之一安装依赖项：
使用 Poetry：poetry sync --extras “dev test” 或 poetry sync --all-extras
使用 uv：uv sync --extra dev --extra test 或 uv sync --all-extras
安装预提交hooks：pre-commit install

Docker 环境

LeRobot 提供三种 Docker 镜像，适用于不同的开发场景：

使用这些docker images：

CPU image

docker pull huggingface/lerobot-cpu

GPU image (requires NVIDIA Container Toolkit)

docker pull huggingface/lerobot-gpu

Development image

docker pull huggingface/lerobot-gpu:dev

测试框架

LeRobot 项目使用 pytest 进行测试，并包含一个全面的测试套件。

本地运行测试

可以使用 pytest 运行测试，命令如下：

Run all tests

python -m pytest -sv ./tests

Run specific test file

pytest tests/test_specific.py -v

Run end-to-end

tests make test-end-to-end

测试套件使用 Git LFS 来存储测试 artifacts。请确保设置好 Git LFS 并拉取 artifacts：
git lfs install
git lfs pull

CI/CD 工作流程

LeRobot 使用 GitHub Actions 进行持续集成和部署（CI/CD）工作流程。

Pull 请求工作流

创建 Pull 请求时，以下工作流会自动运行：
1.测试工作流 (test.yml) - 使用不同配置运行 pytest：

• 包含所有附加组件的完整安装
• 最小化安装
• 端到端测试

2.质量工作流 (quality.yml) - 检查代码质量：

• Ruff 用于 linting 和格式化
• 拼写检查

3.Docker 测试 (test-docker-build.yml) - 当 Dockerfile 发生更改时，测试 Docker 构建

调度的工作流

以下工作流按每日调度运行：
1.夜间测试 (nightly-tests.yml) - 在 Docker 容器中进行全面测试：

• CPU 容器测试
• GPU 容器测试

2.Docker 构建 (build-docker-images.yml) - 构建并发布 Docker 镜像：
huggingface/lerobot-cpu
huggingface/lerobot-gpu
huggingface/lerobot-gpu:dev

安全检查

密钥扫描 (trufflehog.yml) - 每次推送时运行，以检测意外密钥泄露

贡献指南

代码风格和预提交 hooks

LeRobot 使用预提交 hooks 来强制执行代码风格和质量：
pre-commit install # Install hooks
pre-commit # Run hooks on staged files
pre-commit run --all-files # Run hooks onallfiles

预提交的配置包括：

Pull 请求流程

• 分叉并克隆代码库
• 创建分支用于修改：
  git checkout -b descriptive-branch-name
• 进行修改并确保测试通过
• 使用预提交功能，维护代码质量
• 将修改推送到分叉（fork）
• 创建包含清晰描述的 pull 请求
• 在审核期间处理反馈

创建 pull 请求时：

• 使用描述性标题概括贡献
• 对任何相关的问题做参考
• 确保所有测试通过
• 将正在进行的 pull 请求，标记为 [WIP] 或草稿拉取请求

开发最佳实践

文件结构

LeRobot 使用标准 Python 项目结构。开发者需要注意的关键文件和目录：

1. pyproject.toml - 包配置和依赖项
2. .pre-commit-config.yaml - 预提交钩子配置
3. tests/ -测试套件
4. .github/workflows/ - CI/CD 配置
5. docker/ - Docker 配置

忽略的文件

Git 和 Docker 中忽略的文件和目录：

1. 构建文件：build/、dist/、*.egg-info/
2. 虚拟环境：.venv/、env/
3. 缓存文件：pycache/、.pytest_cache/
4. 日志和数据：logs/、data/、outputs/、wandb/
5. IDE 设置：.vscode/

开发工具

推荐的开发工具包括：

• Poetry 或 uv 用于依赖管理
• pre-commit 用于代码质量监控
• pytest 用于测试
• Git 和 GitHub 用于版本控制
• Docker 用于容器化开发和测试

在此介绍 LeRobot 可用的 Docker 环境、其配置以及如何与 CI/CD 流水线集成。Docker 容器为 LeRobot 应用程序的开发、测试和部署提供一致的环境。

可用的 Docker images

lerobot-cpu

lerobot-cpu image 提供了一个轻量级容器，用于在仅 CPU 环境下运行 LeRobot：

• 基于 Python 3.10 slim 镜像
• 包含必要的构建工具和库
• 配置了 MuJoCo EGL 渲染后端
• 已安装常用依赖项的LeRobot
• 用于推理的 PyTorch CPU 版本

lerobot-gpu

lerobot-gpu image 支持 GPU 加速训练和推理：

• 基于 NVIDIA CUDA 12.4.1 和 Ubuntu 22.04
• 包含必要的构建工具和库
• 配置了 MuJoCo EGL 渲染后端
• 已安装常用依赖项的 LeRobot
• 支持 CUDA 的 PyTorch

lerobot-gpu-dev

lerobot-gpu-dev image 专为为 LeRobot 做出贡献的开发者设计：

• 基于 NVIDIA CUDA 12.2.2 开发类 image，搭载 Ubuntu 22.04 操作系统
• 包含全面的开发工具（git、vim、htop 等）
• 包含用于视频处理的 FFmpeg 构建依赖项
• 包含用于代码库交互的 GitHub CLI
• 使用 Poetry 进行依赖项管理
• 无需预装 LeRobot 软件包（仅供开发使用）

Docker image 架构

Docker image 内容

Docker image 的分层和内容

CI/CD 集成

LeRobot 使用 Docker 容器作为其 CI/CD 流水线，确保在不同机器上保持一致的测试环境。

Docker 构建工作流

build-docker-images.yml 工作流自动构建 Docker image 并将其推送到 DockerHub：

• 按每日调度运行
• 构建所有三个 Docker images（CPU、GPU、GPU-Dev）
• 将它们推送到 huggingface 组织下的DockerHub
• 也可以手动触发

Docker 测试工作流程

当 Dockerfile 发生更改时，test-docker-build.yml 工作流程会确保构建成功：

• 触发修改 Dockerfile 文件的拉取请求
• 检测哪些 Dockerfile 已更改
• 仅构建修改后的 Dockerfile
• 在合并前验证构建是否成功完成

使用 Docker 进行夜间测试

nightly-tests.yml 工作流使用 Docker 容器进行全面测试：

• 在 CPU 机器上使用 lerobot-cpu image
• 运行测试 在 GPU 机器上使用 lerobot-gpu image
• 运行测试在两种环境中执行端到端测试

Docker CI/CD 工作流

。。。。。。待续。。。。。。