🤖 X-VLA：基于软提示的Transformer作为可扩展的跨机器人形态视觉-语言-动作模型

📄 论文	🌐 项目页面	🤗 Hugging Face
阅读完整研究	探索演示	访问模型与数据集

🏆 亮点与新闻

🎉 热烈喜讯：X-VLA 被 ICLR 2026 接收

我们非常高兴地宣布，X-VLA 已被 ICLR 2026 接收。

🚀 现已在 LeRobot 中支持

X-VLA 现已原生集成到 LeRobot 平台。
快来试试吧！我们由衷感谢 Hugging Face 团队的支持与合作。

🥇 IROS 2025 冠军得主

X-VLA 在 IROS 2025 举办的 AgiBot 世界挑战赛 中荣获 第一名（冠军）。

---

🧩 概述

成功的通用型 视觉–语言–动作（VLA） 模型依赖于跨不同机器人形态的大规模、可扩展训练。
为充分利用大规模机器人数据集的异构性，X-VLA 引入了一种 软提示 机制——即特定于机器人形态的可学习嵌入，用以引导统一的 Transformer 主干网络实现高效的多领域策略学习。

由此构建的架构——X-VLA-0.9B——在六个仿真平台和三台真实机器人上实现了 最先进的泛化能力，其灵巧性、适应性和效率均超越了先前的 VLA 方法。

https://github.com/user-attachments/assets/c047bac4-17c3-4d66-8036-badfab2b8c41

---

🚀 快速入门：安装与部署

1️⃣ 安装

# 克隆仓库
git clone https://github.com/2toinf/X-VLA.git
cd X-VLA

# 创建并激活 Conda 环境
conda create -n XVLA python=3.10 -y
conda activate XVLA

# 安装依赖
pip install -r requirements.txt

或者

conda env create -f environment.yml
conda activate xvla-stable

---

2️⃣ 部署 X-VLA 进行推理

X-VLA 采用 服务器–客户端 架构，将模型环境与仿真或机器人特定依赖项分离。 这种设计避免了包冲突，并支持在多 GPU、SLURM 集群或边缘设备上进行分布式推理。

🧠 可用的预训练模型

• 我们发现将模型转换为 HF 格式后，性能略有下降（在不同数据集上约 1%），我们正在积极调查原因。

🧠 关于 Libero 的设置与评估

• 如有关于相对动作到绝对动作的转换及其实现的问题，请先参考 issue #2 和 #15。我们已在 这里 更新了完整的预处理指南。

🔥 更新：我们已发布 LoRA 微调代码，以及检查点和相关的推理代码。

模型 ID	载体	描述	性能	评估指南
2toINF/X-VLA-Pt	基础模型	在大规模异构的机器人–视觉–语言数据集上预训练，用于通用迁移。	—	—
2toINF/X-VLA-AgiWorld-Challenge	Agibot-G1	针对 AgiWorld 挑战赛微调。	冠军🥇	-
2toINF/X-VLA-Calvin-ABC_D	Franka	在 CALVIN 基准测试（ABC_D 子集）上微调	4.43	Calvin 评估
2toINF/X-VLA-Google-Robot	Google Robot	在大规模 Google Robot 数据集上微调	83.5%(VM) 76.4%(VA)	Simpler 评估
2toINF/X-VLA-Libero	Franka	在 LIBERO 基准测试上微调	98.1%	LIBERO 评估
2toINF/X-VLA-VLABench	Franka	在 VLABench 基准测试上微调	51.1分	VLABench 评估
2toINF/X-VLA-RoboTwin2	Agilex	基于 RoboTwin2 数据集训练，用于双臂协同操作（每项任务 50 次演示）。	70%	RoboTwin2.0 评估
2toINF/X-VLA-WidowX	WidowX	在 BridgeDataV2（Simpler 基准）上微调。	95.8%	Simpler 评估
2toINF/X-VLA-SoftFold	Agilex	在 Soft-Fold 数据集上微调。专门用于可变形物体的操作（如折叠和布料控制）。	2 小时内布料折叠成功率达到 100%。	SoftFold-Agilex
LoRA 适配器
2toINF/X-VLA-libero-spatial-peft	Franka	在 LIBERO 基准测试上微调	96.2%	LIBERO 评估
2toINF/X-VLA-libero-object-peft	Franka	在 LIBERO 基准测试上微调	96%	LIBERO 评估
2toINF/X-VLA-libero-goal-peft	Franka	在 LIBERO 基准测试上微调	94.4%	LIBERO 评估
2toINF/X-VLA-libero-long-peft	Franka	在 LIBERO 基准测试上微调	83.2%	LIBERO 评估
2toINF/X-VLA-simpler-widowx-peft	WidowX	在 BridgeDataV2（Simpler 基准）上微调。	66.7%	Simpler 评估

