LeRobot 框架的开发指南 （下）

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

。。。。。。继续。。。。。。

在此记录 LeRobot 项目中使用的测试框架，涵盖本地开发测试和持续集成工作流程。本指南将帮助开发者了解如何在代码库中编写、运行和自动化测试。

测试架构

LeRobot 框架采用全面的测试策略，包含多层验证，从本地开发检查到自动化 CI/CD 流水线。

测试组件概述

本地测试

预提交 hooks

预提交 hooks 在每次提交前自动运行，以便在开发过程的早期发现问题。这些 hooks 可以强制执行代码质量、代码风格和安全标准。

建立预提交 hooks：

Install pre-commit

pip install pre-commit

Install the hooks

pre-commitinstall

Run all hooks manually (useful before pushing)

pre-commit run --all-files

运行单元测试

LeRobot 使用 pytest 进行单元测试。该测试套件涵盖从数据集到策略的各个组件。
要在本地运行测试：

Run all tests

python -m pytest tests -v

Run tests with coverage report

python -m pytest tests -v --cov=./lerobot

Run a specific test file

python -m pytest tests/path/to/test_file.py

Pytest 会自动发现 tests/ 目录中的测试并运行。测试文件应以 test_ 为前缀命名。

端到端测试

端到端 (E2E) 测试，验证从训练到评估的完整工作流程。它们在 Makefile 中定义，并使用特定数据集测试不同的策略类型。

Run all end-to-end tests

make test-end-to-end

Run a specific end-to-end test

make test-act-ete-train

CI/CD 测试

LeRobot 使用 GitHub Actions 进行持续集成和测试。多个工作流会根据拉取请求和预定时间间隔自动运行。

主测试工作流

主测试工作流根据 Pull 请求运行并推送到主分支。它包括：
完整安装测试 (pytest)
最小安装测试（仅包含核心依赖项的 pytest）
端到端测试

测试工作流程使用 uv（一种 Python 打包工具）来管理依赖项并运行带有覆盖率报告的测试。

质量工作流程

质量工作流程检查代码风格并检测拼写错误：

Docker 构建测试

Docker 构建测试用于验证 Docker image 是否可以成功构建：

当 Dockerfiles 在 PR 中被修改时，这些测试就会运行，确保对容器化的更改不会破坏构建。

夜间测试

夜间测试按每日调度运行更全面的测试套件：

夜间测试在 Docker 容器中运行，确保 CPU 和 GPU 测试的环境一致。

端到端测试

端到端测试验证策略训练和评估的整个工作流程。这些测试使用小型数据集并以最少的步骤运行，但会测试系统的所有组件。

策略端到端测试结构

LeRobot 端到端测试三种策略类型：

1.ACT（动作分块 Transformer）
训练
从检查点恢复训练
评估

2.扩散策略
训练
评估

3.TDMPC（时间差分模型预测控制）
训练
评估

每个测试都使用一个小型环境配置和数据集运行。

示例测试命令

以下是 ACT 策略训练测试命令的示例：

python lerobot/scripts/train.py \
–policy.type=act \
–policy.dim_model=64 \
–policy.n_action_steps=20 \
–policy.chunk_size=20 \
–policy.device=$(DEVICE) \
–env.type=aloha \
–env.episode_length=5 \
–dataset.repo_id=lerobot/aloha_sim_transfer_cube_human \
–dataset.image_transforms.enable=true \
–dataset.episodes=“[0]” \
–batch_size=2 \
–steps=4 \
–eval_freq=2 \
–eval.n_episodes=1 \
–eval.batch_size=1 \
–save_freq=2 \
–save_checkpoint=true \
–log_freq=1 \
–wandb.enable=false \
–output_dir=tests/outputs/act/

测试 artifacts

某些测试需要测试 artifacts（权重、样本数据）才能正常运行。这些工件使用 Git LFS 存储在 tests/artifacts/ 目录中。
设置 Git LFS
要使用测试 artifacts：

Install Git LFS

On Mac

