ggml_fit: Train a Model (dispatcher)

In ggmlR: 'GGML' Tensor Operations for Machine Learning

Train a Model (dispatcher)

Description

Dispatcher: if the first argument is a ggml_sequential_model, delegates to the Keras-style high-level API (ggml_fit_sequential); otherwise delegates to the low-level optimizer loop (ggml_fit_opt).

Usage

## S3 method for class 'ggml_functional_model'
ggml_fit(
  model,
  x,
  y,
  epochs = 1L,
  batch_size = 32L,
  validation_split = 0,
  validation_data = NULL,
  verbose = 1L,
  shuffle = TRUE,
  callbacks = list(),
  ...
)

ggml_fit(model, ...)

## S3 method for class 'ggml_sequential_model'
ggml_fit(model, ...)

## Default S3 method:
ggml_fit(model, ...)

Arguments

model	A compiled model object.
x	Training data (matrix or array).
y	Training labels (matrix, one-hot encoded).
epochs	Number of training epochs (default: 1).
batch_size	Batch size (default: 32).
validation_split	Fraction of data for validation (default: 0).
validation_data	Optional list(x_val, y_val). Overrides validation_split.
verbose	0 = silent, 1 = progress (default: 1).
shuffle	Shuffle the data (default TRUE). The dataset is shuffled once before the train/validation split, then the training portion is reshuffled each epoch while the validation portion stays fixed. Set to FALSE for time series or exactly reproducible runs.
callbacks	List of callback objects, e.g. ggml_callback_early_stopping or an LR scheduler. Each is a list with on_epoch_begin(epoch, logs, state) and/or on_epoch_end(epoch, logs, state); setting state$stop <- TRUE stops training. logs holds train_loss, train_accuracy, val_loss and val_accuracy, and for a multi-output model also train_<output>_loss, train_<output>_accuracy, val_<output>_loss and val_<output>_accuracy, so a callback can monitor one head rather than the total. These are the same names model$history uses, so a monitor= naming one of them matches a column there. Both phases carry a prefix on purpose: it keeps an output named val_x from colliding with another output's validation key. ggml_evaluate reports the same per-head quantities under the bare <output>_loss, since a single evaluation has no train/val phases to tell apart.
...	Arguments passed to the appropriate implementation.

Details

Keras-style (Sequential model):

model

A compiled ggml_sequential_model

x

Training data (matrix or array)

y

Training labels (matrix, one-hot encoded for classification)

epochs

Number of training epochs (default: 1)

batch_size

Batch size (default: 32)

validation_split

Fraction of data for validation (default: 0)

validation_data

Optional list(x_val, y_val) for validation. Overrides validation_split.

class_weight

Named vector of weights per class, e.g. c("0"=1, "1"=10). Cannot be used with sample_weight.

sample_weight

Per-sample weights: a numeric vector of length nrow(x), or – for mean_squared_error only – a nrow(x) by ncol(y) matrix acting as a per-output loss mask. A mask trains only the outputs whose weight is non-zero, which is what a Q-model needs: 1 on the action that has a TD target, 0 elsewhere. The denominator is unchanged (sum(w*(pred-y)^2)/nelements), so masking does not renormalise over the active outputs. Cannot be used with class_weight.

verbose

0 = silent, 1 = progress (default: 1)

shuffle

Shuffle the data (default: TRUE). Shuffled once before the train/validation split, then the training portion each epoch; the validation portion stays fixed. FALSE for time series or exactly reproducible runs.

callbacks

List of callback objects (early stopping, LR schedules)

generator

Function of no arguments yielding list(x, y) for one batch, or NULL when exhausted – an alternative to x and y that keeps only the current batch in memory. See ggml_fit_generator, to which the call is forwarded along with steps_per_epoch, initial_epoch, validation_generator and validation_steps. The arguments that are defined in terms of a whole dataset – validation_split, validation_data, class_weight and sample_weight – are rejected rather than ignored, and shuffle is inert because the generator owns its own order.

Low-level (optimizer loop):

sched

Backend scheduler

ctx_compute

Compute context

inputs

Input tensor

outputs

Output tensor

dataset

Dataset from ggml_opt_dataset_init()

loss_type

Loss type (default: MSE)

optimizer

Optimizer type (default: AdamW)

nepoch

Number of epochs (default: 10)

nbatch_logical

Logical batch size (default: 32)

val_split

Validation fraction (default: 0)

shuffle

Shuffle the data (default: TRUE)

callbacks

List of callback objects

silent

Suppress output (default: FALSE)

Value

For Sequential models: the trained model (invisibly). For the low-level API: a data frame with columns epoch, train_loss, train_accuracy, val_loss, val_accuracy.

See Also

ggml_fit_opt, ggml_compile

Examples

ggml_set_n_threads(1L)  # deterministic, single OpenMP pool
n <- 128
x <- matrix(runif(n * 4), nrow = n, ncol = 4)
y <- matrix(0, nrow = n, ncol = 2)
for (i in seq_len(n)) { y[i, if (sum(x[i,]) > 2) 1L else 2L] <- 1 }

model <- ggml_model_sequential() |>
  ggml_layer_dense(8, activation = "relu") |>
  ggml_layer_dense(2, activation = "softmax")
model$input_shape <- 4L
model <- ggml_compile(model, optimizer = "adam",
                      loss = "categorical_crossentropy")

# Basic training
model <- ggml_fit(model, x, y, epochs = 5, batch_size = 32, verbose = 0)

# With validation_data
x_val <- matrix(runif(32 * 4), nrow = 32, ncol = 4)
y_val <- matrix(0, nrow = 32, ncol = 2)
for (i in seq_len(32)) { y_val[i, if (sum(x_val[i,]) > 2) 1L else 2L] <- 1 }
model <- ggml_fit(model, x, y, epochs = 3, batch_size = 32,
                  validation_data = list(x_val, y_val), verbose = 0)

# With class_weight (useful for imbalanced classes)
model <- ggml_fit(model, x, y, epochs = 3, batch_size = 32,
                  class_weight = c("0" = 1, "1" = 2), verbose = 0)

# With sample_weight
sw <- runif(n, 0.5, 1.5)
model <- ggml_fit(model, x, y, epochs = 3, batch_size = 32,
                  sample_weight = sw, verbose = 0)

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