PEFT AutoPeftModel 自动加载指南一行代码按任务类型加载 LoRA 等 PEFT 模型【免费下载链接】peft PEFT: State-of-the-art Parameter-Efficient Fine-Tuning.项目地址: https://gitcode.com/gh_mirrors/pe/peft本文基于 AutoPeftModel 官方 API 文档 展开并深入 src/peft/auto.py 源码与 tests/test_auto.py 测试系统性讲解 PEFT 库中AutoPeftModel系列类的设计原理、任务类型推断机制、安全导入白名单以及实际加载配置。读完本文你将掌握如何在不手动指定模型类、不手动加载PeftConfig的前提下用一行代码从 Hugging Face Hub 或本地目录加载经过 LoRA、IA3、Prompt Tuning 等参数高效微调PEFT方法训练好的模型并能根据报错信息快速定位任务类型或导入白名单问题。AutoPeftModel是 PEFT 库中面向开箱即用的自动模型加载入口。它解决的核心痛点是传统方式加载 PEFT 模型时需要先明确知道模型属于哪种任务类型因果语言建模、序列到序列、序列分类等再手动挑选对应的PeftModelForXxx子类同时还要自行处理PeftConfig的读取——这些步骤繁琐且容易出错。AutoPeftModel通过读取适配器配置文件中的task_type字段自动推断并实例化正确的 PEFT 模型类把整个加载流程压缩为一次from_pretrained调用。一、AutoPeftModel 类家族总览AutoPeftModel并非单个类而是一组围绕同一套推断逻辑的类族全部定义在 src/peft/auto.py 中并从 src/peft/init.py 顶层导出位于peft命名空间导入方式为from peft import AutoPeftModel等。它们共享同一个基类_BaseAutoPeftModel基类中实现了全部加载逻辑各子类只通过两个类属性声明该加载什么类名_target_class基础模型类_target_peft_classPEFT 包装类适用任务AutoPeftModel无依赖auto_mapping推断PeftModel通用任务如 Whisper 语音识别或未声明task_type的配置AutoPeftModelForCausalLMAutoModelForCausalLMPeftModelForCausalLM因果语言建模task_typeCAUSAL_LMAutoPeftModelForSeq2SeqLMAutoModelForSeq2SeqLMPeftModelForSeq2SeqLM序列到序列任务task_typeSEQ_2_SEQ_LMAutoPeftModelForSequenceClassificationAutoModelForSequenceClassificationPeftModelForSequenceClassification序列分类task_typeSEQ_CLSAutoPeftModelForTokenClassificationAutoModelForTokenClassificationPeftModelForTokenClassification词元分类/NERtask_typeTOKEN_CLSAutoPeftModelForQuestionAnsweringAutoModelForQuestionAnsweringPeftModelForQuestionAnswering问答任务task_typeQUESTION_ANSAutoPeftModelForFeatureExtractionAutoModelPeftModelForFeatureExtraction特征提取/句向量task_typeFEATURE_EXTRACTION对应关系由auto.py第 45–52 行的MODEL_TYPE_TO_PEFT_MODEL_MAPPING字典统一定义它把task_type字符串映射到具体的 PEFT 模型类MODEL_TYPE_TO_PEFT_MODEL_MAPPING: dict[str, type[PeftModel]] { SEQ_CLS: PeftModelForSequenceClassification, SEQ_2_SEQ_LM: PeftModelForSeq2SeqLM, CAUSAL_LM: PeftModelForCausalLM, TOKEN_CLS: PeftModelForTokenClassification, QUESTION_ANS: PeftModelForQuestionAnswering, FEATURE_EXTRACTION: PeftModelForFeatureExtraction, }原文档 auto_class.md 明确说明这些类的设计目标是单行代码快速加载 PEFT 模型无需关心具体需要哪个模型类也无需手动加载PeftConfig。二、基本用法一行代码加载 PEFT 模型2.1 有明确任务类型时使用AutoPeftModelForXxx对于在配置中写明了task_type的适配器直接使用与任务对应的子类即可。例如加载一个用 LoRA 微调过的因果语言模型完整示例可见 docs/source/quicktour.md 与 docs/source/package_reference/lora.mdfrom peft import AutoPeftModelForCausalLM # 从 Hub 加载自动读取 adapter_config.json推断任务类型并实例化正确的 PEFT 模型 model AutoPeftModelForCausalLM.from_pretrained(ybelkada/opt-350m-lora) # 本地路径同样支持例如由 PeftModel.save_pretrained 保存的目录 model AutoPeftModelForCausalLM.from_pretrained(./my_peft_model_dir/) # 直接推理 inputs tokenizer(Hello, my dog is, return_tensorspt) outputs model.generate(**inputs)2.2 无任务类型时使用基础AutoPeftModel如果模型的配置文件没有设置task_type例如 Whisper 语音识别、Stable Diffusion 等不在上表范围内的任务需要使用基础类AutoPeftModel。此时类本身不知道基础模型类加载逻辑会退化为读取配置中由save_pretrained自动写入的auto_mapping字段来还原基础模型类详见第四节from peft import AutoPeftModel model AutoPeftModel.from_pretrained(smangrul/openai-whisper-large-v2-LORA-colab)tests/test_auto.py中的test_peft_whisper用例正是验证了这一路径AutoPeftModel.from_pretrained加载 Whisper LoRA 模型后返回对象是PeftModel实例且dtype等参数正确传递到了model.base_model.model.model.encoder.embed_positions.weight。2.3 加载时传参适配器名、可训练标志、dtype 等from_pretrained支持与PeftModel.from_pretrained等价的位置参数与关键字参数差异点在下文标注常用调用方式model AutoPeftModelForCausalLM.from_pretrained( ybelkada/opt-350m-lora, # 模型 id 或本地目录 default, # adapter_name多适配器场景下指定要加载的适配器名 False, # is_trainableFalse 表示冻结适配器仅用于推理 dtypetorch.bfloat16, # 其余 kwargs 会一路透传给基础模型加载与 PeftConfig )tests/test_auto.py中的test_peft_causal_lm验证了这种位置参数 kwargs的调用方式并断言model.base_model.lm_head.weight.dtype与传入的dtype一致证明 kwargs 被正确透传到基础模型实例化过程。三、from_pretrained 关键参数详解AutoPeftModel.from_pretrained的完整签名在 src/peft/auto.py其 docstring 明确说明这是用户加载 PEFT 模型所需全部预处理步骤的封装kwargs 会传递给PeftConfig由其自动过滤 Hub 方法与配置对象初始化的参数。参数类型与默认值说明pretrained_model_name_or_pathstr/PathLike必填Hugging Face Hub 上的模型仓库 id或包含adapter_config.json与权重文件的本地目录adapter_namestr默认default要加载的适配器名称多适配器加载时用于区分is_trainablebool默认False是否让适配器可训练False时适配器冻结仅用于推理configOptional[PeftConfig]默认None手动传入已加载的配置对象替代自动读取配置文件与pretrained_model_name_or_path互斥使用revisionOptional[str]默认NoneHub 仓库的版本号/分支与PeftConfig.from_pretrained语义一致import_allowlistOptional[list[str]]默认取get_default_import_allowlist()允许被动态导入的库白名单用于实例化基础模型类安全机制详见 4.3 节**kwargs—透传给PeftConfig、transformers 的from_pretrained及PeftModel.from_pretrained如dtype、token、use_auth_token、trust_remote_code、cache_dir、subfolder等其中import_allowlist是本类独有的参数默认白名单由get_default_import_allowlist()返回src/peft/auto.pydef get_default_import_allowlist(): return [ diffusers, lerobot, megatron-core, transformers, ]如果你的基础模型来自其他库例如某个自定义库加载时需显式把它加入白名单否则会抛出ValueError详见第五节排查部分。四、底层工作机制AutoPeftModel 是如何自动的from_pretrained的核心逻辑全部在 src/peft/auto.py大致分为四步。4.1 第一步读取配置拿到基础模型路径peft_config PeftConfig.from_pretrained(pretrained_model_name_or_path, revisionrevision, **kwargs) base_model_path peft_config.base_model_name_or_path base_model_revision peft_config.revision注意这里读取的是适配器配置adapter_config.json其中的base_model_name_or_path记录了原始基础模型的位置。这正是无需手动加载PeftConfig的体现——配置读取被封装进了from_pretrained。4.2 第二步推断基础模型类三条分支源码按优先级处理三种情况指定了任务子类cls._target_class is not None直接使用该类绑定的 transformersAutoModelForXxx例如AutoPeftModelForCausalLM._target_class AutoModelForCausalLM。使用基础AutoPeftModel但配置带task_type抛错。源码中给出明确提示Cannot useAutoPeftModelwith a task type, please use a specific class for your task type. (e.g.AutoPeftModelForCausalLMfortask_typeCAUSAL_LM)——也就是说能用具体子类时就别用基础类。配置带task_type时校验一致性从MODEL_TYPE_TO_PEFT_MODEL_MAPPING查出期望类与当前子类绑定的_target_peft_class比对不一致则报错。例如用AutoPeftModelForCausalLM加载一个task_typeSEQ_2_SEQ_LM的适配器会得到类似 Expected target PEFT class: PeftModelForSeq2SeqLM, but you have asked for: PeftModelForCausalLM 的ValueError从源码看这是auto.py第 130–136 行的显式校验。配置无task_type但有auto_mapping走 auto mapping 分支详见下小节。4.3 第三步auto_mapping 与导入安全白名单对于无task_type的配置如 WhisperPeftModel.save_pretrained在保存时会自动写入auto_mapping字段——见 src/peft/peft_model.py其中记录了基础模型类的名称与所属库auto_mapping_dict { base_model_class: base_model_class.__name__, parent_library: parent_library, # 即 base_model_class.__module__ } peft_config.save_pretrained(output_dir, auto_mapping_dictauto_mapping_dict)加载端auto.py第 137–150 行则读取该映射并动态导入基础模型类base_model_class auto_mapping[base_model_class] parent_library_name auto_mapping[parent_library] if not check_import_allowlist(import_allowlist, parent_library_name): raise ValueError(...) parent_library importlib.import_module(parent_library_name) target_class getattr(parent_library, base_model_class)由于这里使用了importlib.import_module动态导入任意库PEFT 采取了两道防线防止被用作执行恶意代码的载体这一点在check_import_allowlist的 docstring 中有明确说明一是白名单校验parent_library必须位于默认白名单内或其前缀如transformers.xxx二是PeftConfig加载时会校验配置文件来源与内容。tests/test_auto.py的test_import_allow_list_prevents_arbitrary_imports专门验证了这一点把auto_mapping篡改为{parent_library: os, base_model_class: system}后加载必然抛出包含 which is not in the import allowlist 的ValueError。4.4 第四步实例化基础模型、处理词表扩展、加载适配器权重拿到target_class后依次执行base_model target_class.from_pretrained(base_model_path, revisionbase_model_revision, **kwargs)随后检查适配器目录中是否存在分词器配置tokenizer_config.json常量定义于 src/peft/utils/constants.py 的TOKENIZER_CONFIG_NAME。若存在且基础模型有get_input_embeddings则自动加载分词器并做词表扩展处理embedding_size base_model.get_input_embeddings().weight.shape[0] if len(tokenizer) embedding_size: base_model.resize_token_embeddings(len(tokenizer))注意判断条件是分词器词表大于嵌入维度才扩容。这是对历史上一个 bug 的修复见tests/test_auto.py中test_embedding_size_not_reduced_if_greater_vocab_size的注释关联 issue #2415此前无论词表大小都会强行 resize导致 Qwen 这类预留了冗余嵌入的模型嵌入维度 151936 词表 151646嵌入被缩小加载权重时报size mismatch。当前实现只在需要扩展词表如微调时新增了特殊 token时才 resize。最后调用cls._target_peft_class.from_pretrained(base_model, pretrained_model_name_or_path, ...)完成适配器权重的挂载返回一个完整的 PEFT 模型实例。五、常见报错与排查基于源码中的显式校验以下是几个高频错误场景及应对场景报错特征源码位置解决办法用AutoPeftModel加载带task_type的配置Cannot useAutoPeftModelwith a task type...src/peft/auto.py换成对应的AutoPeftModelForXxx子类任务子类与配置的task_type不匹配Expected target PEFT class: ... but you have asked for: ...src/peft/auto.py使用与配置文件task_type一致的子类auto_mapping指向白名单外的库which is not in the import allowlistsrc/peft/auto.py若确定安全传入import_allowlist[你的库名]配置既无task_type又无auto_mappingCannot infer the auto class from the config...src/peft/auto.py确认配置文件完整或手动加载PeftConfig后用PeftModel.from_pretrained六、AutoPeftModel 与 PeftModel.from_pretrained 的分工PeftModel.from_pretrained 是加载 PEFT 模型最灵活的方式它不关心模型来自哪个框架transformers、timm 或任意原生 PyTorch 模型因为基础模型由调用者自行实例化后传入。而AutoPeftModel本质上是它的便捷包装docs/source/guides/peft_model_config.md 中亦有此说明两者参数基本等价区别在于AutoPeftModel额外替你完成了读取配置 → 推断并实例化基础模型 → 处理词表这三步。选用建议适配器由 PEFT 标准流程save_pretrained保存且基础模型来自 transformers 生态 → 优先用AutoPeftModelForXxx最省事适配器来自非 transformers 框架timm、纯 PyTorch或你需要精细控制基础模型的加载参数 → 用PeftModel.from_pretrained手动传入已实例化的模型任务不在六类标准任务中如语音、扩散模型→ 用基础AutoPeftModel依赖auto_mapping或直接PeftModel。七、测试验证与仓库索引tests/test_auto.py为本文描述的每个行为提供了可复现的验证用例可作为理解各任务类型加载细节的参考test_peft_causal_lm/test_peft_seq2seq_lm/test_peft_sequence_cls/test_peft_token_classification/test_peft_question_answering/test_peft_feature_extraction分别验证六类任务的 Hub 加载、save_pretrained后本地目录循环加载、kwargsdtype透传test_peft_whisper验证基础AutoPeftModel的 auto mapping 加载路径test_embedding_size_not_reduced_if_greater_vocab_size验证词表扩展的边界条件修复test_import_allow_list_prevents_arbitrary_imports验证导入白名单安全机制。相关源码与文档索引核心实现src/peft/auto.py类定义与from_pretrained全流程被包装的对象src/peft/peft_model.pyPeftModel及六个任务子类、save_pretrained中写入auto_mapping的逻辑配置类src/peft/config.pyPeftConfig、auto_mapping字段顶层导出src/peft/init.pyfrom peft import AutoPeftModel...官方文档package_reference/auto_class.md本文依据的原始 API 参考、quicktour.md、guides/peft_model_config.md测试用例tests/test_auto.py八、小结AutoPeftModel把读取PeftConfig、推断基础模型类、实例化基础模型、处理词表、挂载适配器这五步压缩进一次from_pretrained调用有task_type时用AutoPeftModelForXxx七选一无task_type时用基础AutoPeftModel走auto_mapping。理解其推断规则、import_allowlist安全机制与词表处理逻辑后无论是从 Hub 拉取开源适配器还是加载本地微调产物都能以最小代码量获得类型正确、行为符合预期的 PEFT 模型实例。【免费下载链接】peft PEFT: State-of-the-art Parameter-Efficient Fine-Tuning.项目地址: https://gitcode.com/gh_mirrors/pe/peft创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 PEFT AutoPeftModel 自动加载指南：一行代码按任务类型加载 LoRA 等 PEFT 模型
PEFT AutoPeftModel 自动加载指南一行代码按任务类型加载 LoRA 等 PEFT 模型【免费下载链接】peft PEFT: State-of-the-art Parameter-Efficient Fine-Tuning.项目地址: https://gitcode.com/gh_mirrors/pe/peft本文基于 AutoPeftModel 官方 API 文档 展开并深入 src/peft/auto.py 源码与 tests/test_auto.py 测试系统性讲解 PEFT 库中AutoPeftModel系列类的设计原理、任务类型推断机制、安全导入白名单以及实际加载配置。读完本文你将掌握如何在不手动指定模型类、不手动加载PeftConfig的前提下用一行代码从 Hugging Face Hub 或本地目录加载经过 LoRA、IA3、Prompt Tuning 等参数高效微调PEFT方法训练好的模型并能根据报错信息快速定位任务类型或导入白名单问题。AutoPeftModel是 PEFT 库中面向开箱即用的自动模型加载入口。它解决的核心痛点是传统方式加载 PEFT 模型时需要先明确知道模型属于哪种任务类型因果语言建模、序列到序列、序列分类等再手动挑选对应的PeftModelForXxx子类同时还要自行处理PeftConfig的读取——这些步骤繁琐且容易出错。AutoPeftModel通过读取适配器配置文件中的task_type字段自动推断并实例化正确的 PEFT 模型类把整个加载流程压缩为一次from_pretrained调用。一、AutoPeftModel 类家族总览AutoPeftModel并非单个类而是一组围绕同一套推断逻辑的类族全部定义在 src/peft/auto.py 中并从 src/peft/init.py 顶层导出位于peft命名空间导入方式为from peft import AutoPeftModel等。它们共享同一个基类_BaseAutoPeftModel基类中实现了全部加载逻辑各子类只通过两个类属性声明该加载什么类名_target_class基础模型类_target_peft_classPEFT 包装类适用任务AutoPeftModel无依赖auto_mapping推断PeftModel通用任务如 Whisper 语音识别或未声明task_type的配置AutoPeftModelForCausalLMAutoModelForCausalLMPeftModelForCausalLM因果语言建模task_typeCAUSAL_LMAutoPeftModelForSeq2SeqLMAutoModelForSeq2SeqLMPeftModelForSeq2SeqLM序列到序列任务task_typeSEQ_2_SEQ_LMAutoPeftModelForSequenceClassificationAutoModelForSequenceClassificationPeftModelForSequenceClassification序列分类task_typeSEQ_CLSAutoPeftModelForTokenClassificationAutoModelForTokenClassificationPeftModelForTokenClassification词元分类/NERtask_typeTOKEN_CLSAutoPeftModelForQuestionAnsweringAutoModelForQuestionAnsweringPeftModelForQuestionAnswering问答任务task_typeQUESTION_ANSAutoPeftModelForFeatureExtractionAutoModelPeftModelForFeatureExtraction特征提取/句向量task_typeFEATURE_EXTRACTION对应关系由auto.py第 45–52 行的MODEL_TYPE_TO_PEFT_MODEL_MAPPING字典统一定义它把task_type字符串映射到具体的 PEFT 模型类MODEL_TYPE_TO_PEFT_MODEL_MAPPING: dict[str, type[PeftModel]] { SEQ_CLS: PeftModelForSequenceClassification, SEQ_2_SEQ_LM: PeftModelForSeq2SeqLM, CAUSAL_LM: PeftModelForCausalLM, TOKEN_CLS: PeftModelForTokenClassification, QUESTION_ANS: PeftModelForQuestionAnswering, FEATURE_EXTRACTION: PeftModelForFeatureExtraction, }原文档 auto_class.md 明确说明这些类的设计目标是单行代码快速加载 PEFT 模型无需关心具体需要哪个模型类也无需手动加载PeftConfig。二、基本用法一行代码加载 PEFT 模型2.1 有明确任务类型时使用AutoPeftModelForXxx对于在配置中写明了task_type的适配器直接使用与任务对应的子类即可。例如加载一个用 LoRA 微调过的因果语言模型完整示例可见 docs/source/quicktour.md 与 docs/source/package_reference/lora.mdfrom peft import AutoPeftModelForCausalLM # 从 Hub 加载自动读取 adapter_config.json推断任务类型并实例化正确的 PEFT 模型 model AutoPeftModelForCausalLM.from_pretrained(ybelkada/opt-350m-lora) # 本地路径同样支持例如由 PeftModel.save_pretrained 保存的目录 model AutoPeftModelForCausalLM.from_pretrained(./my_peft_model_dir/) # 直接推理 inputs tokenizer(Hello, my dog is, return_tensorspt) outputs model.generate(**inputs)2.2 无任务类型时使用基础AutoPeftModel如果模型的配置文件没有设置task_type例如 Whisper 语音识别、Stable Diffusion 等不在上表范围内的任务需要使用基础类AutoPeftModel。此时类本身不知道基础模型类加载逻辑会退化为读取配置中由save_pretrained自动写入的auto_mapping字段来还原基础模型类详见第四节from peft import AutoPeftModel model AutoPeftModel.from_pretrained(smangrul/openai-whisper-large-v2-LORA-colab)tests/test_auto.py中的test_peft_whisper用例正是验证了这一路径AutoPeftModel.from_pretrained加载 Whisper LoRA 模型后返回对象是PeftModel实例且dtype等参数正确传递到了model.base_model.model.model.encoder.embed_positions.weight。2.3 加载时传参适配器名、可训练标志、dtype 等from_pretrained支持与PeftModel.from_pretrained等价的位置参数与关键字参数差异点在下文标注常用调用方式model AutoPeftModelForCausalLM.from_pretrained( ybelkada/opt-350m-lora, # 模型 id 或本地目录 default, # adapter_name多适配器场景下指定要加载的适配器名 False, # is_trainableFalse 表示冻结适配器仅用于推理 dtypetorch.bfloat16, # 其余 kwargs 会一路透传给基础模型加载与 PeftConfig )tests/test_auto.py中的test_peft_causal_lm验证了这种位置参数 kwargs的调用方式并断言model.base_model.lm_head.weight.dtype与传入的dtype一致证明 kwargs 被正确透传到基础模型实例化过程。三、from_pretrained 关键参数详解AutoPeftModel.from_pretrained的完整签名在 src/peft/auto.py其 docstring 明确说明这是用户加载 PEFT 模型所需全部预处理步骤的封装kwargs 会传递给PeftConfig由其自动过滤 Hub 方法与配置对象初始化的参数。参数类型与默认值说明pretrained_model_name_or_pathstr/PathLike必填Hugging Face Hub 上的模型仓库 id或包含adapter_config.json与权重文件的本地目录adapter_namestr默认default要加载的适配器名称多适配器加载时用于区分is_trainablebool默认False是否让适配器可训练False时适配器冻结仅用于推理configOptional[PeftConfig]默认None手动传入已加载的配置对象替代自动读取配置文件与pretrained_model_name_or_path互斥使用revisionOptional[str]默认NoneHub 仓库的版本号/分支与PeftConfig.from_pretrained语义一致import_allowlistOptional[list[str]]默认取get_default_import_allowlist()允许被动态导入的库白名单用于实例化基础模型类安全机制详见 4.3 节**kwargs—透传给PeftConfig、transformers 的from_pretrained及PeftModel.from_pretrained如dtype、token、use_auth_token、trust_remote_code、cache_dir、subfolder等其中import_allowlist是本类独有的参数默认白名单由get_default_import_allowlist()返回src/peft/auto.pydef get_default_import_allowlist(): return [ diffusers, lerobot, megatron-core, transformers, ]如果你的基础模型来自其他库例如某个自定义库加载时需显式把它加入白名单否则会抛出ValueError详见第五节排查部分。四、底层工作机制AutoPeftModel 是如何自动的from_pretrained的核心逻辑全部在 src/peft/auto.py大致分为四步。4.1 第一步读取配置拿到基础模型路径peft_config PeftConfig.from_pretrained(pretrained_model_name_or_path, revisionrevision, **kwargs) base_model_path peft_config.base_model_name_or_path base_model_revision peft_config.revision注意这里读取的是适配器配置adapter_config.json其中的base_model_name_or_path记录了原始基础模型的位置。这正是无需手动加载PeftConfig的体现——配置读取被封装进了from_pretrained。4.2 第二步推断基础模型类三条分支源码按优先级处理三种情况指定了任务子类cls._target_class is not None直接使用该类绑定的 transformersAutoModelForXxx例如AutoPeftModelForCausalLM._target_class AutoModelForCausalLM。使用基础AutoPeftModel但配置带task_type抛错。源码中给出明确提示Cannot useAutoPeftModelwith a task type, please use a specific class for your task type. (e.g.AutoPeftModelForCausalLMfortask_typeCAUSAL_LM)——也就是说能用具体子类时就别用基础类。配置带task_type时校验一致性从MODEL_TYPE_TO_PEFT_MODEL_MAPPING查出期望类与当前子类绑定的_target_peft_class比对不一致则报错。例如用AutoPeftModelForCausalLM加载一个task_typeSEQ_2_SEQ_LM的适配器会得到类似 Expected target PEFT class: PeftModelForSeq2SeqLM, but you have asked for: PeftModelForCausalLM 的ValueError从源码看这是auto.py第 130–136 行的显式校验。配置无task_type但有auto_mapping走 auto mapping 分支详见下小节。4.3 第三步auto_mapping 与导入安全白名单对于无task_type的配置如 WhisperPeftModel.save_pretrained在保存时会自动写入auto_mapping字段——见 src/peft/peft_model.py其中记录了基础模型类的名称与所属库auto_mapping_dict { base_model_class: base_model_class.__name__, parent_library: parent_library, # 即 base_model_class.__module__ } peft_config.save_pretrained(output_dir, auto_mapping_dictauto_mapping_dict)加载端auto.py第 137–150 行则读取该映射并动态导入基础模型类base_model_class auto_mapping[base_model_class] parent_library_name auto_mapping[parent_library] if not check_import_allowlist(import_allowlist, parent_library_name): raise ValueError(...) parent_library importlib.import_module(parent_library_name) target_class getattr(parent_library, base_model_class)由于这里使用了importlib.import_module动态导入任意库PEFT 采取了两道防线防止被用作执行恶意代码的载体这一点在check_import_allowlist的 docstring 中有明确说明一是白名单校验parent_library必须位于默认白名单内或其前缀如transformers.xxx二是PeftConfig加载时会校验配置文件来源与内容。tests/test_auto.py的test_import_allow_list_prevents_arbitrary_imports专门验证了这一点把auto_mapping篡改为{parent_library: os, base_model_class: system}后加载必然抛出包含 which is not in the import allowlist 的ValueError。4.4 第四步实例化基础模型、处理词表扩展、加载适配器权重拿到target_class后依次执行base_model target_class.from_pretrained(base_model_path, revisionbase_model_revision, **kwargs)随后检查适配器目录中是否存在分词器配置tokenizer_config.json常量定义于 src/peft/utils/constants.py 的TOKENIZER_CONFIG_NAME。若存在且基础模型有get_input_embeddings则自动加载分词器并做词表扩展处理embedding_size base_model.get_input_embeddings().weight.shape[0] if len(tokenizer) embedding_size: base_model.resize_token_embeddings(len(tokenizer))注意判断条件是分词器词表大于嵌入维度才扩容。这是对历史上一个 bug 的修复见tests/test_auto.py中test_embedding_size_not_reduced_if_greater_vocab_size的注释关联 issue #2415此前无论词表大小都会强行 resize导致 Qwen 这类预留了冗余嵌入的模型嵌入维度 151936 词表 151646嵌入被缩小加载权重时报size mismatch。当前实现只在需要扩展词表如微调时新增了特殊 token时才 resize。最后调用cls._target_peft_class.from_pretrained(base_model, pretrained_model_name_or_path, ...)完成适配器权重的挂载返回一个完整的 PEFT 模型实例。五、常见报错与排查基于源码中的显式校验以下是几个高频错误场景及应对场景报错特征源码位置解决办法用AutoPeftModel加载带task_type的配置Cannot useAutoPeftModelwith a task type...src/peft/auto.py换成对应的AutoPeftModelForXxx子类任务子类与配置的task_type不匹配Expected target PEFT class: ... but you have asked for: ...src/peft/auto.py使用与配置文件task_type一致的子类auto_mapping指向白名单外的库which is not in the import allowlistsrc/peft/auto.py若确定安全传入import_allowlist[你的库名]配置既无task_type又无auto_mappingCannot infer the auto class from the config...src/peft/auto.py确认配置文件完整或手动加载PeftConfig后用PeftModel.from_pretrained六、AutoPeftModel 与 PeftModel.from_pretrained 的分工PeftModel.from_pretrained 是加载 PEFT 模型最灵活的方式它不关心模型来自哪个框架transformers、timm 或任意原生 PyTorch 模型因为基础模型由调用者自行实例化后传入。而AutoPeftModel本质上是它的便捷包装docs/source/guides/peft_model_config.md 中亦有此说明两者参数基本等价区别在于AutoPeftModel额外替你完成了读取配置 → 推断并实例化基础模型 → 处理词表这三步。选用建议适配器由 PEFT 标准流程save_pretrained保存且基础模型来自 transformers 生态 → 优先用AutoPeftModelForXxx最省事适配器来自非 transformers 框架timm、纯 PyTorch或你需要精细控制基础模型的加载参数 → 用PeftModel.from_pretrained手动传入已实例化的模型任务不在六类标准任务中如语音、扩散模型→ 用基础AutoPeftModel依赖auto_mapping或直接PeftModel。七、测试验证与仓库索引tests/test_auto.py为本文描述的每个行为提供了可复现的验证用例可作为理解各任务类型加载细节的参考test_peft_causal_lm/test_peft_seq2seq_lm/test_peft_sequence_cls/test_peft_token_classification/test_peft_question_answering/test_peft_feature_extraction分别验证六类任务的 Hub 加载、save_pretrained后本地目录循环加载、kwargsdtype透传test_peft_whisper验证基础AutoPeftModel的 auto mapping 加载路径test_embedding_size_not_reduced_if_greater_vocab_size验证词表扩展的边界条件修复test_import_allow_list_prevents_arbitrary_imports验证导入白名单安全机制。相关源码与文档索引核心实现src/peft/auto.py类定义与from_pretrained全流程被包装的对象src/peft/peft_model.pyPeftModel及六个任务子类、save_pretrained中写入auto_mapping的逻辑配置类src/peft/config.pyPeftConfig、auto_mapping字段顶层导出src/peft/init.pyfrom peft import AutoPeftModel...官方文档package_reference/auto_class.md本文依据的原始 API 参考、quicktour.md、guides/peft_model_config.md测试用例tests/test_auto.py八、小结AutoPeftModel把读取PeftConfig、推断基础模型类、实例化基础模型、处理词表、挂载适配器这五步压缩进一次from_pretrained调用有task_type时用AutoPeftModelForXxx七选一无task_type时用基础AutoPeftModel走auto_mapping。理解其推断规则、import_allowlist安全机制与词表处理逻辑后无论是从 Hub 拉取开源适配器还是加载本地微调产物都能以最小代码量获得类型正确、行为符合预期的 PEFT 模型实例。【免费下载链接】peft PEFT: State-of-the-art Parameter-Efficient Fine-Tuning.项目地址: https://gitcode.com/gh_mirrors/pe/peft创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考