LeRobot 数据格式 v3.0
面向机器人学习的标准化时序格式:多相机视频、状态与动作、任务语言指令统一组织。
可本地录制、Hub 托管,也可流式训练。本文对应 codebase_version = v3.0。
1. 组织形式
v3 的核心原则是存储与 API 解耦:磁盘上把多 episode 拼进少量大文件; 对用户仍按 episode / frame 访问。布局由三块组成。
表格 · Parquet
状态、动作、时间戳等低维高频信号按帧写入。多个 episode 连续拼进同一 file-*.parquet。
视觉 · MP4
每个相机一条视频流,多 episode 在时间轴上拼接;靠 from/to_timestamp 切回单集。
元数据 · JSON / Parquet
schema、fps、归一化统计、任务表,以及 episode 在共享文件中的行 / 时间偏移。
dataset/
├── meta/
│ ├── info.json # schema / fps / 路径模板 / 版本
│ ├── stats.json # 全局 mean / std / min / max
│ ├── tasks.parquet # 任务文本 ↔ task_index
│ └── episodes/ # 每集长度、偏移、相机时间窗
│ └── chunk-000/file-000.parquet
├── data/ # 帧级表格(多 episode / 文件)
│ └── chunk-000/file-000.parquet
└── videos/ # 按相机分目录
└── observation.images.laptop/
└── chunk-000/file-000.mp4
路径模板写在 meta/info.json,默认:
data_path = "data/chunk-{chunk_index:03d}/file-{file_index:03d}.parquet"
video_path = "videos/{video_key}/chunk-{chunk_index:03d}/file-{file_index:03d}.mp4"
2. Schema 约定
一切特征以 info.json → features 为准。硬件侧经
hw_to_dataset_features() 映射成统一命名。
| Key | 含义 | 典型 dtype / shape | 存放 |
|---|---|---|---|
observation.state |
关节 / 本体状态向量 | float32 · (D,),names 为电机名 |
Parquet 列 |
action |
控制指令向量 | float32 · (D,) |
Parquet 列 |
observation.images.<cam> |
相机画面(RGB / depth) | video 或 image · (H,W,C) |
MP4 / 图像 |
timestamp |
相对 episode 起点的秒数 | float32 |
Parquet |
frame_index / episode_index / index |
集内帧号 / 集号 / 全局帧号 | int64 |
Parquet(自动) |
task_index → task |
任务语言指令 | 整数索引,加载时查表成字符串 | tasks + 列 |
Episode 如何定位分片
-
表格:
data/chunk_index、data/file_index+dataset_from_index…dataset_to_index -
视频:每相机
videos/<key>/{chunk,file}_index+from_timestamp/to_timestamp - 重建:先找文件,再按行区间 / 时间窗切出单集
训练侧样本字典
observation.state→ Tensor(D,)action→ Tensor(D,)observation.images.*→ Tensor(C,H,W)task→ 自然语言字符串- 可选:
delta_timestamps展开成(T,…)时序窗
3. 使用方式
从录制、加载、训练到 Hub 发布,都走同一套 LeRobotDataset API。
录制
lerobot-record \
--robot.type=so101_follower \
--dataset.repo_id=${HF_USER}/my-task \
--dataset.num_episodes=50 \
--dataset.single_task="Pick the black cube" \
--dataset.streaming_encoding=true
from lerobot.datasets import LeRobotDataset
dataset = LeRobotDataset.create(
repo_id="user/demo", fps=30, features=features, use_videos=True
)
for episode in episodes:
for frame in episode:
dataset.add_frame(frame)
dataset.save_episode()
dataset.finalize() # 必须:否则 parquet 可能损坏
dataset.push_to_hub()
加载与训练
from lerobot.datasets import LeRobotDataset
import torch
ds = LeRobotDataset("lerobot/svla_so101_pickplace")
sample = ds[100]
# sample["observation.state"], sample["action"],
# sample["observation.images.*"], sample["task"]
# 时序窗口:相对当前帧的秒数,须对齐 1/fps
ds = LeRobotDataset(
"yaak-ai/L2D-v3",
delta_timestamps={"observation.images.front_left": [-0.2, -0.1, 0.0]},
)
# → images 形状变为 (T, C, H, W)
loader = torch.utils.data.DataLoader(ds, batch_size=16, num_workers=4)
流式训练(不先整包下载)
lerobot-train \
--dataset.repo_id=yaak-ai/L2D-v3 \
--dataset.streaming=true \
--policy.type=act
from lerobot.datasets import StreamingLeRobotDataset
ds = StreamingLeRobotDataset("yaak-ai/L2D-v3")
meta/stats.json;语言条件策略读 task 字段。
4. 这种数据格式有何特点
相较「一集一文件」的朴素布局,v3 面向百万级 episode、Hub 流式与多模态策略训练做了针对性取舍。
File-based,而非 Episode-based
多集拼大 Parquet / MP4,文件数随数据规模缓慢增长,显著降低 inode 压力与初始化开销,适合对象存储。
元数据驱动的逻辑视图
Episode 边界不靠文件名,而靠行索引与视频时间戳重建。API 仍是「按帧 / 按集」,存储却可自由分片。
模态分离、时序对齐
低维信号走列存 Parquet(快扫、mmap),高带宽相机走压缩视频;用统一
timestamp + fps 约束保证同步。
Schema 自描述 + Hub 原生
info.json 即可预览形状与相机;直接对接 Hugging Face Hub / Storage Bucket,支持
revision 与 streaming 训练。
训练友好的附属信息
内置全局统计量(归一化)、任务表(语言条件)、可选 Lance 后端(随机访问 / 索引),一条链路打通录制→训练。
可扩展但不失约定
命名空间稳定(observation.* / action);自定义相机、深度图、语言列可挂进
features,策略侧有统一转换。
5. 相对 v2.x 的变化
若手头仍是 v2.1 数据集,可用官方转换脚本聚合为 v3.0。
| 维度 | v2.0 / v2.1 | v3.0 |
|---|---|---|
| 表格路径 | data/.../episode_XXXXXX.parquet |
data/.../file-YYY.parquet + 行区间 |
| 视频路径 | 每 episode 一个 mp4 | 拼接 mp4 + from/to_timestamp |
| Episode 元数据 | episodes.jsonl |
meta/episodes/*.parquet |
| 任务表 | tasks.jsonl |
tasks.parquet |
| 规模表现 | 文件数 ∝ episode 数 | 文件数随分片策略缓慢增长 |
python -m lerobot.scripts.convert_dataset_v21_to_v30 --repo-id=<HF_USER/DATASET_ID>