在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

huggingface/transformers

菜单

自动类系统

相关源文件

Auto Classes 系统是 Transformers 库的核心架构组件，它提供了一个统一且简化的 API，可以根据模型类型和配置动态加载相应的实现类。该系统使用户能够通过一致的接口处理数百种模型架构，而无需了解每种模型的具体实现细节。

目的与范围

Auto Classes 系统有几个关键目的：

  1. 简化的模型加载：允许用户使用单个一致的 API 加载任何模型。
  2. 动态实现选择：根据模型类型自动选择相应的实现类。
  3. 框架灵活性：为 PyTorch、TensorFlow 和 Flax 实现提供一致的接口。
  4. 延迟加载：通过仅在需要时加载必要的组件来优化导入时间。

本页面专门介绍 Auto Classes 架构及其内部工作原理。有关使用特定模型实现的信息，请参阅其各自的文档页面。

Auto Classes 架构

Auto Classes 系统围绕 _BaseAutoModelClass 和 _LazyAutoMapping 构建，它们根据模型配置动态实例化相应的实现类。该系统通过 _LazyModule 使用延迟加载来优化导入性能。

核心 Auto Classes

该库为不同组件提供了多个 Auto Classes：

Auto Class基类目的映射字典
AutoConfig_BaseAutoModelClass配置加载CONFIG_MAPPING_NAMES
AutoModel_BaseAutoModelClass基础模型加载MODEL_MAPPING_NAMES
AutoModelForCausalLM_BaseAutoModelClass因果语言模型MODEL_FOR_CAUSAL_LM_MAPPING_NAMES
AutoModelForSequenceClassification_BaseAutoModelClass序列分类MODEL_FOR_SEQUENCE_CLASSIFICATION_MAPPING_NAMES
AutoTokenizer_LazyAutoMapping分词器加载TOKENIZER_MAPPING_NAMES
AutoProcessor_LazyAutoMapping多模态处理器PROCESSOR_MAPPING_NAMES
AutoImageProcessor_LazyAutoMapping图像处理器IMAGE_PROCESSOR_MAPPING_NAMES

来源: src/transformers/models/auto/auto_factory.py21-26 src/transformers/models/auto/modeling_auto.py32-357 src/transformers/models/auto/configuration_auto.py36-387 src/transformers/models/auto/tokenization_auto.py57-58 src/transformers/models/auto/processing_auto.py52-53 src/transformers/models/auto/image_processing_auto.py57-58

系统工作流程

来源: src/transformers/models/auto/auto_factory.py21-26 src/transformers/configuration_utils.py25 src/transformers/models/auto/configuration_auto.py473-506

映射系统

Auto Classes 系统使用 OrderedDict 映射来将模型类型链接到实现类名称。每个映射包含数百个模型类型条目，这些条目由 _LazyAutoMapping 使用以动态加载正确的类。

映射架构

关键映射示例

模型类型配置基础模型因果 LM分词器
"bert""BertConfig""BertModel""BertLMHeadModel"("BertTokenizer", "BertTokenizerFast")
"llama""LlamaConfig""LlamaModel""LlamaForCausalLM"("LlamaTokenizer", "LlamaTokenizerFast")
"gpt2""GPT2Config""GPT2Model""GPT2LMHeadModel"("GPT2Tokenizer", "GPT2TokenizerFast")
"whisper""WhisperConfig""WhisperModel"不适用("WhisperTokenizer", "WhisperTokenizerFast")

来源: src/transformers/models/auto/configuration_auto.py36-387 src/transformers/models/auto/modeling_auto.py32-357 src/transformers/models/auto/modeling_auto.py534-531 src/transformers/models/auto/tokenization_auto.py57-673 src/transformers/utils/import_utils.py51 src/transformers/__init__.py1018-1022

延迟加载机制

Transformers 库使用 _LazyModule 来推迟到第一次访问时才进行导入，从而优化启动时间。该系统维护一个 _import_structure 字典，将模块名称映射到其可导出的对象。

关键组件

  • _LazyModule：自定义模块类，实现 __getattr__ 以按需导入。
  • _import_structure：将模块路径映射到可导出对象列表的字典。
  • define_import_structure()：从文件系统结构构建导入映射的函数。
  • sys.modules 替换：主 transformers 模块被替换为 _LazyModule 实例。

