跳转到内容
StarVLA

快速开始

前置知识

Section titled “前置知识”

如果你对以下概念还不熟悉，先花 1 分钟了解一下：

  • VLM（Vision-Language Model，视觉-语言模型）：能同时理解图像和文字的 AI 模型，例如 Qwen-VL、GPT-4V。
  • VLA（Vision-Language-Action Model，视觉-语言-动作模型）：在 VLM 的基础上增加动作输出，让模型不仅能”看”和”说”，还能”做”——输入图像和自然语言指令，输出机器人动作（如关节角度，即机器人每个关节应该转到的角度值）。除了从 VLM 出发，也可以从 WM（World Model，世界模型） 出发构建类似的具身模型。
  • StarVLA 做的事：就像 PyTorch 之于深度学习——StarVLA 为 VLM→VLA 的改造提供全套基础设施：数据加载、训练循环、评测部署管线全部可复用，你只需要专注于模型本身。不管你是从 VLM 还是 WM 出发，都可以用同一套工具完成训练和评测。

环境要求

Section titled “环境要求”
项目最低要求推荐
GPU1 张 NVIDIA GPU（>=16GB 显存）8×A800 或更多（A100 / H200 等）
CUDA12.0+12.4
Python3.103.10
磁盘空间~20GB（代码 + 基础模型）100GB+（含数据集）
操作系统Linux（Ubuntu 20.04+）Ubuntu 22.04

第一步：安装

Section titled “第一步：安装”

  1. 克隆仓库

    Terminal window
    git clone https://github.com/starVLA/starVLA
    cd starVLA

  2. 创建 conda 环境

    Terminal window
    conda create -n starVLA python=3.10 -y
    conda activate starVLA

  3. 安装依赖

    Terminal window
    # 安装基础依赖
    pip install -r requirements.txt
    

    # 安装 FlashAttention2（加速 Transformer 推理，必装）
    # 注意：flash-attn 需要从源码编译，首次安装可能需要 10-20 分钟，这是正常的
    pip install flash-attn --no-build-isolation
    

    # 以开发模式安装 starVLA（-e 表示 editable/开发模式：
    # 安装后修改代码无需重新安装，改动会立即生效）
    pip install -e .

常见问题：flash-attn 安装失败

Section titled “常见问题：flash-attn 安装失败”

flash-attn 对 CUDA 版本和 PyTorch 版本非常敏感。如果安装失败，先检查版本是否匹配：

Terminal window
# 查看 CUDA 版本
nvcc -V


# 查看 PyTorch 和已安装包的版本
pip list | grep -E 'torch|transformers|flash-attn'

已验证的组合：

  • flash-attn==2.7.4.post1 + CUDA 12.0 / 12.4 + PyTorch 2.6.0

如果 nvcc 版本和 PyTorch 的 CUDA 版本不一致（例如 nvcc 是 11.8 但 PyTorch 是 cu121），需要统一。最简单的方法是根据你的 nvcc 版本重装 PyTorch：

Terminal window
# 例：nvcc 12.4 对应安装
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu124

第二步：快速验证

Section titled “第二步：快速验证”

验证安装是否成功，只需要两步：

  1. 下载基础模型

    StarVLA 基于 Qwen-VL 系列模型，你需要先下载一个基础模型。

    Terminal window
    # 先安装 huggingface 命令行工具（如果还没装的话）
    pip install huggingface_hub[cli]
    

    # 下载 Qwen3-VL-4B 模型（约 8GB）
    huggingface-cli download Qwen/Qwen3-VL-4B-Instruct --local-dir ./playground/Pretrained_models/Qwen3-VL-4B-Instruct

  2. 运行框架自检

    用假数据跑一次前向传播，确认模型能正常加载和预测：

    Terminal window
    python starVLA/model/framework/QwenGR00T.py

    看到以下输出就说明安装成功了：

    • 打印出完整的模型结构
    • model.predict_action(fake_data) 成功返回动作数组（形状为 [batch, action_horizon, action_dim]）
    • 没有报错退出

    如果遇到 CUDA out of memory，说明显存不够，可以尝试用更小的模型（如 Qwen2.5-VL-3B）。

目录结构概览

Section titled “目录结构概览”

安装完成后，你需要了解 StarVLA 的目录结构，后续训练和评测都会用到：

starVLA/                          # 项目根目录（git 仓库）
├── starVLA/                      # 核心代码包（Python 包惯例：外层是项目目录，内层同名目录是实际的包代码）
│   ├── model/framework/          # 模型定义（QwenOFT.py, QwenGR00T.py 等）
│   ├── dataloader/               # 数据加载器
│   ├── training/                 # 训练脚本
│   └── config/                   # DeepSpeed 和训练配置模板
├── deployment/                   # 部署相关（策略服务器）
├── examples/                     # 各 Benchmark 的评测与训练示例
│   ├── LIBERO/
│   ├── SimplerEnv/
│   ├── Robocasa_tabletop/
│   ├── Robotwin/
│   └── Behavior/
├── playground/                   # 模型和数据存放约定目录
│   ├── Pretrained_models/        # 放预训练模型（如 Qwen3-VL-4B-Instruct）
│   └── Datasets/                 # 放训练数据集
└── results/                      # 训练输出（checkpoint、日志）
    └── Checkpoints/

下一步该做什么？

Section titled “下一步该做什么？”

安装验证通过后，根据你的目标选择路径：

你的目标推荐阅读
了解 StarVLA 的设计理念乐高式设计
用已有 checkpoint 跑评测先看 模型库 下载 checkpoint，再看对应 Benchmark（如 LIBERO、SimplerEnv）
用自己的数据训练模型使用自己的 LeRobot 数据集
在 VLM 数据上联合训练与 VLM 数据联合训练
查看常见问题FAQ