fine-tuning-openvla-oft

OpenVLA-OFT

公式の openvla-oft コードベースを使用した、OpenVLA-OFT と OpenVLA-OFT+ のファインチューニングおよび評価ワークフローです。何もない状態からのマシンセットアップに加え、連続アクション予測ヘッドを用いたロボットアクション生成のための OpenVLA の LoRA ベースの適応について説明します。

クイックスタート

公開リポジトリをクローンし、公式のセットアップ手順に従ってから、事前学習済みの LIBERO チェックポイントを評価します。

git clone https://github.com/moojink/openvla-oft.git
cd openvla-oft
python experiments/robot/libero/run_libero_eval.py \
  --pretrained_checkpoint moojink/openvla-7b-oft-finetuned-libero-spatial \
  --task_suite_name libero_spatial \
  --center_crop True \
  --num_trials_per_task 50 \
  --seed 7

主な概念

OpenVLA-OFT による変更点：標準の OpenVLA では、連続アクションを離散ビンにトークン化するため、精度が失われます。OFT では、VLA バックボーンを凍結したまま LoRA で適応させ、専用の連続アクションヘッド（L1 回帰または拡散）に置き換えます。

OFT と OFT+ のバリアント：

バリアント	FiLM	画像	代表的な用途
OFT	オフ	2（正面＋手首）	LIBERO シミュレーション
OFT+	オン	3（高所＋左右の手首）	ALOHA 実環境

主なアーキテクチャの選択肢：

• LoRA 適応：VLA バックボーンにランク 32 の LoRA を適用します（全体のファインチューニングは不要です）。
• 連続アクション：L1 回帰ヘッド（デフォルト）または拡散ヘッド
• FiLM による条件付け：OFT+ で言語によるグラウンディングを強化する、特徴ごとの線形変調
• 複数画像入力：num_images_in_input で 2 または 3 個のカメラストリームを設定できます。

計算要件

タスク	GPU	VRAM	備考
LIBERO 評価	1x A100/A40	~16 GB	単一 GPU
ALOHA 評価	1x A100/A40	~18 GB	単一 GPU
LIBERO ファインチューニング	8x A100	~27 GB/GPU	論文でのデフォルト
ALOHA ファインチューニング（OFT+）	8x A100	~35 GB/GPU	FiLM ＋ 3 枚の画像
LoRA マージ	1x 任意の GPU	~16 GB	1 回限りのステップ

期待される性能ベンチマーク

公式の結果（論文の設定、seed=7、各タスク 50 試行）：

タスクスイート	タスク固有	結合ポリシー	備考
LIBERO-Spatial	97.2%	96.8%	最も簡単なスイート
LIBERO-Object	97.4%	97.0%	物体操作
LIBERO-Goal	95.8%	95.4%	50k～100k ステップでピークに達する場合があります
LIBERO-10	98.0%	98.0%	長期的なタスク
平均	97.1%	96.8%	ほぼ同等

再現に関する注意：結果は Python 3.10.14、PyTorch 2.2.0、NVIDIA A100、カスタム Transformers フォークに依存します。

代替手段と比べた場合の選び方

次の場合は OpenVLA-OFT を使用します：

• 対象タスクが、視覚と言語による条件付けを伴うロボットアクション生成である
• openvla/openvla-7b の LoRA ベースの適応を優先する
• OpenVLA-OFT 論文の公式 LIBERO または ALOHA ワークフローが必要である
• トークン化されたアクションではなく、連続アクションヘッド（L1 回帰または拡散）が必要である

次の場合は代替手段を使用します：

• 別の VLA アーキテクチャが必要である（pi0/pi0.5 モデルには fine-tuning-serving-openpi を使用してください）
• NVIDIA Cosmos Policy スタックが必要である（evaluating-cosmos-policy を使用してください）
• ロボットアクションヘッドを使用しない、一般的な LLM のファインチューニングが必要である

---

ワークフロー 1：環境をセットアップする

このチェックリストをコピーして、進捗を記録します。

Setup Progress:
- [ ] Step 1: Create conda env and install PyTorch
- [ ] Step 2: Install openvla-oft package in editable mode
- [ ] Step 3: Install FlashAttention2
- [ ] Step 4: Verify critical versions

ステップ 1：conda 環境を作成してリポジトリをクローンする

conda create -n openvla-oft python=3.10 -y
conda activate openvla-oft
git clone https://github.com/moojink/openvla-oft.git
cd openvla-oft
pip3 install torch==2.2.0 torchvision==0.17.0 torchaudio==2.2.0
pip3 install robosuite==1.4.0

ステップ 2：パッケージをインストールする

pip install -e .

ステップ 3：FlashAttention2 をインストールする

pip install packaging ninja
pip install "flash-attn==2.5.5" --no-build-isolation

ステップ 4：バージョンを確認する

