Transformers 4.37 中文文档（十四）（4）

Transformers 4.37 中文文档（十四）（3）https://developer.aliyun.com/article/1564957

日志记录

原始文本：huggingface.co/docs/transformers/v4.37.2/en/main_classes/logging

🤗 Transformers 具有集中的日志记录系统，因此您可以轻松设置库的详细程度。

目前库的默认详细程度为WARNING。

要更改详细程度，请使用其中一个直接设置器。例如，以下是如何将详细程度更改为 INFO 级别。

import transformers
transformers.logging.set_verbosity_info()

您还可以使用环境变量TRANSFORMERS_VERBOSITY来覆盖默认的详细程度。您可以将其设置为以下之一：debug，info，warning，error，critical。例如：

TRANSFORMERS_VERBOSITY=error ./myprogram.py

此外，通过将环境变量TRANSFORMERS_NO_ADVISORY_WARNINGS设置为真值（如1），可以禁用一些warnings。这将禁用使用logger.warning_advice记录的任何警告。例如：

TRANSFORMERS_NO_ADVISORY_WARNINGS=1 ./myprogram.py

以下是如何在您自己的模块或脚本中使用与库相同的记录器的示例：

from transformers.utils import logging
logging.set_verbosity_info()
logger = logging.get_logger("transformers")
logger.info("INFO")
logger.warning("WARN")

此日志记录模块的所有方法都在下面有文档记录，主要方法是 logging.get_verbosity()用于获取记录器中当前详细程度的级别和  logging.set_verbosity()用于将详细程度设置为您选择的级别。按顺序（从最不详细到最详细），这些级别（及其相应的整数值）为：

• transformers.logging.CRITICAL或transformers.logging.FATAL（整数值，50）：仅报告最关键的错误。
  
• transformers.logging.ERROR（整数值，40）：仅报告错误。
  
• transformers.logging.WARNING或transformers.logging.WARN（整数值，30）：仅报告错误和警告。这是库使用的默认级别。
  
• transformers.logging.INFO（整数值，20）：报告错误，警告和基本信息。
  
• transformers.logging.DEBUG（整数值，10）：报告所有信息。
  

默认情况下，在模型下载期间将显示tqdm进度条。logging.disable_progress_bar()和 logging.enable_progress_bar()可用于抑制或取消抑制此行为。

日志记录与警告

Python 有两个经常一起使用的日志记录系统：logging，如上所述，和warnings，允许进一步对警告进行分类，例如，FutureWarning用于已经被弃用的功能或路径，DeprecationWarning用于指示即将被弃用的内容。

我们在transformers库中同时使用这两种。我们利用并调整logging的captureWarning方法，以允许通过上述详细程度设置器管理这些警告消息。

这对库的开发人员意味着什么？我们应该遵守以下启发式：

• warnings应该优先考虑库的开发人员和依赖于transformers的库。
  
• logging应该用于每天项目中使用该库的最终用户
  

请参阅下面的captureWarnings方法的参考。

transformers.utils.logging.captureWarnings

<来源>

( capture )

调用logging库中的captureWarnings方法，以启用对warnings库发出的警告的管理。

在此处阅读有关此方法的更多信息：docs.python.org/3/library/logging.html#integration-with-the-warnings-module

所有警告都将通过py.warnings记录器记录。

注意：如果此记录器尚未具有处理程序，则此方法还会向此记录器添加处理程序，并将该记录器的记录级别更新为库的根记录器。

基本设置器

transformers.utils.logging.set_verbosity_error

<来源>

( )

将详细程度设置为ERROR级别。

transformers.utils.logging.set_verbosity_warning

<来源>

( )

将详细程度设置为WARNING级别。

transformers.utils.logging.set_verbosity_info

<来源>

( )

将详细程度设置为INFO级别。

transformers.utils.logging.set_verbosity_debug

<来源>

( )

将详细程度设置为DEBUG级别。

其他函数

transformers.utils.logging.get_verbosity

<来源>

( ) → export const metadata = 'undefined';int

返回

int

记录级别。

以 int 形式返回🤗 Transformers 的根记录器的当前级别。

🤗 Transformers 有以下记录级别：

• 50：transformers.logging.CRITICAL或transformers.logging.FATAL
  
• 40：transformers.logging.ERROR
  
• 30：transformers.logging.WARNING或transformers.logging.WARN
  
• 20：transformers.logging.INFO
  
• 10：transformers.logging.DEBUG
  

transformers.utils.logging.set_verbosity

<来源>

( verbosity: int )

参数

• verbosity（int）— 记录级别，例如：

• transformers.logging.CRITICAL或transformers.logging.FATAL
  
