Hugging Face Transformers Auto Classes 完全指南自动架构推断、任务映射与自定义模型注册【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers自动类Auto Classes是 Transformers 的核心设计之一只要给定预训练模型的名称或本地路径它就能从from_pretrained()自动推断出对应的模型架构省去手动查找与导入具体模型类的繁琐工作。本篇指南以仓库中的官方文档 docs/source/ja/model_doc/auto.md 为骨架结合src/transformers/models/auto/下的源码实现系统讲解 AutoClass 的工作原理、按任务划分的自动类家族、如何用register()注册自定义模型以及from_pretrained/from_config的底层加载流程。读完本文你将能够熟练使用 AutoClass 加载任意支持的模型并把自己的自定义模型无缝接入这套自动分发机制。AutoClass 是什么一行代码加载任意架构在大多数情况下你并不需要知道想加载的模型具体属于哪个类——只需把预训练模型的名字或路径传给from_pretrained()库就会根据名字或路径自动推断出架构。AutoClass 正是为完成这项推断工作而存在给它一个指向预训练权重/配置/词表的名称或路径它就会自动取回与之对应的模型。实例化AutoConfig、AutoModel或AutoTokenizer中的任何一个都会直接创建出对应架构的类。例如from transformers import AutoModel model AutoModel.from_pretrained(google-bert/bert-base-cased)这一行代码创建出的model实际上就是一个BertModel的实例——你不必手动from transformers import BertModelAutoClass 已经帮你完成了架构判定。注意加载模型时默认会调用model.eval()将其置于评估模式dropout 等模块会被停用。如果要训练模型需要先调用model.train()切回训练模式。从源码看这种推断能力建立在config.json中记录的model_type之上。AutoClass 加载模型时首先通过AutoConfig.from_pretrained()读取配置文件再以配置类为键在映射表中查找对应的模型类详见 configuration_auto.py 与 auto_factory.py 中的_get_model_class。一整套按任务与后端划分的 AutoModel 家族AutoClass 并非只有一个AutoModel而是每个任务一个类针对每一种任务因果语言建模、序列分类、目标检测、语音识别……以及每一个后端PyTorch、TensorFlow、Flax都存在对应的自动类。这意味着你可以在不关心具体模型实现的前提下仅通过任务的语义例如我要一个能做文本生成的模型来加载模型。以 PyTorch 为例仓库中 modeling_auto.py 从MODEL_MAPPING_NAMES出发为每个任务定义了独立的_LazyAutoMapping如MODEL_FOR_CAUSAL_LM_MAPPING、MODEL_FOR_SEQUENCE_CLASSIFICATION_MAPPING再通过auto_class_update()批量生成AutoModel、AutoModelForCausalLM等公开类。类的 docstring 由工厂函数动态注入其中from_pretrained的文档会列出该任务下所有可用的模型选项。自动类的扩展把自定义模型注册进 AutoClass每个自动类都提供了用于扩展的方法你可以把自己的自定义类注册进去。例如假设你定义了一个名为NewModel的自定义模型类并且已经准备好了对应的NewModelConfig那么可以这样把它们加入自动类from transformers import AutoConfig, AutoModel AutoConfig.register(new-model, NewModelConfig) AutoModel.register(NewModelConfig, NewModel)完成注册之后你就可以像使用内置模型一样使用自动类了model AutoModel.from_pretrained(new-model)注册时的两条硬性约束注册并非无条件的官方文档明确给出了两个需要确保一致性的前提如果NewModelConfig是PreTrainedConfig的子类请确保它的model_type属性与注册配置时使用的键此处为new-model相同如果NewModel是PreTrainedModel的子类请确保它的config_class属性与注册模型时使用的类此处为NewModelConfig相同。register 的源码级校验从源码看_BaseAutoModelClass.register会做一次一致性校验如果模型类带有config_class属性而该属性与传入的配置类名不一致就会直接抛出ValueError提示模型类的config_class属性与传入的配置类不一致并要求修正其中一方。这与文档中的 Tip 警告完全对应。注册的底层机制位于_LazyAutoMapping.registerauto_factory.py如果键配置类已存在于内置映射且exist_okFalse会抛出ValueError(... is already used by a Transformers model.)如果传入的是transformers内置模块中的配置类则直接跳过注册——这是为了兼容那些使用原生配置但自定义模型的远程代码场景避免在同一次会话中把原生配置永久重映射到自定义模型否则新映射会被存入_extra_content并在后续的__getitem__/__contains__中优先于内置映射被命中。对于AutoConfig其registerconfiguration_auto.py同样是先检查键是否已被占用exist_okFalse时冲突即报错然后写入_extra_content。常用自动类逐个看AutoConfig / AutoTokenizerAutoConfig根据模型名或路径自动加载对应的配置类不加载权重。它是整个自动分发链的起点——AutoModel.from_pretrained内部正是先通过它拿到配置对象。AutoTokenizer自动加载与模型匹配的分词器。它会根据模型类型在快分词器基于 tokenizers与慢分词器之间自动选择合适实现并处理tokenizer_config.json、词表文件等的下载与缓存。预处理器自动类AutoFeatureExtractor针对音频、图像等模态自动加载特征提取器feature extractor。AutoImageProcessor自动加载图像处理器负责将原始图像转换为模型输入resize、归一化、张量化等。AutoProcessor面向多模态模型如视觉-语言模型的组合式处理器自动加载文本分词器 图像/音频处理器的组合。此外当前仓库的 auto 模块还包含video_processing_auto.py对应视频处理器的自动加载能力英文文档中对应的AutoVideoProcessor一节可参考 docs/source/en/model_doc/auto.md。通用基座模型类Generic model classes以下自动类用于实例化不带特定任务头的基座模型AutoModel不带任何任务头的通用基座模型类from_pretrained(google-bert/bert-base-cased)返回BertModel实例即是典型例子。通用预训练类Generic pretraining classes以下自动类用于实例化带预训练任务头的模型AutoModelForPreTraining对应各模型的预训练头如 BERT 的 MLM NSP 头适用于需要继续预训练的场景。按任务分类的完整自动类清单下面清单完整继承自关联文档并按照任务领域分组。每个类都可以通过from_pretrained()或from_config()使用且这些名称均可从transformers顶层导入。自然语言处理Natural Language Processing自动类适用任务AutoModelForCausalLM因果语言建模自回归生成如 GPT 系列AutoModelForMaskedLM掩码语言建模如 BERT 预训练AutoModelForMaskGeneration掩码生成AutoModelForSeq2SeqLM序列到序列建模如 T5、BART 的生成AutoModelForSequenceClassification序列分类情感分析、文本分类等AutoModelForMultipleChoice多项选择阅读理解AutoModelForNextSentencePrediction下一句预测AutoModelForTokenClassification词元级分类命名实体识别、词性标注等AutoModelForQuestionAnswering抽取式问答AutoModelForTextEncoding文本编码得到句子/词元的稠密向量表示计算机视觉Computer vision自动类适用任务AutoModelForDepthEstimation深度估计AutoModelForImageClassification图像分类AutoModelForVideoClassification视频分类AutoModelForMaskedImageModeling掩码图像建模图像自监督预训练AutoModelForObjectDetection目标检测AutoModelForImageSegmentation图像分割AutoModelForImageToImage图像到图像如超分、去噪、上色AutoModelForSemanticSegmentation语义分割AutoModelForInstanceSegmentation实例分割AutoModelForUniversalSegmentation通用分割可同时处理语义/实例/全景分割AutoModelForZeroShotImageClassification零样本图像分类AutoModelForZeroShotObjectDetection零样本目标检测音频Audio自动类适用任务AutoModelForAudioClassification音频分类如声音事件分类AutoModelForAudioFrameClassification音频帧级分类AutoModelForCTC基于 CTC 的语音识别AutoModelForSpeechSeq2Seq序列到序列语音识别如 Whisper 类AutoModelForAudioXVector说话人验证/识别x-vectorAutoModelForTextToSpectrogram文本到频谱图TTS 前端AutoModelForTextToWaveform文本到波形端到端 TTS多模态Multimodal自动类适用任务AutoModelForTableQuestionAnswering表格问答AutoModelForDocumentQuestionAnswering文档问答文档图像理解AutoModelForVisualQuestionAnswering视觉问答AutoModelForImageTextToText图像文本到文本视觉语言生成如 VLM时间序列Time Series自动类适用任务AutoModelForTimeSeriesPrediction时间序列预测补充说明上述清单忠实于关联文档 docs/source/ja/model_doc/auto.md。当前仓库的英文版文档 docs/source/en/model_doc/auto.md 在此基础上还扩展了AutoModelForNormalEstimation、AutoModelForTextRecognition、AutoModelForTableRecognition、AutoModelForPoseEstimation、AutoModelForKeypointDetection、AutoModelForMultimodalLM、AutoModelForAudioTokenization等更新的任务类具体可用集合以对应语言文档及transformers顶层导出为准。源码视角from_pretrained 与 from_config 的加载流程为了真正理解 AutoClass值得走进工厂函数 auto_factory.py 看两条核心调用链。不能直接实例化_BaseAutoModelClass.__init__会直接抛出OSError提示该类设计为通过from_pretrained()或from_config()使用。也就是说AutoModel()这类写法是错误的唯一入口是这两个类方法。from_pretrained 的主要步骤_BaseAutoModelClass.from_pretrained大体做了以下几件事准备 Hub 参数从 kwargs 中剥离cache_dir、force_download、local_files_only、proxies、revision、subfolder、token等 Hub 相关参数获取 commit hash优先解析config.json以尽早确定模型的 commit 版本加载配置如果调用方没有显式传入config则通过AutoConfig.from_pretrained()加载配置对象此时会临时弹出torch_dtypeauto、dtypeauto等对配置无意义的参数加载后再按需回填保证用户显式指定的 dtype/量化配置生效判定代码来源检查配置是否带auto_map远程代码标记以及配置类是否在本地映射中从而决定走远程代码动态加载还是本地映射查找两条分支本地映射分支调用_get_model_class(config, cls._model_mapping)拿到模型类。若配置声明了architectures且能在候选模型元组中找到匹配项则返回该架构否则回退到元组第一个默认模型类远程代码分支通过get_class_from_dynamic_module从 Hub 动态拉取模型类并自动register到当前自动类同时调用add_generation_mixin_to_remote_model为旧版远程模型补齐generate方法最后委托给模型类自身的from_pretrained完成权重加载。from_config 与注意实现选择from_config只依据配置类实例化模型、不加载权重并支持传入attn_implementation参数eager、sdpa、flash_attention_2、flash_attention_3。在 torch ≥ 2.1.1 且可用时默认优先使用 SDPA否则回退到手写eager实现。配置类到模型类的映射如何建立_LazyAutoMappingauto_factory.py是一个惰性映射它同时持有config_mappingmodel_type → 配置类名与model_mappingmodel_type → 模型类名并在首次访问时才通过importlib按需导入对应模型模块model_type_to_module_name会把bert之类键转换为transformers.models.bert模块。这种惰性设计使得加载任意单个模型时无需导入全部数百个模型模块显著降低启动开销。映射表从哪里来所有内置映射集中在 auto_mappings.pyCONFIG_MAPPING_NAMES与 modeling_auto.pyMODEL_MAPPING_NAMES、MODEL_FOR_*_MAPPING_NAMES。该文件由utils/check_auto.py --fix_and_overwrite根据各模型配置类中的model_type自动生成文件头注释明确警告不要手工编辑。这正是文档要求注册自定义模型时model_type必须与注册键一致的根因库自身的自动分发完全依赖这一键值约定。实战一套代码覆盖多架构AutoClass 最大的实用价值在于架构无关的代码。下面给出两个可直接运行的示例。示例一统一加载不同架构的因果语言模型from transformers import AutoModelForCausalLM, AutoTokenizer # 同一段代码更换模型名即可切换到不同架构 for model_id in [gpt2, facebook/opt-350m, mistralai/Mistral-7B-v0.1]: tokenizer AutoTokenizer.from_pretrained(model_id) model AutoModelForCausalLM.from_pretrained(model_id, device_mapauto) inputs tokenizer(Machine learning is, return_tensorspt) outputs model.generate(**inputs, max_new_tokens20) print(tokenizer.decode(outputs[0], skip_special_tokensTrue))示例二只加载配置不加载权重from transformers import AutoConfig config AutoConfig.from_pretrained(google-bert/bert-base-cased) print(config.model_type) # bert如需加载权重再配合AutoModel.from_config(config)或直接用from_pretrained。源码阅读路线图如果希望进一步深入建议按以下顺序阅读当前仓库中的相关文件auto_mappings.pymodel_type → 配置类/模型类的全部内置映射configuration_auto.pyAutoConfig、_LazyConfigMapping与配置注册机制auto_factory.py_BaseAutoModelClass、from_pretrained/from_config、register、_LazyAutoMappingmodeling_auto.pyAutoModel与各任务自动类的生成tokenization_auto.py、feature_extraction_auto.py、image_processing_auto.py、processing_auto.py、video_processing_auto.py分词器与预处理器的自动加载。小结AutoClass 是 Transformers 中约定优于配置思想的集中体现通过统一的from_pretrained()入口、以model_type为键的惰性映射表以及面向每个任务独立分发的自动类家族让模型加载代码与具体架构解耦。无论是日常加载预训练模型、按任务切换模型还是把自己的自定义模型注册进生态理解这套机制都能让你写出更通用、更健壮的深度学习代码。【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考