import torch, transformers, peft
print(f"PyTorch: {torch.__version__}")         # Expected: 2.2.0
print(f"Transformers: {transformers.__version__}")
print(f"PEFT: {peft.__version__}")             # Expected: 0.11.1

---

ワークフロー 2：事前学習済みチェックポイントを LIBERO で評価する

LIBERO Eval Progress:
- [ ] Step 1: Install LIBERO dependencies
- [ ] Step 2: Choose checkpoint and task suite
- [ ] Step 3: Run evaluation
- [ ] Step 4: Parse and validate results

ステップ 1：LIBERO をインストールする

git clone https://github.com/Lifelong-Robot-Learning/LIBERO.git
pip install -e LIBERO
pip install -r experiments/robot/libero/libero_requirements.txt

ステップ 2：チェックポイントを選択する

チェックポイント	タスクスイート
moojink/openvla-7b-oft-finetuned-libero-spatial	libero_spatial
moojink/openvla-7b-oft-finetuned-libero-object	libero_object
moojink/openvla-7b-oft-finetuned-libero-goal	libero_goal
moojink/openvla-7b-oft-finetuned-libero-10	libero_10
moojink/openvla-7b-oft-finetuned-libero-spatial-object-goal-10	結合

ステップ 3：評価を実行する

python experiments/robot/libero/run_libero_eval.py \
  --pretrained_checkpoint moojink/openvla-7b-oft-finetuned-libero-spatial \
  --task_suite_name libero_spatial \
  --center_crop True \
  --num_trials_per_task 50 \
  --seed 7

ステップ 4：結果を解析する

import re

def parse_libero_log(log_path):
    """Extract per-task success rates from LIBERO eval log."""
    with open(log_path) as f:
        content = f.read()
    matches = re.findall(r"Task (.+?): (\d+)/(\d+) successes", content)
    for task, successes, trials in matches:
        rate = int(successes) / int(trials)
        print(f"  {task}: {rate:.0%} ({successes}/{trials})")

parse_libero_log("experiments/logs/latest.log")

---

ワークフロー 3：LIBERO でファインチューニングする

詳細なリファレンス：LIBERO のセットアップ全体、チェックポイントの選択戦略、LoRA のマージ手順については、references/libero-workflow.md を参照してください。

LIBERO Fine-Tune Progress:
- [ ] Step 1: Prepare RLDS dataset
- [ ] Step 2: Launch torchrun with OFT defaults
- [ ] Step 3: Evaluate intermediate and final checkpoints
- [ ] Step 4: Merge LoRA for deployment if needed

ステップ 1：データセット

RLDS データセット libero_spatial_no_noops、libero_object_no_noops、libero_goal_no_noops、libero_10_no_noops を使用します。

ステップ 2：トレーニングを開始する

torchrun --standalone --nnodes 1 --nproc-per-node 8 vla-scripts/finetune.py \
  --vla_path openvla/openvla-7b \
  --data_root_dir /PATH/TO/RLDS/DATASETS/ \
  --dataset_name libero_spatial_no_noops \
  --run_root_dir /YOUR/CHECKPOINTS/ \
  --use_l1_regression True \
  --use_diffusion False \
  --use_film False \
  --num_images_in_input 2 \
  --use_proprio True \
  --batch_size 8 \
  --learning_rate 5e-4 \
  --num_steps_before_decay 100000 \
  --max_steps 150005 \
  --save_freq 10000 \
  --save_latest_checkpoint_only False \
  --image_aug True \
  --lora_rank 32 \
  --wandb_entity YOUR_WANDB_ENTITY \
  --wandb_project YOUR_WANDB_PROJECT

ステップ 3：チェックポイントを評価する

50k、100k、150k のチェックポイントを評価します。LIBERO-Goal は、ほかのスイートより早い段階で性能のピークに達することがあります。トレーニング損失だけでなく、実際のタスク成功率に基づいて、スイートごとに最良のチェックポイントを選びます。

ステップ 4：LoRA をマージする

python vla-scripts/merge_lora_weights_and_save.py \
  --base_checkpoint openvla/openvla-7b \
  --lora_finetuned_checkpoint_dir /PATH/TO/CHECKPOINT_DIR

---

ワークフロー 4：ALOHA で OpenVLA-OFT+ をトレーニングして評価する

詳細なリファレンス：ALOHA のサーバーとクライアントのセットアップ全体、データの前処理、データセットの登録、トラブルシューティングについては、references/aloha-workflow.md を参照してください。

ALOHA Progress:
- [ ] Step 1: Preprocess raw ALOHA demonstrations
- [ ] Step 2: Convert to RLDS and register dataset configs
- [ ] Step 3: Fine-tune OFT+ with FiLM and 3 images
- [ ] Step 4: Start VLA server on GPU machine
- [ ] Step 5: Run client-side robot evaluation

