Hugging Face 的 LOGO

PEFT 文档

模型

Hugging Face's logo
加入 Hugging Face 社区

并获得增强的文档体验

开始使用

模型

PeftModel 是用于指定基础 Transformer 模型和配置以应用 PEFT 方法的基础模型类。基础 PeftModel 包含从 Hub 加载和保存模型的方法。

PeftModel

class peft.PeftModel

< >

( model: PreTrainedModel peft_config: PeftConfig adapter_name: str = 'default' autocast_adapter_dtype: bool = True low_cpu_mem_usage: bool = False )

参数

  • model (PreTrainedModel) — 用于 Peft 的基础 Transformer 模型。
  • peft_config (PeftConfig) — Peft 模型的配置。
  • adapter_name (str, 可选) — 适配器的名称，默认为 "default"。
  • autocast_adapter_dtype (bool, 可选) — 是否自动转换适配器的数据类型。默认为 True。目前，这只会将使用 float16 和 bfloat16 的适配器权重转换为 float32，因为这通常是稳定训练所必需的，并且只影响特定的 PEFT 微调器。
  • low_cpu_mem_usage (bool, 可选, 默认为 False) — 在元设备（meta device）上创建空的适配器权重。有助于加快加载过程。

    在为训练创建新的 PEFT 适配器时，不要使用 low_cpu_mem_usage=True。

包含各种 Peft 方法的基础模型。

属性:

  • base_model (torch.nn.Module) — 用于 Peft 的基础 Transformer 模型。
  • peft_config (PeftConfig) — Peft 模型的配置。
  • modules_to_save (list of str) — 保存模型时要保存的子模块名称列表。
  • prompt_encoder (PromptEncoder) — 如果使用 PromptLearningConfig，则为 Peft 使用的提示编码器。
  • prompt_tokens (torch.Tensor) — 如果使用 PromptLearningConfig，则为 Peft 使用的虚拟提示令牌。
  • transformer_backbone_name (str) — 如果使用 PromptLearningConfig，则为基础模型中 Transformer 主干的名称。
  • word_embeddings (torch.nn.Embedding) — 如果使用 PromptLearningConfig，则为基础模型中 Transformer 主干的词嵌入。

add_adapter

< >

( adapter_name: str peft_config: PeftConfig low_cpu_mem_usage: bool = False )

参数

  • adapter_name (str) — 要添加的适配器的名称。
  • peft_config (PeftConfig) — 要添加的适配器的配置。
  • low_cpu_mem_usage (bool, 可选, 默认为 False) — 在元设备（meta device）上创建空的适配器权重。在加载已保存的适配器时有助于加快处理速度。在为训练创建新的 PEFT 适配器时不要使用此选项。

根据传入的配置向模型添加一个适配器。

此适配器未经训练。要加载已训练的适配器，请查看 PeftModel.load_adapter()。

新适配器的名称应该是唯一的。

新适配器不会自动设置为活动适配器。使用 PeftModel.set_adapter() 设置活动适配器。

create_or_update_model_card

< >

( output_dir: str )

更新或创建模型卡以包含有关 peft 的信息

  1. 添加 peft 库标签
  2. 添加 peft 版本
  3. 添加基础模型信息
  4. 如果使用了量化，则添加量化信息

delete_adapter

< >

( adapter_name: str )

参数

  • adapter_name (str) — 要删除的适配器的名称。

删除一个现有的适配器。

disable_adapter

< >

( )

禁用适配器模块的上下文管理器。使用此管理器在基础模型上运行推理。

示例

>>> with model.disable_adapter():
...     model(inputs)

forward

< >

( *args: Any **kwargs: Any )

模型的前向传播。

from_pretrained

< >

( model: torch.nn.Module model_id: Union[str, os.PathLike] adapter_name: str = 'default' is_trainable: bool = False config: Optional[PeftConfig] = None autocast_adapter_dtype: bool = True ephemeral_gpu_offload: bool = False low_cpu_mem_usage: bool = False key_mapping: Optional[dict[str, str]] = None **kwargs: Any )

参数

  • model (torch.nn.Module) — 要被适配的模型。对于 🤗 Transformers 模型，该模型应使用 from_pretrained 进行初始化。
  • model_id (str 或 os.PathLike) — 要使用的 PEFT 配置的名称。可以是：
    • 一个字符串，即托管在 Hugging Face Hub 模型仓库中的 PEFT 配置的 model id。
    • 一个包含使用 save_pretrained 方法保存的 PEFT 配置文件的目录路径 (./my_peft_config_directory/)。
  • adapter_name (str, 可选, 默认为 "default") — 要加载的适配器的名称。这对于加载多个适配器很有用。
  • is_trainable (bool, 可选, 默认为 False) — 适配器是否可训练。如果为 False，适配器将被冻结，只能用于推理。
  • config (PeftConfig, 可选) — 要使用的配置对象，而不是自动加载的配置。此配置对象与 model_id 和 kwargs 互斥。当配置在调用 from_pretrained 之前已经加载时，此参数很有用。
  • autocast_adapter_dtype (bool, 可选) — 是否自动转换适配器的数据类型。默认为 True。仅与特定的适配器类型相关。
  • ephemeral_gpu_offload (bool, 可选) — 是否对部分加载的模块使用临时 GPU 卸载。默认为 False。当模型的某些部分和/或组件（如适配器）保存在 CPU 内存中直到需要时，此参数很有用。数据不是在小数据上执行昂贵的操作，而是按需传输到 GPU，执行操作，然后将结果移回 CPU 内存。这会带来轻微的瞬时 VRAM 开销，但在某些情况下可以提供数量级的加速。
  • low_cpu_mem_usage (bool, 可选, 默认为 False) — 在加载已保存的权重之前，在元设备（meta device）上创建空的适配器权重。有助于加快处理速度。
  • torch_device (str, 可选, 默认为 None) — 加载适配器的设备。如果为 None，将自动推断设备。
  • key_mapping (dict, 可选, 默认为 None) — 在加载 state_dict 之前应用的 PEFT state_dict 键的额外映射。当应用此映射时，会预先删除 PEFT 特定的 "base_model.model" 前缀，并且尚未插入适配器名称（例如 "default"）。仅在您清楚自己在做什么时才传递此参数。
  • kwargs — (可选): 传递给特定 PEFT 配置类的其他关键字参数。

