This repository contains the official implementation of the Spirit-v1.5 VLA model, as well as the runtime wrapper required to reproduce our results on the RoboChallenge benchmark. As of Jan 11, 2026, Spirit-v1.5 ranks #1 on the RoboChallenge Table30 benchmark.

📰 News

• [2026-01] Initial Release: Technical blog, inference code, base model checkpoint, and a fine-tuned checkpoint are now available.
• [2026-4] Fine-tuning code released!

Directory Structure

spirit-v1.5/
├── model/                        # Model architecture
│   ├── modeling_spirit_vla.py    # Main model architecture (Qwen3-VL backbone + DiT head + policy API)
│
├── dataset/                      # Dataset and data processing
│   ├── dataset.py                # Dataset implementation
│   └── transforms.py             # Data transformations
│
├── utils/                        # Utility functions
│   ├── checkpoint.py             # Checkpoint loading/saving utilities
│   ├── distributed.py            # Distributed training utilities
│   ├── logger.py                 # Logging utilities
│   ├── normalization.py          # Data normalization utilities
│   ├── sampling.py               # Sampling strategies
│   ├── tensor_ops.py             # Tensor operations
│   └── vlm_utils.py              # Vision-Language Model utilities
│
├── robochallenge/                # RoboChallenge integration
│   ├── run_robochallenge.py      # Python entrypoint
│   ├── runner/
│   │   ├── executor.py           # RoboChallengeExecutor (Checkpoint loading, inference, I/O)
│   │   └── task_info.py          # Task metadata (robot type, action type, prompts, etc.)
│   ├── robot/                    # Derived from open-source RoboChallengeInference
│   │   ├── interface_client.py   # RoboChallenge HTTP client
│   │   └── job_worker.py         # Job polling loop and execution flow
│   └── utils/                    # Derived from open-source RoboChallengeInference
│       ├── enums.py              # Shared enums/constants
│       ├── log.py                # Logging helpers
│       └── util.py               # Misc utilities
│
├── scripts/                      # Execution scripts
│   ├── run_robochallenge.sh      # RoboChallenge runtime launcher
│   └── run_finetune.sh           # Training launcher
│
├── train.py                      # Main training script
├── requirements-base.txt         # Core dependencies (inference only)
├── requirements-train.txt        # Additional training dependencies
├── requirements.txt              # Complete dependencies (base + training)
├── pyproject.toml                # Project configuration with optional dependencies
└── README.md                     # This file

Installation & Setup

System Requirements

• Hardware: Tested on NVIDIA A100 80GB GPU.
• Software: Python 3.10+.

Installation Options

Option 1: uv (recommended)

For inference only:

uv sync
source .venv/bin/activate

For training:

uv sync --extra train
source .venv/bin/activate

Option 2: pip

For inference only:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements-base.txt

For training:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements-base.txt
pip install -r requirements-train.txt

Note: flash-attn requires matching CUDA and PyTorch versions. If installation fails, refer to the flash-attn installation guide.

Dependency Files

• requirements-base.txt - Core dependencies for inference (backward compatible)
• requirements-train.txt - Additional dependencies for training
• requirements.txt - Complete dependencies (base + training)
• pyproject.toml - Project configuration with optional [train] extra

Key Dependencies

Base (Inference):

• torch==2.8.0 - PyTorch deep learning framework
• torchvision==0.23.0 - Computer vision utilities
• transformers==4.57.1 - Hugging Face transformers library
• diffusers==0.35.2 - Diffusion models library
• safetensors==0.5.3 - Safe tensor serialization
• numpy==2.2.6 - Numerical computing
• pillow==10.4.0 - Image processing
• requests==2.32.5 - HTTP library
• scipy==1.15.2 - Scientific computing

Training (Additional):

• opencv-python>=4.8.0 - Image processing for data augmentation
• wandb>=0.16.0 - Experiment tracking and logging
• tqdm>=4.66.0 - Progress bars
• einops==0.8.1 - Tensor operations (required by flash-attn)
• flash-attn==2.8.3 - Flash Attention 2 for efficient training