来源: src/transformers/__init__.py1023-1029 src/transformers/utils/import_utils.py51 src/transformers/__init__.py57-280 src/transformers/utils/_LazyModule

自动工厂系统

Auto Classes 是使用自动工厂系统生成的，该系统根据映射创建必要的类。这是通过 _BaseAutoModelClass 及类似的基础类以及 auto_class_update 函数完成的。

Auto Classes 与实现的关联

来源: src/transformers/models/auto/auto_factory.py

框架支持

Auto Classes 系统使用 OptionalDependencyNotAvailable 异常和虚拟对象进行条件导入，以优雅地处理多种框架。

特定于框架的类

框架Auto Classes虚拟对象映射名称
PyTorchAutoModel, AutoModelForCausalLMdummy_pt_objectsMODEL_MAPPING_NAMES
TensorFlowTFAutoModel, TFAutoModelForCausalLMdummy_tf_objectsTF_MODEL_MAPPING_NAMES
FlaxFlaxAutoModel, FlaxAutoModelForCausalLMdummy_flax_objectsFLAX_MODEL_MAPPING_NAMES

虚拟对象实现

当框架不可用时，虚拟类会引发有用的错误消息。

来源：src/transformers/__init__.py341-348 src/transformers/__init__.py473-479 src/transformers/__init__.py520-528 src/transformers/utils/dummy_pt_objects.py573-577 src/transformers/utils/dummy_tf_objects.py5-9 src/transformers/models/auto/modeling_tf_auto.py28-29

Auto类如何解析模型

当调用from_pretrained()时，系统会加载配置，提取model_type，通过映射解析实现类，然后实例化。

关键解析函数

解析过程使用几个关键函数

  • PretrainedConfig.from_pretrained()：从Hub或本地路径加载模型配置
  • get_values(mapping)：从延迟映射字典中提取类名
  • model_type_to_module_name()：将模型类型转换为用于导入的模块路径
  • getattr(module, class_name)：动态导入特定的模型类

来源：src/transformers/models/auto/auto_factory.py21-26 src/transformers/models/auto/configuration_auto.py473-506 src/transformers/configuration_utils.py25 src/transformers/models/auto/configuration_auto.py653-672

使用模式

基本用法

最常见的用法模式是使用Auto类加载预训练模型

特定框架的使用

对于TensorFlow或Flax模型

特定任务的模型

有针对不同任务的专用Auto类

任务Auto Class
文本分类AutoModelForSequenceClassification
问答AutoModelForQuestionAnswering
因果语言建模AutoModelForCausalLM
掩码语言建模AutoModelForMaskedLM
图像分类AutoModelForImageClassification
语音识别AutoModelForSpeechSeq2Seq
还有更多...

来源：src/transformers/models/auto/modeling_auto.py1349-3018

系统优势

  1. 统一的API：为500多种模型架构提供单一的from_pretrained()接口
  2. 延迟加载：_LazyModule将初始导入时间从几秒缩短到几毫秒
  3. 框架无关：自动检测框架并提供优雅的回退机制
  4. 类型安全：OrderedDict映射提供可预测的模型解析
  5. 可扩展性：通过向映射字典添加条目即可集成新模型

模型注册过程

要添加新的模型架构，开发人员必须更新多个映射字典

新模型所需更新

  1. 配置映射：添加到CONFIG_MAPPING_NAMES中，位于src/transformers/models/auto/configuration_auto.py36-387
  2. 模型映射：添加到中的相关映射src/transformers/models/auto/modeling_auto.py32-357
  3. 分词器映射：添加到中的TOKENIZER_MAPPING_NAMES，位于src/transformers/models/auto/tokenization_auto.py57-673
  4. 导入结构：更新中的_import_structure位于src/transformers/__init__.py57-280
  5. 验证：确保模型通过中的检查utils/check_repo.py46-47

信任远程代码支持

对于第三方模型，系统通过以下方式支持trust_remote_code=True

  • get_class_from_dynamic_module()：下载和导入外部模型代码
  • resolve_trust_remote_code()：验证信任设置和用户权限
  • 动态模块加载：支持核心映射中没有的模型

来源：src/transformers/models/auto/configuration_auto.py25-27 src/transformers/dynamic_module_utils.py25-26 utils/check_repo.py46-47 utils/check_copies.py15-32

Auto Classes系统提供了一个强大而灵活的架构，简化了Transformers库中提供的各种模型的使用，同时保持了库的性能和可扩展性。