sim2lerobot 文档

主题

LeRobot 版本研究：PyPI 包版本 ↔ Dataset 格式版本 ​

TL;DR ​

项决策
L3 venv 装哪个 PyPI 包lerobot==0.3.3
L3 venv Python3.12（与 L2 venv 对齐）
输出 dataset 格式meta/info.json 里 codebase_version: "v2.1" + 全局 meta/stats.json（带 q01/q99 6 字段）[1]
L2 venv torch / IsaacSim不动（torch==2.10.0 cu128 是 IsaacSim 6.0.0 硬要求，所以 lerobot 必须装在独立 L3 venv）

一句话：0.3.3 是最后一个 default 写 codebase_version=v2.1 的 PyPI 发布[2]，下一版 0.4.0 起 default 切到 v3[3]，再装更新版只会徒增一步反向转换。

背景：两个独立的 "版本号" ​

NOTE

讨论 LeRobot 必须把这两件事分开：

  • lerobot PyPI 包版本（0.3.3 / 0.5.1 / …）：pip install lerobot==X.Y.Z，是 Python 库本身。
  • LeRobot Dataset 磁盘格式版本（v2.0 / v2.1 / v3.0）：写在 dataset meta/info.json 的 codebase_version 字段。

GR00T 要求的是后者的 v2，与 PyPI 包号无关。每个 PyPI 版本都能读 v2.0/v2.1（通过 check_version_compatibility），但写只用一个全局常量 CODEBASE_VERSION。

PyPI ↔ Dataset 默认 default 对应表 ​

来源：直接 WebFetch 各 tag 下 src/lerobot/datasets/lerobot_dataset.py 顶部的 CODEBASE_VERSION 常量（>=0.5.0 后被拆到 dataset_metadata.py）。

PyPI 版本发布默认写出requires-pythontorch 范围
0.3.22025-08-01v2.1——
0.3.32025-08-06v2.1（最后一版 default v2）[2:1]>=3.10[4]>=2.2.1,<2.8.0[4:1]
0.4.02025-10-23v3.0（v3 转折点）[3:1][5]>=3.10>=2.2.1,<2.8.0
0.4.1–0.4.42025–2026v3.0[6]同 0.4.0同 0.4.0
0.5.02026-03-09v3.0>=3.12>=2.7,<2.11.0
0.5.12026-04-07v3.0[7]>=3.12[8]>=2.7,<2.11.0[8:1]

NOTE

v0.2.x 在 PyPI history 看不到，可能未发或被 yank。

为什么不是 0.4.x / 0.5.x ​

  • 0.4.x：torch 上限仍 <2.8.0，没改善依赖冲突，但 default 已 v3，反而要再跑一次 v3→v2.1 转换[9]，没好处。
  • 0.5.x：torch >=2.7,<2.11.0 数字范围能装 torch 2.10，但 default 是 v3 必须额外反转。即便能跟 L2 venv 共享 torch 版本号，依赖冲突的根源不只是 torch（还有 huggingface_hub / datasets / pyav / torchcodec 等），所以 "共享 torch" 不是把 lerobot 塞回 L2 venv 的充分理由——L3 独立 venv 仍是首选。
  • 在 0.5.x 上强制写 v2 不可行（不打补丁）：CODEBASE_VERSION 是模块级常量，被 LeRobotDatasetMetadata.create() 当 create_empty_dataset_info(...) 实参用，签名没有 codebase_version 参数；唯一官方转换脚本是正向的 convert_dataset_v21_to_v30.py[10]，反向脚本只在 NVIDIA 那边[9:1]。Monkey-patch CODEBASE_VERSION = "v2.1" 会写出 "v2.1 标记 + v3 布局" 的混合体（meta/episodes 是 parquet 而非 jsonl）——不要走这条路。

L3 venv 的额外考虑 ​

  • L2 venv 用 cu128（Blackwell）；L3 venv 不需要跟 L2 共享 GPU stack。HDF5 → parquet + mp4 是 CPU 工作（cv2.VideoWriter 走 ffmpeg / mp4v），装 CPU torch wheel 即可，绕过 cu128 wheel 是否齐全的问题。
  • convert.py 实际不依赖 lerobot 运行时（只用 h5py + numpy + pandas），保留 lerobot==0.3.3 在 venv 里只为后续 dataset load 验证用。
  • 实测 uv sync 装的是 cu12 wheel（lerobot 0.3.3 间接依赖 torchcodec 等），但 convert 不用 GPU。

