引數

• 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 分量的狀態字典。