LeRobot 数据集 v2.1 → v3.0 迁移记录

- 问题描述
- [v2.1 → v3.0 格式差异](#v2.1 → v3.0 格式差异)
- 处理步骤
- - [步骤 1：修复 episodes_stats.jsonl 格式](#步骤 1：修复 episodes_stats.jsonl 格式)
  - [步骤 2：运行 v2.1 → v3.0 转换脚本](#步骤 2：运行 v2.1 → v3.0 转换脚本)
  - [步骤 3：验证](#步骤 3：验证)
- 备注

问题描述

使用 lerobot-train 训练 pi0.5 模型时，数据集加载失败：

复制代码

NotImplementedError: Contact the maintainer on Discord.

根本原因 : 数据集的 codebase_version 为 v2.1，但当前 lerobot 代码库要求 v3.0 格式。v2.1 和 v3.0 之间存在不兼容的结构变化。

v2.1 → v3.0 格式差异

内容	v2.1 格式	v3.0 格式
数据文件	`data/chunk-000/episode_000000.parquet`	`data/chunk-000/file-000.parquet`
视频文件	`videos/chunk-000/{camera}/episode_000000.mp4`	`videos/{camera}/chunk-000/file-000.mp4`
Episodes 元数据	`meta/episodes.jsonl`	`meta/episodes/chunk-000/file-000.parquet`
Tasks 元数据	`meta/tasks.jsonl`	`meta/tasks.parquet`
统计数据	`meta/episodes_stats.jsonl` + `meta/stats.json`	`meta/stats.json`（aggregated）

处理步骤

步骤 1：修复 episodes_stats.jsonl 格式

转换脚本对统计数据的格式有严格验证，要求所有值（包括 count）都是数组格式。

原始 episodes_stats.jsonl 中 count 字段是标量（如 285），需要转为数组（如 [285]）。

python 复制代码

import json

input_path = 'data/dataset_2026-03-13_17-00-18/meta/episodes_stats.jsonl'
output_path = 'data/dataset_2026-03-13_17-00-18/meta/episodes_stats_fixed.jsonl'

with open(input_path) as f_in, open(output_path, 'w') as f_out:
    for line in f_in:
        entry = json.loads(line)
        for feat_key, feat_stats in entry['stats'].items():
            for stat_key, stat_value in feat_stats.items():
                if not isinstance(stat_value, list):
                    feat_stats[stat_key] = [stat_value]
        f_out.write(json.dumps(entry) + '\n')

然后替换原文件：

bash 复制代码

cp meta/episodes_stats.jsonl meta/episodes_stats.jsonl.bak
mv meta/episodes_stats_fixed.jsonl meta/episodes_stats.jsonl

步骤 2：运行 v2.1 → v3.0 转换脚本

bash 复制代码

cd /home/xxx/Project/xxxxxx_vla_train/lerobot

python -m lerobot.datasets.v30.convert_dataset_v21_to_v30 \
    --repo-id=dataset_2026-03-13_17-00-18 \
    --root=/home/xxx/Project/fawbot_vla_train/data \
    --push-to-hub=false \
    --force-conversion

参数说明:

--repo-id: 设置为数据集目录名（因为本地转换时，脚本会拼接 root/repo-id 作为数据集路径）
--root: 数据集的父目录
--push-to-hub=false: 不推送到 HuggingFace Hub
--force-conversion: 跳过 Hub 上的 v3.0 检查

转换过程:

转换 info.json（更新版本号、路径模板等）
转换 tasks.jsonl → tasks.parquet
合并数据文件：104 个 episode_*.parquet → file-000.parquet
合并视频文件：4 个摄像头 × 104 集 → 按大小合并为多个 file-*.mp4
转换 episodes 元数据为 parquet 格式
聚合统计数据写入 stats.json
自动完成目录替换（原目录 → _old，新目录 → 原路径）

步骤 3：验证

转换后的目录结构：

复制代码

dataset_2026-03-13_17-00-18/
├── data/chunk-000/file-000.parquet
├── meta/
│   ├── info.json                          (codebase_version: v3.0)
│   ├── stats.json
│   ├── tasks.parquet
│   └── episodes/chunk-000/file-000.parquet
└── videos/
    ├── observation_images_chest/chunk-000/file-{000..003}.mp4
    ├── observation_images_head/chunk-000/file-{000..001}.mp4
    ├── observation_images_left_wrist/chunk-000/file-{000..003}.mp4
    └── observation_images_right_wrist/chunk-000/file-{000..003}.mp4

原始 v2.1 数据备份在 dataset_2026-03-13_17-00-18_old/。

备注

训练脚本 train.sh 中的 --dataset.root 路径无需修改，因为转换脚本自动将新数据放回原路径
如需回滚，可将 _old 目录重命名为原目录名