Finetune

Create a job

Owned training data is always identified by an immutable DatasetVersion UUID. Repository names, branches, mutable dataset rows, and Hugging Face dataset IDs are not accepted.

from qualia import Qualia

client = Qualia()
dataset_version_id = "44444444-4444-4444-8444-444444444444"

features = client.data.get_training_features(dataset_version_id)
camera_keys = {camera.key for camera in features.camera_features}
assert "observation.images.top" in camera_keys

job = client.finetune.create(
    project_id="123e4567-e89b-42d3-a456-426614174000",
    model_id="lerobot/smolvla_base",
    vla_type="smolvla",
    dataset_version_id=dataset_version_id,
    hours=2.0,
    camera_mappings={"image_top": "observation.images.top"},
    batch_size=32,
    name="Towel folding",
)

The service resolves the version once into a digest-bound native read plan. Training workers receive only that exact version/plan identity and a separate, attempt-scoped read credential.

Parameters

Parameter	Required	Description
project_id	Yes	Project UUID that owns the run.
vla_type	Yes	act, smolvla, pi05, or sarm.
dataset_version_id	Yes	Immutable QDS DatasetVersion UUID.
hours	Yes	Maximum scheduled training time, up to 168 hours.
camera_mappings	Yes	Model camera slot to an adapter-pinned dataset camera key.
model_id	Conditional	External model origin for SmolVLA/Pi0.5; forbidden for ACT/SARM. Built-in aliases resolve to reviewed Qualia mirror commits.
model_revision	Conditional	Exact 40-character lowercase Hugging Face commit SHA; required for every custom model_id.
instance_type	No	GPU instance type; otherwise selected automatically.
region	No	Compute region; otherwise selected automatically.
batch_size	No	Training batch size, 1–512; default 32.
vla_hyper_spec	No	Validated model-specific hyperparameters.

The built-in lerobot/smolvla_base and lerobot/pi05_base aliases are server-pinned to model commits verified against the shipped LeRobot runtime. For any other Hugging Face repository, pass its exact commit:

job = client.finetune.create(
    # ...dataset and run fields...
    vla_type="smolvla",
    model_id="your-org/custom-smolvla",
    model_revision="0123456789abcdef0123456789abcdef01234567",
)

Mutable branches, tags, and omitted revisions are rejected for custom models.

Reward-aware behavior cloning

RA-BC uses a verified SARM progress artifact produced inside the same pipeline graph. It is currently supported for SmolVLA.

job = client.finetune.create(
    project_id="123e4567-e89b-42d3-a456-426614174000",
    model_id="lerobot/smolvla_base",
    vla_type="smolvla",
    dataset_version_id=dataset_version_id,
    hours=4.0,
    camera_mappings={"image_top": "observation.images.top"},
    job_type="vla_w_reward",
    use_rabc=True,
    sarm_reward_model_id="your-org/sarm-reward-model",
    sarm_reward_model_revision="0123456789abcdef0123456789abcdef01234567",
    sarm_image_observation_key="observation.images.top",
    rabc_head_mode="sparse",
)

The SARM observation key must be one of the selected camera-mapping values. Reward models are resolved only by exact Hub commit; tags, branches, and omitted revisions are rejected.

Hyperparameters

params = client.finetune.get_hyperparams_defaults(
    vla_type="smolvla",
    model_id="lerobot/smolvla_base",
)
params["training"]["learning_rate"] = 1e-5

validation = client.finetune.validate_hyperparams(
    vla_type="smolvla",
    hyperparams=params,
)
if not validation.valid:
    raise ValueError(validation.issues)

Passing vla_hyper_spec=params to create() performs the same validation before the run is submitted.

Watch and inspect a job

for event in client.finetune.watch(job.job_id):
    if message := event.data.get("message"):
        print(message)

status = client.finetune.get(job.job_id)
print(status.status, status.current_phase)

The visible phases reflect durable pipeline operations: credit reservation, optional SARM progress, model training, model publication, and credit finalization. A failed, cancelled, or superseded attempt cannot refresh its dataset read capability.

Cancel a job

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