参数

• r (int) — LoRA 注意力维度（即“秩”）。
• target_modules (Optional[Union[List[str], str]]) — 应用适配器的模块名称。如果指定，只有具有指定名称的模块将被替换。当传入字符串时，将执行正则表达式匹配。当传入字符串列表时，将执行精确匹配，或者检查模块名称是否以任何传入的字符串结尾。如果指定为 'all-linear'，则选择所有线性/Conv1D 模块（如果模型是 PreTrainedModel，则排除输出层）。如果未指定，将根据模型架构选择模块。如果架构未知，将引发错误——在这种情况下，您应该手动指定目标模块。要避免定位任何模块（因为您想应用 `target_parameters`），请设置 `target_modules=[]`。
• exclude_modules (Optional[Union[List[str], str]]) — 不应用适配器的模块名称。当传入字符串时，将执行正则表达式匹配。当传入字符串列表时，将执行精确匹配，或者检查模块名称是否以任何传入的字符串结尾。
• lora_alpha (int) — LoRA 缩放的 alpha 参数。
• lora_dropout (float) — LoRA 层的 dropout 概率。
• fan_in_fan_out (bool) — 如果要替换的层存储的权重形式为（fan_in, fan_out），则将其设置为 True。例如，gpt-2 使用 `Conv1D`，它存储权重的方式是（fan_in, fan_out），因此应将其设置为 `True`。
• bias (str) — LoRA 的偏置类型。可以是 ‘none’、‘all’ 或 ‘lora_only’。如果为 ‘all’ 或 ‘lora_only’，相应的偏置将在训练期间更新。请注意，这意味着即使禁用适配器，模型的输出也不会与未进行自适应的基础模型相同。
• use_rslora (bool) — 当设置为 True 时，使用 Rank-Stabilized LoRA，它将适配器缩放因子设置为 `lora_alpha/math.sqrt(r)`，因为这被证明效果更好。否则，它将使用原始的默认值 `lora_alpha/r`。
• modules_to_save (List[str]) — 除了适配器层之外，要设置为可训练并保存在最终检查点中的模块列表。
• init_lora_weights (bool | Literal["gaussian", "eva", "olora", "pissa", "pissa_niter_[number of iters]", "corda", "loftq", "orthogonal"]) — 如何初始化适配器层的权重。传入 True（默认值）会使用微软参考实现中的默认初始化，LoRA B 权重设置为 0。这意味着在没有进一步训练的情况下，LoRA 适配器将是一个空操作。将初始化设置为 False 会导致 LoRA A 和 B 的随机初始化，意味着在训练前 LoRA 不是空操作；此设置用于调试目的。传入 'gaussian' 会导致高斯初始化，并按 LoRA 秩进行缩放。传入 `'loftq'` 以使用 LoftQ 初始化。传入 `'eva'` 会导致 可解释方差自适应（Explained Variance Adaptation） 的数据驱动初始化。EVA 基于层输入激活的 SVD 初始化 LoRA，并因其能适应微调数据而达到 SOTA 性能。传入 `'olora'` 以使用 OLoRA 初始化。传入 `'pissa'` 会导致 https://huggingface.co/papers/2404.02948’

  主奇异值和奇异向量自适应（Principal Singular values and Singular vectors Adaptation, PiSSA）的初始化，它比 LoRA 收敛更快，并最终实现更优异的性能。此外，PiSSA 与 QLoRA 相比减少了量化误差，从而进一步提升了性能。传入 `'pissa_niter_[number of iters]'` 会启动基于快速 SVD 的 PiSSA 初始化，其中 `[number of iters]` 表示执行 FSVD 的子空间迭代次数，并且必须是一个非负整数。当 `[number of iters]` 设置为 16 时，可以在几秒内完成一个 7B 模型的初始化，并且训练效果约等于使用 SVD。传入 `'corda'` 会导致 面向上下文的分解自适应（Context-Oriented Decomposition Adaptation） 的初始化，在指令预览模式下比 PiSSA 收敛更快，并且在知识保留模式下比 LoRA 更好地保留世界知识。传入 `"orthogonal"` 会导致 LoRA A 和 B 被正交初始化；在这方面，它类似于 `"olora"`，但基础权重保持不变（要求 `r` 为偶数，目前仅支持线性层）。

