LeRobot v3.0 数据集格式：从设计理念到实战加载的深度解析

1. 为什么我们需要LeRobot v3.0？一个数据格式的“哲学”转变

如果你和我一样，在机器人学习领域摸爬滚打了好些年，肯定没少和数据格式“打架”。早期做项目，最头疼的就是数据。一个任务下来，状态数据是CSV，图像是一堆JPG散落在不同文件夹里，动作记录在另一个TXT里，元数据还得自己写个JSON来关联。训练模型前，光写数据加载和清洗的代码就得花上一两周，更别提团队协作时，每个人定义的数据结构都不一样，合并起来简直是灾难。

这就是LeRobot v3.0诞生的背景。它不是一个简单的版本升级，而是一次从“文件管理思维”到“数据服务思维”的根本性转变。Hugging Face团队这次下了狠心，要解决机器人学习数据处理的几个核心痛点：海量小文件导致的I/O瓶颈、数据加载慢、以及跨团队协作的标准化难题。

v3.0的设计理念，我总结下来就两个词：解耦与聚合。

解耦，指的是把“数据怎么存”和“用户怎么用”彻底分开。以前我们写代码，经常要关心文件路径、命名规则（比如episode_001.pkl）。在v3.0里，你完全不用管数据是存在一个文件里还是一百个文件里。你只需要告诉数据集：“我要第5个episode的第120帧”，它就像个服务生一样，准确无误地给你端上来。底层存储哪怕翻天覆地，你的上层训练代码也一行不用改。

聚合，则是解决性能问题的杀手锏。机器人数据动辄成千上万个episode，如果每个episode都存成独立文件，光是列个文件列表，系统就要卡半天。v3.0把成百上千个小episode打包进少数几个“数据块”（chunk）文件里，格式用了高效的列式存储Parquet和视频编码MP4。带来的好处是实实在在的：数据集初始化速度提升了3到5倍，对文件系统的压力骤降，尤其是在网络存储或者直接从Hugging Face Hub流式加载时，体验流畅得不像话。

所以，v3.0格式瞄准的，是那些真正想做大规模、可复现机器人学习的开发者和研究员。它让你从繁琐的数据工程中解脱出来，把精力聚焦在算法和模型本身。接下来，我们就掰开揉碎，看看这套新格式是怎么搭建起来的。

2. 深入核心：三大支柱与目录结构解剖

理解了“为什么”，我们再来看“是什么”。LeRobot v3.0的整个大厦，建立在三根坚实的支柱上：表格数据、视觉数据和元数据。这三者各司其职，又通过元数据精密地联动在一起。

2.1 三大支柱的分工与协作

第一支柱：表格数据。这是机器人的“本体感觉”和“运动指令”存放地。所有结构化的、低维的、高频采样的数据都归它管，比如关节状态、末端执行器位姿、动作指令、力传感器读数、时间戳等等。它的存储格式是Apache Parquet。我实测下来，Parquet的列式存储对机器学习太友好了。当你训练时只需要observation.state和action这两列，系统就只会读取这两列的数据，I/O效率极高，完全避免了读取整行再丢弃无用字段的浪费。这些数据文件存放在 dataset_root/data/chunk-XXX/file-XXX.parquet 这样的路径下。

第二支柱：视觉数据。机器人怎么“看”世界？就靠这里了。所有摄像头图像序列，都被编码成MP4视频文件。这里有个很聪明的设计：它不是按episode，而是按摄像头类型来组织视频流。比如，front_camera的所有帧，无论来自哪个episode，都可能被连续编码进同一个MP4文件里。这样做最大的好处是利于压缩和连续读取。视频编码（如H.264）的压缩率远高于存储一堆PNG或JPEG，而且读取连续帧的速度极快。文件路径模板是 dataset_root/videos/{camera_key}/chunk-XXX/file-XXX.mp4。

第三支柱：元数据。这是整个系统的“大脑”和“地图”。它不存储具体的传感器读数或像素，而是存储关于数据的描述和索引。你可以把它理解为一本详细的图书目录和说明书。元数据告诉系统：数据集里有哪些特征（Schema）、每个特征的形状和类型是什么、数据整体的统计信息（用于归一化）、一共有多少个episode、每个episode的起止点在那些大文件（Parquet/MP4）的什么位置。正是有了这份精确的“地图”，前面提到的“解耦”才得以实现。你通过API请求一个数据点时，系统会先去查元数据这张“地图”，定位到具体文件的精确偏移量，再把数据提取出来给你。

2.2 目录结构：一切皆有规矩

光说概念可能有点虚，我们直接看一个标准v3.0数据集的目录树。这个结构非常清晰，我强烈建议你在自己创建数据集时也严格遵守：

your_dataset_repo/
├── meta/                    # 元数据目录（核心大脑）
│   ├── info.json           # 数据集Schema定义（有什么特征，什么类型）
│   ├── stats.json          # 全局统计信息（均值、标准差，用于归一化）
│   ├── tasks.parquet       # 任务描述映射表（任务ID对应什么文字描述）
│   └── episodes/           # Episode索引目录
│       └── chunk-000/
│           └── file-000.parquet  # 记录每个episode的起止位置等信息
├── data/                   # 表格数据目录（本体感觉）
│   └── chunk-000/
│       └── file-000.parquet      # 存储了多个episode的状态、动作等数据
└── videos/                 # 视觉数据目录（眼睛）
    ├── front_camera/
    │   └── chunk-000/
    │       └── file-000.mp4      # 存储多个episode的前置摄像头视频
    └── wrist_camera/
        └── chunk-000/
            └── file-000.mp4      # 存储多个episode的腕部摄像头视频

我特别喜欢这种设计，因为它把不同类型的文件物理隔离了。你想备份纯数值数据？只拷data/目录。只想分析图像？看videos/就行。想了解数据集概貌？翻翻meta/里的文件。这种模块化让数据管理变得异常清爽。

3. 元数据：读懂数据集的“说明书”

元数据是v3.0的灵魂，值得单独拎出来细讲。它就像你买家电附带的说明书，不看说明书你也能瞎按几个按钮，但想用出全部功能，非得仔细读读不可。

3.1 info.json：数据集的“宪法”

meta/info.json 文件定义了这个数据集最基本的构成规则，也就是Schema。我们来看一个真实的片段：

{
  "codebase_version": "v3.0",
  "robot_type": "so100",
  "fps": 30,
  "features": {
    "timestamp": {
      "dtype": "float32",
      "shape": [1]
    },
    "observation.state": {
      "dtype": "