• transformers.logging.ERROR
  
• transformers.logging.WARNING或transformers.logging.WARN
  
• transformers.logging.INFO
  
• transformers.logging.DEBUG
  

为🤗 Transformers 的根记录器设置详细程度级别。

transformers.utils.logging.get_logger

<来源>

( name: Optional = None )

返回具有指定名称的记录器。

这个功能不应该直接访问，除非你正在编写一个自定义的 transformers 模块。

transformers.utils.logging.enable_default_handler

<来源>

( )

启用 HuggingFace Transformers 的根记录器的默认处理程序。

transformers.utils.logging.disable_default_handler

<来源>

( )

禁用 HuggingFace Transformers 的根记录器的默认处理程序。

transformers.utils.logging.enable_explicit_format

<来源>

( )

为每个 HuggingFace Transformers 的记录器启用显式格式。显式格式如下：

[LEVELNAME|FILENAME|LINE NUMBER] TIME >> MESSAGE

此方法影响当前绑定到根记录器的所有处理程序。#### transformers.utils.logging.reset_format

<来源>

( )

重置 HuggingFace Transformers 的记录格式。

此方法影响当前绑定到根记录器的所有处理程序。

transformers.utils.logging.enable_progress_bar

<来源>

( )

启用 tqdm 进度条。

transformers.utils.logging.disable_progress_bar

<来源>

( )

禁用 tqdm 进度条。

模型

huggingface.co/docs/transformers/v4.37.2/en/main_classes/model

基类 PreTrainedModel、TFPreTrainedModel 和 FlaxPreTrainedModel  实现了从本地文件或目录加载/保存模型的常用方法，或从库提供的预训练模型配置（从 HuggingFace 的 AWS S3 存储库下载）加载模型。

PreTrainedModel 和 TFPreTrainedModel 还实现了一些所有模型共有的方法：

• 当新的标记添加到词汇表中时，调整输入标记嵌入大小
  
• 修剪模型的注意力头。
  

每个模型共有的其他方法在 ModuleUtilsMixin（用于 PyTorch 模型）和 ~modeling_tf_utils.TFModuleUtilsMixin（用于  TensorFlow 模型）中定义，或者用于文本生成的 GenerationMixin（用于 PyTorch  模型）、TFGenerationMixin（用于 TensorFlow 模型）和 FlaxGenerationMixin（用于 Flax/JAX  模型）。

PreTrainedModel

class transformers.PreTrainedModel

< source >

( config: PretrainedConfig *inputs **kwargs )

所有模型的基类。

PreTrainedModel 负责存储模型的配置，并处理加载、下载和保存模型以及一些所有模型共有的方法：

• 调整输入嵌入大小，
  
• 修剪自注意力头中的头。
  

类属性（派生类覆盖）：

• config_class (PretrainedConfig) — 用作此模型架构的配置类的 PretrainedConfig 的子类。
  
• load_tf_weights (Callable) — 用于在 PyTorch 模型中加载 TensorFlow 检查点的 Python 方法，参数为：

• model (PreTrainedModel) — 要加载 TensorFlow 检查点的模型实例。
  
• config (PreTrainedConfig) — 与模型关联的配置实例。
  
• path (str) — TensorFlow 检查点的路径。
  

• base_model_prefix (str) — 一个字符串，指示派生类中基础模型关联的属性，该属性在基础模型的顶部添加模块。
  
• is_parallelizable (bool) — 一个指示此模型是否支持模型并行化的标志。
  
• main_input_name (str) — 模型的主要输入名称（通常为 NLP 模型的 input_ids，视觉模型的 pixel_values 和语音模型的 input_values）。
  

push_to_hub

< source >

( repo_id: str use_temp_dir: Optional = None commit_message: Optional = None private: Optional = None token: Union = None max_shard_size: Union = '5GB' create_pr: bool = False safe_serialization: bool = True revision: str = None commit_description: str = None tags: Optional = None **deprecated_kwargs )

参数

• repo_id (str) — 您要推送模型的存储库名称。在推送到特定组织时，应包含您的组织名称。
  
• use_temp_dir（bool，可选）— 是否使用临时目录存储保存的文件，然后将它们推送到 Hub。如果没有名为repo_id的目录，则默认为True，否则为False。
  
• commit_message（str，可选）— 推送时要提交的消息。默认为"Upload model"。
  
• private（bool，可选）— 是否应该创建私有存储库。
  
• token（bool或str，可选）— 用作远程文件的 HTTP bearer 授权的令牌。如果为True，将使用运行huggingface-cli login时生成的令牌（存储在~/.huggingface中）。如果未指定repo_url，则默认为True。
  
