Train a LoRA adapter (DPO)

What it does

Training jobs fine-tune a base model using a dataset of (input, output) pairs. You submit a job specifying the dataset, recipe (DPO or SFT), learning rate, epochs, and evaluation split. The job runs asynchronously and streams logs in real-time. Once complete, the adapter is available for use in chat.

Prerequisites

• At least one dataset with >10 rows (guide 04).
• A base model id (e.g. qwen2.5:3b — see Catalog).
• Expected training time: 5-30 minutes depending on dataset size and hardware.

Steps

1. Open Training page

Click Training in the left rail. The page shows a submit form on the left and a list of past jobs on the right.

2. Fill the training form

• Base model — dropdown to pick the model to fine-tune (default: qwen2.5:3b).
• Dataset — dropdown to pick a dataset with >10 rows.
• Recipe — DPO (default) or SFT. DPO trains on preference pairs (up/down feedback); SFT trains on any input-output pairs.
• Learning rate — default 2e-4; lower for stability, higher for faster convergence.
• Epochs — default 1; increase to 2-3 for small datasets.
• Eval split — default 0.1 (10% of rows reserved for validation).

3. Submit the job

Click Submit. A toast confirms the job id; the list refreshes to show the new job with running status.

4. Monitor the job

The job card shows:

• Status — running (blue), succeeded (green), failed (red), cancelled (yellow).
• Progress — epoch / total epochs (e.g. "Epoch 1/1").
• Elapsed time — how long the job has been running.

Click the View Logs button to open a side drawer with real-time SSE stream of training output.

5. (Optional) Cancel the job

If the job is stuck or you want to stop it, click the Cancel button (only available while running). The job transitions to cancelled and logs stop streaming.

(Direct API) Submit a training job via curl

curl -s -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BIGWAVE_TOKEN" \
  -d '{
    "base_model": "qwen2.5:3b",
    "dataset_id": "my-dataset-123",
    "recipe": "dpo",
    "learning_rate": 0.0002,
    "epochs": 1,
    "eval_split": 0.1
  }' \
  "http://localhost:8080/admin/training/jobs" | jq '.job_id'

Returns 202 Accepted with the job_id.

Verify

• Submit a training job; the Jobs list updates in real-time.
• Click View Logs; logs stream from the backend (epoch progress, loss curves, etc.).
• Wait for the job to reach succeeded status.
• Go to Adapters page; the new adapter appears with a metric chip showing eval metrics.

Common issues

Symptom	Cause	Fix
"Dataset not found"	dataset_id is invalid or the dataset has <10 rows	Pick a different dataset or upload a larger one
Job stays running for >1 hour	Underlying training process is hung	Cancel and check api container logs for Python tracebacks
Job transitions to failed	Training crashed (OOM, invalid hyperparams, etc.)	Click View Logs to see the error; adjust hyperparams or dataset and try again
Logs don't stream	SSE connection dropped or backend is buffering	Refresh the browser; logs will stream from the current position

Related

• Upload or build a dataset — datasets feed training jobs.
• Promote an adapter to active — completed training produces adapters.
• Run an eval against a golden set — run evals on your trained adapter to measure quality.