• layers_to_transform (Union[List[int], int]) — 要转换的层索引。如果传入一个整数列表，它将把适配器应用于此列表中指定的层索引。如果传入单个整数，它将对此索引处的层应用转换。
• layers_pattern (Optional[Union[List[str], str]]) — 层模式名称，仅在 `layers_to_transform` 不为 `None` 时使用。这应该针对模型的 `nn.ModuleList`，通常称为 `'layers'` 或 `'h'`。
• rank_pattern (dict) — 从层名称或正则表达式到秩的映射，这些秩与 `r` 指定的默认秩不同。例如，`{'^model.decoder.layers.0.encoder_attn.k_proj': 16}`。
• alpha_pattern (dict) — 从层名称或正则表达式到 alpha 值的映射，这些 alpha 值与 `lora_alpha` 指定的默认 alpha 值不同。例如，`{'^model.decoder.layers.0.encoder_attn.k_proj': 16}`。
• megatron_config (Optional[dict]) — Megatron 的 TransformerConfig 参数。它用于创建 LoRA 的并行线性层。您可以像这样获取它：`core_transformer_config_from_args(get_args())`，这两个函数都来自 Megatron。这些参数将用于初始化 Megatron 的 TransformerConfig。当您想将 LoRA 应用于 megatron 的 ColumnParallelLinear 和 RowParallelLinear 层时，需要指定此参数。
• megatron_core (Optional[str]) — 要使用的 Megatron 核心模块，默认为 `"megatron.core"`。
• trainable_token_indices (Optional[Union[List[int], dict[str, List[int]]]]) — 允许您使用 `peft.TrainableTokensModel` 方法选择性地微调特定的词元索引，而无需重新训练整个嵌入矩阵。您可以通过两种方式指定词元索引。可以指定一个索引列表，这将针对模型的输入嵌入层（如果未找到，则为 `embed_tokens`）。或者，您可以指定一个字典，其中键是嵌入模块的名称，值是词元索引列表，例如 `{'embed_tokens': [0, 1, ...]}`。请注意，使用 FSDP 进行训练需要 `use_orig_params=True` 以避免 `requires_grad` 不均匀导致的问题。
• loftq_config (Optional[LoftQConfig]) — LoftQ 的配置。如果此项不为 None，则将使用 LoftQ 来量化主干权重并初始化 Lora 层。同时也要传递 `init_lora_weights='loftq'`。请注意，在这种情况下，您不应传入已量化的模型，因为 LoftQ 将自行对模型进行量化。
• eva_config (Optional[EvaConfig]) — EVA 的配置。至少需要设置数据集参数（使用与微调相同的数据集）。
• corda_config (Optional[CordaConfig]) — CorDA 的配置。如果此项不为 None，则将使用 CorDA 来构建适配器层。同时也要传递 `init_lora_weights='corda'`。
• use_dora (bool) — 启用‘权重分解低秩自适应’（DoRA）。该技术将权重的更新分解为幅度和方向两部分。方向由普通的 LoRA 处理，而幅度由一个单独的可学习参数处理。这可以提高 LoRA 的性能，尤其是在低秩时。目前，DoRA 仅支持线性和 Conv2D 层。DoRA 引入的开销比纯 LoRA 大，因此建议在推理时合并权重。更多信息，请参阅 https://huggingface.co/papers/2402.09353。
• layer_replication (List[Tuple[int, int]]) — 通过根据指定的范围堆叠原始模型层来构建新的层堆栈。这允许在不复制基础模型权重的情况下扩展（或缩小）模型。新层都将附加独立的 LoRA 适配器。
• runtime_config (LoraRuntimeConfig) — 运行时配置（不保存或恢复）。
• lora_bias (bool) — 默认为 `False`。是否为 LoRA B 参数启用偏置项。通常，这应该被禁用。其主要用途是当 LoRA 权重是从完全微调的参数中提取时，可以考虑这些参数的偏置。
• target_parameters (List[str], *可选*) — 要用 LoRA 替换的参数名称列表或参数名称的正则表达式。此参数的行为类似于 `target_modules`，但应传递参数名称。通常，您应该使用 `target_modules` 来定位模块（例如 `nn.Linear`）。然而，在某些情况下，这是不可能的。例如，在 HF Transformers 的许多专家混合（MoE）层中，使用的是 `nn.Parameter` 而不是 `nn.Linear`。PEFT 通常会为 LoRA 重写 `forward` 方法，但 `nn.Parameter` 没有 `forward` 方法。因此，要将 LoRA 应用于该参数，需要使用 `target_parameters` 来定位它。例如，对于 Llama4，您可以传递：`target_parameters=['feed_forward.experts.gate_up_proj', 'feed_forward.experts.down_proj]`。尚未实现传递字符串进行正则表达式匹配。

