Architecture

The managed fine-tuning jobs API hides most of the machinery: you upload a dataset, submit a job and read back a result_model. The low-level training API exposes that machinery directly. Either way, the same four resources do the work, and knowing how they relate makes the reference pages much easier to navigate.

The resource hierarchy

session  sess_A1
├─ training run  run_3Bz           live GPU state: weights, optimizer, step count
│  ├─ checkpoint  (training)       resumable snapshot of the run
│  └─ checkpoint  (sampler)        servable weights
└─ sampler  sess_A1:sample:0       inference session

Sessions group everything opened together. You never create one directly: opening a training run or a sampler opens a session implicitly, and the create response carries its session_id. Retrieve a session returns every run and sampler opened under it, and assigning a session to a project moves the session and everything under it into a project in one call.

Training runs hold live GPU state. Create a training run allocates GPUs and loads the base model with a LoRA adapter of the requested rank (default 32). From then on the run carries the adapter weights, the optimizer state and the current step count, and every training route is keyed on its training_run_id. Each forward-backward pass and optimizer step mutates that state in place.

Checkpoints are snapshots written from a run with Create a checkpoint. One route, two products, selected by type. A training checkpoint captures what is needed to resume the run later: pass its path as from_path when creating a new run, or load it into a live run with Load state. A sampler checkpoint emits servable weights: its path is what Create a sampler and the compatibility routes accept as a model.

Samplers are inference sessions, opened against either a base_model or a model_path pointing at sampler weights. Once open, a sampler serves Generate samples and Compute prompt logprobs requests.

The nucleus:// path scheme

Weights live at stable, addressable paths. Every checkpoint has one, and it is the value you pass around whenever a route asks for a model that is not a base model.

nucleus://run_3Bz:train:0/sampler_weights/000240
          │       │     │ │               │
          │       │     │ │               └─ step number
          │       │     │ └─ weight kind
          │       │     └─ service index
          │       └─ service
          └─ training run ID

Paths appear throughout the API:

• result_model on a finished fine-tuning job is the sampler-weights path of your trained model.
• path in the checkpoint create response identifies the snapshot you just wrote.
• model_path when creating a sampler points it at your own weights instead of a base model.
• from_path when creating a training run resumes from a training checkpoint, and Load state loads one into a run that is already open.
• Evaluations take a path as the model to score.
• The model parameter on the OpenAI-compatible and Anthropic-compatible routes accepts a path, so existing SDKs can call your fine-tuned weights directly.
• The path query parameter on List all checkpoints resolves a path back to its checkpoint, base model and LoRA rank.

Lifecycle and cost

Runs and samplers hold GPU allocations from the moment they are created until you close them. Checkpoints hold storage until they expire or are deleted. Nothing is released implicitly, so the shape of a well-behaved workload is: open a run, train, write a sampler checkpoint, close the run, and serve from a sampler you close when traffic stops.

Set ttl_seconds when you write a checkpoint to have it cleaned up automatically, or leave it null to keep the checkpoint until you delete it. You can change your mind later with Update checkpoint expiry.

Creating runs and writing checkpoints allocate real resource, so those POST routes accept an Idempotency-Key header; closing and deleting are plain DELETE calls and are always safe to retry. See Errors and retries.