ggml_fit_opt_multi: Fit a multi-output model with an R-side epoch loop and...

In ggmlR: 'GGML' Tensor Operations for Machine Learning

Fit a multi-output model with an R-side epoch loop and callbacks

Description

Multi-output counterpart of ggml_fit_opt(). Each output head has its own labels, loss type and weight; the optimized total is sum(loss_weights[i] * loss_i). Because the epoch loop runs in R, this path supports callbacks (early stopping, LR schedulers) and the shuffle/shuffle_all controls, which the single C call ggml_opt_fit_multi() cannot offer.

Usage

ggml_fit_opt_multi(
  sched,
  ctx_compute,
  inputs,
  outputs,
  dataset,
  loss_types,
  loss_weights = rep(1, length(outputs)),
  labels_offs = NULL,
  head_names = NULL,
  optimizer = ggml_opt_optimizer_type_adamw(),
  nepoch = 10L,
  nbatch_logical = 32L,
  val_split = 0,
  shuffle = TRUE,
  shuffle_all = shuffle,
  callbacks = list(),
  silent = FALSE,
  weight_decay = 0
)

Arguments

sched	Backend scheduler
ctx_compute	Compute context holding the model graph
inputs	Input tensor with shape [ne_datapoint, batch_size]
outputs	List of output tensors, one per head
dataset	Dataset with data and concatenated labels
loss_types	Integer vector of loss type constants, one per head
loss_weights	Numeric vector of head weights (default: all 1)
labels_offs	Numeric vector of 0-based label offsets, one per head. Defaults to laying the heads out back to back in head order, using each head's ne[0] as its width.
head_names	Character vector naming the heads, one per head, used for the per-head keys in logs and as the column names of the returned matrices. Defaults to head_1, head_2, ... Callers that have real output names should pass them, so a callback's monitor= matches what the training history shows.
optimizer	Optimizer type (default: AdamW)
nepoch	Number of epochs
nbatch_logical	Logical batch size (for gradient accumulation)
val_split	Fraction of data for validation (0.0 to 1.0)
shuffle	Shuffle the training portion each epoch (default TRUE). Set to FALSE for time series or to make a run exactly reproducible.
shuffle_all	Shuffle the whole dataset once before the train/validation split is taken, so the validation portion is a random sample rather than the tail of the input. Defaults to shuffle.
callbacks	List of callback lists, as for ggml_fit_opt(). Each element may have 'on_epoch_begin(epoch, logs, state)' and/or 'on_epoch_end(epoch, logs, state)'. 'state' is a mutable environment with 'stop', 'lr_ud' and 'nepoch'. 'logs' carries the aggregate metrics ('train_loss', 'train_accuracy', 'val_loss', 'val_accuracy') and, for each head, 'train_<head>_loss', 'train_<head>_accuracy', 'val_<head>_loss' and 'val_<head>_accuracy' – so a scheduler or early stopping can monitor one head rather than the total. Both phases are prefixed, so a head named ‘val_x' cannot collide with another head’s validation key. Per-head validation keys are 'NA' when 'val_split' is 0, and accuracy keys are 'NA' for heads whose loss is not cross-entropy.
silent	Whether to suppress per-epoch progress output
weight_decay	Decoupled weight decay in [0, 1], as for ggml_opt_init_for_fit; 0 turns it off.

Details

All heads share the dataset's datapoints. The dataset's labels hold every head's labels concatenated along the first dimension: head i occupies labels_offs[i] + seq_len(width_i) of each label row.

Value

Data frame with columns epoch, train_loss, train_accuracy, val_loss, val_accuracy – one row per epoch actually run, so a callback that stops early shortens it. The per-head metrics come as attributes rather than columns, since they are matrices, each [nepoch_run x n_head] with columns named after the heads: attr(h, "head_loss"), attr(h, "head_accuracy"), attr(h, "val_head_loss") and attr(h, "val_head_accuracy"), plus attr(h, "head_names").

See Also

Other optimization: ggml_fit_opt(), ggml_fit_opt_gen(), ggml_opt_alloc(), ggml_opt_context_optimizer_type(), ggml_opt_dataset_data(), ggml_opt_dataset_free(), ggml_opt_dataset_get_batch(), ggml_opt_dataset_get_batch_head(), ggml_opt_dataset_init(), ggml_opt_dataset_labels(), ggml_opt_dataset_ndata(), ggml_opt_dataset_shuffle(), ggml_opt_dataset_weights(), ggml_opt_default_params(), ggml_opt_epoch(), ggml_opt_eval(), ggml_opt_fit(), ggml_opt_fit_multi(), ggml_opt_free(), ggml_opt_get_lr(), ggml_opt_grad_acc(), ggml_opt_init(), ggml_opt_init_for_fit(), ggml_opt_init_for_fit_multi(), ggml_opt_inputs(), ggml_opt_labels(), ggml_opt_loss(), ggml_opt_loss_i(), ggml_opt_loss_type_binary_cross_entropy(), ggml_opt_loss_type_cross_entropy(), ggml_opt_loss_type_huber(), ggml_opt_loss_type_mae(), ggml_opt_loss_type_mean(), ggml_opt_loss_type_mse(), ggml_opt_loss_type_sum(), ggml_opt_loss_type_weighted_mse(), ggml_opt_n_loss(), ggml_opt_ncorrect(), ggml_opt_optimizer_name(), ggml_opt_optimizer_type_adamw(), ggml_opt_optimizer_type_sgd(), ggml_opt_outputs(), ggml_opt_outputs_i(), ggml_opt_pred(), ggml_opt_prepare_alloc(), ggml_opt_reset(), ggml_opt_result_accuracy(), ggml_opt_result_free(), ggml_opt_result_init(), ggml_opt_result_loss(), ggml_opt_result_loss_i(), ggml_opt_result_n_loss(), ggml_opt_result_ndata(), ggml_opt_result_pred(), ggml_opt_result_reset(), ggml_opt_set_lr(), ggml_opt_static_graphs(), ggml_snapshot_free(), ggml_trainer()

Examples

if (FALSE) {
history <- ggml_fit_opt_multi(sched, ctx_compute, inputs, list(out_a, out_b),
  dataset, loss_types = c(ggml_opt_loss_type_mse(), ggml_opt_loss_type_mse()),
  nepoch = 50, val_split = 0.2,
  callbacks = list(ggml_callback_early_stopping(monitor = "val_loss", patience = 5)))
attr(history, "head_loss")
}

ggmlR documentation built on Oct. 23, 2026, 1:07 a.m.