Source code for nvalchemi.training.peft.lora_hook

# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
"""LoRA fine-tuning hooks."""

from __future__ import annotations

from collections.abc import Mapping
from enum import Enum
from typing import Any, ClassVar, Final

from pydantic import BaseModel, ConfigDict

from nvalchemi.hooks._context import HookContext
from nvalchemi.training.hooks.finetune import _matched_names
from nvalchemi.training.peft import _peft
from nvalchemi.training.peft.lora import LORA_PEFT_METHOD, LoRAConfig
from nvalchemi.training.peft.lora_wrappers import (
    LoRAWrappableLayer,
    LoRAWrapper,
    LoRAWrapperRegistrations,
    _temporary_lora_wrapper_registrations,
)

__all__ = [
    "LoRAWrapper",
    "LoRAHook",
    "LoRAWrapperRegistrations",
    "LoRAWrappableLayer",
]

_LORA_PARAMETER_SOURCE: Final = LORA_PEFT_METHOD


def _collate_lora_metadata(
    model_name: str,
    model: Any,
    result: _peft.ApplyResult,
) -> tuple[set[str], set[str]]:
    """Return trainable and managed names for a model."""
    wrapped_module_names = [
        name for name, module in model.named_modules() if _peft.is_lora_layer(module)
    ]
    model_parameter_names = {name for name, _parameter in model.named_parameters()}
    trainable_names = getattr(result, "trainable_names", None)
    if trainable_names is None:
        trainable_names = [
            name
            for name, parameter in model.named_parameters()
            if parameter.requires_grad
        ]
    if not isinstance(trainable_names, (list, tuple, set)):
        raise TypeError(
            "LoRA apply result trainable_names must be a list, tuple, or set, "
            f"got {type(trainable_names).__name__}."
        )
    if not all(isinstance(name, str) for name in trainable_names):
        raise TypeError("LoRA apply result trainable_names must contain only strings.")
    trainable_names = sorted(set(trainable_names))
    missing = sorted(set(trainable_names) - model_parameter_names)
    if missing:
        raise RuntimeError(
            "LoRA apply result references trainable parameter(s) that are not "
            f"present on model {model_name!r}: "
            f"{[f'{model_name}.{name}' for name in missing]!r}."
        )
    qualified_trainable_names = {f"{model_name}.{name}" for name in trainable_names}
    qualified_managed_names: set[str] = set()
    for module_name in wrapped_module_names:
        prefix = f"{module_name}." if module_name else ""
        qualified_managed_names.update(
            f"{model_name}.{name}"
            for name in model_parameter_names
            if name.startswith(prefix)
        )
    return qualified_trainable_names, qualified_managed_names


[docs] class LoRAHook(BaseModel): """Apply LoRA adapters to models. This hook is automatically prepended when :class:`~nvalchemi.training.FineTuningStrategy` receives a :class:`~nvalchemi.training.peft.lora.LoRAConfig`. Parameters ---------- lora_config : LoRAConfig LoRA PEFT configuration describing adapter targets, rank, scaling, dropout, MLP wrapping, and custom wrapper registrations. register_parameters : bool, optional If ``True``, register LoRA adapter parameters as trainable and managed on the workflow. Set to ``False`` for standalone model loading where no training workflow registry exists. Defaults to ``True``. Attributes ---------- frequency : int Required by the hook protocol; always ``1``. stage : None This hook does not run at training stages. """ lora_config: LoRAConfig register_parameters: bool = True frequency: ClassVar[int] = 1 stage: ClassVar[None] = None model_config = ConfigDict(arbitrary_types_allowed=True) def _runs_on_stage(self, stage: Enum) -> bool: """Return ``False`` because LoRA injection runs on registration.""" return False def __call__(self, ctx: HookContext, stage: Enum) -> None: """No-op stage hook; LoRA injection is handled by :meth:`on_register`.""" return
[docs] def on_register(self, workflow: Any) -> None: """Register wrappers, inject adapters, and register adapter parameters. The public configuration is validated before creating this hook. During registration, model-prefixed targets are converted to model-local targets for each model to be compatible with the PhysicsNeMo ``apply_lora`` function. For example, ``"student.model.projection"`` becomes the PhysicsNeMo ``target_modules`` entry ``"model.projection"`` for the ``"student"`` model. Adapters are then injected, and their trainable and managed parameter names are registered on the workflow. """ # Validate workflow models = getattr(workflow, "models", None) if not isinstance(models, Mapping): raise TypeError("LoRAHook requires a workflow with a models mapping.") if getattr(workflow, "_optimizers", None) or getattr( workflow, "_flat_opts", None ): raise RuntimeError( "LoRAHook must be registered before optimizers are built." ) # Apply LoRA to models and collect registration data. # Adapter selectors operate on one model at a time. Convert # model-prefixed selectors such as "student.model.projection" to # model-local selectors before delegating to the PhysicsNeMo # ``apply_lora`` function. # Get all module names in the models. model_names = set(models) module_names = { f"{model_name}.{name}" for model_name, model in models.items() for name, _module in model.named_modules() if name } # Identify module names that match the LoRA target patterns. matched_module_names = tuple( sorted( _matched_names( self.lora_config.lora_target_patterns, module_names, label="LoRA target", target_type="module", ) ) ) # Apply LoRA to each model. lora_trainable_names: set[str] = set() lora_managed_names: set[str] = set() for model_name, model in models.items(): # Identify module names that are local to the model and match the LoRA target patterns. local_targets: list[str] = [] for target in matched_module_names: prefix, separator, module_name = target.partition(".") if not separator: raise ValueError( f"LoRA target module {target!r} must include a model prefix, " "for example 'main.model.projection'." ) if prefix not in model_names: raise KeyError( f"LoRA target module {target!r} references unknown model " f"{prefix!r}; available models: {sorted(model_names)}." ) if prefix == model_name: local_targets.append(module_name) # Reconstruct the LoRA configuration for this model. model_lora_config = _peft.PhysicsNeMoLoRAConfig( rank=self.lora_config.rank, alpha=self.lora_config.alpha, target_modules=local_targets or ["__nvalchemi_no_lora_target__"], lora_dropout=self.lora_config.lora_dropout, extras_trainable=[], wrap_mlp=self.lora_config.wrap_mlp, init="default", # hardcode adapter initialization for now ) if not local_targets: continue # Apply LoRA to the model and collect names to register. with _temporary_lora_wrapper_registrations( self.lora_config.wrapper_registrations or () ): result: _peft.ApplyResult = _peft.apply_lora( model, model_lora_config, compute_fingerprint=False ) ( model_trainable_names, model_managed_names, ) = _collate_lora_metadata( model_name, model, result, ) lora_trainable_names.update(model_trainable_names) lora_managed_names.update(model_managed_names) if not self.register_parameters: return # Register LoRA trainable and managed parameter names on the workflow. # Trainable parameters refer to the trainable adapter parameters. # Managed parameters refer to the parameters of the underlying modules modified by LoRA. # These managed parameters are protected from being overridden by other hooks modifying the models. for method_name in ( "register_trainable_parameter_names", "register_managed_parameter_names", ): method = getattr(workflow, method_name, None) if not callable(method): raise TypeError( "LoRAHook requires a workflow with a " f"{method_name}(names, source=...) method." ) workflow.register_trainable_parameter_names( tuple(sorted(lora_trainable_names)), source=_LORA_PARAMETER_SOURCE, ) workflow.register_managed_parameter_names( tuple(sorted(lora_managed_names)), source=_LORA_PARAMETER_SOURCE, )