---

🧩 注意事项

• 所有模型采用一致的架构：configuration_xvla.py、modeling_xvla.py 和统一的分词器 (tokenizer.json)。
• X-VLA-Pt 模型是 基础检查点，在多个机器人领域上进行了训练。
• 每种载体都在其各自环境中进行了微调，同时保持跨载体的一致性。
• 评估脚本（位于 evaluation/ 目录下）遵循标准化格式，以实现可重复的基准测试。

---

📊 性能指标遵循论文中详述的标准评估协议，详情请参阅 论文。

---

3️⃣ 启动推理服务器

from transformers import AutoModel, AutoProcessor
import json_numpy

# 加载模型和处理器
model = AutoModel.from_pretrained("2toINF/X-VLA-WidowX", trust_remote_code=True)
processor = AutoProcessor.from_pretrained("2toINF/X-VLA-WidowX", trust_remote_code=True)

# 启动推理服务器
print("🚀 正在启动 X-VLA 推理服务器...")
model.run(processor, host="0.0.0.0", port=8000)

启动后，API 端点如下：

POST http://<server_ip>:8000/act

---

4️⃣ 客户端交互与动作预测

客户端通过 HTTP POST 方法进行通信，以 JSON 负载的形式发送多模态数据（视觉 + 语言 + 本体感知）。

负载结构

键	类型	描述
proprio	json_numpy.dumps(array)	当前本体感知状态（例如，关节位置）。
language_instruction	str	任务指令（例如，“拿起红色方块”）。
image0	json_numpy.dumps(array)	主摄像头图像（RGB）。
image1, image2	可选	如适用，其他摄像头视图。
domain_id	int	当前机器人本体/领域的标识符。
steps	int	基于流匹配生成的去噪步数（例如，10步）。

示例客户端代码

import requests
import numpy as np
import json_numpy

server_url = "http://localhost:8000/act"
timeout = 5

# 准备输入
proprio = np.zeros(7, dtype=np.float32)
image = np.zeros((256, 256, 3), dtype=np.uint8)
instruction = "将夹爪移动到目标位置"

payload = {
    "proprio": json_numpy.dumps(proprio),
    "language_instruction": instruction,
    "image0": json_numpy.dumps(image),
    "domain_id": 0,
    "steps": 10
}

try:
    response = requests.post(server_url, json=payload, timeout=timeout)
    response.raise_for_status()
    result = response.json()
    actions = np.array(result["action"], dtype=np.float32)
    print(f"✅ 收到 {actions.shape[0]} 个预测动作。")
except Exception as e:
    print(f"⚠️ 请求失败：{e}")
    actions = np.zeros((30, 20), dtype=np.float32)

预期输出

[服务器] 模型已成功加载至 cuda:0
[服务器] 正在监听 0.0.0.0:8000
[客户端] 向服务器发送观测数据...
✅ 收到 30 个预测动作。

---

5️⃣ 标准化控制接口：EE6D

为确保不同本体之间的一致性，X-VLA 采用统一的 EE6D（末端执行器 6D） 控制空间。