ステップ 1：生データを前処理する

python experiments/robot/aloha/preprocess_split_aloha_data.py \
  --dataset_path /path/to/aloha_raw/task_name/ \
  --out_base_dir /path/to/aloha_preprocessed/ \
  --percent_val 0.05

ステップ 2：RLDS データセットを登録する

以下のファイルにエントリーを追加します。

• prismatic/vla/datasets/rlds/oxe/configs.py
• prismatic/vla/datasets/rlds/oxe/transforms.py
• prismatic/vla/datasets/rlds/oxe/mixtures.py

prismatic/vla/constants.py で ALOHA 定数を設定します。

# Expected defaults for ALOHA
NUM_ACTIONS_CHUNK = 25        # Match control frequency (25 Hz)
ACTION_DIM = 14               # 7 joints x 2 arms
PROPRIO_DIM = 14
ACTION_PROPRIO_NORMALIZATION_TYPE = "BOUNDS"  # Absolute joint angles

ステップ 3：OFT+ をファインチューニングする

torchrun --standalone --nnodes 1 --nproc-per-node 8 vla-scripts/finetune.py \
  --vla_path openvla/openvla-7b \
  --data_root_dir /PATH/TO/RLDS/DATASETS/ \
  --dataset_name aloha_task_name \
  --run_root_dir /YOUR/CHECKPOINTS/ \
  --use_l1_regression True \
  --use_diffusion False \
  --use_film True \
  --num_images_in_input 3 \
  --use_proprio True \
  --batch_size 4 \
  --learning_rate 5e-4 \
  --num_steps_before_decay 50000 \
  --max_steps 100005 \
  --use_val_set True \
  --val_freq 10000 \
  --save_freq 10000 \
  --lora_rank 32

ステップ 4：VLA サーバーを起動する（GPU マシン）

python vla-scripts/deploy.py \
  --pretrained_checkpoint /PATH/TO/FINETUNED/CHECKPOINT/ \
  --use_l1_regression True \
  --use_film True \
  --num_images_in_input 3 \
  --use_proprio True \
  --center_crop True \
  --unnorm_key aloha_task_name

サーバーは http://<server-ip>:8777/act でリッスンします。

ステップ 5：クライアント評価を実行する

python experiments/robot/aloha/run_aloha_eval.py \
  --center_crop True \
  --num_open_loop_steps 25 \
  --use_vla_server True \
  --vla_server_url http://<SERVER_IP>:8777 \
  --num_rollouts_planned 50 \
  --max_steps 1500

---

重要な不変条件

以下のフラグは、トレーニング時と推論時で必ず一致させてください。一致しないと、エラーが表面化しないまま失敗することがあります。

項目	必要な整合性	不一致の場合の問題
アクションヘッド	use_l1_regression と use_diffusion の整合性	ヘッドの読み込み誤り、無効なアクション
FiLM	トレーニング／評価／デプロイ間で use_film を一致させる	言語によるグラウンディングの低下
画像ストリーム	num_images_in_input の一致	形状の不一致、または性能低下
固有受容情報	use_proprio の一致	状態条件付けの不一致
LoRA ランク	lora_rank の一致	アダプターの読み込みエラー
クロップ	トレーニングで image_aug=True の場合、評価では center_crop=True にする	成功率の大幅な低下
アクションチャンク	num_open_loop_steps ≈ NUM_ACTIONS_CHUNK	レイテンシーと成功率のトレードオフが変化
正規化解除キー	チェックポイントの統計情報に unnorm_key が存在すること	アクションのスケールが不適切になる

簡易検証：

# Verify config parity before long eval runs
train_flags = {"use_film": False, "num_images": 2, "use_proprio": True, "lora_rank": 32}
eval_flags  = {"use_film": False, "num_images": 2, "use_proprio": True, "lora_rank": 32}
for k in train_flags:
    assert train_flags[k] == eval_flags[k], f"Mismatch: {k}: {train_flags[k]} vs {eval_flags[k]}"
print("All flags consistent")

---

よくある問題

問題：GPU の種類を変えてチェックポイントを移動した後、アクションの品質が低下する

対処法：下流デバイスで LoRA アダプターを再度マージします。

python vla-scripts/merge_lora_weights_and_save.py \
  --base_checkpoint openvla/openvla-7b \
  --lora_finetuned_checkpoint_dir /PATH/TO/CHECKPOINT_DIR

問題：アクションのスケールが誤っている、または正規化解除に失敗する

対処法：--unnorm_key がチェックポイント内のデータセット統計情報と一致しているか確認します。

import torch
ckpt = torch.load("checkpoint/model.pt", map_location="cpu")
print("Available norm keys:", list(ckpt.get("norm_stats", {}).keys()))

問題：評価の成功率が予想外に低い

