# X-VLA: 任意のロボット、任意のタスクに対応する、初のソフトプロンプト型ロボット基盤モデル

## 概要

長年にわたり、ロボティクス分野では、自然な人間の指示に従い、多様な環境やロボット本体を巧みに操作できるエージェントの構築が目標とされてきました。LLMやVLMにおける最近のブレイクスルーは、前進への道筋を示唆しています。これらの基盤モデルのアーキテクチャを、アクションに根ざすことで具現化された制御に拡張するのです。これにより、Vision-Language-Action (VLA) モデルの台頭がもたらされました。単一の汎用モデルが、広範なセマンティック理解と堅牢な操作スキルを組み合わせることを期待しています。

しかし、このようなモデルの学習は困難です。ロボットのデータは、プラットフォーム、センサー、エンボディメント、収集プロトコルごとに断片化しています。異質性はあらゆる場所に現れます。異なるアーム構成、異なるアクション空間、異なるカメラセットアップ、異なる視覚ドメイン、異なるタスク分布などです。これらの不一致は、大きな分布シフトを生み出し、事前学習を不安定にし、適応を信頼できないものにします。

メタ学習とプロンプト学習に着想を得て、私たちは次の問いを投げかけます。**「VLAモデルが、LLMがタスクをプロンプトを通じて学習するのと同じ方法で、各ロボットやデータセットの構造を学習できたらどうなるか？」**

**X-VLA**は、ソフトプロンプトとフローマッチングを用いたVLAフレームワークです。各ハードウェア構成を「タスク」として扱い、少数の学習可能な埋め込みベクトルでエンコードします。これらの**Soft Prompts**は、エンボディメントやドメイン固有の変動を捉え、マルチモーダル融合の初期段階からTransformerを導きます。この仕組みにより、X-VLAは多様なロボットの形態、データタイプ、センサー構成を、単一の統合アーキテクチャ内で調整できます。

  <img
    src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/lerobot/xvla-architecture.png"
    alt="XVLA Architecture"
    style="max-width: 100%; height: auto; width: 800px;"
  />

純粋な Transformer エンコーダーで構築された X-VLA は、モデルサイズとデータセットの多様性に応じて自然にスケールします。6 つのシミュレーションベンチマークと 3 台の実ロボットにわたって、Soft Prompts はハードウェアやドメインの違いを扱う際に既存の手法を一貫して上回ります。7 つのロボットプラットフォームにまたがる 29 万エピソードで学習された X-VLA-0.9B は、フェーズ I でエンボディメントに依存しない汎用ポリシーを学習し、バックボーンを凍結したまま新しいプロンプトセットを学習するだけで、フェーズ II では新しいロボットに効率的に適応します。

  <img
    src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/lerobot/xvla-architecture2.png"
    alt="XVLA Architecture 2"
    style="width: 60%; height: auto;"
  />

パラメータのわずか1%（9M）をチューニングしただけで、X-VLA-0.9Bは、**学習可能なパラメータ数が300分の1**であるにもかかわらず、LIBEROおよびSimpler-WidowXでπ₀に匹敵するパフォーマンスを達成しています。また、2分未満で布をたたむといった、実世界での高い器用さを、ごく少数のデモレーションで示しています。

  <img
    src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/lerobot/xvla-fold.png"
    alt="XVLA fold visualization"
    style="width: 95%; max-width: 1100px; height: auto;"
  />

X-VLAは、汎用的なロボット知能にはますます複雑なアーキテクチャではなく、異質性を吸収するための適切な方法のみが必要であることを示しています。Soft Promptsは、多様なロボットデータを統合するためのシンプルでスケーラブルなメカニズムを提供し、適応可能でクロスエンボディメントなロボット基盤モデルへの道を切り拓きます。

## インストール

LeRobotのインストール後、X-VLAの依存関係をインストールします:

```bash
pip install -e ".[xvla]"
```