从预训练模型和加载的 PEFT 权重实例化一个 PEFT 模型。

请注意，传入的 model 可能会被就地修改。

get_base_model

< >

( )

返回基础模型。

get_layer_status

< >

( ) → 列表peft.peft_model.TunerLayerStatus

参数

  • model (~PeftModel) — 要获取适配器层状态的模型。

返回

列表peft.peft_model.TunerLayerStatus

一个数据类列表，每个数据类包含相应适配器层的状态。

获取模型中每个适配器层的状态。

此方法返回一个 TunerLayerStatus 数据类实例列表，每个实例包含以下属性：

  • name (str)：适配器层的名称，例如 model.encoder.block.0.layer.0.SelfAttention.q。
  • module_type (str)：适配器层的类型，例如 lora.Linear。
  • enabled (bool)：适配器层是否已启用。
  • active_adapters (list[str])：活动适配器的名称（如果有），例如 ["default"]。
  • merged_adapters (list[str])：已合并的适配器的名称（如果有），例如 ["default"]。
  • available_adapters (list[str])：可用适配器的名称，例如 ["default"]。

get_model_status

< >

( ) → peft.peft_model.TunerModelStatus

参数

  • model (~PeftModel) — 要获取适配器层状态的模型。

返回

peft.peft_model.TunerModelStatus

包含模型状态的数据类。

获取模型中微调器的状态。

此方法返回一个 TunerModelStatus 数据类实例，其中包含以下属性：

  • base_model_type (str)：基础模型的类型，例如 T5Model。
  • adapter_model_type (str)：适配器模型的类型，例如 LoraModel。
  • peft_types (dict[str, str])：适配器名称到适配器类型的映射，例如 {"default": "LORA"}。
  • trainable_params (int)：模型中可训练参数的数量。
  • total_params (int)：模型中的总参数数量。
  • num_adapter_layers (int)：模型中适配器层的数量。
  • enabled (bool, Literal["irregular"])：是否所有适配器层都已启用。如果有些启用而有些未启用，此值将为 "irregular"。这意味着您的模型处于不一致的状态，可能无法按预期工作。
  • active_adapters (list[str], Literal["irregular"])：活动适配器的名称。如果活动适配器在所有层中不一致，此值将为 "irregular"，这意味着您的模型处于不一致的状态，可能无法按预期工作。
  • merged_adapters (list[str], Literal["irregular"])：已合并的适配器的名称。如果已合并的适配器在所有层中不一致，此值将为 "irregular"，这意味着您的模型处于不一致的状态，可能无法按预期工作。
  • available_adapters (list[str])：可用适配器的名称，例如 ["default"]。

get_nb_trainable_parameters

< >

( )

返回模型中可训练参数的数量和所有参数的数量。

get_prompt

< >

( batch_size: int task_ids: Optional[torch.Tensor] = None max_cache_len: Optional[int] = None )

返回用于 Peft 的虚拟提示。仅适用于使用提示学习方法时。

get_prompt_embedding_to_save

< >

( adapter_name: str )

返回在保存模型时要保存的提示嵌入。仅适用于使用提示学习方法时。

load_adapter

< >

( model_id: Union[str, os.PathLike] adapter_name: str is_trainable: bool = False torch_device: Optional[str] = None autocast_adapter_dtype: bool = True ephemeral_gpu_offload: bool = False low_cpu_mem_usage: bool = False key_mapping: Optional[dict[str, str]] = None **kwargs: Any )

