nvalchemi.training.FineTuningStrategy.from_pretrained_checkpoint

classmethod FineTuningStrategy.from_pretrained_checkpoint(checkpoint_dir, *, checkpoint_index=-1, map_location=None, validators=None, use_original_loss=False, use_original_opt_class=False, optimizer_lr=_DEFAULT_PRETRAINED_CHECKPOINT_LR, **strategy_kwargs)

Start a new fine-tuning run from checkpointed model weights.

This alternate constructor initializes a fresh FineTuningStrategy from a model stored in a native nvalchemi checkpoint. It is intentionally different from load_checkpoint(), which resumes an interrupted fine-tuning strategy by restoring the saved optimizer, scheduler, counters, hooks, and strategy configuration.

from_pretrained_checkpoint loads the complete checkpoint model set as initialization. Single-model checkpoints are passed to the strategy as a single model; multi-model checkpoints are passed as a named model mapping. Source optimizer state, scheduler state, hooks, epoch/step limits, and runtime counters are not inherited. The new fine-tuning strategy starts with reset counters and applies any module_patches or trainable-parameter filters before optimizer construction.

By default, callers provide a new loss_fn and optimizer_configs. Set use_original_loss=True or use_original_opt_class=True to fill either value from the source checkpoint metadata when the caller omits it. Reused optimizer configs keep the original optimizer and scheduler classes, but their optimizer lr is overwritten with optimizer_lr unless optimizer_lr=None is passed.

Parameters:

• checkpoint_dir (Path | str) – Root directory containing a checkpoint written by TrainingStrategy.save_checkpoint() or CheckpointHook.

• checkpoint_index (int, optional) – Checkpoint index to read. -1 loads the latest index recorded in the checkpoint manifest.

• map_location (str | torch.device | None, optional) – Device override forwarded to checkpoint loading.

• validators (Sequence[Any] | None, optional) – Optional checkpoint validators forwarded to the lower-level loader.

• use_original_loss (bool, optional) – If True and loss_fn is not supplied, rebuild the loss from the source strategy checkpoint metadata.

• use_original_opt_class (bool, optional) – If True and optimizer_configs is not supplied, rebuild the optimizer/scheduler configs from source checkpoint metadata.

• optimizer_lr (float | None, optional) – Learning rate written into reused optimizer configs. Defaults to 1e-5 for conservative fine-tuning. Pass None to preserve the checkpoint’s serialized optimizer learning rates.

• **strategy_kwargs (Any) – Normal FineTuningStrategy constructor arguments except models. The loaded checkpoint model is supplied as models.

Returns:

A new fine-tuning strategy initialized from checkpointed model weights.

Return type:

FineTuningStrategy

Raises:

ValueError – If models is supplied, if no checkpoint models are loaded, or if requested source loss/optimizer metadata is unavailable.

Notes

Use load_checkpoint() instead when the goal is to resume the same fine-tuning run with its saved optimizer state, scheduler state, hooks, counters, and training limits. Source loss and optimizer config reuse here is initialization-only and never restores optimizer state.