brew install git-lfs
git lfs install

On Ubuntu

sudo apt-get install
git-lfs git lfs install

Pull artifacts if not already present

git lfs pull

安全测试

LeRobot 采用了多种安全扫描工具：

TruffleHog 工作流程在每次推送时运行，以检查是否存在意外的证据暴露。

测试覆盖率

在 CI 运行期间，使用 pytest-cov 跟踪测试覆盖率。覆盖率报告显示测试覆盖了哪些代码部分。

要在本地运行覆盖率测试，执行以下操作：
pytest tests -v --cov=./lerobot --cov-report=xml

编写测试

为 LeRobot 项目编写新测试时，遵循以下准则：
将测试放置在 tests/ 目录中的适当位置
使用 test_ 前缀命名测试文件
使用 test_ 前缀命名测试函数
使用 pytest 夹具进行通用设置
测试成功和失败的情况
保持测试快速且独立

测试结构示例：
deftest_feature_behavior():
# Setup
# Execute
# Assert

指标追踪

LeRobot 提供用于在测试和训练过程中追踪指标的工具。MetricsTracker 类提供诸如损失、已处理样本和 epochs 等指标的标准化报告：

在此记录 LeRobot 框架中使用的持续集成和持续部署 (CI/CD) 工作流程。这些自动化流水线可确保代码质量、验证测试覆盖率、构建 Docker image 并执行安全扫描。

CI/CD 工作流程概述

LeRobot 使用 GitHub Actions 进行 CI/CD，其中包含几个专门的工作流程，用于处理开发过程的不同方面：

测试工作流程

主要测试工作流程

当 pull 请求或推送到主要分支影响代码库中的相关路径时，test.yml 工作流程将运行：

这个工作执行不同类型的测试：

夜间测试工作流程

nightly-tests.yml 工作流程使用 Docker 容器按计划运行全面测试：

代码质量工作流程

质量工作流程

quality.yml 工作流程强制执行代码风格并检查拼写错误：

此工作流程使用与 .pre-commit-config.yaml 中配置的预提交 hooks 相同的工具，确保本地开发环境和持续集成环境之间的一致性。

Docker 工作流程

Docker 构建工作流程

build-docker-images.yml 工作流程创建 Docker 镜像并将其推送到 DockerHub：

Docker 测试工作流程

test-docker-build.yml 工作流程无需推送到 DockerHub 即可测试 Docker 构建：

安全工作流程

trufflehog.yml 工作流程会扫描代码库中潜在的安全问题：

工作流触发器和路径

CI/CD 工作流使用各种触发条件来确定何时运行：

对于test.yml来说，触发工作流的具体路径包括：