参数

  • model_id (str or os.PathLike) — 要使用的 PEFT 配置的名称。可以是以下两种之一：
    • 字符串，即 Hugging Face Hub 上模型仓库中托管的 PEFT 配置的 model id。
    • 使用 save_pretrained 方法保存的包含 PEFT 配置文件的目录路径 (./my_peft_config_directory/)。
  • adapter_name (str) — 要添加的适配器的名称。
  • is_trainable (bool, optional, 默认为 False) — 适配器是否应可训练。如果为 False，适配器将被冻结，只能用于推理。
  • torch_device (str, optional, 默认为 None) — 加载适配器的设备。如果为 None，将自动推断设备。
  • autocast_adapter_dtype (bool, optional, 默认为 True) — 是否自动转换适配器的数据类型。默认为 True。目前，这只会将使用 float16 和 bfloat16 的适配器权重转换为 float32，因为这通常是稳定训练所必需的，并且只影响特定的 PEFT 微调器。
  • ephemeral_gpu_offload (bool, optional, 默认为 False) — 是否对部分加载的模块使用临时 GPU 卸载。默认为 False。
  • low_cpu_mem_usage (bool, optional, 默认为 False) — 在加载保存的权重之前，在元设备上创建空的适配器权重。有助于加速该过程。
  • key_mapping (dict, optional, 默认为 None) — 在加载 state_dict 之前应用的 PEFT state_dict 键的额外映射。应用此映射时，会预先移除 PEFT 特定的 "base_model.model" 前缀，并且尚未插入适配器名称（例如 "default"）。仅在您清楚自己在做什么时才传递此参数。
  • kwargs — (optional): 用于修改适配器加载方式的附加参数，例如 Hugging Face Hub 的 token。

将训练好的适配器加载到模型中。

新适配器的名称应该是唯一的。

新适配器不会自动设置为活动适配器。使用 PeftModel.set_adapter() 设置活动适配器。

prepare_model_for_gradient_checkpointing

< >

( model: PreTrainedModel )

如有必要，为梯度检查点准备模型

print_trainable_parameters

< >

( )

打印模型中可训练参数的数量。

注意：print_trainable_parameters() 使用 get_nb_trainable_parameters()，这与 huggingface/transformers 的 num_parameters(only_trainable=True) 不同。get_nb_trainable_parameters() 返回 Peft 模型的（可训练参数，所有参数），其中包括修改后的主干 transformer 模型。对于像 LoRA 这样的技术，主干 transformer 模型会被 LoRA 模块原地修改。然而，对于提示调整，主干 transformer 模型是未经修改的。num_parameters(only_trainable=True) 返回主干 transformer 模型的可训练参数数量，这可能有所不同。

save_pretrained

< >

( save_directory: str safe_serialization: bool = True selected_adapters: Optional[list[str]] = None save_embedding_layers: Union[str, bool] = 'auto' is_main_process: bool = True path_initial_model_for_weight_conversion: Optional[str] = None **kwargs: Any )

参数

  • save_directory (str) — 将保存适配器模型和配置文件的目录（如果不存在，则会创建）。
  • safe_serialization (bool, optional) — 是否以 safetensors 格式保存适配器文件，默认为 True。
  • selected_adapters (List[str], optional) — 要保存的适配器列表。如果为 None，则默认为所有适配器。
  • save_embedding_layers (Union[bool, str], optional, 默认为 "auto") — 如果为 True，除了适配器权重外，还保存嵌入层。如果为 auto，当可用时，会在配置的 target_modules 中检查常见的嵌入层 peft.utils.other.EMBEDDING_LAYER_NAMES，并自动设置布尔标志。这仅适用于 🤗 transformers 模型。
  • is_main_process (bool, optional) — 调用此方法的进程是否是主进程。默认为 True。如果不是在主进程上，则不会保存检查点，这对于多设备设置（例如 DDP）非常重要。
  • path_initial_model_for_weight_conversion (str, *optional*) — 指向初始化适配器的路径，该适配器是在使用 PiSSA/CorDA/OLoRA 初始化模型后、进行任何训练之前获得的。当 path_initial_model_for_weight_conversion 不为 None 时，会计算微调前后适配器的差异。这个差异可以表示为标准 LoRA 适配器的参数。使用这个转换后的适配器不需要对基础模型进行更改，从而方便地允许将多个 PiSSA/CorDA/OLoRA 适配器与 LoRA 适配器一起使用，并可以激活或停用任何适配器。请注意，如果 rslora 与 rank_pattern 或 alpha_pattern 结合使用，则不支持此转换。
  • kwargs (附加关键字参数, optional) — 传递给 push_to_hub 方法的附加关键字参数。

此函数将适配器模型和适配器配置文件保存到一个目录中，以便可以使用 PeftModel.from_pretrained() 类方法重新加载，并且也可以被 PeftModel.push_to_hub() 方法使用。

set_adapter

< >

( adapter_name: str )

参数

  • adapter_name (str) — 要设置为活动状态的适配器的名称。适配器必须先加载。

设置活动的适配器。

一次只能有一个适配器处于活动状态。

此外，此函数会将指定的适配器设置为可训练状态（即 requires_grad=True）。如果不需要此行为，请使用以下代码。

>>> for name, param in model_peft.named_parameters():
...     if ...:  # some check on name (ex. if 'lora' in name)
...         param.requires_grad = False

PeftModelForSequenceClassification

一个用于序列分类任务的 PeftModel。

class peft.PeftModelForSequenceClassification

< >

( model: torch.nn.Module peft_config: PeftConfig adapter_name: str = 'default' **kwargs )

参数

  • model (PreTrainedModel) — 基础 transformer 模型。
  • peft_config (PeftConfig) — Peft 配置。
  • adapter_name (str, optional) — 适配器的名称，默认为 "default"。
  • autocast_adapter_dtype (bool, optional) — 是否自动转换适配器的数据类型。默认为 True。目前，这只会将使用 float16 和 bfloat16 的适配器权重转换为 float32，因为这通常是稳定训练所必需的，并且只影响特定的 PEFT 微调器。

