# 大規模なデータセットをLeRobot Dataset v3.0へ移植する

このチュートリアルでは、大規模なロボティクスデータセットをLeRobot Dataset v3.0形式へ移行する方法を説明します。主な例として**DROID 1.0.1**データセットを使用し、SLURMクラスタ上で数千のシャードにまたがるテラバイト単位のデータセットを扱う方法を示します。

## ファイル構成: v2.1 と v3.0

Dataset v3.0は、データの組織化と保存方法が根本的に変更されます:

**v2.1 構造（エピソードベース）**：

```
dataset/
├── data/chunk-000/episode_000000.parquet
├── data/chunk-000/episode_000001.parquet
├── videos/chunk-000/camera/episode_000000.mp4
└── meta/episodes.jsonl
```

**v3.0 構造（ファイルベース）**：

```
dataset/
├── data/chunk-000/file-000.parquet        # Multiple episodes per file
├── videos/camera/chunk-000/file-000.mp4   # Consolidated video chunks
└── meta/episodes/chunk-000/file-000.parquet  # Structured metadata
```

個々のエピソードファイルからファイルベースのチャンクへの移行により、パフォーマンスが大幅に向上し、ストレージのオーバーヘッドが削減されます。

## Dataset v3.0の新機能

Dataset v3.0では、大規模なデータセットの処理に関する大幅な改善が導入されました:

### 🏗️ **強化されたファイル構成**

- **ファイルベースの構造**: エピソードは個別のエピソードファイルではなく、チャンク化されたファイルにグループ化されました
- **設定可能なファイルサイズ**: データファイルおよび動画ファイル用
- **ストレージ効率の向上**: より良い圧縮とオーバーヘッドの削減

### 📊 **モダンなメタデータ管理**

- **Parquetベースのメタデータ**: JSON Linesを効率的なparquet形式に置き換え
- **構造化エピソードへのアクセス**: `dataset.meta.episodes` を介した pandas DataFrame への直接アクセス
- **エピソードごとの統計**: エピソードレベルでの統計追跡の強化

### 🚀 **パフォーマンスの向上**

- **メモリマップドアクセス**: PyArrowのメモリマッピングによるRAM使用量の改善
- **高速な読み込み**: データセットの初期化時間が大幅に短縮されました
- **より優れたスケーラビリティ**: 数百万のエピソードを含むデータセット向けに設計されています

## 前提条件

大規模なデータセットを移植する前に、以下が揃っていることを確認してください。

- v3.0 対応の **LeRobot** がインストールされました。[インストールガイド](./installation)に従ってください。
- **十分なストレージ**: 生データセットは非常に大きくなることがあります（例: DROIDには2TB必要）
- **クラスタへのアクセス**（大規模データセットに推奨）: SLURMまたは同様のジョブスケジューラ
- **データセット固有の依存関係**: DROID の場合は、TensorFlow Dataset ユーティリティが必要です

## DROIDデータセットの理解

