基础类和模型加载

相关源文件

• README.md
• docs/source/en/_toctree.yml
• docs/source/en/index.md
• docs/source/en/perf_infer_gpu_one.md
• src/transformers/__init__.py
• src/transformers/configuration_utils.py
• src/transformers/feature_extraction_utils.py
• src/transformers/file_utils.py
• src/transformers/modeling_flax_utils.py
• src/transformers/modeling_tf_utils.py
• src/transformers/models/__init__.py
• src/transformers/models/auto/configuration_auto.py
• src/transformers/models/auto/feature_extraction_auto.py
• src/transformers/models/auto/image_processing_auto.py
• src/transformers/models/auto/modeling_auto.py
• src/transformers/models/auto/processing_auto.py
• src/transformers/models/auto/tokenization_auto.py
• src/transformers/models/udop/convert_udop_to_hf.py
• src/transformers/tokenization_utils_base.py
• src/transformers/utils/dummy_pt_objects.py
• src/transformers/utils/dummy_vision_objects.py
• src/transformers/utils/hub.py
• tests/models/fnet/test_tokenization_fnet.py
• tests/models/layoutlmv2/test_tokenization_layoutlmv2.py
• tests/models/layoutlmv3/test_tokenization_layoutlmv3.py
• tests/models/layoutxlm/test_tokenization_layoutxlm.py
• tests/models/markuplm/test_tokenization_markuplm.py
• tests/models/tapas/test_tokenization_tapas.py
• tests/models/udop/test_tokenization_udop.py
• tests/test_configuration_common.py
• tests/test_feature_extraction_common.py
• tests/test_modeling_flax_common.py
• tests/test_modeling_tf_common.py
• tests/test_tokenization_common.py
• utils/check_repo.py

本文档涵盖了 Hugging Face Transformers 库中基础的基类和模型加载基础设施。它解释了所有模型、配置和分词器继承的核心抽象，以及从 Hub 或本地存储加载预训练模型的基础机制。

有关基于这些基类构建的 Auto Classes 系统的信息，请参阅 Auto Classes 系统。有关分词器基类的详细信息，请参阅 分词器系统。

基类架构

Transformers 库围绕几个关键的基类构建，这些基类为所有模型实现提供了通用功能。这些类负责配置管理、权重加载/保存和特定于框架的行为。

基类层次结构和框架支持

来源：src/transformers/__init__.py554 src/transformers/configuration_utils.py45 src/transformers/modeling_tf_utils.py1 src/transformers/modeling_flax_utils.py1

PretrainedConfig 基类

PretrainedConfig 类是 Transformers 中所有模型配置的基础。它负责参数存储、序列化和从 Hub 加载。

核心功能

方法	目的	关键参数
from_pretrained	从 Hub 或本地路径加载配置	pretrained_model_name_or_path、cache_dir、revision
save_pretrained	将配置保存到目录	save_directory、push_to_hub
to_dict	将配置转换为字典	use_diff
from_dict	从字典创建配置	config_dict、kwargs

配置加载流程

配置加载和缓存机制

配置系统支持：

• Hub 集成：从 Hugging Face Hub 自动下载和缓存
• 本地加载：从本地目录加载
• Revision 支持：特定提交、分支或标签
• 自定义配置：动态加载用户定义的配置类

来源：src/transformers/configuration_utils.py45-700 src/transformers/utils/hub.py136-144

PreTrainedModel 基类

PreTrainedModel 类是 Transformers 中所有 PyTorch 模型的基础。它负责模型初始化、权重加载/保存和设备管理。

主要功能

PreTrainedModel 核心特性和方法

权重加载基础设施

模型加载系统支持多种权重格式和存储后端

格式	文件扩展名	后端
PyTorch	.bin	torch.load
SafeTensors	.safetensors	safetensors
TensorFlow	.h5	h5py
GGUF	.gguf	自定义加载器

来源：src/transformers/utils/dummy_pt_objects.py573-577 src/transformers/modeling_gguf_pytorch_utils.py26

特定于框架的基类

TensorFlow 模型 (TFPreTrainedModel)

TensorFlow 实现扩展了 Keras Model 的功能，并加入了 Transformers 特有的功能

TensorFlow 模型架构和 Mixins

关键的 TensorFlow 特有功能

• Keras 兼容性：与 Keras 训练循环完全集成
• 损失函数：针对不同任务的专用损失函数（TFCausalLanguageModelingLoss、TFQuestionAnsweringLoss）
• 序列化：通过 @keras_serializable 装饰器提供自定义序列化支持

来源：src/transformers/modeling_tf_utils.py126-147 src/transformers/modeling_tf_utils.py213-253

JAX/Flax 模型 (FlaxPreTrainedModel)

Flax 模型为 JAX 提供了函数式编程范例

JAX/Flax 模型结构和能力

来源：src/transformers/modeling_flax_utils.py1-100

模型加载基础设施

模型加载系统集成了多个组件，为加载预训练模型提供了一个统一的接口

加载流程

带有 Auto Classes 和权重格式的完整模型加载架构

自动模型选择

Auto Classes 使用映射字典根据配置确定正确的模型类

映射	目的	示例条目
CONFIG_MAPPING_NAMES	配置类选择	"bert": "BertConfig"
MODEL_MAPPING_NAMES	模型类选择	"bert": "BertModel"
TOKENIZER_MAPPING_NAMES	分词器选择	"bert": ("BertTokenizer", "BertTokenizerFast")

_LazyAutoMapping 类提供模型的延迟加载，以避免在启动时导入所有模型。

来源：src/transformers/models/auto/configuration_auto.py36-357 src/transformers/models/auto/modeling_auto.py32-357 src/transformers/models/auto/tokenization_auto.py57-300

与 Hub 和缓存的集成

基类通过几个关键的实用程序与 Hugging Face Hub 集成

Hub 集成组件

Hub 集成和本地缓存系统

缓存系统以结构化格式存储模型，该格式允许

• 版本控制：同一模型的不同提交/分支
• 共享存储：多个模型可以共享相同的缓存文件
• 离线模式：缓存后即可在没有互联网连接的情况下使用模型

来源：src/transformers/utils/hub.py1-500 src/transformers/__init__.py552-1037