用于序列分类任务的 Peft 模型。

属性:

  • config (PretrainedConfig) — 基础模型的配置对象。
  • cls_layer_name (str) — 分类层的名称。

示例

>>> from transformers import AutoModelForSequenceClassification
>>> from peft import PeftModelForSequenceClassification, get_peft_config

>>> config = {
...     "peft_type": "PREFIX_TUNING",
...     "task_type": "SEQ_CLS",
...     "inference_mode": False,
...     "num_virtual_tokens": 20,
...     "token_dim": 768,
...     "num_transformer_submodules": 1,
...     "num_attention_heads": 12,
...     "num_layers": 12,
...     "encoder_hidden_size": 768,
...     "prefix_projection": False,
...     "postprocess_past_key_value_function": None,
... }

>>> peft_config = get_peft_config(config)
>>> model = AutoModelForSequenceClassification.from_pretrained("bert-base-cased")
>>> peft_model = PeftModelForSequenceClassification(model, peft_config)
>>> peft_model.print_trainable_parameters()
trainable params: 370178 || all params: 108680450 || trainable%: 0.3406113979101117

PeftModelForTokenClassification

一个用于词元分类任务的 PeftModel。

class peft.PeftModelForTokenClassification

< >

( model: torch.nn.Module peft_config: PeftConfig = None adapter_name: str = 'default' **kwargs )

参数

  • model (PreTrainedModel) — 基础 transformer 模型。
  • peft_config (PeftConfig) — Peft 配置。
  • adapter_name (str, optional) — 适配器的名称，默认为 "default"。
  • autocast_adapter_dtype (bool, optional) — 是否自动转换适配器的数据类型。默认为 True。目前，这只会将使用 float16 和 bfloat16 的适配器权重转换为 float32，因为这通常是稳定训练所必需的，并且只影响特定的 PEFT 微调器。

用于词元分类任务的 Peft 模型。

属性:

  • config (PretrainedConfig) — 基础模型的配置对象。
  • cls_layer_name (str) — 分类层的名称。

示例

>>> from transformers import AutoModelForSequenceClassification
>>> from peft import PeftModelForTokenClassification, get_peft_config

>>> config = {
...     "peft_type": "PREFIX_TUNING",
...     "task_type": "TOKEN_CLS",
...     "inference_mode": False,
...     "num_virtual_tokens": 20,
...     "token_dim": 768,
...     "num_transformer_submodules": 1,
...     "num_attention_heads": 12,
...     "num_layers": 12,
...     "encoder_hidden_size": 768,
...     "prefix_projection": False,
...     "postprocess_past_key_value_function": None,
... }

>>> peft_config = get_peft_config(config)
>>> model = AutoModelForTokenClassification.from_pretrained("bert-base-cased")
>>> peft_model = PeftModelForTokenClassification(model, peft_config)
>>> peft_model.print_trainable_parameters()
trainable params: 370178 || all params: 108680450 || trainable%: 0.3406113979101117

PeftModelForCausalLM

一个用于因果语言建模的 PeftModel。

class peft.PeftModelForCausalLM

< >

( model: torch.nn.Module peft_config: PeftConfig adapter_name: str = 'default' **kwargs )

参数

  • model (PreTrainedModel) — 基础 transformer 模型。
  • peft_config (PeftConfig) — Peft 配置。
  • adapter_name (str, optional) — 适配器的名称，默认为 "default"。
  • autocast_adapter_dtype (bool, optional) — 是否自动转换适配器的数据类型。默认为 True。目前，这只会将使用 float16 和 bfloat16 的适配器权重转换为 float32，因为这通常是稳定训练所必需的，并且只影响特定的 PEFT 微调器。

用于因果语言建模的 Peft 模型。

示例

>>> from transformers import AutoModelForCausalLM
>>> from peft import PeftModelForCausalLM, get_peft_config

>>> config = {
...     "peft_type": "PREFIX_TUNING",
...     "task_type": "CAUSAL_LM",
...     "inference_mode": False,
...     "num_virtual_tokens": 20,
...     "token_dim": 1280,
...     "num_transformer_submodules": 1,
...     "num_attention_heads": 20,
...     "num_layers": 36,
...     "encoder_hidden_size": 1280,
...     "prefix_projection": False,
...     "postprocess_past_key_value_function": None,
... }

>>> peft_config = get_peft_config(config)
>>> model = AutoModelForCausalLM.from_pretrained("gpt2-large")
>>> peft_model = PeftModelForCausalLM(model, peft_config)
>>> peft_model.print_trainable_parameters()
trainable params: 1843200 || all params: 775873280 || trainable%: 0.23756456724479544

PeftModelForSeq2SeqLM

一个用于序列到序列语言建模的 PeftModel。

class peft.PeftModelForSeq2SeqLM

< >

( model: torch.nn.Module peft_config: PeftConfig adapter_name: str = 'default' **kwargs )

参数

  • model (PreTrainedModel) — 基础 transformer 模型。
  • peft_config (PeftConfig) — Peft 配置。
  • adapter_name (str, optional) — 适配器的名称，默认为 "default"。
  • autocast_adapter_dtype (bool, optional) — 是否自动转换适配器的数据类型。默认为 True。目前，这只会将使用 float16 和 bfloat16 的适配器权重转换为 float32，因为这通常是稳定训练所必需的，并且只影响特定的 PEFT 微调器。