[DROID 1.0.1](https://droid-dataset.github.io/droid/the-droid-dataset)は、大規模なロボティクスデータセットの優れた例です:

- **サイズ**: 1.7TB (RLDS形式)、8.7TB (生データ)
- **構造**: 2048個の事前定義されたTensorFlowデータセットシャード
- **内容**: Franka Emika Panda ロボットによる 76,000 件以上のロボット操作軌跡
- **スコープ**: 複数の環境とオブジェクトにわたる現実世界の操作タスク
- **形式**: 元々は TensorFlow Records/RLDS 形式で、LeRobot 形式への変換が必要です
- **ホスティング**: `gsutil` を介してパブリックアクセスが可能な Google Cloud Storage

データセットには、以下の多様な操作デモが含まれています:

- 複数のカメラビュー（手首カメラ、外部カメラ）
- 自然言語タスクの説明
- ロボットの固有受容性状態とアクション
- 成功/失敗のアノテーション

### DROID機能スキーマ

```python
DROID_FEATURES = {
    # Episode markers
    "is_first": {"dtype": "bool", "shape": (1,)},
    "is_last": {"dtype": "bool", "shape": (1,)},
    "is_terminal": {"dtype": "bool", "shape": (1,)},

    # Language instructions
    "language_instruction": {"dtype": "string", "shape": (1,)},
    "language_instruction_2": {"dtype": "string", "shape": (1,)},
    "language_instruction_3": {"dtype": "string", "shape": (1,)},

    # Robot state
    "observation.state.gripper_position": {"dtype": "float32", "shape": (1,)},
    "observation.state.cartesian_position": {"dtype": "float32", "shape": (6,)},
    "observation.state.joint_position": {"dtype": "float32", "shape": (7,)},

    # Camera observations
    "observation.images.wrist_left": {"dtype": "video", "shape": (180, 320, 3), "names": ["height", "width", "channels"]},
    "observation.images.exterior_1_left": {"dtype": "video", "shape": (180, 320, 3), "names": ["height", "width", "channels"]},
    "observation.images.exterior_2_left": {"dtype": "video", "shape": (180, 320, 3), "names": ["height", "width", "channels"]},

    # Actions
    "action.gripper_position": {"dtype": "float32", "shape": (1,)},
    "action.cartesian_position": {"dtype": "float32", "shape": (6,)},
    "action.joint_position": {"dtype": "float32", "shape": (7,)},

    # Standard LeRobot format
    "observation.state": {"dtype": "float32", "shape": (8,)},  # joints + gripper
    "action": {"dtype": "float32", "shape": (8,)},  # joints + gripper
}
```

## アプローチ1: 単一コンピュータへの移植

### ステップ1: 依存関係のインストール

DROIDに特化して:

```bash
pip install tensorflow
pip install tensorflow_datasets
```

その他のデータセットについては、ソース形式に適したリーダーをインストールしてください。

### ステップ2: 生データのダウンロード

`gsutil` を使用して、Google Cloud Storage から DROID をダウンロードします:

```bash
# Install Google Cloud SDK if not already installed
# https://cloud.google.com/sdk/docs/install

# Download the full RLDS dataset (1.7TB)
gsutil -m cp -r gs://gresearch/robotics/droid/1.0.1 /your/data/

# Or download just the 100-episode sample (2GB) for testing
gsutil -m cp -r gs://gresearch/robotics/droid_100 /your/data/
```

> [!WARNING]
> 大規模なデータセットには、かなりの時間とストレージが必要です:
>
> - **フル DROID (1.7TB)**: バンド幅によって数日かかるダウンロード - **処理時間**: フルデータのローカル移植に7日以上 - **アップロード時間**: Hugging Face Hub へのプッシュに3日以上 - **ローカルストレージ**: 処理済み LeRobot 形式で約400GB

### ステップ3: データセットの移植

```bash
python examples/port_datasets/port_droid.py \
    --raw-dir /your/data/droid/1.0.1 \
    --repo-id your_id/droid_1.0.1 \
    --push-to-hub
```

### 開発とテスト

開発のために、単一のシャードを移植できます:

```bash
python examples/port_datasets/port_droid.py \
    --raw-dir /your/data/droid/1.0.1 \
    --repo-id your_id/droid_1.0.1_test \
    --num-shards 2048 \
    --shard-index 0
```

このアプローチは、小規模なデータセットやテストには有効ですが、大規模なデータセットにはクラスタコンピューティングが必要です。

## アプローチ2: SLURMクラスタへの移植（推奨）

DROIDのような大規模なデータセットでは、複数ノードにわたる並列処理により、処理時間が大幅に短縮されます。

### ステップ1: クラスタの依存関係をインストールする

```bash
pip install datatrove  # Hugging Face's distributed processing library
```

### ステップ2: SLURM環境を設定する

パーティション情報を確認します:

```bash
sinfo --format="%R"  # List available partitions
sinfo -N -p your_partition -h -o "%N cpus=%c mem=%m"  # Check resources
```

**CPUパーティション**を選択します。データセットの移植にはGPUは不要です。

### ステップ3: 並列ポータリングジョブの起動

```bash
python examples/port_datasets/slurm_port_shards.py \
    --raw-dir /your/data/droid/1.0.1 \
    --repo-id your_id/droid_1.0.1 \
    --logs-dir /your/logs \
    --job-name port_droid \
    --partition your_partition \
    --workers 2048 \
    --cpus-per-task 8 \
    --mem-per-cpu 1950M
```

#### パラメータのガイドライン

- **`--workers`**: 並列ジョブの数(DROIDのシャード数では最大2048)
- **`--cpus-per-task`**: フレームエンコードの並列化には、8つのCPUを推奨します
- **`--mem-per-cpu`**: 生フレームの読み込みに必要な合計RAM約16GB（8×1950M）

> [!TIP]
> 数千のジョブを起動する前に、クラスタ設定をテストするために、ワーカーを少数（例: 100）から開始してください。

### ステップ4: 進捗を監視する

実行中のジョブを確認します:

```bash
squeue -u $USER
```

全体の進捗を監視します:

```bash
jobs_status /your/logs
```

個々のジョブのログを確認します:

```bash
less /your/logs/port_droid/slurm_jobs/JOB_ID_WORKER_ID.out
```

失敗したジョブのデバッグ:

```bash
failed_logs /your/logs/port_droid
```

### ステップ5: シャードの集約

すべての移植ジョブが完了すると:

```bash
python examples/port_datasets/slurm_aggregate_shards.py \
    --repo-id your_id/droid_1.0.1 \
    --logs-dir /your/logs \
    --job-name aggr_droid \
    --partition your_partition \
    --workers 2048 \
    --cpus-per-task 8 \
    --mem-per-cpu 1950M
```

### ステップ6: Hubにアップロード

```bash
python examples/port_datasets/slurm_upload.py \
    --repo-id your_id/droid_1.0.1 \
    --logs-dir /your/logs \
    --job-name upload_droid \
    --partition your_partition \
    --workers 50 \
    --cpus-per-task 4 \
    --mem-per-cpu 1950M
```

> [!NOTE]
> Upload は、計算処理がボトルネックではなくネットワークがボトルネックとなるため、より少ないワーカー数（50）を使用します。

## Dataset v3.0 ファイル構造

完成したデータセットは、このモダンな構造になります:

```
dataset/
├── meta/
│   ├── episodes/
│   │   └── chunk-000/
│   │       └── file-000.parquet    # Episode metadata
│   ├── tasks.parquet               # Task definitions
│   ├── stats.json                  # Aggregated statistics
│   └── info.json                   # Dataset information
├── data/
│   └── chunk-000/
│       └── file-000.parquet        # Consolidated episode data
└── videos/
    └── camera_key/
        └── chunk-000/
            └── file-000.mp4        # Consolidated video files
```

この変更により、従来のエピソードごとのファイル構成が、効率的で最適なサイズのチャンクに置き換えられます。

## Dataset v2.1からの移行

v2.1形式の既存データセットがある場合は、移行ツールを使用してください。

```bash
python src/lerobot/scripts/convert_dataset_v21_to_v30.py \
    --repo-id your_id/existing_dataset
```

これにより、自動的に以下が実行されます:

- ファイル構造をv3.0形式に変換します
- メタデータをJSON Linesからparquetへ移行します
- 統計を集約し、エピソードごとの統計を作成します
- バージョン情報を更新します

## パフォーマンスの利点

Dataset v3.0は、大規模なデータセットに対して大幅な改善をもたらします:

- **高速な読み込み**: 初期化時間の3〜5分の1に短縮
- **メモリ効率**: メモリマッピングによるRAM使用量の改善
- **スケーラブルな処理**: 数百万のエピソードを効率的に処理します
- **ストレージの最適化**: ファイル数の削減と圧縮率の向上

