首页 / Robot / 数据采集 / LeRobot 数据格式
01 LeRobot · Dataset v3.0

LeRobot 数据格式 v3.0

面向机器人学习的标准化时序格式:多相机视频、状态与动作、任务语言指令统一组织。 可本地录制、Hub 托管,也可流式训练。本文对应 codebase_version = v3.0。

1. 组织形式

v3 的核心原则是存储与 API 解耦:磁盘上把多 episode 拼进少量大文件; 对用户仍按 episode / frame 访问。布局由三块组成。

01 · TABULAR

表格 · Parquet

状态、动作、时间戳等低维高频信号按帧写入。多个 episode 连续拼进同一 file-*.parquet。

02 · VISUAL

视觉 · MP4

每个相机一条视频流,多 episode 在时间轴上拼接;靠 from/to_timestamp 切回单集。

03 · METADATA

元数据 · 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,默认:

meta/info.json · path templates
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 如何定位分片

训练侧样本字典

3. 使用方式

从录制、加载、训练到 Hub 发布,都走同一套 LeRobotDataset API。

STEP 01
录制 lerobot-record 写入缓冲帧,save_episode 落盘
STEP 02
Finalize 关闭 parquet writer,写齐 footer / 元数据
STEP 03
推送 Hub push_to_hub,打上 v3.0 版本 tag
STEP 04
加载训练 LeRobotDataset + DataLoader / streaming
STEP 05
策略消费 stats 归一化 · task 条件 · 图像增强

录制

CLI · lerobot-record
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
Python · create / add_frame / finalize
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()

加载与训练

lerobot.datasets.LeRobotDataset
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)

流式训练(不先整包下载)

CLI / StreamingLeRobotDataset
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 数 文件数随分片策略缓慢增长
convert v2.1 → v3.0
python -m lerobot.scripts.convert_dataset_v21_to_v30 --repo-id=<HF_USER/DATASET_ID>
浏览器预览: LeRobot Dataset Visualizer · 文档: LeRobotDataset v3.0