用于序列到序列语言建模的 Peft 模型。

示例

>>> from transformers import AutoModelForSeq2SeqLM
>>> from peft import PeftModelForSeq2SeqLM, get_peft_config

>>> config = {
...     "peft_type": "LORA",
...     "task_type": "SEQ_2_SEQ_LM",
...     "inference_mode": False,
...     "r": 8,
...     "target_modules": ["q", "v"],
...     "lora_alpha": 32,
...     "lora_dropout": 0.1,
...     "fan_in_fan_out": False,
...     "enable_lora": None,
...     "bias": "none",
... }

>>> peft_config = get_peft_config(config)
>>> model = AutoModelForSeq2SeqLM.from_pretrained("t5-base")
>>> peft_model = PeftModelForSeq2SeqLM(model, peft_config)
>>> peft_model.print_trainable_parameters()
trainable params: 884736 || all params: 223843584 || trainable%: 0.3952474242013566

PeftModelForQuestionAnswering

一个用于问答的 PeftModel。

class peft.PeftModelForQuestionAnswering

< >

( model: torch.nn.Module peft_config: PeftConfig adapter_name: str = 'default' **kwargs )

参数

  • model (PreTrainedModel) — 基础 transformer 模型。
  • peft_config (PeftConfig) — Peft 配置。
  • adapter_name (str, optional) — 适配器的名称，默认为 "default"。
  • autocast_adapter_dtype (bool, optional) — 是否自动转换适配器的数据类型。默认为 True。目前，这只会将使用 float16 和 bfloat16 的适配器权重转换为 float32，因为这通常是稳定训练所必需的，并且只影响特定的 PEFT 微调器。

用于抽取式问答的 Peft 模型。

属性:

  • config (PretrainedConfig) — 基础模型的配置对象。
  • cls_layer_name (str) — 分类层的名称。

示例

>>> from transformers import AutoModelForQuestionAnswering
>>> from peft import PeftModelForQuestionAnswering, get_peft_config

>>> config = {
...     "peft_type": "LORA",
...     "task_type": "QUESTION_ANS",
...     "inference_mode": False,
...     "r": 16,
...     "target_modules": ["query", "value"],
...     "lora_alpha": 32,
...     "lora_dropout": 0.05,
...     "fan_in_fan_out": False,
...     "bias": "none",
... }

>>> peft_config = get_peft_config(config)
>>> model = AutoModelForQuestionAnswering.from_pretrained("bert-base-cased")
>>> peft_model = PeftModelForQuestionAnswering(model, peft_config)
>>> peft_model.print_trainable_parameters()
trainable params: 592900 || all params: 108312580 || trainable%: 0.5473971721475013

PeftModelForFeatureExtraction

一个用于从 transformer 模型中提取特征/嵌入的 PeftModel。

class peft.PeftModelForFeatureExtraction

< >

( model: torch.nn.Module peft_config: PeftConfig adapter_name: str = 'default' **kwargs )

参数

  • model (PreTrainedModel) — 基础 Transformer 模型。
  • peft_config (PeftConfig) — Peft 配置。
  • adapter_name (str, optional) — 适配器名称，默认为 "default"。
  • autocast_adapter_dtype (bool, optional) — 是否自动转换适配器的数据类型。默认为 True。目前，这只会将使用 float16 和 bfloat16 的适配器权重转换为 float32，因为这通常是稳定训练所必需的，并且只影响特定的 PEFT 微调器。

用于从 Transformer 模型中提取特征/嵌入的 Peft 模型。

属性:

  • config (PretrainedConfig) — 基础模型的配置对象。

示例

>>> from transformers import AutoModel
>>> from peft import PeftModelForFeatureExtraction, get_peft_config

>>> config = {
...     "peft_type": "LORA",
...     "task_type": "FEATURE_EXTRACTION",
...     "inference_mode": False,
...     "r": 16,
...     "target_modules": ["query", "value"],
...     "lora_alpha": 32,
...     "lora_dropout": 0.05,
...     "fan_in_fan_out": False,
...     "bias": "none",
... }
>>> peft_config = get_peft_config(config)
>>> model = AutoModel.from_pretrained("bert-base-cased")
>>> peft_model = PeftModelForFeatureExtraction(model, peft_config)
>>> peft_model.print_trainable_parameters()

PeftMixedModel

一个用于混合不同适配器类型（例如 LoRA 和 LoHa）的 PeftModel。

class peft.PeftMixedModel

< >

( model: nn.Module peft_config: PeftConfig adapter_name: str = 'default' )

参数

  • model (torch.nn.Module) — 需要被微调的模型。
  • config (PeftConfig) — 需要被微调模型的配置。适配器类型必须兼容。
  • adapter_name (str, optional, defaults to "default") — 第一个适配器的名称。
  • low_cpu_mem_usage (bool, optional, defaults to False) — 在 meta 设备上创建空的适配器权重。有助于加速加载过程。

PeftMixedModel 用于加载混合不同类型的适配器以进行推理。

这个类不支持加载/保存，通常不应直接初始化。相反，应使用带有参数 mixed=True 的 get_peft_model。

