Fine-tuning

Pick a base model, point at a dataset, and Hanzo runs the training job on its own GPUs. When it succeeds you deploy the checkpoint and it becomes a model id you call like any other.

Fine-tuning runs from console.hanzo.ai → Fine-tuning. The operations below are that surface's contract; they authenticate with your console session rather than an sk- key.

Choosing a base

Any Hugging Face causal LM works — training runs a transformers + PEFT + TRL image, so an arbitrary repo id resolves to a generic runtime. Eight bases ship with tuned runtimes and are the ones to reach for first:

Base models and datasets are searched through Hugging Face from GET /v1/finetune/hf/models, /hf/datasets, and /hf/repo. The Hugging Face token is resolved server-side from KMS, so gated and private repos resolve without your browser ever holding a token.

Method and preset

method picks how much of the model moves:

task is instruct (default), chat, or completion. preset is recommended (default), balanced — one extra epoch — or aggressive, which adds two epochs, raises the learning rate by half, and doubles LoRA rank and alpha.

Quote before you run

GET /v1/finetune/presets returns the catalogue — base models, methods, tasks, presets, and GPUs. Add a selection and it also returns a recommendation: the GPU type and count, the hyperparameters, estimated minutes, and estimated cost.

GET /v1/finetune/presets?baseModel=meta-llama/Llama-3.1-8B-Instruct
                        &method=qlora&task=instruct&preset=recommended
                        &datasetExamples=5000

One rate table drives both the quote and the bill:

GPU-hours are metered once, when the job reaches a terminal state, and the clock starts when the job actually begins running — queue time is never billed.

Create a job

POST /v1/finetune/jobs. baseModel and dataset are the only required fields; everything else falls back to the recommendation.

{
  "displayName": "support-tone-v2",
  "baseModel": "meta-llama/Llama-3.1-8B-Instruct",
  "dataset": "my-org/support-transcripts",
  "method": "qlora",
  "task": "instruct",
  "preset": "recommended",
  "datasetExamples": 5000
}

Supply hyperparams to override the recommendation wholesale: epochs, learningRate, batchSize, gradAccum, maxSeqLen, loraRank, loraAlpha, loraDropout, quant4bit, gradientCheckpointing, warmupRatio, weightDecay. gpuType, gpuCount, and numNodes override the recommended hardware.

The job name is derived server-side from the base model plus a random suffix, and the checkpoint URI is assigned for you.

If the cluster refuses the submission, the job is still saved — with status: "failed" and the reason in error — rather than disappearing into an error response. On success the status is queued.

Watch it

GET /v1/finetune/jobs lists your jobs and refreshes the live status of every non-terminal one from the cluster on each read; GET /v1/finetune/job?name= reads one. A job carries status, progress (0–100), message, gpuSeconds, costCents, startedTime, and finishedTime. Terminal states are succeeded, failed, and cancelled.

POST /v1/finetune/cancel tears down the run, meters the GPU-hours used so far, and marks the job cancelled.

Deploy the result

POST /v1/finetune/deploy serves the checkpoint and registers it as a routable model id on api.hanzo.ai — from then on it is just another string in model.

Deploy refuses unless the job succeeded, and refuses up front if the cluster advertises no accelerators, rather than registering a model whose every call would fail. Re-deploying updates in place.

curl https://api.hanzo.ai/v1/chat/completions \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama-3-1-8b-instruct-quiet-river",
    "messages": [{ "role": "user", "content": "Draft a refund reply." }]
  }'

Related

• Inference — deploy and serve a model you built elsewhere
• Models — the catalogue your deployed model joins
• GPUs — the accelerators these jobs run on
• Evals — check the tuned model actually beats the base
• API Reference — every endpoint at api.hanzo.ai