# マルチタスクDiTポリシー

Multitask Diffusion Transformer (DiT) Policy は、元の Diffusion Policy アーキテクチャの進化形であり、テキストとビジョンの条件付けを用いた大規模な DiT を活用してマルチタスクのロボット学習を実現します。この実装では、アクション生成のために拡散とフローマッチングの両方の目的関数をサポートしており、言語指示を条件としてロボットが多様な操作タスクを実行できるようにします。

## モデル概要

モデルは以下を使用します:

- **CLIP Vision Encoder**: 複数のカメラビューからのRGB画像を処理します
- **CLIP Text Encoder**: 言語タスクの指示をエンコードします（学習可能な射影を持つ凍結された重み）
- **Diffusion Transformer**: 観察と言語を条件として、アクションシーケンスを予測します
- **2つの目的**: アクション生成において、拡散（DDPM/DDIM）とフローマッチングの両方をサポートします

このモデルは、わずか約450Mのパラメータと大幅に少ない学習量で、数十億パラメータ規模のVLAに匹敵する極めて高い器用さを達成できるため、非常に注目されています。

## インストール要件

Multitask DiT Policyには追加の依存関係があります。…でインストールしてください。

```bash
pip install 'lerobot[multi_task_dit]'
```

これにより、CLIPモデル用のHuggingFace Transformersライブラリを含む、すべての必要な依存関係がインストールされます。

## 使用方法

LeRobot の設定で Multitask DiT を使用するには、ポリシータイプを以下のように指定します:

```python
policy.type=multi_task_dit
```

## トレーニング

### 基本的なトレーニングコマンド

あなたのデータセットでMultitask DiTを学習するための完全な学習コマンドを以下に示します。

```bash
lerobot-train \
  --dataset.repo_id=YOUR_DATASET \
  --output_dir=./outputs/multitask_dit_training \
  --batch_size=32 \
  --steps=5000 \
  --save_freq=500 \
  --log_freq=100 \
  --policy.type=multi_task_dit \
  --policy.device=cuda \
  --policy.repo_id="HF_USER/multitask-dit-your-robot" \
  --trackio.enable=true
```

### 推奨ハイパーパラメータとデータセットの詳細（30Hzの制御周波数）

安定したパフォーマンスを得るには、以下の推奨デフォルトのハイパーパラメータから開始してください：

```bash
lerobot-train \
  --dataset.repo_id=YOUR_DATASET \
  --output_dir=./outputs/mutitask_dit_training \
  --batch_size=320 \
  --steps=30000 \
  --policy.type=multi_task_dit \
  --policy.device=cuda \
  --policy.horizon=32 \
  --policy.n_action_steps=24 \
  --policy.objective=diffusion \
  --policy.noise_scheduler_type=DDPM \
  --policy.num_train_timesteps=100 \
  --policy.repo_id="HF_USER/multitask-dit-your-robot" \
  --trackio.enable=true
```

**主要なパラメータ:**

- **バッチサイズ**: 192-320 - このサイズをサポートできるGPUにアクセスできる場合、最適な学習ダイナミクスが得られます
- **Horizon**: 32 - 予測するアクションステップ数、30Hzで約1.0秒
- **n_action_steps**: 24 - 30Hzで約0.8秒
- **目的**: `diffusion` - diffusionから開始し、生成品質が低い場合はflow matchingで実験する
- **学習ステップ**: 単一タスクには30kステップ以上を推奨

### トレーニング設定パラメータ

#### 目的の選択

拡散とフローマッチングから選択します:

```bash
# Diffusion objective (default)
--policy.objective=diffusion \
--policy.noise_scheduler_type=DDPM \
--policy.num_train_timesteps=100 \
--policy.num_inference_steps=10 \
--policy.beta_schedule=squaredcos_cap_v2 \
--policy.prediction_type=epsilon \
--policy.clip_sample=true \
--policy.clip_sample_range=1.0

# Flow matching objective
--policy.objective=flow_matching \
--policy.timestep_sampling_strategy=beta \
--policy.num_integration_steps=100 \
--policy.integration_method=euler \
--policy.sigma_min=0.0
```