阅读混合适配器类型指南以了解更多关于使用不同适配器类型的信息。

示例

>>> base_model = ...  # load the base model, e.g. from transformers
>>> peft_model = PeftMixedModel.from_pretrained(base_model, path_to_adapter1, "adapter1").eval()
>>> peft_model.load_adapter(path_to_adapter2, "adapter2")
>>> peft_model.set_adapter(["adapter1", "adapter2"])  # activate both adapters
>>> peft_model(data)  # forward pass using both adapters

add_adapter

< >

( adapter_name: str peft_config: PeftConfig low_cpu_mem_usage: bool = False )

参数

  • adapter_name (str) — 要添加的适配器名称。
  • peft_config (PeftConfig) — 要添加的适配器的配置。
  • low_cpu_mem_usage (bool, optional, defaults to False) — 在 meta 设备上创建空的适配器权重。在加载已保存的适配器时有助于加速过程。

    在为训练创建新的 PEFT 适配器时，不要使用 low_cpu_mem_usage=True（通常不鼓励对 PeftMixedModel 进行训练，且未经测试）。

根据传入的配置向模型添加一个适配器。

此适配器未经训练。要加载已训练的适配器，请查看 PeftModel.load_adapter()。

新适配器的名称应该是唯一的。

新适配器不会自动设置为活动适配器。使用 PeftModel.set_adapter() 设置活动适配器。

disable_adapter

< >

( )

禁用适配器模块。

forward

< >

( *args: Any **kwargs: Any )

模型的前向传播。

from_pretrained

< >

( model: nn.Module model_id: str | os.PathLike adapter_name: str = 'default' is_trainable: bool = False config: Optional[PeftConfig] = None **kwargs: Any )

参数

  • model (nn.Module) — 需要适配的模型。
  • model_id (str or os.PathLike) — 要使用的 PEFT 配置的名称。可以是：
    • 一个字符串，即托管在 Hugging Face Hub 模型仓库中的 PEFT 配置的 model id。
    • 一个包含使用 save_pretrained 方法保存的 PEFT 配置文件的目录路径（./my_peft_config_directory/）。
  • adapter_name (str, optional, defaults to "default") — 要加载的适配器的名称。这对于加载多个适配器很有用。
  • is_trainable (bool, optional, defaults to False) — 适配器是否应可训练。如果为 False，适配器将被冻结并用于推理。
  • config (PeftConfig, optional) — 要使用的配置对象，而不是自动加载的配置。此配置对象与 model_id 和 kwargs 互斥。当在调用 from_pretrained 之前已加载配置时，此参数很有用。
  • low_cpu_mem_usage (bool, optional, defaults to False) — 在加载保存的权重之前，在 meta 设备上创建空的适配器权重。有助于加速该过程。
  • kwargs — (optional)：传递给特定 PEFT 配置类的额外关键字参数。

从预训练模型和已加载的 PEFT 权重实例化一个 PEFT 混合模型。

请注意，传入的 model 可能会被就地修改。

生成

< >

( *args: Any **kwargs: Any )

生成输出。

get_nb_trainable_parameters

< >

( )

返回模型中可训练参数的数量和所有参数的总数。

load_adapter

< >

( model_id: str adapter_name: str *args: Any **kwargs: Any )

参数

  • adapter_name (str) — 要添加的适配器名称。
  • peft_config (PeftConfig) — 要添加的适配器的配置。
  • is_trainable (bool, optional, defaults to False) — 适配器是否应可训练。如果为 False，适配器将被冻结，并且只能用于推理。
  • torch_device (str, optional, defaults to None) — 加载适配器的设备。如果为 None，将自动推断设备。
  • autocast_adapter_dtype (bool, optional, defaults to True) — 是否自动转换适配器的数据类型。默认为 True。目前，这只会将使用 float16 和 bfloat16 的适配器权重转换为 float32，因为这通常是稳定训练所必需的，并且只影响特定的 PEFT 微调器。
  • ephemeral_gpu_offload (bool, optional, defaults to False) — 是否对部分加载的模块使用临时 GPU 卸载。默认为 False。
  • low_cpu_mem_usage (bool, optional, defaults to False) — 在加载保存的权重之前，在 meta 设备上创建空的适配器权重。有助于加速该过程。
  • kwargs — (optional)：用于修改适配器加载方式的额外参数，例如 Hugging Face Hub 的 token。

将训练好的适配器加载到模型中。

新适配器的名称应该是唯一的。

新适配器不会自动设置为活动适配器。使用 PeftModel.set_adapter() 设置活动适配器。

merge_and_unload

< >

( *args: Any **kwargs: Any )

参数

  • progressbar (bool) — 是否显示表示卸载和合并过程的进度条。
  • safe_merge (bool) — 是否激活安全合并检查，以检查适配器权重中是否存在潜在的 Nan 值。
  • adapter_names (List[str], optional) — 应被合并的适配器名称列表。如果为 None，则所有活动的适配器都将被合并。默认为 None。

此方法将适配器层合并到基础模型中。如果有人想将基础模型用作独立模型，则需要此操作。

print_trainable_parameters

< >

( )

打印模型中可训练参数的数量。

