lerobot-lancedb¶

一句话定位：LeRobotDataset 的 drop-in 替换——保留 LeRobot v3 的元数据结构和训练器接口，把帧数据从"拼接 MP4 + 关系型元数据"换成"Lance 列存 + Blob V2"，实现 2-5x 训练吞吐提升且与上游 bit-exact 对齐¹。

核心问题：LeRobotDataset 训练时的 IO 瓶颈¶

LeRobot v3 用 Parquet 帧数据 + 拼接 MP4 视频 组织数据。DiffusionPolicy 这类时间窗口采样（delta_timestamps 取 8 帧/sample）的训练循环下，IO 是关键瓶颈：

每 batch（32 sample × 8 帧 × N 相机）的实际 IO：

  1. Parquet 元数据查询（按 episode_index 定位）   → 多文件随机读
  2. MP4 解码（按 timestamp seek）                  → 单文件顺序读
  3. 帧解码（CPU AV1/H.264 decode）                → CPU 密集
  4. 拼成 batch tensor                            → 内存拷贝

实测在 H100 + CPU decode 上，ALOHA 4 相机数据集仅 18.7 fps——GPU 算力远远等不满，瓶颈在解码侧的 IO 与 CPU。

lerobot-lancedb 的解法：保留 LeRobot v3⁵ 元数据 schema，把帧数据搬到 Lance 列存里，让 Lance 的列统计 + Blob V2 处理帧定位与视频解码。

技术亮点¶

两种存储 Layout¶

lerobot-lancedb 提供两种 dataset class，对应 Lance 的两种 blob 存储语义²³：

关键设计权衡：

• JPEG layout：单帧随机访问最快（一次 Lance 读 + JPEG 解码），但像素有损——ALOHA 自然背景压缩干净（mean abs diff 0.0021），Koch 高对比度乐高场景掉到 0.0047
• Video blob layout：保持上游 MP4 原貌，体积几乎不变（实测与上游差异 < 0.5%），通过 torchcodec 按帧索引访问——更接近 LeRobot v3 的语义但 IO 路径完全在 Lance 内

Reader 实现差异：

Frames format（__getitems__）：
  1. Lance 列读 tabular 字段（state / action）
  2. Lance 列读 JPEG bytes（image）
  3. PIL 批量解码
  → 一次 Lance IO 拉齐整批

Video format（__getitems__）：
  1. Lance 列读 tabular 字段
  2. 对每帧定位到 (video_key, chunk, file) 三元组
  3. take_blobs(video_bytes) 拉对应 mp4 bytes
  4. VideoDecoder LRU 缓存（per-worker，默认 16）
  5. decoder.get_frames_at([...]) 按 timestamp 取帧
  → 一个 batch 通常只需一次 mp4 IO + 多次 frame index 查询

Benchmark：3-5x 训练吞吐提升¶

在 H100 + 4 worker + batch 32 + 8 帧/sample 的真实训练读取模式下⁴：

三个关键观察：

1. video-blob 速度略低于 JPEG（如 pusht 2853 vs 3510 fps），但像素 bit-exact 且体积相当——为追求训练精度首选
2. JPEG-95 vs JPEG-100：提高 JPEG 质量反而降低吞吐（Koch：70.8 → 49 fps），因为解码耗时增加
3. 吞吐瓶颈不在 IO 总量，在 CPU 解码：Lance 把多文件随机读合并成列存顺序读，解码仍需 CPU——H100 算力未饱和，扩展到 NVJPEG/GPU decode 还有进一步空间

训练精度 Parity 验证¶

性能提升不能以牺牲训练精度为代价。lerobot-lancedb 在两个标准任务上做了 head-to-head 验证：

pusht + DiffusionPolicy（200k steps，env eval @ seed=100000）：

关键结论：Lance video-blob 达到 68.4% success，与上游 head-to-head 68.0% 在误差范围内对齐，证明视频数据 bit-exact 传递对训练结果可复现。

Cloud/Hub 集成¶

两种 layout 都支持对象存储直读——不需要全量下载数据集：

# HF Hub 直读
LeRobotLanceDataset(repo_id="lance-format/pusht-lerobot-lancedb")
LeRobotLanceVideoDataset(repo_id="lance-format/pusht-lerobot-lancedb-video")

# S3 / GCS 直读
LeRobotLanceVideoDataset(uri="s3://bucket/path/aloha_cups_open.lance")

底层机制：Lance 对 S3/GCS 做 byte-range 抓取——只下载访问到的 mp4 字节范围，不全量拉数据集。Blob V2 列不会被物化到 Arrow buffer，远程访问尤其高效。

与 LanceDB 主库的关系：这是 LanceDB 库文档中 Blob V2 "Dedicated 模式"（每个 blob 一个独立 .lance 文件）的工程化落地——把整 MP4 文件当 blob 存，让字节范围抓取和分块缓存成为可能。

与 LeRobot v3 的关系¶

LeRobot v3 标准数据栈：
  Parquet（帧表）+ 拼接 MP4（视频）+ 元数据 JSON
                    ↓
         lerobot-lancedb 替换数据层
                    ↓
Lance 列存（帧表）+ Lance Blob V2 dedicated（MP4 文件）+ LeRobot v3 元数据（保留）

保留的 LeRobot v3 接口：

• meta/info.json、meta/stats.json、meta/tasks.parquet、meta/episodes/*.parquet 结构不变
• delta_timestamps、batch_size、num_workers 等训练参数不变
• LeRobotLanceDataset/LeRobotLanceVideoDataset 都继承 LeRobotDataset——trainer / sampler / isinstance 检查无需改动

迁移路径：

# mp4 → video-blob layout（推荐，bit-exact）
lerobot-convert-to-lance-video \
    --repo-id=lerobot/aloha_static_cups_open \
    --output=./aloha_cups_open_lance_video --overwrite

# 原始帧 → JPEG layout（最快，但有损）
lerobot-convert-to-lance --repo-id=lerobot/pusht_image ...

数据集训练完可直接发布到 HF Hub 作为 dtype=lance 变体——这是 OXE / LeRobot 生态原生支持的数据类型扩展点。

为什么值得知道¶

1. drop-in 替换的工程示范：lerobot-lancedb 展示了"性能优化层"如何与上游训练框架解耦——保留 schema 与 API，把存储层换成 Lance 即可获得 2-5x 提速，无需改 trainer 一行代码。这套模式可推广到其他需要随机时序窗口采样的 ML 数据栈
2. Blob V2 的最佳实践案例：把整个 MP4 文件作为 dedicated blob 存入 Lance 列，配合 byte-range fetch 实现远程数据集的按需加载，是 LanceDB 多模态存储策略在具身数据上的真实落地
3. bit-exact 而非"近似等价"：video-blob layout 通过保留上游 MP4 字节、提供 bit-exact 帧访问，把训练精度的可复现性作为首要指标——避免了"换了存储格式，模型性能也变了"的常见工程陷阱
4. 具身数据 IO 优化的标杆：具身训练数据集常以"高分辨率 + 多相机 + 长时序"为特征，IO 瓶颈突出。lerobot-lancedb 在 ALOHA 4 相机场景下 2.44x 提速，对应训练时间从 100 小时降到 40 小时级别——具身算法迭代速度的关键加速点

参考资料¶