finetune( )

Starts, resumes, inspects, pauses, or cancels a finetuning job for a loaded model.

function finetune(params: FinetuneRunParams, rpcOptions?: RPCOptions): FinetuneHandle;
function finetune(params: FinetuneStopParams | FinetuneGetStateParams, rpcOptions?: RPCOptions): Promise<FinetuneResult>;

Parameters

Name	Type	Required?	Description
params	`FinetuneRunParams` \| `FinetuneStopParams` \| `FinetuneGetStateParams`	✓	The finetuning parameters — shape determines the overload
rpcOptions	`RPCOptions`	✗	Optional RPC transport options

`FinetuneRunParams`

Used to start or resume a finetuning job.

Field	Type	Required?	Description
modelId	`string`	✓	The identifier of the loaded model to finetune
operation	`"start" \| "resume"`	✗	Omit to let the add-on choose whether to start fresh or resume automatically
options	`FinetuneOptions`	✓	Finetuning configuration

`FinetuneStopParams`

Used to pause or cancel a running job.

Field	Type	Required?	Description
modelId	`string`	✓	The identifier of the model
operation	`"pause" \| "cancel"`	✓	The stop operation

`FinetuneGetStateParams`

Used to inspect the current state of a finetuning job.

Field	Type	Required?	Description
modelId	`string`	✓	The identifier of the model
operation	`"getState"`	✓	Must be `"getState"`
options	`FinetuneOptions`	✓	Finetuning configuration

`FinetuneOptions`

Field	Type	Required?	Description
trainDatasetDir	`string`	✓	Directory containing the training dataset
validation	`FinetuneValidation`	✓	Validation configuration
outputParametersDir	`string`	✓	Directory where output adapter parameters are written
numberOfEpochs	`number`	✗	Number of epochs to run
learningRate	`number`	✗	Learning rate override
contextLength	`number`	✗	Context length override
batchSize	`number`	✗	Batch size override
microBatchSize	`number`	✗	Micro batch size override
assistantLossOnly	`boolean`	✗	Compute loss only on assistant tokens
loraRank	`number`	✗	LoRA rank override
loraAlpha	`number`	✗	LoRA alpha override
loraInitStd	`number`	✗	LoRA initialization standard deviation
loraSeed	`number`	✗	LoRA initialization seed
loraModules	`string`	✗	Comma-separated LoRA module selection
checkpointSaveDir	`string`	✗	Directory for checkpoint snapshots
checkpointSaveSteps	`number`	✗	Checkpoint save interval (in steps)
chatTemplatePath	`string`	✗	Custom chat template path
lrScheduler	`"constant" \| "cosine" \| "linear"`	✗	Learning rate scheduler
lrMin	`number`	✗	Minimum learning rate
warmupRatio	`number`	✗	Warmup ratio (0–1)
warmupRatioSet	`boolean`	✗	Enable warmup ratio
warmupSteps	`number`	✗	Warmup step count
warmupStepsSet	`boolean`	✗	Enable explicit warmup steps
weightDecay	`number`	✗	Weight decay override

`FinetuneValidation`

Discriminated union on type:

Variant	Fields	Description
`{ type: "none" }`	—	No validation
`{ type: "split", fraction?: number }`	fraction defaults to `0.05`	Split training data for validation
`{ type: "dataset", path: string }`	—	Use a separate validation dataset

Returns

The return type depends on the operation:

Run overload (operation omitted, "start", or "resume"):

FinetuneHandle — Object with the following fields:

Field	Type	Description
progressStream	`AsyncGenerator<FinetuneProgress>`	Stream of training progress ticks
result	`Promise<FinetuneResult>`	Resolves when the job finishes

Reply overload ("pause", "cancel", or "getState"):

Promise<FinetuneResult>

`FinetuneProgress`

Field	Type	Description
is_train	`boolean`	Whether this tick is from the training phase (vs validation)
loss	`number \| null`	Current loss value
loss_uncertainty	`number \| null`	Loss uncertainty
accuracy	`number \| null`	Current accuracy
accuracy_uncertainty	`number \| null`	Accuracy uncertainty
global_steps	`number`	Total steps completed
current_epoch	`number`	Current epoch index
current_batch	`number`	Current batch index
total_batches	`number`	Total batches in the epoch
elapsed_ms	`number`	Elapsed time in milliseconds
eta_ms	`number`	Estimated time remaining in milliseconds

`FinetuneResult`

Field	Type	Description
type	`"finetune"`	Response type discriminator
status	`FinetuneStatus`	Current job status
stats	`FinetuneStats` `\| undefined`	Final training statistics (present when completed)

`FinetuneStatus`

"IDLE" | "RUNNING" | "PAUSED" | "CANCELLED" | "COMPLETED"

`FinetuneStats`

Field	Type	Description
train_loss	`number \| undefined`	Final training loss
train_loss_uncertainty	`number \| null \| undefined`	Training loss uncertainty
val_loss	`number \| undefined`	Final validation loss
val_loss_uncertainty	`number \| null \| undefined`	Validation loss uncertainty
train_accuracy	`number \| undefined`	Final training accuracy
train_accuracy_uncertainty	`number \| null \| undefined`	Training accuracy uncertainty
val_accuracy	`number \| undefined`	Final validation accuracy
val_accuracy_uncertainty	`number \| null \| undefined`	Validation accuracy uncertainty
learning_rate	`number \| undefined`	Final learning rate
global_steps	`number`	Total steps completed
epochs_completed	`number`	Total epochs completed

Throws

Error	When
`INVALID_RESPONSE_TYPE`	Response type does not match expected `"finetune"`
`STREAM_ENDED_WITHOUT_RESPONSE`	Stream ended without receiving the terminal finetune response

Example

const handle = finetune({
  modelId,
  options: {
    trainDatasetDir: "./dataset/train",
    validation: { type: "split", fraction: 0.05 },
    outputParametersDir: "./artifacts/lora",
    numberOfEpochs: 2,
  },
});

for await (const progress of handle.progressStream) {
  console.log(progress.global_steps, progress.loss);
}

console.log(await handle.result);

// Pause a running job
const pauseResult = await finetune({ modelId, operation: "pause" });
console.log(pauseResult.status); // "PAUSED"

// Inspect current state
const state = await finetune({
  modelId,
  operation: "getState",
  options: {
    trainDatasetDir: "./dataset/train",
    validation: { type: "none" },
    outputParametersDir: "./artifacts/lora",
  },
});
console.log(state.status);

finetune( )

On this page