注意：print_trainable_parameters() 使用 get_nb_trainable_parameters()，这与 huggingface/transformers 的 num_parameters(only_trainable=True) 不同。get_nb_trainable_parameters() 返回 Peft 模型的（可训练参数，所有参数），其中包括修改后的主干 transformer 模型。对于像 LoRA 这样的技术，主干 transformer 模型会被 LoRA 模块原地修改。然而，对于提示调整，主干 transformer 模型是未经修改的。num_parameters(only_trainable=True) 返回主干 transformer 模型的可训练参数数量，这可能有所不同。

set_adapter

< >

( adapter_name: Union[str, list[str]] )

参数

  • adapter_name (str or List[str]) — 要激活的适配器名称。

为模型设置活动的适配器。

请注意，在前向传播期间应用适配器的顺序可能与将它们传递给此函数的顺序不同。相反，前向传播期间的顺序是由适配器加载到模型中的顺序决定的。活动适配器仅确定哪些适配器在前向传播期间是活动的，而不决定它们的应用顺序。

此外，此函数将把指定的适配器设置为可训练的（即 requires_grad=True）。如果不希望如此，请使用以下代码。

>>> for name, param in model_peft.named_parameters():
...     if ...:  # some check on name (ex. if 'lora' in name)
...         param.requires_grad = False

unload

< >

( *args: Any **kwargs: Any )

通过移除所有适配器模块而不进行合并，恢复基础模型。这将返回原始的基础模型。

实用工具

peft.cast_mixed_precision_params

< >

( model dtype )

参数

  • model (torch.nn.Module) — 需要转换其不可训练参数的模型。
  • dtype (torch.dtype) — 不可训练参数要转换到的数据类型。dtype可以是 torch.float16 或

将模型中所有不可训练的参数转换为给定的 dtype。根据你正在进行的混合精度训练，dtype 可以是 torch.float16 或 torch.bfloat16。可训练的参数被转换为全精度。这样做旨在通过对不可训练参数使用半精度数据类型来减少使用 PEFT 方法时的 GPU 内存占用。将可训练参数保持在全精度可以保证在使用自动混合精度训练时的训练稳定性。

torch.bfloat16，具体取决于你正在执行的混合精度训练。

peft.get_peft_model

< >

( model: PreTrainedModel peft_config: PeftConfig adapter_name: str = 'default' mixed: bool = False autocast_adapter_dtype: bool = True revision: Optional[str] = None low_cpu_mem_usage: bool = False )

参数

  • model (transformers.PreTrainedModel) — 将被包装的模型。
  • peft_config (PeftConfig) — 包含 Peft 模型参数的配置对象。
  • adapter_name (str, optional, defaults to "default") — 要注入的适配器名称，如果未提供，则使用默认适配器名称（“default”）。
  • mixed (bool, optional, defaults to False) — 是否允许混合不同（兼容的）适配器类型。
  • autocast_adapter_dtype (bool, optional) — 是否自动转换适配器的数据类型。默认为 True。目前，这只会将使用 float16 或 bfloat16 的适配器权重转换为 float32，因为这通常是稳定训练所必需的，并且只影响特定的 PEFT 微调器。
  • revision (str, optional, defaults to main) — 基础模型的版本。如果未设置，保存的 peft 模型将加载基础模型的 main 版本。
  • low_cpu_mem_usage (bool, optional, defaults to False) — 在 meta 设备上创建空的适配器权重。有助于加速加载过程。如果你打算训练模型，请将此设置保持为 False，除非适配器权重将在训练开始前被不同的权重替换。

从一个模型和一个配置返回一个 Peft 模型对象，其中模型将被原地修改。

peft.inject_adapter_in_model

< >

( peft_config: PeftConfig model: torch.nn.Module adapter_name: str = 'default' low_cpu_mem_usage: bool = False state_dict: Optional[dict[str, torch.Tensor]] = None )

参数

  • peft_config (PeftConfig) — 包含 Peft 模型参数的配置对象。
  • model (torch.nn.Module) — 将要注入适配器的输入模型。
  • adapter_name (str, 可选, 默认为 "default") — 要注入的适配器名称，如果未提供，则使用默认的适配器名称（“default”）。
  • low_cpu_mem_usage (bool, 可选, 默认为 False) — 在元设备（meta device）上创建空的适配器权重。有助于加快加载过程。
  • state_dict (dict, 可选, 默认为 None) — 如果在此处传递了 state_dict，将根据 state_dict 的条目注入适配器。当 PEFT 方法的确切 target_modules 未知时，这会很有用，例如因为检查点是在没有元数据的情况下创建的。请注意，不使用 state_dict 中的值，仅使用其键来确定应适配的正确层。

一个简单的 API，用于在模型中就地创建并注入适配器。目前该 API 不支持提示学习（prompt learning）方法和 adaption prompt。请确保在 peft_config 对象中设置了正确的 target_names。该 API 在底层调用 get_peft_model，但仅限于非提示学习方法。

peft.get_peft_model_state_dict

< >

( model state_dict = None adapter_name = 'default' unwrap_compiled = False save_embedding_layers = 'auto' )