组件	规格	备注
本体输入	当前 EE6D 姿态（位置 + 方向）	必须与训练空间的归一化一致。
动作输出	预测的目标位移/绝对姿态（EE6D）	由下游控制器执行。
维度	20 维向量 = 3（EE 位置） + 6（6D 旋转） + 1（夹爪） + 10（填充）
单臂情况	如果仅有一只手臂，则用零填充以保持 20 维向量。

⚙️ 参考后处理：

from datasets.utils import rotate6d_to_xyz
action_final = np.concatenate([
    action_pred[:3],
    rotate6d_to_xyz(action_pred[3:9]),
    np.array([1.0 如果 action_pred[9] > 0.5 else 0])
])

将本体感知输入模型时，应相应地应用 逆变换。

---

6️⃣ 参考客户端实现

每个发布的模型都包含一个对应的 参考客户端，位于 evaluation/<domain>/<robot>/client.py 中，用于复现确切的部署行为。我们强烈建议在连接物理或仿真机器人时，基于这些客户端进行适配。

---

7️⃣ SLURM 和集群部署

对于大规模或分布式训练/部署（例如，HPC 集群、AgiBot 节点）：

python -m deploy --model_path /path/to/your/model

该脚本会自动检测 SLURM 环境变量，启动分布式服务器，并将连接元数据写入 info.json 文件中。

---

⚙️ 自定义数据上的训练/微调

X-VLA 支持通过模块化且可扩展的数据集接口，对新演示数据进行微调。

数据准备流程

1. 准备元 JSON 文件 — 每个领域都有一个 meta.json 文件，列出轨迹文件路径。

2. 实现自定义处理器 — 编写具有 iter_episode(traj_idx) 生成器的领域加载类。

3. 注册领域 — 更新：

   • datasets/domain_handler/registry.py
   • datasets/domain_config.py

示例处理器

处理器	数据集	描述
"lerobot"	Agibot-Beta	针对 LEROBOT 格式优化
"h5py"	RoboMind / 模拟	从 .h5 轨迹高效加载
"scattered"	AGIWorld	处理分散存储的轨迹

---

使用 Accelerate 启动训练

accelerate launch \
    --mixed_precision bf16 \
    train.py \
    --models '2toINF/X-VLA-Pt' \
    --train_metas_path /path/to/meta_files.json \
    --learning_rate 1e-4 \
    --learning_coef 0.1 \
    --iters 50000 \
    --freeze_steps 1000 \
    --warmup_steps 2000

参数	描述
--models	基础模型（例如，'2toINF/X-VLA-Pt'）
--train_metas_path	元 JSON 文件路径
--batch_size	批量大小
--learning_rate	基础学习率
--learning_coef	软提示的学习率乘数
--iters	总训练迭代次数
--freeze_steps	冻结主干网络的步数
--warmup_steps	热身迭代次数

---

📚 引用

如果您在研究中使用 X-VLA，请引用以下内容：

@article{zheng2025x,
  title   = {X-VLA: 基于软提示的 Transformer 作为可扩展的跨本体视觉-语言-动作模型},
  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 预印本 arXiv:2510.10274},
  year    = {2025}
}

---

🪪 许可证

本仓库采用 Apache 2.0 许可证 许可。您可以在该许可证的条款下自由地使用、修改和分发代码。

版权所有 2025 2toINF（https://github.com/2toinf）
依照 Apache 许可证第 2.0 版授权。

---

由 2toINF 维护 💬 欢迎通过 GitHub Discussions 或 Pull Requests 提出反馈、报告问题或贡献代码。

X-VLA 快速上手指南

X-VLA 是一个基于软提示（Soft-Prompt）机制的可扩展跨具身视觉 - 语言 - 动作模型，支持多种机器人平台的通用策略学习。本指南将帮助您快速完成环境搭建与推理部署。