| フラグ                                  | 注記                                                                            |
| ------------------------------------- | -------------------------------------------------------------------------------- |
| `--policy.noise_scheduler_type`       | `DDPM`または`DDIM`                                                                 |
| `--policy.num_inference_steps`        | ステップ数が少ないほど推論が高速になります                                                |
| `--policy.beta_schedule`              | ノイズスケジュールの種類                                                              |
| `--policy.prediction_type`            | `epsilon`（ノイズを予測）または`sample`（クリーンなデータを予測）                            |
| `--policy.clip_sample`                | デノイジング中のサンプルをクリップ                                                    |
| `--policy.clip_sample_range`          | クリッピング範囲 `[-x, x]`                                                         |
| `--policy.timestep_sampling_strategy` | `beta`または`uniform`。実用上、`beta`戦略の方がはるかに効果的であることが示されています |
| `--policy.integration_method`         | `euler`または`rk4`                                                                 |
| `--policy.sigma_min`                  | フロー補間パスにおける最小ノイズ                                     |

#### Transformerアーキテクチャ

データセットのサイズに基づいてモデルの容量を調整します:

```bash
# Small datasets (< 100 examples)
--policy.num_layers=4 \
--policy.hidden_dim=512 \
--policy.num_heads=8  # should ideally be hidden_dim // 64

# Medium datasets (100-5k examples) - default
--policy.num_layers=6 \
--policy.hidden_dim=512 \
--policy.num_heads=8  # should ideally be hidden_dim // 64

# Large datasets (> 5k examples)
--policy.num_layers=8 \
--policy.hidden_dim=512 \
--policy.num_heads=8   # should ideally be hidden_dim // 64
```

**位置エンコーディングのオプション:**

モデルは、アクションシーケンスに対して2つの位置エンコーディング手法をサポートしています:

```bash
# Rotary Position Embedding (RoPE) - default, recommended
--policy.use_rope=true \
--policy.rope_base=10000.0  # Base frequency for RoPE

# Absolute positional encoding
--policy.use_positional_encoding=true  # Disables RoPE when true
```

**その他の Transformer パラメータ:**

```bash
--policy.dropout=0.1  # Dropout rate for DiT blocks (0.0-1.0)
--policy.timestep_embed_dim=256  # Timestep embedding dimension
```

#### ビジョンエンコーダーの設定

```bash
# Use different CLIP model for more expressivity at the cost of inference time
# experiment with larger or smaller models depending on the complexity of your tasks and size of dataset
--policy.vision_encoder_name=openai/clip-vit-large-patch14

# Use separate vision encoder per camera
# This may be useful when cameras have significantly different characteristics, but
# be wary of increased VRAM footprint.
--policy.use_separate_rgb_encoder_per_camera=true

# Image preprocessing (you may need to resize your images for inference speed ups)
--policy.image_resize_shape=[XXX,YYY] \
--policy.image_crop_shape=[224,224] \
--policy.image_crop_is_random=true  # Random during training, center at inference
```

#### テキストエンコーダーの設定

```bash
# Use different CLIP text encoder model
# same as vision: experiment with larger or smaller models depending on the
# complexity of your tasks and size of dataset
--policy.text_encoder_name=openai/clip-vit-large-patch14
```

#### 学習率の設定

ビジョンエンコーダーには別の学習率乗数が使用され、理想的な開始点として1/10が推奨されています:

```bash
--policy.optimizer_lr=2e-5 \
--policy.vision_encoder_lr_multiplier=0.1  # Vision encoder LR = 0.1 * optimizer_lr
```

### トレーニングチューニングガイドライン

#### 1. ベータサンプリングを用いたフローマッチング