対処法：上の表にあるすべての不変条件を確認します。最もよくある原因は、image_aug=True でトレーニングしたにもかかわらず、center_crop=True を指定していないことです。

問題：LIBERO の評価で、データセットのパスを要求する EOFError が発生する

対処法：LIBERO_CONFIG_PATH を設定し、ヘッドレス評価の前に対話なしで読み込める設定ファイルを作成します。

問題：ALOHA クライアントで ROS のインポート時に libffi のシンボルエラーが発生する

対処法：conda install -c conda-forge libffi

問題：flash-attn のインストールに失敗する

対処法：TMPDIR と PIP_CACHE_DIR を同じファイルシステム上に設定してから、--no-cache-dir を指定して再試行します。

問題：EGL の終了処理ログに EGL_NOT_INITIALIZED が表示される

対処法：終了コードが 0 以外でない限り、終了処理に伴うノイズとして扱います。EGL 環境変数を設定します。

export MUJOCO_GL=egl PYOPENGL_PLATFORM=egl
export CUDA_VISIBLE_DEVICES=0 MUJOCO_EGL_DEVICE_ID=0

---

HPC／クラスターのユーザー向け

Slurm クラスターでは、/home のクォータを使い切らないよう、キャッシュをスクラッチ領域に割り当てます。

export HF_HOME=/scratch/$USER/.cache/huggingface
export XDG_CACHE_HOME=/scratch/$USER/.cache
export PIP_CACHE_DIR=/scratch/$USER/.cache/pip
export TMPDIR=/scratch/$USER/tmp

conda を使用する場合は、クラスターの Python モジュールを重ねて読み込まないでください。通常は module load cuda だけで十分です。

---

高度なトピック

論文の概要とチェックポイント：references/paper-and-checkpoints.mdを参照してください。 LIBERO ワークフローの詳細：references/libero-workflow.mdを参照してください。 ALOHA ワークフローの詳細：references/aloha-workflow.mdを参照してください。 設定マップとトラブルシューティング表：references/config-troubleshooting.mdを参照してください。

リソース

• プロジェクトのウェブサイト：https://openvla-oft.github.io/
• 論文：https://arxiv.org/abs/2502.19645
• リポジトリ：https://github.com/moojink/openvla-oft
• RLDS ビルダー：https://github.com/moojink/rlds_dataset_builder

エージェントの実行手順

1. 環境を確認します。 GPU メモリ、モデルのチェックポイントとライセンス、フレームワークのバージョン、入力形式を確認します。
2. 入力を特定します。 データまたはユーザーに確認し、形式、識別子、パラメーターを確認します。結果を変える値については、推測せずに尋ねます。
3. まず小規模に実行します。 最初に、低解像度または短い長さで単一サンプルの推論を実行します。
4. 上記の手順と参考資料を使用して、タスク全体を実行します。
5. 結果を検証します。 出力を定性的に評価し、タスクの指標で確認します。生成コンテンツに関するライセンス上の制限も確認します。
6. 報告します。 実行した内容（バージョン、コマンド、パラメーター）、確認した内容、未確定の事項を伝えます。

次のような場合	対応方法
大きな入力でメモリ不足が発生する	解像度またはシーケンス長を下げる、半精度を使う、または入力をタイル分割します。
これらの手順にある関数、フラグ、エンドポイントがインストール済みバージョンに存在しない	インストール済みバージョンのドキュメント（help()、--help、公式ドキュメント）を確認し、適宜対応してユーザーに伝えます。API を決して捏造しないでください。
必須の入力、識別子、パラメーターが曖昧である	ユーザーに尋ねるか、実行前に前提を明示します。

誠実性に関するルール

• 結果、パラメーター、識別子、引用、統計を決して捏造しないでください。実行または検証できないことがあれば、率直に伝えます。
• 商用利用や公開利用の前に、モデルとデータセットのライセンスを確認します。
• ここに記載されたバージョン固有の詳細は古くなっている可能性があるため、インストール済みバージョンの公式ドキュメントで確認します。
• 費用が発生する操作、共有 GPU またはクラウドのクォータを消費する操作、個人データまたは患者データに触れる操作、取り消せない操作の前には、許可を求めます。

関連スキル

• fine-tuning-serving-openpi：JAX または PyTorch バックエンドを使用して、Physical Intelligence の OpenPI モデル（pi0、pi0-fast、pi0.5）をファインチューニングし、ロボットポリシー推論用に提供します。…
• evaluating-cosmos-policy：LIBERO および RoboCasa のシミュレーション環境で NVIDIA Cosmos Policy を評価します。
• stable-diffusion-image-generation：HuggingFace Diffusers ライブラリを通じて Stable Diffusion モデル（SD 1.5、SDXL、SD 3.0、Flux）で画像を生成します。テキストから画像への生成を対象とします…