1. 环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux (推荐 Ubuntu 20.04+)
• Python 版本: 3.10
• 硬件要求: NVIDIA GPU (支持 CUDA)，显存建议 16GB 以上以运行完整模型
• 前置依赖:
  • Conda (推荐使用 Miniconda 或 Anaconda)
  • Git

💡 国内加速建议： 若下载依赖或模型较慢，建议配置国内镜像源：

• Conda: 使用清华或中科大镜像 (conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/)
• PyPI: 使用阿里云或清华镜像 (pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple)
• Hugging Face: 设置环境变量 export HF_ENDPOINT=https://hf-mirror.com

2. 安装步骤

克隆代码库

git clone https://github.com/2toinf/X-VLA.git
cd X-VLA

创建并激活虚拟环境

推荐使用 Conda 创建隔离环境：

conda create -n XVLA python=3.10 -y
conda activate XVLA

安装依赖

您可以选择通过 requirements.txt 或 environment.yml 进行安装：

方式 A：使用 requirements.txt

pip install -r requirements.txt

方式 B：使用 environment.yml (推荐)

conda env create -f environment.yml
conda activate xvla-stable

3. 基本使用

X-VLA 采用 Server-Client 架构，将模型推理环境与机器人具体依赖解耦。以下是启动服务并获取动作预测的最小化示例。

第一步：启动推理服务器

以下代码将加载预训练模型（以 WidowX 为例）并启动 HTTP 服务：

from transformers import AutoModel, AutoProcessor
import json_numpy

# 加载模型和处理器
# 注意：首次运行会自动从 Hugging Face 下载模型，请确保网络通畅或配置镜像
model = AutoModel.from_pretrained("2toINF/X-VLA-WidowX", trust_remote_code=True)
processor = AutoProcessor.from_pretrained("2toINF/X-VLA-WidowX", trust_remote_code=True)

# 启动推理服务器
print("🚀 Starting X-VLA inference server...")
model.run(processor, host="0.0.0.0", port=8000)

启动成功后，服务端将监听 http://0.0.0.0:8000。

第二步：客户端发送请求并获取动作

客户端通过 HTTP POST 请求发送多模态数据（图像、本体感知、语言指令），并接收预测的动作序列。

import requests
import numpy as np
import json_numpy

server_url = "http://localhost:8000/act"
timeout = 5

# 准备输入数据 (此处为零占位符，实际使用请替换为真实传感器数据)
proprio = np.zeros(7, dtype=np.float32)       # 本体感知状态 (如关节位置)
image = np.zeros((256, 256, 3), dtype=np.uint8) # 主摄像头 RGB 图像
instruction = "Move the gripper to the target position" # 语言指令

# 构建 Payload
payload = {
    "proprio": json_numpy.dumps(proprio),
    "language_instruction": instruction,
    "image0": json_numpy.dumps(image),
    "domain_id": 0,          # 机器人具身标识 ID
    "steps": 10              # 去噪步数 (基于 flow-matching)
}

try:
    response = requests.post(server_url, json=payload, timeout=timeout)
    response.raise_for_status()
    result = response.json()
    
    # 解析返回的动作 (20 维向量：3 位置 + 6 旋转 + 1 夹爪 + 10 填充)
    actions = np.array(result["action"], dtype=np.float32)
    print(f"✅ Received {actions.shape[0]} predicted actions.")
    
except Exception as e:
    print(f"⚠️ Request failed: {e}")
    actions = np.zeros((30, 20), dtype=np.float32)

关键说明

• 控制空间: 模型输出统一为 EE6D (末端执行器 6D) 格式，包含位置、6D 旋转表示及夹爪状态。
• 后处理: 实际部署时，需将输出的 6D 旋转转换为欧拉角或四元数以适配底层控制器（参考官方 rotate6d_to_xyz 工具函数）。
• 模型选择: 可根据具体机器人型号更换 from_pretrained 中的模型 ID（如 2toINF/X-VLA-Libero, 2toINF/X-VLA-Google-Robot 等）。