ここでの元の拡散モデルの実装は、[TRIのLBM論文](https://arxiv.org/abs/2507.05331)に記載されている研究に基づいています。

さらに、[Boston Dynamicsのブログ記事](https://bostondynamics.com/blog/large-behavior-models-atlas-find-new-footing/)で高レベルで説明されているフローマッチングの目的関数を実装しました。

フローマッチングの目的関数をテストし、タスクにおけるパフォーマンスの違いを評価することを検討してください。

```bash
--policy.objective=flow_matching \
--policy.timestep_sampling_strategy=beta \
--policy.timestep_sampling_alpha=1.5 \
--policy.timestep_sampling_beta=1.0 \
--policy.timestep_sampling_s=0.999
```

これがすべてのユースケースにおいて万能の解決策であるとは示されていませんが、場合によってはより滑らかで一貫性のある動作をもたらすことがあります。

#### 2. Transformerレイヤー数

モデルの容量をデータセットのサイズに合わせて調整します:

- **小規模なデータセット**（100例未満）：4層に削減
- **大規模データセット**（5,000件を超える例）: 8層に増加

#### 3. `horizon`チューニング

モデルは選択するホライズンに敏感な場合があります。制御周波数に基づいて、約1秒のホライズンから始めてください:

- **30 Hzの周波数**: `horizon=30`
- **10 Hzの周波数**: `horizon=10`

その後、そこから増やして実験してください。horizonは、モデルが未来のどの時点までアクションを予測するかを決定します。

#### 4. `n_action_steps` の感度

モデルは`n_action_steps`にも非常に敏感な場合があります。制御周波数に基づいて約0.8秒に設定し、そこから調整してください:

- **低い値**: 反応は速くなりますが、長期タスクでは安定性が低下する可能性があります
- **高い値**: 長時間にわたる実行には適していますが、オープンループの失敗に対する回復能力には限界があります

### 推論のチューニング

より高速な推論のために、サンプリングステップを減らしてDDIMを使用します:

```bash
--policy.noise_scheduler_type=DDIM \
--policy.num_inference_steps=10
```

### トレーニングの再開

チェックポイントからトレーニングを再開するには:

```bash
lerobot-train \
  --config_path=./outputs/mutitask_dit_training/checkpoints/last/pretrained_model/train_config.json \
  --resume=true
```

チェックポイントディレクトリには、`model.safetensors`と`config.json`ファイル（学習中に自動的に保存されます）が含まれている必要があります。再開する際は、設定がチェックポイントから読み込まれるため、他のパラメータを指定する必要はありません。

## 一般的な失敗パターンとデバッグ

これらのモデルのトレーニングは、繊細な調整を必要とすることがあります。以下に、よくある失敗パターンとデバッグ手法をまとめます。

### アイドル / 無動作

モデルは推論中に「崩壊」する可能性があり、静止した状態や動きのない結果になることがあります。これは、次のような場合に発生する可能性があります。

1. **学習データが不足している**: 20〜50件のサンプルしかない場合は、データセットのサイズを概ね2倍にすることを試してください。300件を超えてもこの問題が解決しない場合は、タスクが複雑すぎる可能性があります。

2. **複数の類似タスク**: データセットに複数の類似タスク（例: 2つの異なるオブジェクトを拾う）が含まれている場合、モデルが言語条件付けに過度に依存する可能性があります。言語条件付けは、それらのタスクを十分に表現するほど豊かではない場合があります。

**デバッグのコツ:**

- データセットのサイズを拡大する（300例を超えるまで2倍に増やす）
- 損失が頭打ちになっても、最大100kステップまで長く学習を実行します
- モデルが適切な言語指示を受けているか確認するか、指示の多様性を高めてください

### 誤ったタスクの実行

ロボットが指示を完全に無視して、別のタスクを実行することがあります。これは、複数のタスクで学習した場合にのみ一般的に発生します。

**考えられる原因:**

- 言語指示の曖昧さ
- タスク固有の学習データが不足している
- マルチタスクデータセットにおける類似タスク間のモデルの混同

**デバッグのコツ:**

- 言語指示の具体性を検証してください。特に、複数のタスク間で説明が類似している場合は注意が必要です。
- トレーニングデータセットのタスク分布を確認し、失敗または無視されているタスクに重みを追加してください
- タスク固有のファインチューニングを検討する

### トレーニングの不安定性

トレーニング損失が不安定であるか、発散している場合:

- `1e-5`から`3e-4`の範囲で学習率を調整してみてください。
- 可能であればバッチサイズを大きくします
- データセットの正規化が正しいことを確認します
- 画像の前処理が正しく動作していることを確認します

## パフォーマンスに関する考慮事項

### GPU要件

- **推論**: 適切な速度性能を得るには、RTX 5070 Ti（または同等の GPU）以上が推奨されます
- **学習**: 1バッチあたりのサイズが64を超えるモデルをロードできる十分なVRAMを備えたGPUが理想的です。これは、画像の観測数などによって異なります。

### バッチサイズのおすすめ

- **最小値**: 64（これ未満の場合、トレーニングが不安定になる可能性があります）
- **推奨**: 256-320（最高のパフォーマンス、より大きなGPUが必要）

## 例: カスタムデータセットでの学習

カスタムデータセットでの学習の完全な例を以下に示します。

```bash
lerobot-train \
  --dataset.repo_id=YOUR_DATASET \
  --output_dir=./outputs/mutitask_dit_training \
  --batch_size=320 \
  --steps=30000 \
  --save_freq=1000 \
  --log_freq=100 \
  --env_eval_freq=1000 \
  --policy.type=multi_task_dit \
  --policy.device=cuda \
  --policy.horizon=32 \
  --policy.n_action_steps=24 \
  --policy.objective=diffusion \
  --policy.noise_scheduler_type=DDPM \
  --policy.num_layers=6 \
  --policy.hidden_dim=512 \
  --policy.vision_encoder_name=openai/clip-vit-base-patch16 \
  --policy.image_resize_shape=[320,240] \
  --policy.image_crop_shape=[224,224] \
  --policy.repo_id="HF_USER/multitask-dit-your-robot" \
  --trackio.enable=true \
  --trackio.project=multitask_dit
```

## Liberoの結果

```
lerobot-train \
  --dataset.repo_id=HuggingFaceVLA/libero \
  --policy.type=multi_task_dit \
  --policy.push_to_hub=false \
  --output_dir="./outputs/multitask_dit_libero" \
  --job_name="multitask-dit-libero" \
  --trackio.enable=true \
  --trackio.project=multitask_dit_libero \
  --dataset.image_transforms.enable=true \
  --dataset.image_transforms.max_num_transforms=4 \
  --dataset.image_transforms.tfs='{"brightness":{"type":"ColorJitter","kwargs":{"brightness":[0.75,1.25]}},"contrast":{"type":"ColorJitter","kwargs":{"contrast":[0.6,1.4]}},"saturation":{"type":"ColorJitter","kwargs":{"saturation":[0.8,1.2]}},"hue":{"type":"ColorJitter","kwargs":{"hue":[-0.05,0.05]}},"sharpness":{"type":"SharpnessJitter","kwargs":{"sharpness":[0.6,1.4]}},"rotation":{"type":"RandomRotation","kwargs":{"degrees":[-5,5]}},"translation":{"type":"RandomAffine","kwargs":{"degrees":0,"translate":[0.1,0.1]}}}' \
  --dataset.video_backend=torchcodec \
  --policy.use_amp=true \
  --policy.horizon=48 \
  --policy.n_obs_steps=2 \
  --policy.use_rope=true \
  --policy.use_positional_encoding=false \
  --policy.hidden_dim=768 \
  --policy.num_layers=8 \
  --policy.num_heads=12 \
  --policy.dropout=0.1 \
  --policy.timestep_embed_dim=256 \
  --policy.objective=diffusion \
  --policy.optimizer_lr=3e-4 \
  --policy.optimizer_weight_decay=0 \
  --policy.scheduler_warmup_steps=0 \
  --policy.vision_encoder_name=openai/clip-vit-base-patch16 \
  --policy.image_resize_shape=[256,256] \
  --policy.image_crop_is_random=true \
  --policy.text_encoder_name=openai/clip-vit-base-patch16 \
  --policy.vision_encoder_lr_multiplier=0.1 \
  --policy.device=cuda \
  --num_workers=8 \
  --save_freq=4000 \
  --log_freq=100 \
  --steps=100000 \
  --batch_size=320
```

結果:

| LIBERO Spatial | LIBERO Object | LIBERO Goal | LIBERO 10 | 平均 |
| -------------- | ------------- | ----------- | --------- | ------- |
| 87.0           | 98.2          | 93.8        | 83.2      | 90.6    |

## 参考文献

技術的な実装とアーキテクチャの詳細については、以下を参照してください：

- [マルチタスク巧緻性操作のための大規模行動モデルの慎重な検討](https://arxiv.org/abs/2507.05331)
- [Large Behavior ModelsとAtlasが新たな足場を見つける](https://bostondynamics.com/blog/large-behavior-models-atlas-find-new-footing/)
- [マルチタスク拡散トランスフォーマーポリシーの解析とオープンソース化](https://brysonkjones.substack.com/p/dissecting-and-open-sourcing-multitask-diffusion-transformer-policy)