• max_shard_size（int或str，可选，默认为"5GB"）— 仅适用于模型。在分片之前的检查点的最大大小。然后，检查点将分片，每个分片的大小都小于此大小。如果表示为字符串，需要是数字后跟一个单位（如"5MB"）。我们将其默认设置为"5GB"，以便用户可以在免费的 Google Colab 实例上轻松加载模型，而不会出现任何 CPU OOM 问题。
  
• create_pr（bool，可选，默认为False）— 是否创建带有上传文件的 PR 或直接提交。
  
• safe_serialization（bool，可选，默认为True）— 是否将模型权重转换为 safetensors 格式以进行更安全的序列化。
  
• revision（str，可选）— 要将上传的文件推送到的分支。
  
• commit_description（str，可选）— 将创建的提交的描述
  
• tags（List[str]，可选）— 要推送到 Hub 上的标签列表。
  

将模型文件上传到🤗模型中心。

示例：

from transformers import AutoModel
model = AutoModel.from_pretrained("bert-base-cased")
# Push the model to your namespace with the name "my-finetuned-bert".
model.push_to_hub("my-finetuned-bert")
# Push the model to an organization with the name "my-finetuned-bert".
model.push_to_hub("huggingface/my-finetuned-bert")

add_model_tags

<来源>

( tags: Union )

参数

• tags（Union[List[str], str]）— 要注入模型中的所需标签。

将自定义标签添加到推送到 Hugging Face Hub 的模型中。不会覆盖模型中的现有标签。

示例：

from transformers import AutoModel
model = AutoModel.from_pretrained("bert-base-cased")
model.add_model_tags(["custom", "custom-bert"])
# Push the model to your namespace with the name "my-custom-bert".
model.push_to_hub("my-custom-bert")

can_generate

<来源>

( ) → export const metadata = 'undefined';bool

返回

bool

此模型是否可以生成序列，使用.generate()。

返回此模型是否可以生成序列，使用.generate()。

disable_input_require_grads

<来源>

( )

删除_require_grads_hook。

enable_input_require_grads

<来源>

( )

启用输入嵌入的梯度。这对于微调适配器权重并保持模型权重固定很有用。

from_pretrained

<来源>

( pretrained_model_name_or_path: Union *model_args config: Union = None cache_dir: Union = None ignore_mismatched_sizes: bool = False force_download: bool = False local_files_only: bool = False token: Union = None revision: str = 'main' use_safetensors: bool = None **kwargs )

参数

• pretrained_model_name_or_path（str或os.PathLike，可选）— 可以是：

• 一个字符串，托管在 huggingface.co 模型存储库中的预训练模型的模型 ID。有效的模型 ID 可以位于根级别，如bert-base-uncased，或者在用户或组织名称下命名空间化，如dbmdz/bert-base-german-cased。
  
• 指向包含使用 save_pretrained()保存的模型权重的目录的路径，例如，./my_model_directory/。
  
• 指向TensorFlow 索引检查点文件的路径或 URL（例如，./tf_model/model.ckpt.index）。在这种情况下，应将from_tf设置为True，并将配置对象作为config参数提供。使用此加载路径比使用提供的转换脚本将 TensorFlow 检查点转换为 PyTorch 模型并随后加载 PyTorch 模型要慢。
  
• 一个包含flax checkpoint file的模型文件夹的路径或 url，格式为*.msgpack*（例如，./flax_model/包含flax_model.msgpack）。在这种情况下，from_flax应设置为True。
  
• 如果您同时提供配置和状态字典（分别使用关键字参数config和state_dict），则为None。
  

• model_args（位置参数序列，可选）— 所有剩余的位置参数将传递给底层模型的__init__方法。
  
• config（Union[PretrainedConfig, str, os.PathLike]，可选）— 可以是：

• 从 PretrainedConfig 派生的类的实例，
  
• 一个作为输入有效的字符串或路径，用于 from_pretrained()。
  

• 代替自动加载的配置使用的模型配置。当：
  

• 模型是库提供的模型（使用预训练模型的模型 id字符串加载）。
  
• 模型是使用 save_pretrained()保存的，并通过提供保存目录重新加载。
  
• 通过提供本地目录作为pretrained_model_name_or_path加载模型，并在目录中找到名为config.json的配置 JSON 文件。
  

• state_dict（Dict[str, torch.Tensor]，可选）— 一个状态字典，用于替代从保存的权重文件加载的状态字典。
  如果您想从预训练配置创建模型但加载自己的权重，则可以使用此选项。不过，在这种情况下，您应该检查是否使用 save_pretrained()和 from_pretrained()不是更简单的选项。
  