lerobot/**
tests/**
examples/**
.github/**
pyproject.toml
.pre-commit-config.yaml
Makefile
.cache/**

环境和依赖项

所有工作流程均使用 Python 3.10 作为标准 Python 版本。测试工作流程使用 uv（版本 0.6.0）进行依赖项管理，与传统方法相比，它能够提供更快、更可靠的软件包安装。

对于基于 Docker 的测试，代码库维护三个 Docker images：

与开发工作流集成

CI/CD 工作流旨在与开发流程无缝协作。它们有助于确保：
代码更改在合并前经过适当测试
保持代码风格一致性
定期构建和测试 Docker image
及早发现安全问题

在为 LeRobot 贡献代码时，开发者应：
在推送代码前在本地运行预提交 hooks（与质量工作流中使用的工具相同）
确保在提交 PR 前在本地通过测试
注意触发特定工作流的路径

结论

LeRobot 的 CI/CD 工作流提供了一个全面的系统，用于维护代码质量、测试覆盖率和安全性。它们旨在在相关事件发生时自动运行，也可在需要时手动触发。

在此提供为 LeRobot 项目做出贡献的全面指南。无论是修复错误、添加新功能、改进文档还是报告问题，本指南都能帮助了解贡献流程。

贡献方式

LeRobot 项目欢迎各种类型的贡献：
修复现有代码中未解决的问题
实现新的模型、数据集或模拟环境
为示例或文档做出贡献
提交与错误或所需新功能相关的问题
帮助社区中的其他人（Discord、GitHub 问题）
贡献工作流程
设置开发环境

在贡献之前，需要设置开发环境：

1.复制并克隆代码库：
git clone [e-mail]:<你的 Github 用户名>/lerobot.git
cd lerobot
git remote add upstream https://github.com/huggingface/lerobot.git

2. 创建开发分支：
   git checkout main
   git fetch upstream
   git rebase upstream/main
   git checkout -b your-feature-branch

3. 设置开发环境：
   使用 conda：
   conda create -y -n lerobot-dev python=3.10 && conda activate lerobot-dev
   使用 uv：
   uv venv --python 3.10 && source .venv/bin/activate

4. 安装依赖项：
   开发环境：uv sync --extra dev --extra test 或 poetry sync --extras “dev test”
   完整安装：uv sync --all-extras 或 poetry sync --all-extras

5. 安装预提交 hooks：
   pre-commitinstall

进行更改并提交 Pull 请求

在分支上开发功能或修复问题
运行测试以验证更改：
pytest tests/<TEST_TO_RUN>.py

运行预提交 hooks：
pre-commit run --all-files

推送更改：
git push -u origin your-feature-branch

按照 PR 模板在 GitHub 上创建 pull 请求
处理来自代码审查的任何反馈

代码质量标准

LeRobot 通过自动化工具和流程保持高代码质量标准：

预提交 hooks

该项目使用多个预提交 hooks 来确保代码质量：

使用以下命令运行预提交检查：
pre-commit run --all-files

持续集成

LeRobot 使用 GitHub Actions 构建 CI/CD 流水线，以确保代码质量并维护 Docker image：

测试工作流

测试贡献

LeRobot 包含一个全面的测试套件，用于确保代码质量和验证功能：
1.安装 git-lfs 以检索测试工件：

Ubuntu

sudo apt-get install git-lfs
git lfs install

Mac

brew install git-lfs
git lfs install

2. 运行测试：
   python -m pytest -sv ./tests

3. 测试特定组件：
   pytest tests/<TEST_FILE>.py::test_function

添加新组件

在 LeRobot 中实现新组件时，遵循以下指南：

添加新策略

在 lerobot/init.py 中更新 available_policies 和 available_policies_per_env
在策略类中设置所需的 name 类属性
通过导入新的策略类来更新 tests/test_available.py 中的变量

添加新数据集

在 lerobot/init.py 中更新 available_datasets_per_env
确保数据集与 LeRobotDataset API 兼容

添加新环境

在 lerobot/init.py 中更新 available_tasks_per_env 和 available_datasets_per_env
按照标准 API 设计实现环境

问题报告

错误报告

报告错误时，包含以下内容：
操作系统类型和版本、Python 和 PyTorch 版本
一段简短、完整的代码片段，用于重现错误
如果出现异常，提供完整的回溯
其他信息，例如可能有用的屏幕截图

功能请求

请求功能时，包含以下内容：
动机（问题/挫折、项目需求、社区效益）
一段描述该功能的段落
一段演示其未来用途的代码片段（snippet）
相关论文链接（如适用）
其他信息（图表、屏幕截图）

Pull 请求流程

提交 Pull 请求时：
提供描述性标题，概述贡献
参考相关问题
将正在进行的 pull 请求标记为 [WIP] 或草稿 pull 请求
确保现有测试通过
描述变更的测试方式
提供审阅者签出并尝试变更的步骤

LeRobot 开发架构

该图说明 LeRobot 项目中的开发工作流程如何与 CI/CD 流水线和代码质量工具集成。

组件添加过程

该图展示向 LeRobot 添加新组件的过程以及它们如何融入现有架构。

结论

为 LeRobot 贡献代码是一个协作的过程，有助于每个人改进框架。遵循本文档中的指南，可以确保贡献有效地融入项目。