PyPIからLeRobotをインストールした場合は:

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

## クイックスタート

### 基本的な使用方法

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

```bash
policy.type=xvla
```

### 事前学習済みチェックポイントの評価

LIBEROによる評価の例:

```bash
lerobot-eval \
  --policy.path="lerobot/xvla-libero" \
  --env.type=libero \
  --env.task=libero_spatial,libero_goal,libero_10 \
  --env.control_mode=absolute \
  --eval.batch_size=1 \
  --eval.n_episodes=1 \
  --env.episode_length=800 \
  --seed=142
```

## 利用可能なチェックポイント

### 🎯 ベースモデル

**[lerobot/xvla-base](https://huggingface.co/lerobot/xvla-base)**

X-VLAの0.9Bパラメータのインスタンス化です。慎重に設計されたデータ処理と学習レシピを用いて訓練されています。訓練パイプラインは2つのフェーズで構成されています:

- **フェーズ I: プリトレーニング** - Droid、Robomind、Agibot の 29 万エピソードから、5 種類のロボットアーム（単一アームからバイマニュアル構成まで）にまたがる 7 つのプラットフォームでプリトレーニングされています。ソフトプロンプトを活用してエンボディメント固有の変動を吸収することで、モデルはエンボディメントに依存しない汎用ポリシーを学習します。

- **フェーズ II: ドメイン適応** - ターゲットドメイン向けにデプロイ可能なポリシーへ適応させます。新しいソフトプロンプトのセットを導入し、新規ドメインのハードウェア構成をエンコードするように最適化します。この際、事前学習済みバックボーンは凍結されたままにします。

### シミュレーションのチェックポイント

**[lerobot/xvla-libero](https://huggingface.co/lerobot/xvla-libero)**

LIBEROベンチマークで93%の成功率を達成します。シミュレーションタスク用にベースモデルからファインチューニングされています。

**[lerobot/xvla-widowx](https://huggingface.co/lerobot/xvla-widowx)**

BridgeDataでファインチューニングされ、コンパクトなWidowXプラットフォームでのピック&プレイス実験に使用されました。堅牢な操作能力を示しています。

### 🤖 実世界のチェックポイント

**[lerobot/xvla-folding](https://huggingface.co/lerobot/xvla-folding)**

高品質なSoft-FOLD布折りたたみデータセットで学習された、微調整済みの巧みな操作モデル。2時間以上の連続的な布折りたたみにおいて100%の成功率を達成します。

**[lerobot/xvla-agibot-world](https://huggingface.co/lerobot/xvla-agibot-world)**

AgileXロボットの巧緻性操作タスク向けに最適化されています。

**[lerobot/xvla-google-robot](https://huggingface.co/lerobot/xvla-google-robot)**

Google Robotプラットフォーム向けに調整しました。

## X-VLAの学習

### 推奨トレーニング構成

新しいエンボディメントやタスクに対してX-VLAをファインチューニングする際は、VLMをフリーズせず、また`policy.dtype=bfloat16`を設定してOOMエラーを回避することをお勧めします。

```bash
lerobot-train \
  --dataset.repo_id=YOUR_DATASET \
  --output_dir=./outputs/xvla_training \
  --job_name=xvla_training \
  --policy.path="lerobot/xvla-base" \
  --policy.repo_id="HF_USER/xvla-your-robot" \
  --policy.dtype=bfloat16 \
  --policy.action_mode=auto \
  --steps=20000 \
  --policy.device=cuda \
  --policy.freeze_vision_encoder=false \
  --policy.freeze_language_encoder=false \
  --policy.train_policy_transformer=true \
  --policy.train_soft_prompts=true
```

### トレーニングパラメータの説明

| パラメータ                  | デフォルト | 説明                                    |
| -------------------------- | ------- | ---------------------------------------------- |
| `freeze_vision_encoder`    | `false` | VLMのビジョンエンコーダーの重みをフリーズしないでください   |
| `freeze_language_encoder`  | `false` | VLMの言語エンコーダーの重みをフリーズしないでください |
| `train_policy_transformer` | `true`  | ポリシー変換器レイヤーの学習を許可       |
| `train_soft_prompts`       | `true`  | ソフトプロンプトの学習を許可                    |

**💡 ベストプラクティス**: Phase IIでの新しい実装形態への適応では、VLMエンコーダーを凍結せず、ポリシートランスフォーマーとソフトプロンプトも学習してください。

### 例: 両手ロボットでの学習

```bash
lerobot-train \
  --dataset.repo_id=<USER>/bimanual-so100-handover-cube \
  --output_dir=./outputs/xvla_bimanual \
  --job_name=xvla_so101_training \
  --policy.path="lerobot/xvla-base" \
  --policy.dtype=bfloat16 \
  --policy.repo_id="YOUR_USERNAME/xvla-biso101" \
  --steps=3000 \
  --policy.device=cuda \
  --policy.action_mode=so101_bimanual \
  --policy.freeze_vision_encoder=false \
  --policy.freeze_language_encoder=false \
  --policy.train_policy_transformer=true \
  --policy.train_soft_prompts=true
```

💡 **最高性能:** 十分な計算リソースがあり、X-VLAのファインチューニングで最高性能を達成したい場合は、公式のファインチューニング戦略に従う必要があります:

**🔥 カスタムな学習率スキームで全コンポーネントをフルファインチューニング**

安定した最適化を確保するために、Vision-Language Model (VLM) はベースの学習率の 1/10 のみで学習する必要があり、その他のすべてのコンポーネントはフルの学習率を使用します。この学習率の比率は、強力かつ安定したファインチューニングの性能を達成するために不可欠です。これはデフォルトで既に設定されています。❕Note

公式に報告されている性能を完全に一致させるには、soft-prompts に対して追加のウォームアップ LR スケジュールが必要になる場合があります。これによりわずかな改善が得られる可能性があります。最適な結果を得るために、カスタマイズした学習パイプラインでこの実装を行うことを推奨します。

## コアコンセプト

### 1. アクションモード

X-VLAは、異なるアクション空間やエンボディメントを処理するために、**Action Registry**システムを使用しています。`action_mode`パラメータは、アクションの処理方法、使用する損失関数、予測値のポストプロセッシング方法を定義します。

#### 利用可能なアクションモード

| アクションモード      | アクション次元              | 説明                                 | ユースケース                             |
| ---------------- | ----------------------- | ------------------------------------------- | ------------------------------------ |
| `ee6d`           | 20                      | xyz、6D回転、グリップアタッチメント付きの末端エフェクタ | 空間制御を備えたデュアルアーム構成 |
| `joint`          | 14                      | グリッパー付きのジョイント空間                    | 直接関節制御ロボット          |
| `agibot_ee6d`    | 20                      | MSE損失を持つAGI-botのバリアント               | AGI-botプラットフォーム                    |
| `so101_bimanual` | 20（モデル）、12（実数）   | SO101 両手ロボット                        | 両手操作タスク          |
| `auto`           | 20 (モデル)、auto (実数) | データセットからアクション次元を自動検出        | **推奨** 新規ロボット向け       |

#### アクションモードが重要な理由

`lerobot/xvla-base` のような`action_dim=20` で学習された事前学習済みチェックポイントがあり、異なるアクション次元（例えば、両腕アーム用の14など）を持つデータセットで学習したい場合、アクション次元を単純に切り捨てることはできません。アクションモードは以下を統括します：

1. **損失の計算**: 異なるアクション成分に対して異なる損失関数を使用（関節にはMSE、グリップにはBCEなど）
2. **前処理**: グリッパーチャネルのゼロ化、次元のパディング
3. **後処理**: グリッパーのロジットにシグモイドを適用し、パディングをトリムする

#### 例: BimanualSO101 アクションスペース

`so101_bimanual`アクションモードは、モデルの出力（20次元）と実際のロボットの制御（12次元）の間の不一致を処理します：

```python
# Model outputs 20 dimensions for compatibility
dim_action = 20

# Real robot only needs 12 dimensions
# [left_arm (6), right_arm (6)] = [joints (5) + gripper (1)] × 2
REAL_DIM = 12

# Preprocessing: Pad 12D actions to 20D for training
# Postprocessing: Trim 20D predictions to 12D for deployment
```

詳細については、[action_hub.py](https://github.com/huggingface/lerobot/blob/main/src/lerobot/policies/xvla/action_hub.py)の実装を参照してください。

#### オートアクションモード（推奨）

`auto` アクションモードは、あらゆるロボットで X-VLA を使用する最も簡単な方法です。データセットのアクション次元を自動的に検出し、パディングやトリミングを処理します。

```bash
lerobot-train \
  --policy.path="lerobot/xvla-base" \
  --policy.action_mode=auto \
  --policy.max_action_dim=20 \
  ...
```

**仕組み:**

- データセットから`action_feature.shape[-1]`を読み取ります（例: Frankaの場合は7）
- モデルの出力は、事前学習との互換性のために`max_action_dim`（デフォルトは20）です
- 損失は**実次元のみで**計算されます: `MSE(pred[:,:,:real_dim], target[:,:,:real_dim])`
- Postprocessは、ロボット制御のために出力を`real_dim`にトリムします

これにより、ほとんどのロボットに対してカスタムアクションモードを作成する必要がなくなります。

### 2. ドメイン ID

Domain IDは、異なるロボット構成やカメラセットアップに対する学習可能な識別子です。これにより、X-VLAは以下を区別できます。

- 異なるロボット（ロボット1とロボット2）
- 異なるカメラ構成（cam1 と cam2）
- 異なる組み合わせ（Robot1-cam1-cam2 vs Robot1-cam1 vs Robot2-cam1）

#### ドメインIDの設定

**学習中**: デフォルトでは、一般学習用にdomain_idが0に設定されます。

**評価中**: チェックポイントの学習設定と一致する domain_id を指定します。

```python
# Example: LIBERO checkpoint uses domain_id=3
domain_id = 3
```

The domain_id is automatically added to observations by the `XVLAAddDomainIdProcessorStep` in the preprocessing pipeline.

`lerobot/xvla-base` モデルは、以下のドメイン ID で学習されています。ロボット / 構成に最も近いものを選択することをお勧めします:

#### ファインチューニング用データセット

| データセット名     | ドメイン ID |
| ---------------- | --------- |
| ブリッジ           | 0         |
| RT1              | 1         |
| Calvin           | 2         |
| libero           | 3         |
| widowx-air       | 4         |
| AIR-AGILEX-HQ    | 5         |
| robotwin2_abs_ee | 6         |
| robotwin2_clean  | 6         |
| robocasa-human   | 7         |
| VLABench         | 8         |
| AGIBOT-challenge | 9         |
| AIR-AGILEX       | 10        |
| AIRBOT           | 18        |

### 3. Processor ステップ

X-VLAの適切な動作には、特定の前処理および後処理手順が必要です。

#### 必要な前処理手順

1. **XVLAImageToFloatProcessorStep**: 画像を [0, 255] の範囲から [0, 1] の範囲に変換します
2. **XVLAImageNetNormalizeProcessorStep**: ImageNet正規化を適用します（VLMバックボーンに必要）
3. **XVLAAddDomainIdProcessorStep**: 観測にdomain_idを追加します

#### カスタムプロセッサの例

LIBERO環境では、カスタムプロセッサが正規化された観測値を、X-VLAが学習に使用した入力に変換します:

```python
from lerobot.policies.xvla.processor_xvla import LiberoProcessorStep

processor = LiberoProcessorStep()
# Builds the 9D state from the canonical 8D state, with the end-effector rotation in 6D
# Rotates the wrist camera back, since the LIBERO integration rotates every camera by 180°
```

### 4. 設定パラメータ

X-VLAの主要な設定パラメータ:

```python
# Observation and action
n_obs_steps: int = 1          # Number of observation timesteps
chunk_size: int = 32           # Action sequence length
n_action_steps: int = 32       # Number of action steps to execute

# Model architecture
hidden_size: int = 1024        # Transformer hidden dimension
depth: int = 24                # Number of transformer layers
num_heads: int = 16            # Number of attention heads
num_domains: int = 30          # Maximum number of domain IDs
len_soft_prompts: int = 32     # Length of soft prompt embeddings

# Action space
action_mode: str = "ee6d"      # Action space type (use "auto" for auto-detection)
use_proprio: bool = True       # Use proprioceptive state
max_state_dim: int = 32        # Maximum state dimension
max_action_dim: int = 20       # Max action dim for padding (used by "auto" mode)

# Vision
num_image_views: int | None    # Number of camera views
resize_imgs_with_padding: tuple[int, int] | None  # Target image size with padding

# Training
num_denoising_steps: int = 10  # Flow matching denoising steps
```

## カスタムアクションモードの作成

ロボットが独自のアクションスペースを持つ場合、カスタムのアクションモードを作成できます。

### ステップ1: アクションスペースを定義する

```python
from lerobot.policies.xvla.action_hub import BaseActionSpace, register_action
import torch
import torch.nn as nn

@register_action("my_custom_robot")
class MyCustomActionSpace(BaseActionSpace):
    """Custom action space for my robot."""

    dim_action = 15  # Your robot's action dimension
    gripper_idx = (7, 14)  # Gripper channel indices

    def __init__(self):
        super().__init__()
        self.mse = nn.MSELoss()
        self.bce = nn.BCEWithLogitsLoss()

    def compute_loss(self, pred, target):
        """Define your loss computation."""
        # Example: MSE for joints, BCE for grippers
        joints_loss = self.mse(pred[:, :, :7], target[:, :, :7])
        gripper_loss = self.bce(pred[:, :, self.gripper_idx],
                                target[:, :, self.gripper_idx])

        return {
            "joints_loss": joints_loss,
            "gripper_loss": gripper_loss,
        }

    def preprocess(self, proprio, action, mode="train"):
        """Preprocess actions before training."""
        # Example: Zero out grippers in proprioception
        proprio_m = proprio.clone()
        action_m = action.clone() if action is not None else None
        proprio_m[..., self.gripper_idx] = 0.0
        if action_m is not None:
            action_m[..., self.gripper_idx] = 0.0
        return proprio_m, action_m

    def postprocess(self, action):
        """Post-process predictions for deployment."""
        # Example: Apply sigmoid to gripper logits
        action[..., self.gripper_idx] = torch.sigmoid(action[..., self.gripper_idx])
        return action
```

### ステップ2: カスタムアクションモードを使用する

```bash
lerobot-train \
  --policy.action_mode=my_custom_robot \
  --dataset.repo_id=YOUR_DATASET \
  --policy.path="lerobot/xvla-base" \
  ...
```

## 高度なトピック

### マルチカメラ対応

X-VLAは`num_image_views`パラメータを介して複数のカメラビューをサポートしています:

```python
# Configure for 3 camera views
policy.num_image_views=3

# Add empty cameras if you have fewer physical cameras
policy.empty_cameras=1  # Adds 1 zero-padded camera view
```

### カスタム前処理パイプライン

環境に合わせたカスタム前処理パイプラインを作成します:

```python
from lerobot.processor import PolicyProcessorPipeline
from lerobot.policies.xvla import (
    XVLAImageToFloatProcessorStep,
    XVLAImageNetNormalizeProcessorStep,
    XVLAAddDomainIdProcessorStep,
)

# Build custom pipeline
preprocessor = PolicyProcessorPipeline(
    steps=[
        YourCustomProcessorStep(),  # Your custom processing
        XVLAImageToFloatProcessorStep(),  # Required: convert to float
        XVLAImageNetNormalizeProcessorStep(),  # Required: ImageNet norm
        XVLAAddDomainIdProcessorStep(domain_id=5),  # Your domain ID
    ]
)
```

### 異なるアクション次元の処理

データセットのアクション次元数が事前学習モデルよりも少ない場合:

**オプション 1（推奨）**: `auto` アクションモードを使用する

```bash
# Automatically detects your dataset's action dimension
# Works with any robot without custom code
policy.action_mode=auto
policy.max_action_dim=20  # Match pretrained model
```

**オプション 2**: 組み込みの padding を備えた事前定義されたアクションモードを使用する

```python
# Model expects 20D, dataset has 12D
# Action mode handles padding internally
action_mode = "so101_bimanual"  # Pads 12 → 20
```

**オプション 2**: 次元を明示的にマッピングするカスタムアクションモードを作成する

```python
@register_action("my_mapped_action")
class MappedActionSpace(BaseActionSpace):
    dim_action = 20
    REAL_DIM = 12

    def _pad_to_model_dim(self, x):
        # Custom padding logic
        ...
```

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

### よくある問題

**問題**:「アクション次元の不一致」

- **解決策**: ロボットのアクションスペースと`action_mode`が一致していることを確認してください。必要に応じて、カスタムのアクションモードを作成してください。

**問題**:「[0, 1] の範囲外の画像値」

- **解決策**: 正規化の前に、`XVLAImageToFloatProcessorStep` で画像が前処理されていることを確認してください。

**問題**:「ドメイン ID が見つかりません」

- **解決策**: `XVLAAddDomainIdProcessorStep`が正しいdomain_idとともに前処理パイプラインに含まれていることを確認してください。

**問題**:「新しいエンボディメントでの成功率が低い」

- **解決策**:
  1. action_modeが正しいことを確認してください
  2. ソフトプロンプトが学習されていることを確認します（`train_soft_prompts=True`）
  3. 適切な前処理（ImageNet正規化、domain_id）を確認してください
  4. トレーニングステップ数を増やすことを検討してください

**問題**:「学習中にメモリ不足が発生する」

- **解決策**:
  1. `chunk_size`を小さくします（例: 32から16へ）
  2. 勾配チェックポイントを有効にする
  3. バッチサイズを減らす
  4. より多くのコンポーネントをフリーズする

## 引用

研究でX-VLAを使用する場合は、以下を引用してください：

```bibtex
@article{zheng2025x,
  title   = {X-VLA: Soft-Prompted Transformer as Scalable Cross-Embodiment Vision-Language-Action Model},
  author  = {Zheng, Jinliang and Li, Jianxiong and Wang, Zhihao and Liu, Dongxiu and Kang, Xirui
             and Feng, Yuchun and Zheng, Yinan and Zou, Jiayin and Chen, Yilun and Zeng, Jia and others},
  journal = {arXiv preprint arXiv:2510.10274},
  year    = {2025}
}
```

## 追加のリソース

- [X-VLA 論文](https://arxiv.org/pdf/2510.10274)
- [LeRobot ドキュメント](https://github.com/huggingface/lerobot)
- [アクションレジストリの実装](https://github.com/huggingface/lerobot/blob/main/src/lerobot/policies/xvla/action_hub.py)
- [プロセッサの実装](https://github.com/huggingface/lerobot/blob/main/src/lerobot/policies/xvla/processor_xvla.py)
- [モデル設定](https://github.com/huggingface/lerobot/blob/main/src/lerobot/policies/xvla/configuration_xvla.py)

## コントリビューション

コントリビューションを大歓迎しています！ ロボット用に新しいアクションモードやプロセッサを実装した場合は、コミュニティの支援としてPRの提出をご検討ください。

