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.
- [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!
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
- Hardware: Tested on NVIDIA A100 80GB GPU.
- Software: Python 3.10+.
For inference only:
uv sync
source .venv/bin/activateFor training:
uv sync --extra train
source .venv/bin/activateFor inference only:
python -m venv .venv
source .venv/bin/activate
pip install -r requirements-base.txtFor training:
python -m venv .venv
source .venv/bin/activate
pip install -r requirements-base.txt
pip install -r requirements-train.txtNote:
flash-attnrequires matching CUDA and PyTorch versions. If installation fails, refer to the flash-attn installation guide.
requirements-base.txt- Core dependencies for inference (backward compatible)requirements-train.txt- Additional dependencies for trainingrequirements.txt- Complete dependencies (base + training)pyproject.toml- Project configuration with optional[train]extra
Base (Inference):
torch==2.8.0- PyTorch deep learning frameworktorchvision==0.23.0- Computer vision utilitiestransformers==4.57.1- Hugging Face transformers librarydiffusers==0.35.2- Diffusion models librarysafetensors==0.5.3- Safe tensor serializationnumpy==2.2.6- Numerical computingpillow==10.4.0- Image processingrequests==2.32.5- HTTP libraryscipy==1.15.2- Scientific computing
Training (Additional):
opencv-python>=4.8.0- Image processing for data augmentationwandb>=0.16.0- Experiment tracking and loggingtqdm>=4.66.0- Progress barseinops==0.8.1- Tensor operations (required by flash-attn)flash-attn==2.8.3- Flash Attention 2 for efficient training
| Model | Type | Link |
|---|---|---|
| Spirit-v1.5 | Base Model |  |
| Spirit-v1.5-move-objects-into-box | Fine-tuned Model | |
We provide a minimal launcher script located at scripts/run_robochallenge.sh.
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.
| Variable | Description |
|---|---|
TASK_NAME |
Must correspond to a task defined in robochallenge/runner/task_info.py. |
ROBOCHALLENGE_JOB_ID |
The unique ID for the job collection. |
USER_TOKEN |
Your authentication token. |
CKPT_PATH |
Directory containing the model.safetensors file. |
USED_CHUNK_SIZE |
Action chunk size (Default: 60). |
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- Pretrained Spirit-v1.5 base model checkpoint
- Training dataset (see Dataset section below)
- Multi-GPU setup (recommended: 8x A100 80GB)
The training script is located at scripts/run_finetune.sh. It uses PyTorch's torchrun for distributed training.
Set the following environment variables before training:
| Variable | Description | Required |
|---|---|---|
DATA_ROOT |
Path to training dataset directory | Yes |
PRETRAINED_PATH |
Path to pretrained model checkpoint (must contain model.safetensors and config.json) |
Yes |
OUTPUT_DIR |
Directory for saving checkpoints (default: ./outputs) |
No |
NUM_GPUS |
Number of GPUs to use (default: 8) | No |
BATCH_SIZE |
Training batch size per GPU (default: 32) | No |
MAX_TRAIN_STEPS |
Maximum training steps (default: 40000) | No |
LOG_INTERVAL |
Logging interval in steps (default: 25) | No |
SAVE_STEPS |
Checkpoint saving interval (default: 2500) | No |
NUM_WORKERS |
Number of data loading workers (default: 32) | No |
PREFETCH_FACTOR |
Data prefetch factor (default: 8) | No |
WANDB_MODE |
Weights & Biases logging mode (default: disable) |
No |
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.shTraining outputs will be saved to the OUTPUT_DIR:
- Checkpoints: Saved every
SAVE_STEPSsteps - W&B Logs: If enabled, metrics are logged to Weights & Biases
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/datasetSet DATA_ROOT to the downloaded dataset directory when running 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
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.
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.
@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},
}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.
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.