fine-tuning-openvla-oft

OpenVLA-OFT

基于官方 openvla-oft 代码库，为 OpenVLA-OFT 和 OpenVLA-OFT+ 提供微调和评估工作流。涵盖空白机器环境配置，以及使用 LoRA 对 OpenVLA 进行适配，以通过连续动作预测头生成机器人动作。

快速开始

克隆公开仓库，按照官方说明完成配置，然后评估预训练的 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 使用专用的连续动作头（L1 回归或扩散）取代这种做法，同时冻结 VLA 主干网络并通过 LoRA 进行适配。

OFT 与 OFT+ 变体：

变体	FiLM	图像	典型用途
OFT	关闭	2 张（正面 + 腕部）	LIBERO 仿真
OFT+	开启	3 张（高位 + 左腕 + 右腕）	ALOHA 真实场景

关键架构选择：

• LoRA 适配：在 VLA 主干网络上使用秩为 32 的 LoRA（无需完整微调）
• 连续动作：L1 回归头（默认）或扩散头
• FiLM 条件化：特征级线性调制，可在 OFT+ 中加强语言对齐
• 多图像输入：通过 num_images_in_input 配置 2 或 3 路摄像头流

计算资源要求

任务	GPU	显存	备注
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	一次性操作

预期性能基准

官方结果（论文配置，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 分支。

适用场景与替代方案

适用于以下情况：

• 目标任务是结合视觉和语言条件生成机器人动作
• 首选使用 LoRA 适配 openvla/openvla-7b
• 需要 OpenVLA-OFT 论文中的官方 LIBERO 或 ALOHA 工作流
• 希望使用连续动作头（L1 回归或扩散），而不是标记化动作

以下情况可考虑替代方案：

• 需要不同的 VLA 架构（pi0/pi0.5 模型可使用 fine-tuning-serving-openpi）
• 需要 NVIDIA Cosmos Policy 技术栈（可使用 evaluating-cosmos-policy）
• 需要在不使用机器人动作头的情况下微调通用大模型

---

工作流 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 上微调

详细参考：请参阅 references/libero-workflow.md，了解完整的 LIBERO 设置、检查点选择策略和 LoRA 合并说明。

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+

详细参考：请参阅 references/aloha-workflow.md，了解完整的 ALOHA 服务端-客户端设置、数据预处理、数据集注册和故障排查。

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

解决方法：除非退出代码非零，否则将其视为清理阶段的杂音。设置 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