# LeRobot数据集合并算子
LeRobot数据集合并算子用于将多个LeRobot数据集合并为一个V3格式数据集。支持**V2.1** 与**V3**两种格式混合输入：V2.1 数据集会先自动转换为V3，再与原始V3数据集统一合并。
- **核心能力：**
  - 混合格式输入：源数据集可为V2.1 或V3，V2.1会自动转换为V3后再合并。
  
  - 格式校验：合并前对所有源数据集进行格式识别与兼容性校验（帧率、特征 schema）。
  
  - 视频快速合并：视频不重新编码，合并速度快。
  
  - 索引重建：合并后episode从0开始重新编号，统计信息从所有源数据集聚合。
  
  - 单输出：多源数据集合并为一个目标数据集目录。
   
- **输入：** 多个LeRobot数据集目录（V2.1或V3，可混合）。
- **输出：** 单个LeRobot V3格式数据集目录。
#### 参数配置
用户可添加repo_id环境变量用于定义合并完成的LeRobot数据集的repo_id（父文件夹目录），若未设置该环境变量且flat为false的情况下默认按照lr_merged输出目录进行创建。
表1参数说明 
| 参数名     | 是否必填 | 默认值       | 可选值        | 说明                                                                                    |
|:---|:---|:---|:---|:---|
| flat    | 否    | true      | true/false | 结果输出是否平铺。若选择true，则不会创建repo_id文件夹，输出数据集直接展示data、meta、videos目录；若设置为false，则按照repo_id来设置。 |
| repo_id | 否    | lr_merged | 任意字符串类型    | 在创建数据处理任务时，用户可添加或修改该环境变量。含义为转换完成的数据集repo_id，未设置时默认回退为lr_merged。                       |
   
#### 输入说明
支持LeRobot V2.1或V3格式数据，其他格式数据会自动跳过合并。
#### 输入数据集格式
源数据集可为 LeRobot V2.1或V3格式，算子会自动识别分类。
- **LeRobot V3** **格式**
  ```
  <dataset_dir>/
  ├── data/
  │   └── chunk-000/
  │       └── file_*.parquet
  ├── meta/
  │   ├── info.json
  │   ├── stats.json
  │   ├── tasks.parquet
  │   └── episodes/
  └── videos/
      ├── observation.images.front/
      ├── observation.images.wrist_left/
      └── observation.images.wrist_right/
  ```
  
- **LeRobot V2.1** **格式**
  ```
  <dataset_dir>/
  ├── data/
  │   └── chunk-000/
  │       └── episode_*.parquet
  ├── meta/
  │   ├── info.json
  │   ├── tasks.jsonl
  │   ├── episodes.jsonl
  │   └── episodes_stats.jsonl
  ├── images/
  │   └── observation.images.*/
  └── videos/
  ```
  ![](https://support.huaweicloud.com/usermanual-cloudrobo/public_sys-resources/note_3.0-zh-cn.png)
  既非V3也非V2.1格式的目录会被跳过并告警。V2.1数据集会自动转换为V3后再参与合并。
  
 
#### 兼容性校验(非自定义合并策略）
合并前会对所有源数据集（V2.1转换为V3 后）进行兼容性校验，以第一个通过校验的数据集为基准：
| **校验项**         | **说明**                                        | **失败处理**    |
|:---|:---|:---|
| 格式识别            | 识别为V3或V2.1。                                   | 非识别格式跳过并告警。 |
| V2.1转换          | V2.1自动转换为V3。                                  | 转换失败跳过并告警。  |
| V3 加载验证         | 使用LeRobot V3接口加载验证。                           | 加载失败跳过并告警。  |
| 帧率（fps）一致性      | 所有数据集fps必须与基准一致。                              | 不一致跳过并告警。   |
| 特征（features）一致性 | 所有数据集features schema（key、dtype、shape）必须与基准一致。 | 不一致跳过并告警。   |
   
![](https://support.huaweicloud.com/usermanual-cloudrobo/public_sys-resources/note_3.0-zh-cn.png)
不兼容的数据集会被跳过，不影响其他数据集合并。若所有数据集均被跳过（无可用源），作业报错退出。
自定义合并策略（MERGE_MODE=custom）
- 新增 aggregate_custom.py：放松兼容性约束的合并实现，允许 minor diff 的数据集直接合并
- 支持 dtype 自动转换（float64 → float32），通过 MERGE_DTYPE 控制目标类型
- 支持视频 key 自动映射（语义后缀匹配 + 顺序回退），如 observation.images.external → observation.images.cam_external
- 支持分辨率不匹配时自动重编码（MERGE_VIDEO_RESIZE=reencode），使用 PyAV + PIL 纯 CPU 处理
- 支持 names 格式差异（list vs dict）自动适配，使用 reference 值
- 支持 shape 维度顺序差异（HWC vs CHW）自动适配
- 支持 video info 字段差异自动适配
- fps 不一致仍为硬性约束，不可自动适配
#### 输出说明
多数据源输入合并后输出单个目录，格式为LeRobot V3。
#### 输出目录结构
flat为false时合并结果为单个LeRobot V3格式数据集：
```
<repo_id>
├── data/
│   └── chunk-000/
│       ├── file_000000.parquet       
│       ├── file_000001.parquet
│       └── ...
├── meta/
│   ├── info.json                        # 数据集基本信息（codebase_version 为 v3.0）
│   ├── stats.json                       # 从所有源数据集聚合的统计信息
│   ├── tasks.parquet                    # 合并后的任务定义
│   └── episodes/                        # 合并后的 Episode 元信息
└── videos/                              # 合并后的视频数据
    ├── observation.images.front/
    ├── observation.images.wrist_left/
    └── observation.images.wrist_right/
```
```
# flat=true 模式
<output_dir>/
├── data/
│   └── chunk-000/
│       ├── episode_000000.parquet
│       └── ...
├── meta/
│   ├── info.json
│   ├── tasks.jsonl
│   ├── episodes.jsonl
│   └── episodes_stats.jsonl
├── images/
│   ├── observation.images.front/
│   └── ...
└── videos/
```