辅助方法

PEFT 的辅助函数集合。

检查模型是否为 PEFT 模型

peft.helpers.check_if_peft_model

< source >

( model_name_or_path: str ) → bool

参数

model_name_or_path (str) — 要检查的模型 ID，可以是本地路径或 Hugging Face Hub 上的模型。

返回值

bool

如果模型是 PEFT 模型，则为 True，否则为 False。

检查模型是否为 PEFT 模型。

在 LoraLayer 模块中临时重新缩放适配器比例

peft.helpers.rescale_adapter_scale

< source >

( model: Modulemultiplier: float | int )

参数

model — 包含需要调整其缩放因子的 LoraLayer 模块的模型。
multiplier (float 或 int) — 用于重新缩放 scaling 属性的乘数。类型必须为 float 或 int。

引发

ValueError

ValueError — 如果模型不包含任何 LoraLayer 实例，则表明该模型不支持缩放。

上下文管理器，用于临时重新缩放模型中 LoRA 适配器的缩放比例。

当上下文管理器退出时，原始的缩放值会被恢复。此上下文管理器适用于直接加载了 LoRA 适配器的 transformers 和 diffusers 模型。

对于 LoRA，使用乘数在 [0, 1] 范围内的此上下文管理器，与使用 wise-ft 严格等价（详见 #1940）。如果用于微调的训练数据与推理期间使用的测试数据之间存在分布偏移，它可以提升模型的性能。

警告：有报告指出，在使用 PyTorch 的 Apple MPS 后端时，需要在退出上下文后添加一段短暂的睡眠时间，以确保 scales 完全恢复。

示例：

>>> model = ModelWithLoraLayer()
>>> multiplier = 0.5
>>> with rescale_adapter_scale(model, multiplier):
...     outputs = model(**inputs)  # Perform operations with the scaled model
>>> outputs = model(**inputs)  # The original scaling values are restored here

用于在 LoRA 层的前向方法中禁用输入数据类型转换的上下文管理器

peft.helpers.disable_input_dtype_casting

< source >

( model: Moduleactive: bool = True )

参数

model (nn.Module) — 包含 PEFT 模块的模型，其输入 dtype 转换需要被调整。
active (bool) — 上下文管理器是否处于激活状态（默认）或非激活状态。

上下文管理器会禁用将输入数据类型转换为权重数据类型的操作。

用于启用 DoRA 缓存的上下文管理器（推理时速度更快，但需要更多内存）

类 peft.helpers.DoraCaching

< source >

( enabled: bool = True )

用于启用 DoRA 缓存的上下文管理器，它以提高 DoRA 推理速度为代价，但会增加内存开销。

在启用主动缓存时，会缓存物化的 LoRA 权重（B @ A）以及权重范数（基础权重 + LoRA 权重）。

即使在缓存上下文中，如果模型处于训练模式，缓存也会被禁用。当模型切换到训练模式时，缓存将被清除。

示例：

>>> from peft.helpers import DoraCaching

>>> model.eval()  # put in eval model for caching to work

>>> with DoraCaching():  # use as a context manager
...     output = model(inputs)

>>> dora_caching = DoraCaching()
>>> dora_caching(enabled=True)  # permanently enable caching
>>> output = model(inputs)
>>> dora_caching(enabled=False)  # permanently disable caching
>>> output = model(inputs)

KappaTune 目标选择

KappaTuneSelector 和 find_kappa_target_modules 实现了源自 KappaTune 论文的通用目标选择流程。

该方法识别出具有更高灵活性（更高的输出微分熵）和更低专门化程度（对特定输入方向的敏感度更低）的模块。

这些特性使得所选模块成为缓解任何添加可训练参数的适配方法中灾难性遗忘的良好候选，包括 LoRA、DoRA、LoHa、AdaLoRA，甚至是对原始权重的直接微调。

class peft.helpers.KappaTuneSelector

< source >

( model: Modulemax_dim_size_to_analyze: int = 16384moe_param_suffixes: tuple[str, ...] | None = Noneshow_progress: bool = True )

轻量级实用工具，用于计算每个模块/每个参数的条件数，并返回最佳的 LoRA 目标。

支持：

经典 nn.Linear 模块（LoraConfig 中的 target_modules）
以 3D nn.Parameter 形式存储的现代融合 MoE 权重（gate_up_proj / down_proj、gate_proj / up_proj 等），用于 Llama-4、Qwen2_MoE、Qwen3_MoE、Mixtral、OLMoE 及类似模型。这些权重通过 target_parameters 返回。

注意事项：

计算条件数需要运行 SVD，在非常大的模型上可能需要几分钟。可以通过 show_progress 显示或禁用进度条。

peft.find_kappa_target_modules

< source >

( model: Moduletop_p: float = 0.2max_dim_size_to_analyze: int = 16384moe_param_suffixes: tuple[str, ...] | None = Noneshow_progress: bool = True )

参数

model (nn.Module) — 将对其权重进行条件数分析的基础模型。
top_p (float, 可选) — 选择条件数最低的候选模块/参数中占比最高的部分。
max_dim_size_to_analyze (int, optional) — 通过 SVD 分析的最大矩阵维度的上限。默认值为 16384。
moe_param_suffixes (Optional[tuple[str, …]], optional) — 用于标识应通过 target_parameters 返回的融合 MoE 张量的参数名称后缀。如果为 None，则使用合理的默认值。
show_progress (bool, optional) — 是否在计算候选张量/模块的条件数（基于 SVD）时显示进度条。在 CI 或其他非交互式环境中应禁用。默认为 True。

用于 KappaTune 目标选择的一行便捷函数。同时返回 target_modules 和 target_parameters。

Update on GitHub