参数

• model (torch.nn.Module) — 需要被适配的模型。
• config (LoraConfig) — Lora 模型的配置。
• adapter_name (str) — 适配器的名称，默认为 `"default"`。
• low_cpu_mem_usage (bool, `可选`, 默认为 `False`) — 在元设备上创建空的适配器权重。有助于加快加载过程。

LoRA 模型。

参数

• peft_model (PeftModel) — 需要替换权重的模型。必须是带有 LoRA 层的量化 PEFT 模型。
• model_path (Optional[str]) — 模型 safetensors 文件的路径。如果模型是 Hugging Face 模型，将从模型的配置中推断。否则，必须提供此路径。
• adapter_name (str) — 要替换其权重的适配器的名称。默认适配器名称为“default”。
• callback (Optional[Callable[[PeftModel, str], bool]]) — 每个模块被替换后将调用的回调函数。回调函数应以模型和当前模块的名称作为输入，并返回一个布尔值，指示是否应保留替换。如果回调返回 False，替换将被回滚。这对于确认 LoftQ 初始化是否确实减少了模型的量化误差非常有用。例如，此回调可以为给定输入生成 logits，并将其与来自原始非量化模型使用相同输入的 logits 进行比较，仅在有改进时返回 `True`。由于这是一种贪婪优化，多次调用此函数可能会产生增量改进。

参数

• rho (float) — 用于 EVA 重分布的 Rho 值 (>= 1.0)。层的最大秩为 lora_r * rho。默认为 2.0，意味着层的最大允许秩为 2r。增加 rho 将允许在各层之间进行更大程度的秩重分布。一些预训练模型可能对秩重分布更敏感。因此，如果性能低于预期，尝试 rho=1.0（无重分布）可能会有益。
• tau (float) — 用于提前停止的余弦相似度阈值。比较两个连续 SVD 步骤之间右奇异向量的余弦相似度。如果余弦相似度高于此阈值，则停止 SVD 迭代。默认为 0.99。
• use_label_mask (bool) — 为 EVA 初始化使用标签掩码。这意味着 labels=label_mask_value 的位置在 SVD 计算中被忽略。在大多数情况下，首选设置 use_label_mask=True，并且对于多轮对话尤其有益。默认值为 True。根据标签掩码过滤项目有时会导致批量大小过小，从而导致 SVD 计算不稳定。对于大量批次项目会被过滤掉的情况，请设置 use_label_mask=False。
• label_mask_value (int) — 如果 use_label_mask=True，则用于查找要屏蔽的被忽略的标记的值。默认为 -100。
• whiten (bool) — 对奇异向量应用白化处理。默认为 False。白化已被证明在视觉领域对 EVA 有益。
• adjust_scaling_factors (bool) — 在秩重分布后调整 LoRA 缩放因子。将其设置为 True 意味着调整缩放因子，使得所有 LoRA 梯度的尺度都相同，无论其秩如何。默认为 True。

参数

