# FineART-VLA

FineART-VLAは、**Physical Intelligenceのπ0.5**およびその[openpi実装](https://github.com/Physical-Intelligence/openpi)を基盤とし、LeRobotの[Pi05](./pi05)ポリシーを通じて構築されています。この基盤を拡張し、学習可能なPaliGemma言語ヘッドと、言語生成とアクション生成を交互に実行するランタイムを追加しています。単一のチェックポイントで、低レベルのサブタスクを予測し、必要に応じてメモリを更新したり視覚的な質問に答えたり、またそのテキストを条件としてフローマッチングアクションエキスパートを制御できます。

タスク条件付きアクションのみが必要な場合は Pi05 を使用してください。ロールアウト中にポリシーが中間言語を生成または消費する必要がある場合は FineART-VLA を使用してください。

## FineART-VLAとPi05の違い

| 機能          | Pi05                                                   | FineART-VLA                                                                       |
| ------------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------- |
| アクションモデル        | PaliGemmaのビジョン言語プレフィックス + Gemmaのアクションエキスパート | 同じベースアーキテクチャ                                                            |
| 言語ヘッド       | ランタイム生成用にトレーニングされていません                     | テキストのクロスエントロピーで再有効化して学習                                    |
| アクション条件付け | エピソードタスク                                           | アクティブな低レベルサブタスクと正規化されたロボット状態                              |
| 学習ターゲット    | Flow-matchingアクション                                  | Flowアクション、レシピで選択されたテキスト、およびオプションのFASTアクショントークン               |
| データセットの要件 | 標準的な画像、状態、アクション、タスク              | トレーニングするすべての言語機能に対する言語アノテーションを含む、同じフィールド |
| ロールアウト             | タスクからアクションへの直接ポリシー                           | 階層的なタスク → サブタスク → アクションのループ、オプションのメモリとVQA           |

FineART-VLAはPi05のチェックポイントから初期化できます。ポリシーのアーキテクチャは互換性を保ったまま、FineART-VLAは独自のプロセッサを構築するため、レシピラベルやFASTラベルがPi05のプロセッサスタックによって黙って置き換えられることはありません。

## インストール

FineART-VLAの依存関係を含むLeRobotをインストールします:

```bash
git clone https://github.com/huggingface/lerobot.git
cd lerobot
python -m venv .venv
source .venv/bin/activate
pip install -e ".[fineart_vla]"
```

`fineart_vla` 追加パッケージには、PaliGemma/FAST の依存関係が含まれています。Linux 環境で CUDA GPU を使用する場合の任意の融合学習カーネルについては、代わりに `".[fineart_vla_kernels]"` をインストールしてください。これにより、`liger-kernel` と、FlashRT バックエンドで使用される Hugging Face の `kernels` パッケージが追加されます。FlashRT カーネルは一部の PyTorch バージョンのみで公開されているため、対応するビルドがない場合、FlashRT バックエンドは警告をログに記録し、PyTorch にフォールバックします。Liger は `--policy.use_liger_kernels=true` でオプトインできます。これにより、プロセス全体で transformers の PaliGemma RoPE/GeGLU がパッチされるため、同じプロセス内で読み込まれた他の PaliGemma ベースのポリシーも融合カーネルで実行されます。

## 言語アノテーション付きデータの準備

FineART-VLAは、学習中に通常のLeRobotデータセットから教師ありサブタスクを推論しません。データセットには、選択したレシピで使用される言語ターゲットを、任意の`language_persistent`および`language_events`カラムに含める必要があります。

少なくとも、連続的な`subtask`タイムラインをアノテーションし、各トレーニングフレームにアクティブな低レベルの指示があるようにしてください。`memory`、VQA、間投詞、発話のアノテーションは、レシピがそれらの能力をトレーニングする場合にのみ追加してください。

FineART-VLAは、EO-1と同様に、デフォルトのレシピを`FineARTVLAConfig`に埋め込んでいます。高レベルのタスクからサブタスクへの予測を30%、低レベルのサブタスク条件付きアクション学習を70%サンプリングします。各設定は自身のレシピ辞書を保持し、保存されたチェックポイントは推論時にその辞書を保持します。

デフォルトを上書きするには、`--policy.recipe_path=/path/to/custom.yaml` を使用します。`src/lerobot/configs/recipes/` 内の共有レシピは main のセマンティクスを維持しており、FineART-VLA によって置き換えられることはありません。ゴールのみの学習には、`${task}` を含む 1 つの低レベルユーザーメッセージを持つインラインレシピを使用するか、`recipe=None` を設定してテキスト/FAST の損失を無効にし、プレーンな PI05 パイプラインを使用してください。

デフォルトでは、推論を π(a|o, subtask)・π(subtask|o, task) に因数分解します。カスタムのジョイントシーケンスレシピには、タスクと生成されたアシスタントのスパンを、トレーニングと同じ因果マークでレンダリングする対応するランタイムプロセッサが必要です。旧ポリシー側のジョイントプロンプトビルダーは、ロールアウトではもはや使用されません。

Rollout は計画の頻度（`--autosteer_interval_s=3`）、対話コマンド、および同期/RTC スケジューリングを管理します。FineART-VLA はクエリされた場合のみテキストを生成し、通常のアクション呼び出しではランタイムの背後で別のサブタスクを生成することはありません。

統合メモリ/サブタスクスクラッチパッドはデフォルトでは有効になっておらず、カスタムレシピとメモリ対応のランタイムコントローラーが必要です。通常のサブタスク生成では`memory_scratchpad=false`を維持してください。古いスクラッチパッドチェックポイントは、統合レスポンスをアクション制御に直接渡すことに対する明示的なガードを保持しています。

`lerobot-annotate` を使用してこれらの列を生成します。リポジトリには、ソースデータセットと宛先データセットに合わせて編集できる Hugging Face Jobs ランチャーが含まれています。ローカルでのアノテーション実行を行う場合は、まず `pip install -e ".[annotations]"` をインストールしてください。

```bash
HF_TOKEN=hf_... uv run python examples/annotations/run_hf_job.py
```

長時間の学習実行の前に、複数のエピソードを検査し、サブタスクが時間的に正しく、デモ全体をカバーしていることを確認してください。生成と検証については[アノテーションパイプライン](./annotation_pipeline)を、スキーマとレシピリゾルバーについては[言語カラムとレシピ](./language_and_recipes)を参照してください。

  データセットに言語カラムがない場合、レシピのレンダリングは何もしない（no-op）となり、FineART-VLAはプレーンなPi05プロンプトパスにフォールバックします。これは互換性の確保には有用ですが、言語プランナーの学習にはなりません。

## FineART-VLAの学習

この例では、`lerobot/fineart_vla_base` から FineART-VLA を初期化します。このチェックポイントは、FineART 上で中間学習され、自身の次のサブタスクを予測するように訓練されたものです。また、埋め込まれた 70/30 のサブタスクレシピを訓練します。`--policy.path` はベースチェックポイント自身の設定を読み込むため、ファインチューニングでは FAST トークンのレイアウト（`fast_skip_tokens`）と、ベースが訓練されたレシピが維持されます。その他の `--policy.*` フラグはこれを上書きします。

```bash
lerobot-train \
    --dataset.repo_id=${HF_USER}/my_language_annotated_dataset \
    --policy.path=lerobot/fineart_vla_base \
    --policy.tokenizer_max_length=256 \
    --policy.dtype=bfloat16 \
    --policy.device=cuda \
    --policy.freeze_vision_encoder=false \
    --policy.gradient_checkpointing=true \
    --batch_size=8 \
    --steps=30000 \
    --output_dir=outputs/fineart_vla \
    --job_name=fineart_vla \
    --trackio.enable=true
```

まず小規模な実行から開始し、スケールアップする前に、Trackio ダッシュボードで損失が期待通りに振る舞っていることを確認してください。

プレーンなPI0.5チェックポイントから開始するには、FineART-VLAのデフォルト設定を維持したまま、`--policy.pretrained_path`をそれに設定します: `--policy.type=fineart_vla --policy.pretrained_path=lerobot/pi05_base`。OpenPI形式の重みは読み込み時に変換され、テキスト損失とFAST損失はFineARTの中間学習ではなく、PaliGemmaの言語ヘッドから開始されます。

### メインの学習コントロール

| オプション                           | デフォルト | 目的                                                             |
| -------------------------------- | ------: | ------------------------------------------------------------------- |
| `policy.recipe_path`             |  `None` | 組み込みの70/30サブタスクレシピの任意の上書き              |
| `policy.text_loss_weight`        |   `1.0` | 言語ヘッドのクロスエントロピー重み。`0`に設定するとテキストの学習が無効になります      |
| `policy.flow_loss_weight`        |  `10.0` | 連続アクションフロー損失重み                                  |
| `policy.enable_fast_action_loss` |  `true` | 離散的なFASTアクショントークンの教師信号を追加します                         |
| `policy.fast_action_loss_weight` |   `1.0` | FASTクロスエントロピー重み                                           |
| `policy.knowledge_insulation`    |  `true` | VLMのK/Vパスを介して、アクション損失の勾配をブロックします               |
| `policy.flow_num_repeats`        |     `5` | 独立したノイズ除去ターゲットに対して、1つのVLMプレフィックスを再利用します             |
| `policy.lm_head_lr_scale`        |   `1.0` | 言語ヘッドの学習率をスケーリングします。`1.0`の場合、ベースレートを使用します        |
| `policy.fast_skip_tokens`        |  `1152` | FAST id オフセット;`<seg>`+`<loc>` をスキップするため、VQA と FAST が衝突しません |

`fast_skip_tokens=1152` は、FAST コードを PaliGemma の `<loc>` 範囲の下に配置します。openpi の pi0-FAST の慣例は `128` です（FAST が `<loc>` の id を占有します）。この値は、そのように学習されたチェックポイントとの重みの互換性を保つためにのみ使用し、`<loc>` のターゲットが FAST コードと埋め込み行列を共有してしまう VQA レシピとの組み合わせは避けてください。

損失の重みは出発点であり、データセットに依存しない定数ではありません。フロー損失とテキスト/FAST損失を個別に追跡し、総損失のみを根拠にチェックポイントを選択するのではなく、生成されたサブタスクを点検してください。

### データセット固有のFASTトークナイザ

デフォルトでは (`--policy.auto_fit_fast_tokenizer=true`)、学習時に `--policy.action_tokenizer_name` を起点として、学習データセットに FAST トークナイザーを適合させ、`--policy.fast_tokenizer_cache_dir` にキャッシュします。これは `lerobot/fineart_vla_base` などのチェックポイントからのファインチューニングにも適用されるため、FAST のターゲットが新しいロボットのアクション分布に一致します。適合させたトークナイザーはチェックポイントのプロセッサ成果物内に保存されるため、推論時に再利用されます。`--policy.auto_fit_fast_tokenizer=false` を設定すると、`action_tokenizer_name` を変更せずに使用します。

## トレーニングのパフォーマンス

FineART-VLA はデフォルトで最適化された学習パスを使用します:

- Pythonで小さな操作を再生する代わりに、バッチでフローターゲットとサフィックスの射影を繰り返します。
- caches定数のアクションマスクをキャッシュし、1回のforwardごとにRoPEの位置を1回だけ計算します。
- ターゲットの形状とスパース性から、テキスト/FASTクロスエントロピーの実装を選択します。
- 知識隔離されたフロー専用のバッチにおいて、数学的に不要なVLM/ビジョンのバックプロパゲーションをスキップします。
- uses native non-reentrant SigLIP layer checkpointing when gradient checkpointing is enabled; and
- LigerのRoPE/GeGLUカーネルを維持しつつ、SigLIPの形状におけるより低速なLayerNormパッチを回避します。

オプションのトレーニングバックエンドは、デフォルトで無効になっています:

| オプション                                 | 試すタイミング                                                                                    |
| -------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `policy.use_flashrt_adarms=true`       | 対応する CUDA GPU 上で、融合された適応型 RMSNorm とゲーティング付き残差                                 |
| `policy.use_compiled_text_ce=true`     | コンパイル済みマテリアライズド・ロジットCEバケット                                                            |
| `policy.use_compiled_vision=true`      | ビジョンパスに勾配がない場合のみ、ビジョンをコンパイル                                        |
| `policy.use_flex_attention=true`       | 知識の分離と`flow_num_repeats > 1`を備えたプロファイル済み CUDA セットアップ; それ以外の場合は SDPA が使用されます |
| `policy.use_manual_attention=true`     | マテリアライズされたアテンションが高速になることが明示的にプロファイルされた形状                                 |
| `policy.manual_attention_scope=action` | 手動アテンションをアクションクエリに制限します                                                      |

すべてのバックエンドを盲目的に有効にしないでください。Flexと手動アテンションは互いに排他であり、アテンション/AdaRMSの代替実装にはナレッジの分離が必要です。ベンチマークで最良の結果を出した設定では、コンパイル済みテキストCEとFlashRT AdaRMSを使用し、Flex/手動アテンションとコンパイル済みビジョンは無効化されていました。

## 推論パフォーマンス

FineART-VLAには2つの推論ループがあり、どちらも高コストなマルチモーダルプレフィックスの繰り返しエンコードを回避します。

1. **Action denoising**は、画像/言語プレフィックスを一度だけエンコードし、フローステップ間でそのKVキャッシュを再利用し、デバイス上でアクションサフィックスのマスクを構築し、プレフィックスキャッシュのクローン作成の代わりに、一時的なサフィックスK/Vをクロップします。タイムステップスケジュールはチャンクごとに一度だけデバイス上で作成され、従来のタイムステップ演算が保持されます。この実装の詳細は、ベンチマークなしではエンドツーエンドの高速化を保証するものではありません。
2. **Language decoding**は自己回帰型KVキャッシュを使用するため、各新しいトークンは、完全なプレフィックスを再実行するのではなく、キャッシュされた画像/言語キーに対してサンプリングされたトークンのみを処理します。

共有ランタイムは、言語とアクションを異なるレートで実行します。サブタスクがより長く有効なままである場合は`--autosteer_interval_s`を大きくし、言語生成なしで直接指示を渡すには`/subtask`を使用します。間隔を長くすると生成コストは削減されますが、再計画も遅くなります。

## チェックポイントを実行する

チェックポイントに一致するロボット/カメラ構成で`lerobot-rollout`を使用し、`--interactive=true`と`--autosteer_interval_s=3`を指定します。`--inference.type=sync`または`--inference.type=rtc`を選択します。インタラクティブなターミナルでは、`/autosteer <goal>`で生成されたサブタスクを有効にし、`/subtask <instruction>`で手動で1つを指定し、`/start`でロボットの制御を開始します。完全なハードウェアセットアップ、安全動作、および録画制御については、[インタラクティブな言語制御](./inference#interactive-language-control)を参照してください。従来の`--sim`、`--mode`、および`--high_level_hz`アダプターCLIオプションは、このインターフェースの一部ではありません。

## トラブルシューティング

- **大きな flow-loss 勾配:** FineART-VLA は、PyTorch SDPA の math バックエンド上で KI-off 連合 prefix/action attention を実行し、FP32 の attention 演算を用いて、その出力をモデルの dtype にキャストし直します（標準の PI0.5 は eager attention を維持しています）。これにより、大きな query/key アクティベーションを持つ低 flow timestep で勾配が不安定になる原因となる低精度の attention を回避できます。既存のチェックポイントと正規化層は変更されず、KI-off は引き続き VLM の keys と values を通じて学習します。有限な総損失だけに頼るのではなく、`flow_loss`、`text_loss`、およびクリッピング前の勾配ノルムを個別に監視してください。
- **テキストの損失や生成されたサブタスクがない場合:** 選択したレシピがサンプリングされたフレームのアノテーションをバインドできることを確認し、`policy.text_loss_weight > 0` になっていることを確認してください。
- **サブタスクは妥当に見えますが、アクションが失敗します:** サブタスクの境界、正規化された状態/アクションの統計量、およびローレベルのレシピサンプルが存在することを確認してください。
- **テキストが繰り返しトークンや位置トークンに崩壊する:** テキストターゲットのカバレッジ、言語ヘッドの学習率、およびフロー、FAST、テキスト損失のバランスを確認してください。
- **メモリ不足:** まずバッチサイズを減らし、その後で勾配チェックポイントを有効にしてください。カメラ数でのメモリ使用量をプロファイリングせずに、コンパイル済みまたは代替の注意機構バックエンドを有効にしないでください。
- **ロールアウトが遅い:** アクションのレイテンシと言語のレイテンシを分離し、`--autosteer_interval_s`（新しいサブタスクが生成される頻度）と`--policy.num_inference_steps`（フローのデノイジングステップ数）を調整します。

## 引用

FineART-VLAまたはFineARTデータセットを使用する場合は、以下の引用を記載してください。

```bibtex
@misc{choghari2026fineart,
  title  = {FineART: Fine-Grained Annotated Robotic Trajectory Dataset and Vision-Language-Action Model for Bimanual Manipulation},
  author = {Choghari, Jade and Kooijmans, Pepijn and Agarwal, Mansi and Ciftci, Yusuf Umut and Doriwala, Aseem and Weaver, Catherine and Sivapurapu, Mouli and Yang, Kai and Lee, Jackson and Wolf, Thomas and Mannam, Pragna},
  year   = {2026},
}
```

FineART-VLAは、Physical Intelligenceの[π₀.₅](https://arxiv.org/abs/2504.16054)と[knowledge insulation](https://arxiv.org/abs/2505.23705)を基盤としています。

## ライセンス

このモデルは、PI0.5バックボーンがベースにしている元の[OpenPIリポジトリ](https://github.com/Physical-Intelligence/openpi)と一貫して、**Apache 2.0ライセンス**に従っています。