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
( 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
( 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
下加载模型。不同的选项有:
torch.float16
或torch.bfloat16
或torch.float
: 以指定的dtype
加载,忽略模型的config.torch_dtype
(如果存在)。如果未指定
- 模型将以
torch.float
(fp32) 加载。
"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 内存加载模型的实验性功能
以下是它的工作原理:
- 保存我们拥有的 state_dict 键
- 在创建模型之前删除 state_dict,因为后者需要 1 倍模型大小的 CPU 内存
- 在实例化模型后,切换到元设备,所有将从加载的 state_dict 中替换的参数/缓冲区
- 第二次加载 state_dict
- 从 state_dict 中替换参数/缓冲区
目前,它无法处理 deepspeed ZeRO 阶段 3 并忽略加载错误
Transformers 4.37 中文文档(十四)(5)https://developer.aliyun.com/article/1564959