• cache_dir（Union[str, os.PathLike]，可选）— 下载预训练模型配置应缓存在其中的目录路径，如果不使用标准缓存。
  
• from_tf（bool，可选，默认为False) — 从 TensorFlow 检查点保存文件加载模型权重（请参阅pretrained_model_name_or_path参数的文档字符串）。
  
• from_flax（bool，可选，默认为False）— 从 Flax 检查点保存文件加载模型权重（请参阅pretrained_model_name_or_path参数的文档字符串）。
  
• ignore_mismatched_sizes（bool，可选，默认为False) — 如果检查点中的某些权重与模型的权重大小不同，是否引发错误（例如，您从具有 3 个标签的检查点实例化具有 10 个标签的模型）。
  
• force_download（bool，可选，默认为False）— 是否强制（重新）下载模型权重和配置文件，覆盖缓存版本（如果存在）。
  
• resume_download（bool，可选，默认为False) — 是否删除接收不完整的文件。如果存在这样的文件，将尝试恢复下载。
  
• proxies（Dict[str, str]，可选）— 一个代理服务器字典，按协议或端点使用，例如，{'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}。代理在每个请求上使用。
  
• output_loading_info(bool, 可选，默认为False) — 是否返回一个包含缺失键、意外键和错误消息的字典。
  
• local_files_only(bool, 可选，默认为False) — 是否仅查看本地文件（即，不尝试下载模型）。
  
• token（str或bool，可选）— 用作远程文件的 HTTP bearer 授权的令牌。如果为True或未指定，将使用运行huggingface-cli login时生成的令牌（存储在~/.huggingface中）。
  
• revision (str, 可选, 默认为 "main") — 要使用的特定模型版本。它可以是分支名称、标签名称或提交 ID，因为我们在 huggingface.co 上使用基于 git 的系统来存储模型和其他工件，所以 revision 可以是 git 允许的任何标识符。
  要测试您在 Hub 上创建的拉取请求，可以传递 `revision=“refs/pr/“。
  
• mirror (str, 可选) — 镜像源以加速中国的下载。如果您来自中国并且有访问问题，您可以设置此选项来解决。请注意，我们不保证及时性或安全性。请参考镜像站点获取更多信息。
  
• _fast_init(bool, 可选, 默认为 True) — 是否禁用快速初始化。
  为了确保与 transformers.__version__ < 4.6.0 的种子模型初始化向后兼容，应该只禁用 _fast_init。此参数将在下一个主要版本中删除。有关更多信息，请参阅拉取请求 11471。
  

大型模型推理的参数

• low_cpu_mem_usage(bool, 可选) — 尝试在加载模型时不使用超过 CPU 内存中的 1x 模型大小（包括峰值内存）。这是一个实验性功能，随时可能更改。
  
• torch_dtype (str 或 torch.dtype, 可选) — 覆盖默认的 torch.dtype 并在特定的 dtype 下加载模型。不同的选项有：

1. torch.float16 或 torch.bfloat16 或 torch.float: 以指定的 dtype 加载，忽略模型的 config.torch_dtype（如果存在）。如果未指定

• 模型将以 torch.float (fp32) 加载。

2. "auto" - 将尝试使用模型的 config.json 文件中的 torch_dtype 条目。如果找不到此条目，则下一个检查是检查点中第一个浮点类型的权重的 dtype 并将其用作 dtype。这将使用模型在训练结束时保存的 dtype 加载模型。它不能用作模型训练方式的指示器。因为它可能是在半精度 dtype 中训练，但以 fp32 保存。
   

• 对于一些模型，它们训练时使用的 dtype 是未知的 - 您可以尝试查看模型的论文或联系作者，并要求他们将此信息添加到模型的卡片中，并在 Hub 上的 config.json 中插入 torch_dtype 条目。
  
• device_map (str 或 Dict[str, Union[int, str, torch.device]] 或 int 或 torch.device, 可选) — 一个指定每个子模块应该放在哪里的映射。它不需要细化到每个参数/缓冲区名称，一旦给定模块名称在内，它的每个子模块都将被发送到同一设备。如果我们只传递模型将被分配的设备（例如，"cpu"、"cuda:1"、"mps"，或者像 1 这样的 GPU 序数等），设备映射将把整个模型映射到这个设备上。传递 device_map = 0 意味着将整个模型放在 GPU 0 上。
  让 Accelerate 自动计算最优化的 device_map，请设置 device_map="auto"。有关每个选项的更多信息，请参阅设计设备映射。
  
• max_memory (Dict, 可选) — 设备标识符到最大内存的字典。如果未设置，将默认为每个 GPU 可用的最大内存和可用的 CPU RAM。
  
• offload_folder (str 或 os.PathLike, 可选) — 如果 device_map 包含任何值 "disk"，则我们将卸载权重的文件夹。
  
• offload_state_dict (bool, 可选) — 如果为 True，将临时将 CPU 状态字典转移到硬盘，以避免 CPU RAM 不足，如果 CPU 状态字典的重量 + 检查点的最大分片不适合。当存在一些磁盘卸载时，默认为 True。
  
• load_in_8bit (bool, optional, 默认为 False) — 如果为True，将加载的模型转换为混合 8 位量化模型。要使用此功能，请安装bitsandbytes（pip install -U bitsandbytes）。
  
• load_in_4bit (bool, optional, 默认为 False) — 如果为True，将加载的模型转换为 4 位精度量化模型。要使用此功能，请安装最新版本的bitsandbytes（pip install -U bitsandbytes）。
  
• quantization_config (Union[QuantizationConfigMixin,Dict], 可选) — 量化的配置参数字典或 QuantizationConfigMixin 对象（例如 bitsandbytes, gptq）
  
• subfolder (str, optional, 默认为 "") — 如果相关文件位于 huggingface.co 模型仓库的子文件夹中，您可以在这里指定文件夹名称。
  
• variant (str, optional) — 如果指定，将从variant文件名加载权重，例如 pytorch_model..bin。在使用from_tf或from_flax时忽略variant。
  
• use_safetensors (bool, optional, 默认为 None) — 是否使用safetensors检查点。默认为None。如果未指定并且未安装safetensors，则将其设置为False。
  
• kwargs（剩余的关键字参数字典，可选） — 可用于更新配置对象（加载后）并初始化模型（例如，output_attentions=True）。根据是否提供了config或自动加载，行为会有所不同：

• 如果提供了配置config，**kwargs将直接传递给底层模型的__init__方法（我们假设配置的所有相关更新已经完成）
  
• 如果未提供配置，kwargs将首先传递给配置类初始化函数（from_pretrained()）。与配置属性对应的kwargs的每个键将用提供的kwargs值覆盖该属性。不对应任何配置属性的剩余键将传递给底层模型的__init__函数。
  

从预训练模型配置实例化一个预训练的 pytorch 模型。

默认情况下，模型以评估模式设置，使用model.eval()（Dropout 模块被停用）。要训练模型，您应该首先使用model.train()将其设置回训练模式。

警告Weights from XXX not initialized from pretrained model表示 XXX 的权重不是与模型的其余部分一起预训练的。您需要使用下游微调任务来训练这些权重。

警告Weights from XXX not used in YYY表示层 XXX 未被 YYY 使用，因此这些权重将被丢弃。

激活特殊的“离线模式”以在受防火墙保护的环境中使用此方法。

示例：

>>> from transformers import BertConfig, BertModel
>>> # Download model and configuration from huggingface.co and cache.
>>> model = BertModel.from_pretrained("bert-base-uncased")
>>> # Model was saved using *save_pretrained('./test/saved_model/')* (for example purposes, not runnable).
>>> model = BertModel.from_pretrained("./test/saved_model/")
>>> # Update configuration during loading.
>>> model = BertModel.from_pretrained("bert-base-uncased", output_attentions=True)
>>> assert model.config.output_attentions == True
>>> # Loading from a TF checkpoint file instead of a PyTorch model (slower, for example purposes, not runnable).
>>> config = BertConfig.from_json_file("./tf_model/my_tf_model_config.json")
>>> model = BertModel.from_pretrained("./tf_model/my_tf_checkpoint.ckpt.index", from_tf=True, config=config)
>>> # Loading from a Flax checkpoint file instead of a PyTorch model (slower)
>>> model = BertModel.from_pretrained("bert-base-uncased", from_flax=True)

• low_cpu_mem_usage算法：

这是一个使用约 1 倍模型大小 CPU 内存加载模型的实验性功能

以下是它的工作原理：

1. 保存我们拥有的 state_dict 键
   
2. 在创建模型之前删除 state_dict，因为后者需要 1 倍模型大小的 CPU 内存
   
3. 在实例化模型后，切换到元设备，所有将从加载的 state_dict 中替换的参数/缓冲区
   
4. 第二次加载 state_dict
   
5. 从 state_dict 中替换参数/缓冲区
   

目前，它无法处理 deepspeed ZeRO 阶段 3 并忽略加载错误

Transformers 4.37 中文文档（十四）（5）https://developer.aliyun.com/article/1564959