PEFT documentation
模型
模型
PeftModel 是用于指定要应用 PEFT 方法的基础 Transformer 模型及其配置的基础模型类。基础的 PeftModel 包含从 Hub 加载和保存模型的方法。
PeftModel
类 peft.PeftModel
< source >( model: torch.nn.Modulepeft_config: PeftConfigadapter_name: str = 'default'autocast_adapter_dtype: bool = Truelow_cpu_mem_usage: bool = False )
参数
- model (
torch.nn.Module) — 要适配的基础模型,通常是 Transformers 模型。 - peft_config (PeftConfig) — Peft 模型的配置。
- adapter_name (
str, 可选) — 适配器的名称,默认为"default"。 - autocast_adapter_dtype (
bool,可选,默认为True) — 是否自动转换适配器(adapter)的数据类型。默认为True。目前,此操作仅将使用 float16 和 bfloat16 的适配器权重转换为 float32,因为稳定训练通常需要这样做,并且仅影响部分 PEFT 调优器。如果设置为False,数据类型将与对应层的数据类型保持一致。 - low_cpu_mem_usage (
bool,optional, 默认为False) — 在 meta 设备上创建空的适配器权重。有助于加快加载过程。> 在创建用于训练的新 PEFT 适配器时,请勿使用
low_cpu_mem_usage=True。
涵盖各种 Peft 方法的基础模型。
属性:
- base_model (
torch.nn.Module) — 用于 Peft 的基础 Transformer 模型。 - peft_config (PeftConfig) — Peft 模型的配置。
- modules_to_save (
listofstr) — 保存模型时需要保存的子模块名称列表。 - prompt_encoder (PromptEncoder) — 如果使用 PromptLearningConfig,则为 Peft 使用的提示编码器。
- prompt_tokens (
torch.Tensor) — 如果使用 PromptLearningConfig,则为 Peft 使用的虚拟提示词 token。 - transformer_backbone_name (
str) — 如果使用 PromptLearningConfig,则为基模型中 transformer 主干的名称。 - word_embeddings (
torch.nn.Embedding) — 如果使用 PromptLearningConfig,则为基座模型中 Transformer 主干的词嵌入
add_adapter
< source >( adapter_name: strpeft_config: PeftConfiglow_cpu_mem_usage: bool = Falseautocast_adapter_dtype: bool = True )
参数
- adapter_name (
str) — 要添加的适配器的名称。 - peft_config (PeftConfig) — 要添加的适配器的配置。
- low_cpu_mem_usage (
bool,optional, defaults toFalse) — 在 meta 设备上创建空的适配器权重。在加载已保存的适配器时,此选项有助于加快处理速度。在为训练创建新的 PEFT 适配器时,请勿使用此选项。 - autocast_adapter_dtype (
bool,可选,默认为True) — 是否自动转换适配器(adapter)的数据类型。默认为True。目前,此操作仅将使用 float16 和 bfloat16 的适配器权重转换为 float32,因为稳定训练通常需要这样做,并且仅影响部分 PEFT 调优器。如果设置为False,数据类型将与对应层的数据类型保持一致。
根据传入的配置,为模型添加一个适配器。
此适配器未经过训练。若要加载已训练的适配器,请参阅 PeftModel.load_adapter()。
新适配器的名称应该是唯一的。
新适配器不会自动设置为活动适配器。请使用 PeftModel.set_adapter() 来设置活动适配器。
更新或创建模型卡片,以包含有关 peft 的信息:
- 添加
peft库标签 - 添加 peft 版本
- 添加基础模型信息
- 如果使用了量化,则添加量化信息
删除现有的适配器。
用于禁用适配器模块的上下文管理器。使用它可以在基础模型上运行推理。
模型的前向传播。
from_pretrained
< source >( model: torch.nn.Modulemodel_id: Union[str, os.PathLike]adapter_name: str = 'default'is_trainable: bool = Falseconfig: Optional[PeftConfig] = Noneautocast_adapter_dtype: bool = Trueephemeral_gpu_offload: bool = Falselow_cpu_mem_usage: bool = Falsekey_mapping: Optional[dict[str, str]] = Nonestrict_adapter_check: Literal['warn', 'error', 'ignore'] = 'warn'**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/)。
- 一个字符串,即托管在 Hugging Face Hub 模型仓库中的 PEFT 配置的
- adapter_name (
str, 可选, 默认为"default") — 要加载的适配器名称。这在加载多个适配器时非常有用。 - is_trainable (
bool,可选,默认为False) — 适配器是否可训练。如果为False,适配器将被冻结,仅可用于推理。 - config (PeftConfig, 可选) —
用于替代自动加载配置的配置文件对象。此配置对象与
model_id和kwargs互斥。在调用from_pretrained之前已加载配置时,此参数非常有用。 - autocast_adapter_dtype (
bool,可选,默认为True) — 是否自动转换适配器(adapter)的数据类型。默认为True。目前,此操作仅将使用 float16 和 bfloat16 的适配器权重转换为 float32,因为稳定训练通常需要这样做,并且仅影响部分 PEFT 调优器。如果设置为False,数据类型将与对应层的数据类型保持一致。 - ephemeral_gpu_offload (
bool, 可选) — 是否对部分加载的模块使用临时 GPU 卸载。默认为False。当模型的部分和/或组件(例如适配器)在需要之前保留在 CPU 内存中时,此功能非常有用。与其在小数据上执行昂贵的操作,不如将数据按需传输到 GPU,执行操作,然后将结果移回 CPU 内存。这会带来轻微的瞬时 VRAM 开销,但在某些情况下可提供数量级的加速。 - low_cpu_mem_usage (
bool,optional, defaults toFalse) — 在加载已保存的权重之前,先在 meta 设备上创建空的适配器权重。有助于加快该过程。 - key_mapping (dict, 可选,默认为 None) —
在加载
state_dict之前应用的 PEFTstate_dict键的额外映射。应用此映射时,会先移除 PEFT 特有的"base_model.model"前缀,且尚未插入适配器名称(例如"default")。仅当您清楚自己在做什么时,才传入此参数。 - strict_adapter_check (
Literal["warn", "error", "ignore"],可选,默认为"warn") — 在考虑了因结构性原因(如共享参数、提示编码器路径等)而预期存在差异的键之后,如果检查点中存在模型缺失或意外的适配器键,应如何处理。"warn"会发出警告,"error"会引发RuntimeError,而"ignore"则不做任何操作。这与torch.nn.Module.load_state_dict的strict检查不同:PEFT 适配器始终与冻结的基础模型共存,因此此检查仅涉及适配器特定的键,绝不涉及基础模型自身的参数。 - kwargs — (
optional): 传递给特定 PEFT 配置类的额外关键字参数。其中包括torch_device(str,可选):加载适配器所使用的设备(转发至load_adapter[PeftModel.load_adapter]);如果为None,则会自动推断设备。
从预训练模型和已加载的 PEFT 权重实例化一个 PEFT 模型。
请注意,传入的 model 可能会被就地修改。
返回基础模型。
get_layer_status
< source >( ) → listpeft.peft_model.TunerLayerStatus
返回值
listpeft.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"]。quantization_backend(str或None): 量化后端的名称,例如"bnb 4bit",如果未进行量化则为None。
get_model_status
< source >( ) → peft.peft_model.TunerModelStatus
返回值
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"]。quantization_backend(str,None,Literal["irregular"]): 量化后端的名称,例如"bnb 4bit",如果未进行量化则为None。如果后端在所有层之间不一致,则此值为"irregular"。
返回模型中可训练参数的数量和所有参数的数量。
get_prompt
< source >( batch_size: inttask_ids: Optional[torch.Tensor] = Nonemax_cache_len: Optional[int] = None )
返回用于 Peft 的虚拟提示。仅在使用提示学习方法时适用。
在保存模型时返回要保存的提示嵌入。仅在使用提示学习方法时适用。
健康检查
< source >( min_trainable_params: int = 1max_trainable_params_percent = 50 )
在训练之前,检查该模型中是否存在可疑的适配器状态。
此函数汇总了模型和层状态 API,并包含关于适配器状态不一致、已合并的适配器以及可训练参数数量不合理的发现。它不会验证训练循环、优化器或数据集。如果在模型中发现不一致,例如对于同一个适配器,某些层被启用而某些层被禁用,则状态将报告为 "irregular"。这几乎总是意味着出了问题,你应该检查是否不小心错误地更改了模型上的某些属性。
对于提示学习和自适应提示,报告包含模型信息和参数量,但不包含这些方法不支持的特定层状态。
如果检查发现可疑内容,将在 "findings" 字段中报告。空的 "findings"" 列表表示未检测到可疑的适配器状态,并不意味着训练运行一定会成功。
load_adapter
< source >( model_id: Union[str, os.PathLike]adapter_name: stris_trainable: bool = Falsetorch_device: Optional[str] = Noneautocast_adapter_dtype: bool = Trueephemeral_gpu_offload: bool = Falselow_cpu_mem_usage: bool = Falsekey_mapping: Optional[dict[str, str]] = Nonestrict_adapter_check: Literal['warn', 'error', 'ignore'] = 'warn'**kwargs: Any )
参数
- model_id (
str或os.PathLike) — 要使用的 PEFT 配置的名称。可以是以下之一:- 一个字符串,即托管在 Hugging Face Hub 模型仓库中的 PEFT 配置的
model id。 - 指向包含使用
save_pretrained方法保存的 PEFT 配置文件的目录的路径(./my_peft_config_directory/)。
- 一个字符串,即托管在 Hugging Face Hub 模型仓库中的 PEFT 配置的
- adapter_name (
str) — 要添加的适配器的名称。 - is_trainable (
bool,可选,默认为False) — 适配器是否可训练。如果为False,适配器将被冻结,仅可用于推理。 - torch_device (
str,可选,默认为 None) — 用于加载适配器的设备。如果为None,则会自动推断设备。 - autocast_adapter_dtype (
bool,可选,默认为True) — 是否自动转换适配器(adapter)的数据类型。默认为True。目前,此操作仅将使用 float16 和 bfloat16 的适配器权重转换为 float32,因为稳定训练通常需要这样做,并且仅影响部分 PEFT 调优器。如果设置为False,数据类型将与对应层的数据类型保持一致。 - ephemeral_gpu_offload (
bool,可选,默认为False) — 是否对部分加载的模块使用临时 GPU 卸载。默认为False。 - low_cpu_mem_usage (
bool,optional, defaults toFalse) — 在加载已保存的权重之前,先在 meta 设备上创建空的适配器权重。有助于加快该过程。 - key_mapping (dict, 可选,默认为 None) —
在加载
state_dict之前应用的 PEFTstate_dict键的额外映射。应用此映射时,会先移除 PEFT 特有的"base_model.model"前缀,且尚未插入适配器名称(例如"default")。仅当您清楚自己在做什么时,才传入此参数。 - strict_adapter_check (
Literal["warn", "error", "ignore"],可选,默认为"warn") — 在考虑了因结构性原因(如共享参数、提示编码器路径等)而预期存在差异的键之后,如果检查点中存在模型缺失或意外的适配器键,应如何处理。"warn"会发出警告,"error"会引发RuntimeError,而"ignore"则不做任何操作。这与torch.nn.Module.load_state_dict的strict检查不同:PEFT 适配器始终与冻结的基础模型共存,因此此检查仅涉及适配器特定的键,绝不涉及基础模型自身的参数。 - kwargs — (
optional): 用于修改适配器加载方式的额外参数,例如 Hugging Face Hub 的 token。
将训练好的适配器加载到模型中。
新适配器的名称应该是唯一的。
新适配器不会自动设置为活动适配器。请使用 PeftModel.set_adapter() 来设置活动适配器。
merge_adapter
< source >( adapter_names: Optional[list[str]] = Nonesafe_merge: bool = False**kwargs: Any )
将活动适配器合并到基础模型中。
大多数向基础模型添加权重的 PEFT 方法(例如 LoRA、IA³ 或 OFT)都支持合并。对于提示学习方法(例如 prompt tuning)和 adaption prompt,不支持合并,并会引发 TypeError。
注意:即使通常支持合并的 PEFT 方法,在某些模型或层配置下也可能引发错误,例如对 gptq 量化模型抛出 ValueError,对 _ConvNd 层且 groups > 1 的 LoRA 抛出 NotImplementedError,或对 Eetq 层的 LoRA 抛出 AttributeError。
如有必要,为模型准备梯度检查点
注意:在较新的 Transformers 版本中,这被称为“activation checkpointing”。
print_healthcheck
< source >( sink = <built-in function print>min_trainable_params: int = 1max_trainable_params_percent = 50**kwargs )
打印一份紧凑且易于阅读的体检报告。
输出会总结您的 PEFT 模型的状态,并报告适配器状态不一致、已合并的适配器以及可训练参数数量异常等发现。它不会验证训练循环、优化器或数据集。如果在模型中发现不一致之处,例如对于同一个适配器,某些层被启用而某些层被禁用,则状态将报告为 "irregular"。这几乎总是意味着出现了问题,您应该检查是否不小心错误地更改了模型上的某些属性。
如果检测到问题,它们将显示在最后一部分的“findings”下。如果未检测到问题, 并不意味着训练运行一定会成功。
打印模型中可训练参数的数量。
注意:print_trainable_parameters() 使用了 get_nb_trainable_parameters(),它与 huggingface/transformers 中的 num_parameters(only_trainable=True) 不同。get_nb_trainable_parameters() 返回 Peft 模型的(可训练参数,所有参数),其中包括经过修改的骨干 Transformer 模型。对于 LoRA 等技术,骨干 Transformer 模型会被就地修改以添加 LoRA 模块。然而,对于 prompt tuning,骨干 Transformer 模型保持不变。num_parameters(only_trainable=True) 返回骨干 Transformer 模型的可训练参数数量,该数量可能有所不同。
save_pretrained
< source >( save_directory: strsafe_serialization: bool = Trueselected_adapters: Optional[list[str]] = Nonesave_embedding_layers: Union[str, bool] = 'auto'is_main_process: bool = Truepath_initial_model_for_weight_conversion: Optional[str] = None**kwargs: Any )
参数
- save_directory (
str) — 用于保存适配器模型和配置文件的目录(如果该目录不存在,则会自动创建)。 - safe_serialization (
bool, 可选) — 是否以 safetensors 格式保存适配器文件,默认为True。 - selected_adapters (
List[str], 可选) — 要保存的适配器列表。如果为None,则默认为所有适配器。 - save_embedding_layers (
Union[bool, str],可选,默认为"auto") — 如果为True,则在保存适配器权重的同时保存嵌入层。如果为auto,则在可用时检查配置中的target_modules是否包含常见的嵌入层peft.utils.other.EMBEDDING_LAYER_NAMES,并自动设置布尔标志。此功能仅适用于 🤗 transformers 模型。 - is_main_process (
bool, 可选) — 调用此方法的进程是否为主进程。默认值为True。如果不在主进程上,则不会保存检查点,这对于多设备设置(例如 DDP)非常重要。 - path_initial_model_for_weight_conversion (
str, 可选) — 初始化适配器的路径,该路径是在使用 PiSSA/CorDA/OLoRA 初始化模型之后、执行任何训练之前获得的。当path_initial_model_for_weight_conversion不为 None 时,将计算微调前后适配器的差异。该差异可以表示为标准 LoRA 适配器的参数。与 PiSSA 及其类似方法不同,使用此转换后的适配器无需对基础模型进行更改,因此可以方便地将多个 PiSSA/CorDA/OLoRA 适配器与 LoRA 适配器一起使用,并激活或停用任意适配器。请注意,如果在rslora与rank_pattern或alpha_pattern组合使用时,不支持此转换。有关更多信息,请参阅 peft.tuners.lora.LoraModel.subtract_mutated_init()。 - kwargs(额外的关键字参数,可选)—
传递给
push_to_hub方法的额外关键字参数。
此函数将适配器模型和适配器配置文件保存到目录中,以便使用 PeftModel.from_pretrained() 类方法重新加载,并供 PeftModel.push_to_hub() 方法使用。
如果所选的适配器权重包含分布式张量(例如 FSDP2/HSDP),则所有参与的 rank 都必须调用此方法,因为收集权重是一个集合操作。仅在写入检查点的 rank 上设置 is_main_process=True。仅在单个 rank 上调用此方法可能会导致进程组超时。
set_adapter
< source >( adapter_name: strinference_mode: bool = False )
设置活动适配器。
由于并非所有 PEFT 方法都支持多个激活的适配器,因此同一时间只能有一个适配器处于激活状态。要为支持的方法激活多个适配器,请使用 model.base_model.set_adapter(adapter_names)。
此外,除非 inference_mode 为 True,否则该函数会将指定的适配器设置为可训练(即 requires_grad=True)。
set_requires_grad
< source >( adapter_names: str | Sequence[str]requires_grad: bool = True )
在指定的适配器上启用或禁用梯度。
注意:不支持提示学习(prompt learning)方法,例如提示微调(prompt tuning)。
该模型的适配器是否可以转换为 LoRA。
通常,如果 PEFT 方法是加法的,即 W’ = W_base + delta_weight,那么这种方式是可行的。
unmerge_adapter
< source >( force_reshard: bool = False**kwargs: Any )
将适配器从基础模型中分离。
大多数向基础模型添加权重的 PEFT 方法(例如 LoRA、IA³ 或 OFT)都支持取消合并。对于提示学习方法(例如 prompt tuning)和 adaption prompt,不支持取消合并,并会引发 TypeError。
注意:即使通常支持取消合并的 PEFT 方法,也可能针对某些层类型引发错误,例如对 Eetq 层上的 LoRA 会引发 AttributeError,或从 INC 层中取消合并 LoRA 时会引发 NotImplementedError。
PeftModelForSequenceClassification
用于序列分类任务的 PeftModel。
类 peft.PeftModelForSequenceClassification
< source >( model: torch.nn.Modulepeft_config: PeftConfigadapter_name: str = 'default'**kwargs )
参数
- model (PreTrainedModel) — 基础 Transformer 模型。
- peft_config (PeftConfig) — Peft 配置。
- adapter_name (
str, 可选) — 适配器的名称,默认为"default"。 - autocast_adapter_dtype (
bool,可选,默认为True) — 是否自动转换适配器(adapter)的数据类型。默认为True。目前,此操作仅将使用 float16 和 bfloat16 的适配器权重转换为 float32,因为稳定训练通常需要这样做,并且仅影响部分 PEFT 调优器。如果设置为False,数据类型将与对应层的数据类型保持一致。
用于序列分类任务的 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,
... }
>>> 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.3406113979101117PeftModelForTokenClassification
用于 token 分类任务的 PeftModel。
类 peft.PeftModelForTokenClassification
< source >( model: torch.nn.Modulepeft_config: PeftConfig = Noneadapter_name: str = 'default'**kwargs )
参数
- model (PreTrainedModel) — 基础 Transformer 模型。
- peft_config (PeftConfig) — Peft 配置。
- adapter_name (
str, 可选) — 适配器的名称,默认为"default"。 - autocast_adapter_dtype (
bool,可选,默认为True) — 是否自动转换适配器(adapter)的数据类型。默认为True。目前,此操作仅将使用 float16 和 bfloat16 的适配器权重转换为 float32,因为稳定训练通常需要这样做,并且仅影响部分 PEFT 调优器。如果设置为False,数据类型将与对应层的数据类型保持一致。
用于 token 分类任务的 Peft 模型。
属性:
- config (
PretrainedConfig) — 基础模型的配置对象。 - cls_layer_name (
str) — 分类层的名称。
示例:
>>> from transformers import AutoModelForTokenClassification
>>> 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,
... }
>>> 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.3406113979101117add_adapter
< source >( adapter_name: strpeft_config: PeftConfiglow_cpu_mem_usage: bool = Falseautocast_adapter_dtype: bool = True )
参数
- adapter_name (
str) — 要添加的适配器的名称。 - peft_config (PeftConfig) — 要添加的适配器的配置。
- low_cpu_mem_usage (
bool,optional, defaults toFalse) — 在 meta 设备上创建空的适配器权重。在加载已保存的适配器时,此选项有助于加快处理速度。在为训练创建新的 PEFT 适配器时,请勿使用此选项。 - autocast_adapter_dtype (
bool,可选,默认为True) — 是否自动转换适配器(adapter)的数据类型。默认为True。目前,此操作仅将使用 float16 和 bfloat16 的适配器权重转换为 float32,因为稳定训练通常需要这样做,并且仅影响部分 PEFT 调优器。如果设置为False,数据类型将与对应层的数据类型保持一致。
根据传入的配置,为模型添加一个适配器。
此适配器未经过训练。若要加载已训练的适配器,请参阅 PeftModel.load_adapter()。
新适配器的名称应该是唯一的。
新适配器不会自动设置为活动适配器。请使用 PeftModel.set_adapter() 来设置活动适配器。
PeftModelForCausalLM
用于因果语言建模的 PeftModel。
类 peft.PeftModelForCausalLM
< source >( model: torch.nn.Modulepeft_config: PeftConfigadapter_name: str = 'default'**kwargs )
参数
- model (PreTrainedModel) — 基础 Transformer 模型。
- peft_config (PeftConfig) — Peft 配置。
- adapter_name (
str, 可选) — 适配器的名称,默认为"default"。 - autocast_adapter_dtype (
bool,可选,默认为True) — 是否自动转换适配器(adapter)的数据类型。默认为True。目前,此操作仅将使用 float16 和 bfloat16 的适配器权重转换为 float32,因为稳定训练通常需要这样做,并且仅影响部分 PEFT 调优器。如果设置为False,数据类型将与对应层的数据类型保持一致。
用于因果语言建模的 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,
... }
>>> 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.23756456724479544PeftModelForSeq2SeqLM
用于序列到序列语言建模的 PeftModel。
注意:如果您提供了输入 token 但未显式提供解码器输入 token,则此操作会通过 shift_tokens_right() 将输入 token 向右移动一步,从而自动生成解码器输入 token。
类 peft.PeftModelForSeq2SeqLM
< source >( model: torch.nn.Modulepeft_config: PeftConfigadapter_name: str = 'default'**kwargs )
参数
- model (PreTrainedModel) — 基础 Transformer 模型。
- peft_config (PeftConfig) — Peft 配置。
- adapter_name (
str, 可选) — 适配器的名称,默认为"default"。 - autocast_adapter_dtype (
bool,可选,默认为True) — 是否自动转换适配器(adapter)的数据类型。默认为True。目前,此操作仅将使用 float16 和 bfloat16 的适配器权重转换为 float32,因为稳定训练通常需要这样做,并且仅影响部分 PEFT 调优器。如果设置为False,数据类型将与对应层的数据类型保持一致。
用于序列到序列语言建模的 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,
... "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.3952474242013566PeftModelForQuestionAnswering
用于问答的 PeftModel。
类 peft.PeftModelForQuestionAnswering
< source >( model: torch.nn.Modulepeft_config: PeftConfigadapter_name: str = 'default'**kwargs )
参数
- model (PreTrainedModel) — 基础 Transformer 模型。
- peft_config (PeftConfig) — Peft 配置。
- adapter_name (
str, 可选) — 适配器的名称,默认为"default"。 - autocast_adapter_dtype (
bool,可选,默认为True) — 是否自动转换适配器(adapter)的数据类型。默认为True。目前,此操作仅将使用 float16 和 bfloat16 的适配器权重转换为 float32,因为稳定训练通常需要这样做,并且仅影响部分 PEFT 调优器。如果设置为False,数据类型将与对应层的数据类型保持一致。
用于抽取式问答的 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.5473971721475013add_adapter
< source >( adapter_name: strpeft_config: PeftConfiglow_cpu_mem_usage: bool = Falseautocast_adapter_dtype: bool = True )
参数
- adapter_name (
str) — 要添加的适配器的名称。 - peft_config (PeftConfig) — 要添加的适配器的配置。
- low_cpu_mem_usage (
bool,optional, defaults toFalse) — 在 meta 设备上创建空的适配器权重。在加载已保存的适配器时,此选项有助于加快处理速度。在为训练创建新的 PEFT 适配器时,请勿使用此选项。 - autocast_adapter_dtype (
bool,可选,默认为True) — 是否自动转换适配器(adapter)的数据类型。默认为True。目前,此操作仅将使用 float16 和 bfloat16 的适配器权重转换为 float32,因为稳定训练通常需要这样做,并且仅影响部分 PEFT 调优器。如果设置为False,数据类型将与对应层的数据类型保持一致。
根据传入的配置,为模型添加一个适配器。
此适配器未经过训练。若要加载已训练的适配器,请参阅 PeftModel.load_adapter()。
新适配器的名称应该是唯一的。
新适配器不会自动设置为活动适配器。请使用 PeftModel.set_adapter() 来设置活动适配器。
PeftModelForFeatureExtraction
用于从 Transformer 模型中提取特征/嵌入的 PeftModel。
类 peft.PeftModelForFeatureExtraction
< source >( model: torch.nn.Modulepeft_config: PeftConfigadapter_name: str = 'default'**kwargs )
参数
- model (PreTrainedModel) — 基础 Transformer 模型。
- peft_config (PeftConfig) — Peft 配置。
- adapter_name (
str, 可选) — 适配器的名称,默认为"default"。 - autocast_adapter_dtype (
bool,可选,默认为True) — 是否自动转换适配器(adapter)的数据类型。默认为True。目前,此操作仅将使用 float16 和 bfloat16 的适配器权重转换为 float32,因为稳定训练通常需要这样做,并且仅影响部分 PEFT 调优器。如果设置为False,数据类型将与对应层的数据类型保持一致。
用于从 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。
类 peft.PeftMixedModel
< source >( model: nn.Modulepeft_config: PeftConfigadapter_name: str = 'default' )
用于加载不同类型的适配器以进行推理的 PeftMixedModel。
此类不支持加载/保存,通常也不应直接初始化。请改用 get_peft_model 并设置参数 mixed=True。
> 阅读 混合适配器类型 指南,以了解有关使用不同适配器类型的更多信息。
示例:
>>> 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 adaptersadd_adapter
< source >( adapter_name: strpeft_config: PeftConfiglow_cpu_mem_usage: bool = Falseautocast_adapter_dtype: bool = True )
参数
- adapter_name (
str) — 要添加的适配器的名称。 - peft_config (PeftConfig) — 要添加的适配器的配置。
- low_cpu_mem_usage (
bool,optional, 默认为False) — 在 meta 设备上创建空的适配器权重。在加载已保存的适配器时,此选项有助于加快处理速度。> 在创建用于训练的新 PEFT 适配器时,请勿使用
low_cpu_mem_usage=True(对于 PeftMixedModel,训练功能未经测试 > 且通常不推荐使用)。 - autocast_adapter_dtype (
bool,可选,默认为True) — 是否自动转换适配器(adapter)的数据类型。默认为True。目前,此操作仅将使用 float16 和 bfloat16 的适配器权重转换为 float32,因为稳定训练通常需要这样做,并且仅影响部分 PEFT 调优器。如果设置为False,数据类型将与对应层的数据类型保持一致。
根据传入的配置,为模型添加一个适配器。
此适配器未经过训练。若要加载已训练的适配器,请参阅 PeftModel.load_adapter()。
新适配器的名称应该是唯一的。
新适配器不会自动设置为活动适配器。请使用 PeftModel.set_adapter() 来设置活动适配器。
禁用适配器模块。
模型的前向传播。
from_pretrained
< source >( model: nn.Modulemodel_id: str | os.PathLikeadapter_name: str = 'default'is_trainable: bool = Falseconfig: Optional[PeftConfig] = None**kwargs: Any )
参数
- model (
nn.Module) — 要适配的模型。 - model_id (
str或os.PathLike) — 要使用的 PEFT 配置的名称。可以是以下之一:- 一个字符串,即托管在 Hugging Face Hub 模型仓库中的 PEFT 配置的
model id。 - 指向包含使用
save_pretrained方法保存的 PEFT 配置文件的目录的路径(./my_peft_config_directory/)。
- 一个字符串,即托管在 Hugging Face Hub 模型仓库中的 PEFT 配置的
- adapter_name (
str, 可选, 默认为"default") — 要加载的适配器名称。这在加载多个适配器时非常有用。 - is_trainable (
bool,可选,默认为False) — 适配器是否可训练。如果为False,适配器将被冻结并用于推理 - config (PeftConfig, 可选) —
用于替代自动加载配置的配置文件对象。此配置对象与
model_id和kwargs互斥。在调用from_pretrained之前已加载配置时,此参数非常有用。 - low_cpu_mem_usage (
bool,optional, defaults toFalse) — 在加载已保存的权重之前,先在 meta 设备上创建空的适配器权重。有助于加快该过程。 - kwargs — (
optional): 传递给特定 PEFT 配置类的其他关键字参数。
从预训练模型和已加载的 PEFT 权重实例化一个 PEFT 混合模型。
请注意,传入的 model 可能会被就地修改。
生成输出。
返回模型中可训练参数的数量和所有参数的数量。
load_adapter
< source >( model_id: stradapter_name: str*args: Any**kwargs: Any )
参数
- adapter_name (
str) — 要添加的适配器的名称。 - peft_config (PeftConfig) — 要添加的适配器的配置。
- is_trainable (
bool,可选,默认为False) — 适配器是否可训练。如果为False,适配器将被冻结,仅可用于推理。 - torch_device (
str,可选,默认为 None) — 用于加载适配器的设备。如果为None,则会自动推断设备。 - autocast_adapter_dtype (
bool,可选,默认为True) — 是否自动转换适配器(adapter)的数据类型。默认为True。目前,此操作仅将使用 float16 和 bfloat16 的适配器权重转换为 float32,因为稳定训练通常需要这样做,并且仅影响部分 PEFT 调优器。 - ephemeral_gpu_offload (
bool,可选,默认为False) — 是否对部分加载的模块使用临时 GPU 卸载。默认为False。 - low_cpu_mem_usage (
bool,optional, defaults toFalse) — 在加载已保存的权重之前,先在 meta 设备上创建空的适配器权重。有助于加快该过程。 - kwargs — (
optional): 用于修改适配器加载方式的额外参数,例如 Hugging Face Hub 的 token。
将训练好的适配器加载到模型中。
新适配器的名称应该是唯一的。
新适配器不会自动设置为活动适配器。请使用 PeftModel.set_adapter() 来设置活动适配器。
merge_and_unload
< source >( *args: Any**kwargs: Any )
此方法将适配器层合并到基础模型中。如果希望将基础模型作为独立模型使用,则需要执行此操作。
打印模型中可训练参数的数量。
注意:print_trainable_parameters() 使用了 get_nb_trainable_parameters(),它与 huggingface/transformers 中的 num_parameters(only_trainable=True) 不同。get_nb_trainable_parameters() 返回 Peft 模型的(可训练参数,所有参数),其中包括经过修改的骨干 Transformer 模型。对于 LoRA 等技术,骨干 Transformer 模型会被就地修改以添加 LoRA 模块。然而,对于 prompt tuning,骨干 Transformer 模型保持不变。num_parameters(only_trainable=True) 返回骨干 Transformer 模型的可训练参数数量,该数量可能有所不同。
set_adapter
< source >( adapter_name: Union[str, list[str]]inference_mode: bool = False )
设置模型的当前激活适配器。
请注意,在前向传播过程中应用适配器的顺序可能与将它们传递给此函数的顺序不同。相反,前向传播过程中的顺序由适配器加载到模型中的顺序决定。活动适配器仅决定哪些适配器在前向传播过程中处于活动状态,但不决定它们的应用顺序。
此外,除非 inference_mode 为 True,否则该函数会将指定的适配器设置为可训练(即 requires_grad=True)。
通过移除所有适配器模块(而不进行合并)来恢复基础模型。这将返回原始的基础模型。
实用工具
peft.cast_mixed_precision_params
< source >( model: torch.nn.Moduledtype: torch.dtype )
将模型中所有不可训练的参数转换为给定的 dtype。dtype 可以是 torch.float16 或 torch.bfloat16,具体取决于您正在执行的混合精度训练。可训练参数会被转换为全精度。此操作旨在通过使用半精度 dtype 来表示不可训练参数,从而在使用 PEFT 方法时降低 GPU 内存占用。将可训练参数保持为全精度,有助于在使用自动混合精度训练时维持训练稳定性。
torch.bfloat16,具体取决于您正在执行的混合精度训练。
peft.get_peft_model
< source >( model: nn.Modulepeft_config: PeftConfigadapter_name: str = 'default'mixed: bool = Falseautocast_adapter_dtype: bool = Truerevision: Optional[str] = Nonelow_cpu_mem_usage: bool = False )
参数
- model (
torch.nn.Module) — 要包装的模型。通常这是一个 Transformers 模型,但任何nn.Module都可以使用,需要注意的是,特定任务的功能(peft_config.task_type)要求模型遵循 Transformers 的约定。 - peft_config (PeftConfig) — 包含 Peft 模型参数的配置对象。
- adapter_name (
str,optional, 默认为"default") — 要注入的适配器名称。如果未提供,则使用默认适配器名称(“default”)。 - mixed (
bool,optional, defaults toFalse) — 是否允许混合使用不同的(兼容的)适配器类型。 - autocast_adapter_dtype (
bool, 可选) — 是否自动转换适配器数据类型。默认为True。目前,此操作仅将使用 float16 或 bfloat16 的适配器权重转换为 float32,因为稳定训练通常需要这样做,并且仅影响特定的 PEFT 调优器。 - revision (
str,optional, 默认为main) — 基础模型的版本。如果未设置此项,保存的 peft 模型将加载基础模型的main版本 - low_cpu_mem_usage (
bool,optional, defaults toFalse) — 在 meta 设备上创建空的适配器权重。有助于加快加载过程。如果您打算训练该模型,请保持此设置为 False,除非在训练开始前适配器权重将被不同的权重替换。
根据模型和配置返回一个 Peft 模型对象,其中模型将被就地修改。
peft.inject_adapter_in_model
< source >( peft_config: PeftConfigmodel: torch.nn.Moduleadapter_name: str = 'default'low_cpu_mem_usage: bool = Falsestate_dict: Optional[dict[str, torch.Tensor]] = None )
参数
- peft_config (
PeftConfig) — 包含 PEFT 模型参数的配置对象。 - model (
torch.nn.Module) — 将注入适配器的输入模型。 - adapter_name (
str,optional, 默认为"default") — 要注入的适配器名称。如果未提供,则使用默认适配器名称(“default”)。 - low_cpu_mem_usage (
bool,optional, defaults toFalse) — 在 meta 设备上创建空的适配器权重。有助于加快加载过程。 - state_dict (
dict,可选,默认为None) — 如果在此处传入state_dict,适配器将根据 state_dict 中的条目进行注入。 当 PEFT 方法的确切target_modules未知时,这可能会很有用,例如因为检查点在创建时未包含元数据。请注意,state_dict中的值不会被使用,仅使用键来确定应进行适配的正确层。
创建 PEFT 层并将其就地注入模型。
目前,该 API 不支持提示学习方法、自适应提示,或那些在多个目标层之间共享适配器状态的调优器。对于后者,请使用 get_peft_model()。
此函数与 get_peft_model() 类似,但它不会返回 PeftModel 实例。相反,它返回传入模型的原始、已修改的实例。
peft.get_peft_model_state_dict
< source >( modelstate_dict = Noneadapter_name: str = 'default'unwrap_compiled: bool = Falsesave_embedding_layers: bool | Literal['auto'] = 'auto' )
参数
- model (PeftModel) — Peft 模型。当使用 torch.nn.DistributedDataParallel、DeepSpeed 或 FSDP 时,模型应为底层模型/解包后的模型(即 model.module)。
- state_dict (
dict,可选,默认为None) — 模型的 state dict。如果未提供,将使用传入模型的 state dict。 - adapter_name (
str,可选,默认为"default") — 要返回其状态字典的适配器名称。 - 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 模型中指定适配器的状态字典。
这仅包含 PEFT 参数,不包括基础模型的参数。因此,返回的 state_dict 通常远小于完整模型的规模。要获取完整的 state_dict,只需调用 model.state_dict() 即可。
如果所选条目包含分布式张量(例如 FSDP2 或 DTensor TP),则所有参与进程都必须调用此函数:将这些条目收集为完整张量是一个集合通信操作。未选中的基础模型权重将保持分片状态。
请注意,适配器名称会从 state_dict 中移除,因为这只是一个任意名称,可以在加载适配器时更改。因此,例如,如果适配器名称为 'default',且原始键为 'model.q_proj.lora_A.default.weight',则返回的键将是 'model.q_proj.lora_A.weight'。在加载权重时,请结合使用此函数和 set_peft_model_state_dict() 来处理适配器名称。
peft.prepare_model_for_kbit_training
< source >( modeluse_gradient_checkpointing = Trueactivation_checkpointing_kwargs = Noneauto_clear_cache = Truegradient_checkpointing_kwargs = None )
参数
- model (
transformers.PreTrainedModel) — 从transformers加载的模型 - use_gradient_checkpointing (
bool,可选,默认为True) — 如果为 True,则使用梯度检查点以牺牲较慢的反向传播为代价来节省内存。 - activation_checkpointing_kwargs (
dict,可选,默认为None) — 传递给激活检查点函数的关键字参数,有关可以传递给该方法的参数的详细信息,请参阅torch.utils.checkpoint.checkpoint的文档。 请注意,此功能仅在 transformers 版本(> 4.34.1)中可用。 - auto_clear_cache (
bool,可选,默认为True) — 是否在上将参数上转换为 fp32 后清空加速器缓存。这会释放由缓存分配器持有的内存,对于共享主机和加速器内存的设备尤其有用。设置为False可跳过此步骤。 - gradient_checkpointing_kwargs (
dict,可选,默认为None) — 传递给激活检查点函数的关键字参数。此参数仅用于向后兼容,已弃用,请改用activation_checkpointing_kwargs。它将在 PEFT v1.2 中移除。
请注意,此方法仅适用于transformers模型。
此方法封装了运行训练前准备模型的完整协议。包括: 1- 将 layernorm 转换为 fp32 2- 使输出嵌入层需要梯度 3- 将 lm head 的上转换添加到 fp32 4- 冻结基础模型层,以确保它们在训练期间不被更新
peft.get_layer_status
< source >( model: torch.nn.Module ) → listpeft.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","xpu"]。quantization_backend(str或None): 量化后端的名称,例如"bnb 4bit",如果未进行量化则为None。
peft.get_model_status
< source >( model: torch.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","xpu"]。quantization_backend(str,None,Literal["irregular"]): 量化后端的名称,例如"bnb 4bit",如果未进行量化则为None。如果后端在所有层之间不一致,则此值为"irregular"。