参数

  • model (PeftModel) — Peft 模型。当使用 torch.nn.DistributedDataParallel、DeepSpeed 或 FSDP 时，该模型应为底层模型/解包后的模型（即 model.module）。
  • state_dict (dict, 可选, 默认为 None) — 模型的 state dict。如果未提供，将使用传入模型的 state dict。
  • adapter_name (str, 可选, 默认为 "default") — 需要返回其 state dict 的适配器名称。
  • unwrap_compiled (bool, 可选, 默认为 False) — 如果使用了 torch.compile，是否解包模型。
  • save_embedding_layers (Union[bool, str], , 可选, 默认为 auto) — 如果为 True，则在适配器权重之外保存嵌入层。如果为 auto，则在配置的 target_modules 可用时，检查其中常见的嵌入层 peft.utils.other.EMBEDDING_LAYER_NAMES。并根据此检查结果设置布尔标志。这仅适用于 🤗 transformers 模型。

获取 Peft 模型的 state dict。

peft.prepare_model_for_kbit_training

< >

( model use_gradient_checkpointing = True gradient_checkpointing_kwargs = None )

参数

  • model (transformers.PreTrainedModel) — 从 transformers 加载的模型
  • use_gradient_checkpointing (bool, 可选, 默认为 True) — 如果为 True，使用梯度检查点以节省内存，但代价是反向传播速度变慢。
  • gradient_checkpointing_kwargs (dict, 可选, 默认为 None) — 传递给梯度检查点函数的关键字参数，请参阅 torch.utils.checkpoint.checkpoint 的文档以获取有关可以传递给该方法的参数的更多详细信息。请注意，这仅在最新的 transformers 版本（> 4.34.1）中可用。

请注意，此方法仅适用于 transformers 模型。

该方法封装了在运行训练前准备模型的整个流程。这包括： 1- 将 layernorm 转换为 fp32 2- 使输出嵌入层需要梯度（require grads） 3- 添加将 lm_head 上转换为 fp32 的操作 4- 冻结基础模型层以确保它们在训练期间不被更新

peft.get_layer_status

< >

( model: torch.nn.Module ) → listpeft.peft_model.TunerLayerStatus

参数

  • model ([Union[~PeftModel, ~transformers.PreTrainedModel, nn.Module]]) — 需要获取适配器层状态的模型。

返回

列表peft.peft_model.TunerLayerStatus

一个数据类列表，每个数据类包含相应适配器层的状态。

获取模型中每个适配器层的状态。

此函数返回一个 TunerLayerStatus 数据类实例的列表，每个实例包含以下属性

  • name (str)：适配器层的名称，例如 model.encoder.block.0.layer.0.SelfAttention.q。
  • module_type (str)：适配器层的类型，例如 lora.Linear。
  • enabled (bool)：适配器层是否已启用。
  • active_adapters (list[str])：活动适配器的名称（如果有），例如 ["default"]。
  • merged_adapters (list[str])：已合并的适配器的名称（如果有），例如 ["default"]。
  • requires_grad : dict[str, bool | Literal[“irregular”]] 每个适配器模块参数的 requires_grad 状态。理想情况下，它应该是 True 或 False。如果所有参数的 requires_grad 状态不一致，该值将被设置为 "irregular"。
  • available_adapters (list[str])：可用适配器的名称，例如 ["default"]。
  • devices (dict[str, list[str]]): 存储给定适配器参数的设备，例如 ["cuda"]。

peft.get_model_status

< >

( model: torch.nn.Module ) → peft.peft_model.TunerModelStatus

参数

  • model ([Union[~PeftModel, ~transformers.PreTrainedModel, nn.Module]]) — 需要获取适配器层状态的模型。

返回

peft.peft_model.TunerModelStatus

包含模型状态的数据类。

获取模型中微调器的状态。

此函数返回一个 TunerModelStatus 数据类实例，其中包含以下属性

  • base_model_type (str)：基础模型的类型，例如 T5Model。
  • adapter_model_type (str)：适配器模型的类型，例如 LoraModel。
  • peft_types (dict[str, str])：适配器名称到适配器类型的映射，例如 {"default": "LORA"}。
  • trainable_params (int)：模型中可训练参数的数量。
  • total_params (int)：模型中的总参数数量。
  • num_adapter_layers (int)：模型中适配器层的数量。
  • enabled (bool, Literal["irregular"])：是否所有适配器层都已启用。如果有些启用而有些未启用，此值将为 "irregular"。这意味着您的模型处于不一致的状态，可能无法按预期工作。
  • active_adapters (list[str], Literal["irregular"])：活动适配器的名称。如果活动适配器在所有层中不一致，此值将为 "irregular"，这意味着您的模型处于不一致的状态，可能无法按预期工作。
  • merged_adapters (list[str], Literal["irregular"])：已合并的适配器的名称。如果已合并的适配器在所有层中不一致，此值将为 "irregular"，这意味着您的模型处于不一致的状态，可能无法按预期工作。
  • requires_grad (dict[str, bool | Literal["irregular"]]): 对于给定的适配器，其所有适配器层是否都将 requires_grad 设置为 True 或 False。如果存在混合情况，此值将被设置为 "irregular"，这意味着您的模型处于不一致的状态，可能无法按预期工作。
  • available_adapters (list[str])：可用适配器的名称，例如 ["default"]。
  • devices (dict[str, list[str]]): 存储给定适配器参数的设备，例如 ["cuda"]。
< > 在 GitHub 上更新

←AutoPeftModel PEFT 类型→