• model (PeftModel) — 用于计算 SVD 的 peft 模型。
• dataloader (Optional[Iterable]) — 用于前向传播的数据加载器。如果为 None，则需要提供 eva_state_dict。
• eva_state_dict (Optional[dict]) — 要加载到模型中的 state_dict。如果为 None，则需要提供数据加载器，并且将使用 `get_eva_state_dict` 计算 state_dict。
• forward_fn (callable) — 用于前向传播的前向函数。接受两个参数：`model` 和 `inputs`。默认行为是 `return model(**inputs)`
• prepare_model_inputs_fn (Optional[callable]) — 此函数接收模型输入和 peft_config，并将输出传递给 `prepare_layer_inputs_fn`。可用于根据原始模型输入修改 SVD 计算的输入。例如，对于语言建模，注意力掩码用于确定哪些索引是填充标记，不应用于 SVD。此处定义的任何函数都期望两个参数：`model_input` 和 `peft_config`。默认使用 `peft.tuners.lora.eva.prepare_model_inputs_fn_language_modeling`。
• prepare_layer_inputs_fn (Union[callable, Dict[str, callable], None]) — 此函数接收层输入、模型输入（可能由 `prepare_model_inputs_fn` 修改）和层的名称，并返回该特定层应用于 SVD 的输入。此处定义的任何自定义函数都期望三个参数：`layer_input`、`model_input` 和 `layer_name`，并应返回一个 2d 张量。默认逻辑可在 peft.tuners.lora.eva.prepare_layer_inputs_fn_language_modeling 中找到，适用于语言建模。在这种情况下，model_inputs 是用于确定哪些索引应用于 SVD 的掩码（由 `prepare_model_inputs_fn_language_modeling` 创建）。
• adapter_name (str) — 要初始化权重的适配器的名称。
• gather_distributed_inputs (bool) — 是否从所有 ranks 收集层输入。默认为 True，意味着在分布式设置中，将从所有 ranks 收集层输入用于 SVD 计算。对于非分布式设置，此参数被忽略。如果您在分布式设置中使用非分布式数据加载器，请设置为 False。
• show_progress_bar (bool) — 是否显示进度条。默认为 True。

已初始化 LoRA 权重的模型。

参数

• model (torch.nn.Module) — 用于计算 SVD 的模型。不需要是 PeftModel。
• dataloader (Iterable) — 用于前向传播的数据加载器。
• peft_config (Optional[LoraConfig]) — LoRA 层的配置。仅当 `model` 不是 PeftModel 时需要。
• forward_fn (callable) — 用于前向传播的前向函数。接收两个参数：`model` 和 `inputs`。默认行为是 `return model(**inputs)`
• prepare_model_inputs_fn (Optional[callable]) — 此函数接收模型输入和 peft_config，并将其输出传递给 `prepare_layer_inputs_fn`。可用于根据原始模型输入修改 SVD 计算的输入。例如，对于语言模型，注意力掩码（attention mask）用于确定哪些索引是填充标记（padding token），不应用于 SVD。此处定义的任何函数都应接收两个参数：`model_input` 和 `peft_config`。默认使用 `peft.tuners.lora.eva.prepare_model_inputs_fn_language_modeling`。
• prepare_layer_inputs_fn (Union[callable, Dict[str, callable], None]) — 此函数接收层输入、模型输入（可能由 `prepare_model_inputs_fn` 修改过）和层名称，并返回该特定层应用于 SVD 的输入。此处定义的任何自定义函数都应接收三个参数：`layer_input`、`model_input` 和 `layer_name`，并应返回一个二维张量。默认逻辑可在 peft.tuners.lora.eva.prepare_layer_inputs_fn_language_modeling 中找到，适用于语言模型。在这种情况下，model_inputs 是用于确定哪些索引应用于 SVD 的掩码（由 `prepare_model_inputs_fn_language_modeling` 创建）。
• adapter_name (str) — 要为其计算 SVD 的适配器名称。
• gather_distributed_inputs (bool) — 是否从所有排名（rank）中收集层输入。默认为 True，表示在分布式设置中，将从所有排名中收集层输入用于 SVD 计算。对于非分布式设置，此参数将被忽略。如果在分布式设置中使用非分布式数据加载器，则设置为 False。
• show_progress_bar (bool) — 是否显示进度条。默认为 True。

包含每层 SVD 分量的状态字典。