Quickstarts
Your first fine-tune
Upload a small chat dataset, train a LoRA adapter on a base model, follow the job as it runs, and download the trained adapter.
A fine-tuning job trains a base model on your examples and stores the result as a new private model in your project. You pay per training token; the estimated cost is reserved when the job is created.
Upload a dataset
Training data is a JSON Lines file with one example per line. For chat models each line is a conversation with at least one assistant message. Every uploaded file is validated in the background; wait for status: processed (valid) before you use it. An invalid file reports its errors with line numbers in validation.report.
# One JSON object per line: a conversation the model should learn to continue.
for i in $(seq 0 15); do
jq -cn --arg q "What is $i plus $i?" --arg a "$i plus $i is $((i + i))." \
'{messages: [{role: "user", content: $q}, {role: "assistant", content: $a}]}'
done > "$WORK/train.jsonl"
FILE_ID=$(curl -sS --fail-with-body "$API_BASE_URL/files" -H "$AUTH" \
-F purpose=fine-tune -F "file=@$WORK/train.jsonl" | jq -r .id)
while STATUS=$(curl -sS "$API_BASE_URL/files/$FILE_ID" -H "$AUTH" | jq -r .status)
[ "$STATUS" = uploaded ]; do sleep 1; done # validation runs in the background
[ "$STATUS" = processed ] || { echo "file is not valid: $STATUS"; exit 1; }
echo "uploaded $FILE_ID"Create the job
GET /v1/fine-tunes/base-models lists the models you can fine-tune (the samples read BASE_MODEL). The defaults train a LoRA adapter; set adapter.type to full for a full fine-tune. GET /v1/fine-tunes/estimate prices a run before you start it.
JOB_ID=$(
jq -n --arg model "$BASE_MODEL" --arg file "$FILE_ID" '{
model: $model,
training_file_id: $file,
adapter: {type: "lora", rank: 8},
hyperparameters: {epochs: 1, batch_size: 4, max_seq_length: 128}
}' |
curl -sS --fail-with-body "$API_BASE_URL/fine-tunes" \
-H "$AUTH" -H "Content-Type: application/json" -d @- |
jq -r .id
)
echo "fine-tune $JOB_ID"A job is queued until compute is free, then launching, training, and finally succeeded, failed, cancelled or stopped (stopped by billing enforcement when the organization ran out of credit).
Follow it
Events describe what the job is doing (data prepared, training started, each checkpoint); metrics carry the loss curve.
while :; do
STATE=$(curl -sS --fail-with-body "$API_BASE_URL/fine-tunes/$JOB_ID" -H "$AUTH" | jq -r .state)
case "$STATE" in succeeded|failed|cancelled|stopped) break ;; esac
sleep 5
done
curl -sS --fail-with-body "$API_BASE_URL/fine-tunes/$JOB_ID/events?limit=200" -H "$AUTH" |
jq -r '.data[] | "[\(.type)] \(.message)"'
echo "state: $STATE"Download the adapter
A finished job has an adapter (LoRA) and, unless you turned merge_weights off, merged full weights. Both download as tar archives.
curl -sS --fail-with-body -o adapter.tar \
"$API_BASE_URL/fine-tunes/$JOB_ID/download?artifact=adapter" -H "$AUTH"
echo "saved adapter.tar ($(wc -c < adapter.tar) bytes)"Export to Weights & Biases or Hugging Face
A job can also log its training to Weights & Biases and upload the result to a Hugging Face model repository. Store the API key or access token as a project secret first, then name it in integrations: {"wandb": {"api_key_secret_id": "sec_…", "project": "…"}} and {"hugging_face": {"token_secret_id": "sec_…", "repository": "my-org/my-model", "artifact": "adapter"}} (or merged). The value never appears in the job; the trainer receives it when it starts. Both exports are best effort: if one fails (a refused key, a repository you cannot write to), the job still succeeds and an event says why. The console's fine-tuning form offers both under Exports.
Next
- Files: dataset formats and limits.
- Fine-tuning reference: hyperparameters, checkpoints and the resulting models.