LeRobot v3.0 迁移教程v2.1 数据集格式升级的完整决策指南【免费下载链接】lerobot LeRobot: Making AI for Robotics more accessible with end-to-end learning项目地址: https://gitcode.com/GitHub_Trending/le/lerobot本文面向需要升级 LeRobot 数据集格式的用户系统讲清 LeRobot v3.0 迁移这件事v2.1 与 v3.0 两种格式的差异在哪里、三类迁移工具分别适合什么场景、从本地小数据集到 TB 级 DROID 数据该走哪条路以及迁移完成后如何校验。全文以先判断场景 → 再选路线 → 最后落地校验的决策路径组织命令和参数均来自仓库内实际脚本。一、先看懂格式差异v2.1 和 v3.0 到底改了什么在做 LeRobot v2.1 升级 v3.0 之前值得花两分钟理解结构变化本身因为它决定了为什么大文件数、小片段的数据集在旧格式下越来越慢。两种格式的目录布局对比如下# v2.1一个 episode 对应一组独立文件 dataset/ ├── data/chunk-000/episode_000000.parquet ├── data/chunk-000/episode_000001.parquet ├── videos/chunk-000/camera/episode_000000.mp4 └── meta/episodes.jsonl # v3.0多个 episode 合并进文件块file-based chunks dataset/ ├── data/chunk-000/file-000.parquet # 一个文件装多个 episode ├── videos/camera/chunk-000/file-000.mp4 # 视频按相机文件块组织 └── meta/episodes/chunk-000/file-000.parquet # 元数据从 JSONL 换成 Parquet维度v2.1v3.0实际影响数据组织每 episode 一个 parquet 一个 mp4多个 episode 合并进同一文件块文件数量大幅下降初始化不再受海量小文件拖累元数据meta/episodes.jsonlJSON Linesmeta/episodes/chunk-*/file-*.parquet支持 DataFrame 直接读取episode 边界靠偏移量定位统计信息全局stats.json逐 episode 统计 聚合统计便于按 episode 做归一化和校验访问方式以文件名为单位支持内存映射与流式读取StreamingLeRobotDataset可不落盘消费千万级 episode、TB 级数据才有可用空间一句话概括v2.1 是按 episode 建文件v3.0 是按文件大小建块、用元数据找回 episode。官方对加载性能的官方口径是初始化耗时降至原来的 1/3 ~ 1/5具体收益与文件数、episode 长度强相关。决策提示episode 数在几千以内、单机训练跑得动迁移收益有限一旦 episode 数上万、或者需要上 Hub 共享 / 流式训练v3.0 迁移就值得做。二、三种迁移路线怎么选仓库里可用的迁移入口一共三类先对号入座再往下看对应章节你的场景推荐工具入口适合量级手头是已有的 LeRobot v2.1 数据集本地或 Hub 上官方转换脚本src/lerobot/scripts/convert_dataset_v21_to_v30.py单数据集百 GB 级以内要把DROID 等第三方格式导入 v3.0移植示例脚本examples/port_datasets/port_droid.py单机可跑完为止第三方数据超过 1TB / 需要并行SLURM 集群脚本组examples/port_datasets/ 下slurm_*.py三件套DROID 全量1.7TB、2048 分片级别三条路线的关系可以这样理解转换脚本是格式翻译port 脚本是格式翻译 并行切分SLURM 三件套是把 port 脚本的切分能力放到集群上跑。它们不是并列的竞品而是按数据量级递进的。三、先跑通转换一个已有的 v2.1 数据集这是最小可复现的路径建议在正式迁移大仓库之前先用它走一遍流程。3.1 转换 Hub 上的数据集确认本地 lerobot 已包含 v3.0 支持pip install -U lerobot或从源码构建然后python src/lerobot/scripts/convert_dataset_v21_to_v30.py \ --repo-id your_namespace/your_dataset脚本会在 Hub 的main分支推送 v3.0 版本并打上v3.0tag。它实际做了四件事逐 episode 重新计算统计量、把分 episode 的 parquet/mp4 聚合为文件块、清理过期的stats.json、更新info.json中的版本字段。3.2 转换本地数据集就地处理python src/lerobot/scripts/convert_dataset_v21_to_v30.py \ --repo-id your_namespace/your_dataset \ --root /path/to/local_dataset \ --push-to-hub false关键参数说明参数默认值说明--repo-id必填数据集仓库标识--root$HF_LEROBOT_HOME/{repo_id}本地数据集目录须为包含meta/、data/、videos/的那一层--data-file-size-in-mb100聚合后单个 parquet 块的目标大小--video-file-size-in-mb500聚合后单个 mp4 块的目标大小--push-to-hubtrue本地转换时建议显式设为 false--force-conversionfalse已存在 v3.0 版本时是否强制重转块大小参数决定了一个文件装多少 episode。episode 普遍很长例如 10 分钟以上的完整任务时可以适当调大视频块避免块数虚高。四、把第三方数据搬进 v3.0DROID 数据集为例如果你的数据不是 LeRobot 格式比如 DROID 的 RLDS/TensorFlow 格式目标就是边读取、边按 v3.0 布局写出这条路线由 port 脚本承担。以 DROID 为例它是 76,000 条真实操作轨迹、2048 个预切好的 TensorFlow 分片。4.1 准备依赖与原始数据# 读取 RLDS 格式所需 pip install tensorflow tensorflow_datasets # 全量下载约 1.7TB开发阶段建议先拉 2GB 的 100-episode 样本 gsutil -m cp -r gs://gresearch/robotics/droid_100 /data/droid_test4.2 单分片试跑验证链路在做 DROID 数据集转 v3.0 这类重活之前先用单个分片把整条链路跑通python examples/port_datasets/port_droid.py \ --raw-dir /data/droid_test \ --repo-id your_namespace/droid_test \ --num-shards 2048 \ --shard-index 0单分片能跑通写出目录结构、能加载、帧数对得上再考虑全量。加--push-to-hub可把结果直接推上 Hub不加分片参数则是单机串行处理整个数据集——对全量 DROID 而言官方实测需要 7 天以上这就是下一章集群方案的用武之地。五、TB 级数据该走集群SLURM 加速迁移流程SLURM 集群加速迁移的核心思路是port 脚本本身就支持按分片切分--num-shards/--shard-indexSLURM 三件套只是把这个切分能力包装成任务队列每个 worker 负责一个分片各自写一个独立的 shard 仓库最后统一聚合。5.1 环境与资源检查pip install datatrove # Hugging Face 的分布式任务执行库集群脚本的底座 sinfo --format%R # 列出可用分区 sinfo -N -p cpu_partition -h -o %N cpus%c mem%m数据集迁移是纯 CPU 任务选 CPU 分区即可无需 GPU。5.2 三步走分片 → 聚合 → 上传第一步分片并行迁移python examples/port_datasets/slurm_port_shards.py \ --raw-dir /data/droid_raw \ --repo-id your_namespace/droid_v3 \ --logs-dir /data/logs/porting \ --job-name droid_port \ --partition cpu_high \ --workers 2048 \ --cpus-per-task 8 \ --mem-per-cpu 1950M参数选择依据--workers并行任务数。DROID 有 2048 个分片任务数即分片数--cpus-per-task 8帧编码需要多核并行8 核是经验值--mem-per-cpu 1950M合计约 16GB/任务用于加载原始帧并编码。⚠️ 提交 2048 个任务前建议先把--workers降到 50~100 试跑一轮确认分区配额、日志路径、凭据都没问题。第二步监控与排障squeue -u $USER # 查看队列中自己的任务 # 找出未完成/失败的分片及其日志 python examples/port_datasets/display_error_files.py \ --logs-dir /data/logs/porting --job-name droid_portdisplay_error_files.py会比对completions目录与world_size列出缺失 worker 索引并定位对应的slurm_jobs/*.out日志文件。失败的分片只需针对其 shard 索引重跑不必全量重来。第三步聚合与上传# 把 2048 个 shard 仓库合并为一个数据集 python examples/port_datasets/slurm_aggregate_shards.py \ --repo-id your_namespace/droid_v3 \ --logs-dir /data/logs/aggregation \ --job-name droid_agg \ --partition cpu_high # 并行上传到 Hub网络瓶颈任务worker 数少很多即可 python examples/port_datasets/slurm_upload.py \ --repo-id your_namespace/droid_v3 \ --logs-dir /data/logs/upload \ --job-name droid_upload \ --partition cpu_high \ --workers 50上传阶段是网络密集型而非计算密集型50 个 worker 通常足够。另外如果集群镜像可以装hf-transfer并设置HF_HUB_ENABLE_HF_TRANSFER1上传速度会有明显提升slurm_upload.py在未启用时会主动告警提醒。六、迁移后如何校验三步确认迁移完成不等于数据正确建议按结构 → 元数据 → 训练加载三层验证第 1 步目录结构ls -R /path/to/dataset | head -30应看到data/chunk-000/file-000.parquet、videos/camera/chunk-000/file-000.mp4、meta/episodes/chunk-000/file-000.parquet这类文件块命名且不再有episode_*.parquet。第 2 步元数据一致性from lerobot.datasets import LeRobotDataset ds LeRobotDataset(your_namespace/droid_v3) print(ds.meta.codebase_version) # 应显示 v3.0 print(len(ds.meta.episodes)) # episode 总数应与源数据一致 print(ds.meta.episodes) # 可直接当 pandas DataFrame 查看长度/任务/偏移量逐 episode 统计episodes_stats在转换/聚合时已重新计算并和旧统计做过一致性比对重点核对 episode 总数和总帧数两个数字即可。第 3 步抽样读取sample ds[100] # 随机取一条确认 observation.state / action / 图像字段齐全如果能正常抽帧再用StreamingLeRobotDataset(your_namespace/droid_v3)验证流式读取路径不落盘直接迭代这正好是 v3.0 格式带来的新能力。七、常见问题速查症状可能原因处理方式本地加载报版本/格式不兼容Hub 缓存的是旧版本快照清除本地缓存$HF_LEROBOT_HOME下对应 repo 目录与 HF datasets 缓存后重新拉取parquet 文件打开报损坏录制/写入时未调用dataset.finalize()关闭 writer对数据集重新finalize()详见 docs/source/lerobot-dataset-v3.mdx 的 Common Issues视频编码任务在集群中超时单分片过大或节点内存不足调低--mem-per-cpu上限内加大内存或减少单任务处理的帧范围用display_error_files.py定位失败分片后定点重跑上传阶段明显慢未启用hf-transfer或 worker 过多互相争抢带宽安装hf-transfer并设置HF_HUB_ENABLE_HF_TRANSFER1worker 控制在几十以内磁盘空间不够转换/聚合过程产生中间文件目标盘预留至少源数据 1.5~2 倍空间写在最后LeRobot v3.0 迁移可以归纳为一条决策链小数据集用转换脚本一条命令解决第三方格式用 port 脚本先单分片试跑TB 级数据交给 SLURM 三件套分片并行最后聚合上传。工具入口集中在 examples/port_datasets/ 与 src/lerobot/scripts/原理与完整参数文档可参考 docs/source/porting_datasets_v3.mdx 和 docs/source/lerobot-dataset-v3.mdx。需要源码复现时可先克隆仓库git clone https://gitcode.com/GitHub_Trending/le/lerobot再按上文路径定位脚本。迁移是格式升级中的一次性成本换来的是文件数量、加载速度和流式训练能力上的长期收益——数据量越大这笔账越划算。【免费下载链接】lerobot LeRobot: Making AI for Robotics more accessible with end-to-end learning项目地址: https://gitcode.com/GitHub_Trending/le/lerobot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