GR00T 1.7 端的约束 ​

GR00T 训练/推理本身不依赖 lerobot 库（Isaac-GR00T/pyproject.toml 和 uv.lock 里没有该依赖[11]），只直接读盘上文件，所以 PyPI 版本怎么 pin 由我们这边自己决定。

但 GR00T 1.7 对 dataset 内容有强约束：meta/stats.json 必须存在、每个 float feature 必须含 mean/std/min/max/q01/q99 6 字段[1:1]。lerobot v2.1 库默认输出的是 per-episode episodes_stats.jsonl（不带 q01/q99），跟 GR00T 1.7 期望的 v2.0 风格全局 stats.json 不兼容——所以 l3/convert.py 必须自己按 GR00T 1.7 demo dataset 的 schema 写 stats，不能直接用 lerobot 库的 LeRobotDataset.create() 出统计。详见 GR00T 1.7 Dataset 约束。

v3 转折点考古（背景资料） ​

  • 主体 PR：#1412 "Dataset v3"[5:1]，2025-09-15 合入主线（merge commit f55c6e8），共 151 commits。第一个把 default 切到 v3 的 PyPI 发布是 v0.4.0（release notes "What's Changed" 列表里能看到 "Dataset v3 (#1412)"，并非头条）。
  • 早期 v2.0 → v2.1 的 PR 是 #521 + #711，2025-02-25 合入。
  • NVIDIA 的反向脚本 convert_v3_to_v2.py[9:2] 头部注释："needs lerobot version atleast after commit f55c6e89f"、"Tested on lerobot version 0.4.0 (commit: f25ac02)"。

  1. GR00T 1.7 源码 verify（commit 23ace64）：Isaac-GR00T/gr00t/data/dataset/lerobot_episode_loader.py:182-185 硬 assert meta/stats.json 必须存在；Isaac-GR00T/gr00t/data/stats.py:104-112 严格要求每个 float feature 含 mean/std/min/max/q01/q99 6 字段。详见 docs/schema/gr00t-1-7-dataset-constraints.md。 ↩︎ ↩︎

  2. v0.3.3/src/lerobot/datasets/lerobot_dataset.py 顶部 CODEBASE_VERSION = "v2.1"。 ↩︎ ↩︎

  3. v0.4.0/src/lerobot/datasets/lerobot_dataset.py 顶部 CODEBASE_VERSION = "v3.0"。 ↩︎ ↩︎

  4. v0.3.3/pyproject.toml：requires-python = ">=3.10"，torch>=2.2.1,<2.8.0。 ↩︎ ↩︎

  5. lerobot PR #1412 "Dataset v3"。 ↩︎ ↩︎

  6. v0.4.4/src/lerobot/datasets/lerobot_dataset.py 顶部 CODEBASE_VERSION = "v3.0"（v0.4.1–v0.4.3 同主线，未逐字 verify）。 ↩︎

  7. v0.5.1/src/lerobot/datasets/dataset_metadata.py：CODEBASE_VERSION = "v3.0"（v0.5.x 把常量从 lerobot_dataset.py 拆到独立模块）。 ↩︎

  8. v0.5.1/pyproject.toml：requires-python = ">=3.12"，torch>=2.7,<2.11.0。 ↩︎ ↩︎

  9. NVIDIA 自带反向脚本：Isaac-GR00T/scripts/lerobot_conversion/convert_v3_to_v2.py。 ↩︎ ↩︎ ↩︎

  10. lerobot 仓库自带正向脚本 src/lerobot/scripts/convert_dataset_v21_to_v30.py，不提供 v3 → v2 反向脚本。 ↩︎

  11. Isaac-GR00T/pyproject.toml 主依赖列表里没有 lerobot；唯一的 pin 在子项目 scripts/lerobot_conversion/pyproject.toml 第 16 行：lerobot @ git+https://github.com/huggingface/lerobot.git@c75455a6de5c818fa1bb69fb2d92423e86c70475，对应 commit message chore(dependecies): Bump lerobot to 0.4.1 (#2299)、commit date 2025-10-23（本仓库 Isaac-GR00T 子目录第 16 行也能直接 verify），仅供该转换脚本使用。 ↩︎