Model Checkpoints

Run RoboChallenge

We provide a minimal launcher script located at scripts/run_robochallenge.sh.

Environment Configuration

The script requires the following environment variables to be set. Note that USED_CHUNK_SIZE defaults to 60 if not specified; all other variables are mandatory.

Execution Example:

Below is an example for the RoboChallenge task move_objects_into_box.

cd /path/to/spirit_vla_repo

export TASK_NAME=move_objects_into_box
export ROBOCHALLENGE_JOB_ID=your_job_collection_id
export USER_TOKEN=your_user_token
# Download / reference checkpoint:
# https://huggingface.co/Spirit-AI-robotics/Spirit-v1.5-for-RoboChallenge-move-objects-into-box
export CKPT_PATH=/path/to/your_checkpoint_dir
export USED_CHUNK_SIZE=60

./scripts/run_robochallenge.sh

Finetune Guide

Prerequisites

• Pretrained Spirit-v1.5 base model checkpoint
• Training dataset (see Dataset section below)
• Multi-GPU setup (recommended: 8x A100 80GB)

Training Script

The training script is located at scripts/run_finetune.sh. It uses PyTorch's torchrun for distributed training.

Environment Variables

Set the following environment variables before training:

Training Example

cd /path/to/spirit-v1.5

# Set required environment variables
export DATA_ROOT=/path/to/your/training/dataset
export PRETRAINED_PATH=/path/to/pretrained/checkpoint
export OUTPUT_DIR=./outputs/my_finetuned_model

# Optional: Configure training parameters
export NUM_GPUS=8
export BATCH_SIZE=32
export MAX_TRAIN_STEPS=40000
export WANDB_MODE=online  # Enable W&B logging
export WANDB_BASE_URL=https://api.wandb.ai
export WANDB_API_KEY="my_wandb_api_key"

# Run training
./scripts/run_finetune.sh

Training Output

Training outputs will be saved to the OUTPUT_DIR:

• Checkpoints: Saved every SAVE_STEPS steps
• W&B Logs: If enabled, metrics are logged to Weights & Biases

Dataset

Download the training dataset from Hugging Face:

huggingface-cli download RoboChallenge/task_table30_move_objects_into_box \
  --repo-type dataset \
  --local-dir /path/to/your/dataset

Set DATA_ROOT to the downloaded dataset directory when running training.

Distributed Training

The training script uses PyTorch's Fully Sharded Data Parallel (FSDP) for efficient multi-GPU training:

• Automatically shards model parameters across GPUs
• Reduces memory footprint for large models
• Supports gradient checkpointing for memory efficiency

Intended Uses

Spirit-v1.5 is a Vision-Language-Action (VLA) model designed specifically for robotic control. The model accepts current observations and textual descriptions as input and generates the next action chunk for the robot to execute.

Out-of-scope Uses

Our models are not specifically designed for any tasks or scenarios other than robotic manipulations.

Developers should expect failures in generation results regarding the out-of-scope scenarios.

Developers should be aware of and adhere to applicable laws or regulations (including privacy, trade compliance laws, etc.) that are relevant to their use case, and evaluate and mitigate for privacy, safety, and fairness before using within a specific downstream use case, particularly for high-risk scenarios.

Bibtex

@article{spiritai2026spiritv15,
  author = {Spirit AI Team},
  title = {Spirit-v1.5: Clean Data Is the Enemy of Great Robot Foundation Models},
  journal = {Spirit AI Blog},
  year = {2026},
  note = {https://www.spirit-ai.com/en/blog/spirit-v1-5},
}

Acknowledgments

This codebase borrows code from openpi, qwen-vl and RoboChallengeInference. We thank them for their efforts and innovations, which have made the development process more efficient and convenient.

Thank you to everyone who contributed their wisdom and efforts to this project.

Contact

We welcome feedback and collaboration from our audience. If you have suggestions, questions, or observe unexpected/offensive behavior in our technology, please contact us through guojunliang AT spirit-ai.com and miaotianrun AT spirit-ai.com.