Fine-tuning the Spirit-v1.5 Model
Spirit-v1.5 is a Vision-Language-Action (VLA) policy from Spirit AI. The platform registers it under the model identifier spirit-v1.5, uses the spirit training framework, and supports robochallenge, LeRobot v2, and v3 datasets.
Roles and Prerequisites
Roles
| Role | Can create a training task | Description |
|---|
| Administrator | Yes | Not restricted by Module Permissions |
| Project Manager | Requires authorization | An administrator grants Create Training Job in Module Permissions |
| Annotator | Requires authorization | Same as above |
| Auditor | Requires authorization | Same as above |
| Collector | Requires authorization | Same as above |
Viewing training tasks and metrics requires only View Training.
Prerequisites
| Item | Requirement |
|---|
| Dataset version | robochallenge, LeRobot v2, or v3. The RoboChallenge layout can be trained directly, and LeRobot data is converted to the RoboChallenge layout before training |
| Framework | spirit |
| GPU memory | No fixed lower bound; multi-GPU training is recommended. batch_size defaults to 1 per GPU |
| Dependency | The platform's model training service is enabled with at least one training location configured; the training image ships with the Spirit-v1.5 base weights |
| State fields | observation.state has at least 8 dimensions: the first 7 are the end-effector pose and the 8th is the gripper width |
| Video fields | Three RGB video streams are required, mapped to main_realsense_rgb, handeye_realsense_rgb, and side_realsense_rgb |
| Permission | Creating requires Create Training Job; viewing requires View Training |
Data with joint-angle states cannot train Spirit-v1.5 directly; the state space must be adapted first.
Training Task Creation and Parameters
Procedure
- Go to Model → Training and select Create Training Job.
- Choose a training location: a local GPU or a cloud training location enabled by an administrator.
- Under Selected Model, select
spirit-v1.5.
- Under Training Dataset, choose the data source: Export Records, an uploaded LeRobot dataset, Download Link, or Hugging Face.
- Set parameters in Training Parameters; the table below lists their meaning and default values. When using LeRobot data and the camera fields cannot be matched automatically, fill in
camera_map.
- Enter Notes (optional).
- Select Create Training Job.
Training Parameters
| Parameter | Description | Default | Valid range |
|---|
| batch_size | Batch size per GPU | 1 | Integer, ≥ 1 |
| steps | Maximum training steps | 10000 | Integer, ≥ 1 |
| save_interval | Checkpoint save interval | 2500 | Integer, applied when greater than 0 |
| log_freq | Logging interval | 25 | Integer, ≥ 1 |
| num_workers | DataLoader processes | 2 | Integer, ≥ 0 |
| prefetch_factor | DataLoader prefetch factor | 2 | Integer, ≥ 1 |
| num_gpus | Number of torchrun processes | Visible GPU count, otherwise 1 | Positive integer |
| wandb_mode | Metric reporting mode | disabled | disabled, offline, online |
| pretrained_path | Base weights directory | Base weights bundled in the image | A directory containing model.safetensors and config.json |
| task_name | Task name for LeRobot conversion | move_objects_into_box | String |
| task_prompt | Language prompt for LeRobot conversion | Dataset task text | String |
| camera_map | Mapping from LeRobot camera fields to the three Spirit cameras | Auto-inferred | JSON |
Verification
Training Monitoring
The training details page parses metrics in the Spirit log format and plots the curves:
| Metric | Meaning | Criteria |
|---|
| step | Number of completed training steps | Increases step by step up to the configured steps |
| total_steps | Configured total training steps | Matches steps |
| loss | Training loss | Decreases overall |
| learning_rate | Current learning rate | Changes according to the schedule |
Verification Checklist
The training service determines the final task state from the container exit code: exit code 0 is recorded as Success, and a nonzero code as Failed.
| Check | Pass criteria |
|---|
| Task status | The training details page shows Success and the container exit code is 0 |
| Output directory | spirit_train/ under the output directory |
| Checkpoints | Checkpoints lists the checkpoints; the entry that last points to has type Final, and the rest have type Step |
| Metric curves | Training Metrics plots step, loss, and learning_rate |
| Logs | Real-time Logs can be read without repeated errors |
Training and inference are separate for Spirit, and deployment uses the platform's inference service. Checkpoints listed in Checkpoints can be downloaded and synced to object storage; see Model Inference for the inference side.
Error Handling
| Symptom | Possible cause | Action | Owner |
|---|
| Conversion reports missing three cameras | The LeRobot data lacks identifiable camera fields | Explicitly map the three camera fields in camera_map | Algorithm Engineer |
Conversion reports insufficient observation.state dimensions | The state has fewer than 8 dimensions, or is joint angles rather than an end-effector pose | Provide a state vector of a 7-dimensional end-effector pose plus 1-dimensional gripper width | Algorithm Engineer |
| Weights directory unavailable | The specified directory lacks model.safetensors or config.json | Use the base weights bundled in the image, or specify a complete directory | Administrator |
| Out of GPU memory | batch_size or num_workers is too large | Lower batch_size and num_workers; switch to multi-GPU training | Algorithm Engineer |
| Training fails immediately with a dataset-not-found error | The input directory is neither in the RoboChallenge layout nor convertible | Check meta/info.json and the directory structure, then select the dataset again | Project Manager |
| Training location unavailable | The platform has not enabled that training location, or its GPU is unavailable | Switch to another training location; ask an administrator to check the Training Service | Administrator |
Related Pages