Finetune

Create a Job

Start a new fine-tuning job with your configuration.

from qualia import Qualia

client = Qualia()

job = client.finetune.create(
    project_id="...",
    model_id="lerobot/smolvla_base",          # HuggingFace model ID
    vla_type="smolvla",                        # smolvla, pi0, or pi0.5
    dataset_id="lerobot/pusht",                # HuggingFace dataset ID
    hours=2.0,                                 # Training duration (max 168)
    camera_mappings={                          # Map model slots to dataset keys
        "cam_1": "observation.images.top",
    },
    # Optional parameters:
    instance_type="gpu_1x_a100",               # From client.instances.list()
    region="us-east-1",
    batch_size=32,
    name="My training run",
)

Response

{
"job_id": "550e8400-e29b-41d4-a716-446655440000",
"project_id": "123e4567-e89b-12d3-a456-426614174000",
"status": "queuing"
}

Parameters

| Parameter | Type | Required | Description | | ---------------------------- | ----- | ----------- | --------------------------------------------------------------------------------------------------------- | | project_id | str | Yes | Project to create the job in | | model_id | str | Conditional | HuggingFace model ID (required for smolvla, pi0, pi05; omit for act, gr00t_n1_5, sarm (soon)) | | vla_type | str | Yes | Model type: smolvla, pi0, pi05, act, gr00t_n1_5, or sarm (soon) | | dataset_id | str | Yes | HuggingFace dataset ID | | hours | float | Yes | Training duration in hours (max 168) | | camera_mappings | dict | Yes | Map model camera slots to dataset image keys | | instance_type | str | No | GPU instance type (default: auto-selected) | | region | str | No | Cloud region (default: auto-selected) | | batch_size | int | No | Training batch size (default: 32) | | name | str | No | Job description | | use_rabc | bool | No | Enable SARM Reward-Aware Behavior Cloning (soon) | | sarm_reward_model_path | str | No | HuggingFace path to trained SARM reward model (soon) | | sarm_image_observation_key | str | No | Image key from dataset for reward annotations (soon) | | vla_hyper_spec | dict | No | Custom hyperparameters (see Advanced VLA Hyperparameters) |

Reward-Aware Behavior Cloning (RA-BC) (soon)

Use SARM reward models to weight training samples via Reward-Aware Behavior Cloning. This requires a pre-trained SARM reward model on HuggingFace.

job = client.finetune.create(
    project_id="...",
    vla_type="smolvla",
    model_id="lerobot/smolvla_base",
    dataset_id="lerobot/pusht",
    hours=4.0,
    camera_mappings={
        "cam_1": "observation.images.top",
    },
    use_rabc=True,
    sarm_reward_model_path="your-org/sarm-reward-model",
    rabc_head_mode="sparse",
    sarm_image_observation_key="observation.images.top",
)

Advanced VLA Hyperparameters

You can customize model hyperparameters for fine-grained control over training. The SDK validates hyperparameters before submitting the job, so invalid configurations are caught early.

Get Default Hyperparameters

Retrieve the default hyperparameters for a VLA model type. Use these as a starting point for customization.

params = client.finetune.get_hyperparams_defaults(
    vla_type="smolvla",
    model_id="lerobot/smolvla_base",
)

Validate Hyperparameters

Check whether your hyperparameters are valid before creating a job.

validation = client.finetune.validate_hyperparams(
    vla_type="smolvla",
    hyperparams=params,
)

if not validation.valid:
    for issue in validation.issues:
        print(f"  {issue.field}: {issue.message}")

Response

{
"valid": true,
"issues": null
}

{
"valid": false,
"issues": [
  { "field": "chunk_size", "message": "Input should be a valid integer" }
]
}

Create a Job with Advanced VLA Hyperparameters

Pass your customized hyperparameters via vla_hyper_spec when creating a job. The create() method internally calls validate_hyperparams() — if validation fails, a ValueError is raised and no job is created.

# 1. Get defaults and customize
params = client.finetune.get_hyperparams_defaults(
    vla_type="smolvla",
    model_id="lerobot/smolvla_base",
)
params["training"]["learning_rate"] = 1e-5
params["training"]["num_epochs"] = 50

# 2. Create the job with custom hyperparameters
job = client.finetune.create(
    project_id=project.project_id,
    model_id="lerobot/smolvla_base",
    vla_type="smolvla",
    dataset_id="qualiaadmin/oneepisode",
    hours=2.0,
    camera_mappings={"cam_1": "observation.images.side"},
    vla_hyper_spec=params,
)

Get Job Status

Check the status of a fine-tuning job.

status = client.finetune.get(job.job_id)

Response

{
"job_id": "550e8400-e29b-41d4-a716-446655440000",
"current_phase": "training_running",
"status": "running",
"phases": [
  {
    "name": "queuing",
    "status": "completed",
    "started_at": "2024-01-15T10:00:00Z",
    "completed_at": "2024-01-15T10:01:00Z",
    "events": [],
    "error": null
  },
  {
    "name": "training_running",
    "status": "started",
    "started_at": "2024-01-15T10:05:00Z",
    "completed_at": null,
    "events": [
      {
        "status": "started",
        "message": "Training started",
        "error": null,
        "timestamp": "2024-01-15T10:05:00Z",
        "retry_attempt": 0
      }
    ],
    "error": null
  }
]
}

Job Phases

Jobs progress through these phases in order:

| Phase | Description | | ----------------------- | --------------------------------------------- | | queuing | Job is queued and waiting to start | | credit_validation | Validating credit balance | | instance_booting | GPU instance is booting | | instance_activation | Instance is being activated | | instance_setup | Setting up the training environment | | dataset_preprocessing | Preprocessing the dataset | | training_running | Training is in progress | | model_uploading | Uploading the fine-tuned model to HuggingFace | | completed | Job completed successfully | | failed | Job failed (check phase errors for details) | | cancelled | Job was cancelled |

Each phase has a status of started, completed, or failed.

Cancel a Job

Cancel a running fine-tuning job.

result = client.finetune.cancel(job.job_id)

Response

{
"job_id": "550e8400-e29b-41d4-a716-446655440000",
"cancelled": true,
"previous_status": "training_running",
"instance_terminated": true
}