Transformers 4.37 中文文档（十四）（4）https://developer.aliyun.com/article/1564958
get_input_embeddings
( ) → export const metadata = 'undefined';nn.Module
返回
nn.Module
将词汇映射到隐藏状态的 torch 模块。
返回模型的输入嵌入。
get_memory_footprint
( return_buffers = True )
参数
return_buffers（bool，可选，默认为True）— 是否在计算内存占用时返回缓冲张量的大小。缓冲区是不需要梯度且未注册为参数的张量。例如，批量归一化层中的均值和标准差。请参见：discuss.pytorch.org/t/what-pytorch-means-by-buffers/120266/2
获取模型的内存占用。这将以字节为单位返回当前模型的内存占用。有助于基准测试当前模型的内存占用并设计一些测试。解决方案灵感来自 PyTorch 讨论：discuss.pytorch.org/t/gpu-memory-that-model-uses/56822/2
get_output_embeddings
( ) → export const metadata = 'undefined';nn.Module
返回
nn.Module
将隐藏状态映射到词汇表的 torch 模块。
返回模型的输出嵌入。
gradient_checkpointing_disable
( )
为当前模型停用梯度检查点。
请注意，在其他框架中，此功能可能被称为“激活检查点”或“检查点激活”。
gradient_checkpointing_enable
( gradient_checkpointing_kwargs = None )
参数
gradient_checkpointing_kwargs（字典，可选）— 传递给torch.utils.checkpoint.checkpoint函数的附加关键字参数。
为当前模型激活梯度检查点。
请注意，在其他框架中，此功能可能被称为“激活检查点”或“检查点激活”。
我们传递模块的__call__方法而不是forward，因为__call__会附加模块的所有钩子。discuss.pytorch.org/t/any-different-between-model-input-and-model-forward-input/3690/2
init_weights
( )
如果需要修剪并可能初始化权重。如果使用自定义PreTrainedModel，则需要在_init_weights中实现任何初始化逻辑。
post_init
( )
在每个 Transformer 模型初始化结束时执行的方法，用于执行需要模型模块正确初始化的代码（例如权重初始化）。
prune_heads
( heads_to_prune: Dict )
参数
heads_to_prune（Dict[int, List[int]]）— 键为选定的层索引（int）的字典，相关值为该层中要修剪的头部列表（int的列表）。例如{1: [0, 2]，2: [2, 3]}将在第 1 层修剪头部 0 和 2，在第 2 层修剪头部 2 和 3。
修剪基本模型的头部。
register_for_auto_class
( auto_class = 'AutoModel' )
参数
auto_class（str或type，可选，默认为"AutoModel"）— 要注册此新模型的自动类。
将此类与给定的自动类注册。这仅应用于自定义模型，因为库中的模型已经与自动类映射。
此 API 是实验性的，可能在下一个版本中有一些轻微的破坏性更改。
resize_token_embeddings
( new_num_tokens: Optional = None pad_to_multiple_of: Optional = None ) → export const metadata = 'undefined';torch.nn.Embedding
参数
new_num_tokens(int, optional) — 嵌入矩阵中的新标记数。增加大小将在末尾添加新初始化的向量。减小大小将从末尾删除向量。如果未提供或为None，则只返回指向模型的输入标记torch.nn.Embedding模块的指针，而不执行任何操作。pad_to_multiple_of(int, optional) — 如果设置，将填充嵌入矩阵到提供的值的倍数。如果new_num_tokens设置为None，则只会将嵌入填充到pad_to_multiple_of的倍数。
这对于启用 NVIDIA 硬件上的 Tensor Cores 特别有用，计算能力>= 7.5（Volta），或者对于受益于序列长度为 128 的倍数的 TPUs。有关此更多详细信息，或者有关选择调整大小的正确值的帮助，请参阅此指南：docs.nvidia.com/deeplearning/performance/dl-performance-matrix-multiplication/index.html#requirements-tc
返回
torch.nn.Embedding
指向模型的输入标记嵌入模块。
如果new_num_tokens != config.vocab_size，则调整模型的输入标记嵌入矩阵的大小。
在模型类具有tie_weights()方法时负责绑定权重嵌入。
reverse_bettertransformer
( ) → export const metadata = 'undefined';PreTrainedModel
返回
PreTrainedModel
将模型转换回原始建模。
撤消从 to_bettertransformer()的转换，以便使用原始建模，例如为了保存模型。
save_pretrained
( save_directory: Union is_main_process: bool = True state_dict: Optional = None save_function: Callable = <function save at 0x7f3c5f9b0160> push_to_hub: bool = False max_shard_size: Union = '5GB' safe_serialization: bool = True variant: Optional = None token: Union = None save_peft_format: bool = True **kwargs )
参数
save_directory（str或os.PathLike） — 要保存到的目录。如果不存在，将创建该目录。is_main_process(bool, optional, 默认为True) — 调用此函数的进程是否为主进程。在像 TPU 这样的分布式训练中很有用，需要在所有进程上调用此函数。在这种情况下，仅在主进程上设置is_main_process=True，以避免竞争条件。state_dict（torch.Tensor的嵌套字典） — 要保存的模型的状态字典。将默认为self.state_dict()，但可以用于仅保存模型的部分或者在恢复模型的状态字典时需要采取特殊预防措施的情况（例如在使用模型并行时）。save_function(Callable) — 用于保存状态字典的函数。在像 TPU 这样的分布式训练中很有用，当需要用另一种方法替换torch.save时。push_to_hub(bool, optional, 默认为False) — 是否在保存后将模型推送到 Hugging Face 模型中心。您可以使用repo_id指定要推送到的存储库（将默认为您的命名空间中的save_directory的名称）。max_shard_size(int或str，optional，默认为"5GB") — 在分片之前的检查点的最大大小。然后，检查点分片的大小将小于此大小。如果表示为字符串，需要是数字后跟一个单位（如"5MB"）。我们将其默认为 5GB，以便模型能够在免费的 Google Colab 实例上轻松运行，而不会出现 CPU OOM 问题。
如果模型的单个权重大于max_shard_size，则它将在自己的检查点分片中，该分片将大于max_shard_size。safe_serialization(bool, optional, 默认为True) — 是否使用safetensors或传统的 PyTorch 方式（使用pickle）保存模型。variant(str, 可选) — 如果指定，权重将以 pytorch_model..bin 的格式保存。token(str或bool, 可选) — 用作远程文件的 HTTP bearer 授权的令牌。如果为True，或未指定，将使用运行huggingface-cli login时生成的令牌（存储在~/.huggingface中）。save_peft_format(bool, 可选, 默认为True) — 为了向后兼容 PEFT 库，如果适配器权重附加到模型上，适配器状态字典的所有键都需要以base_model.model为前缀。高级用户可以通过将save_peft_format设置为False来禁用此行为。kwargs(Dict[str, Any], 可选) — 传递给 push_to_hub() 方法的额外关键字参数。
将模型及其配置文件保存到目录中，以便可以使用 from_pretrained() 类方法重新加载。
set_input_embeddings
( value: Module )
参数
value(nn.Module) — 将词汇映射到隐藏状态的模块。
设置模型的输入嵌入。
tie_weights
( )
将输入嵌入和输出嵌入之间的权重绑定在一起。
如果配置中设置了 torchscript 标志，则无法处理参数共享，因此我们会克隆权重。
to_bettertransformer
( ) → export const metadata = 'undefined';PreTrainedModel
返回
PreTrainedModel
转换为 BetterTransformer 的模型。
将模型转换为使用PyTorch 的本机注意力实现，通过Optimum 库集成到 Transformers 中。仅支持所有 Transformers 模型的子集。
PyTorch 的注意力快速路径允许通过内核融合和使用嵌套张量加速推理。详细的基准测试可以在这篇博文中找到。
warn_if_padding_and_no_attention_mask
( input_ids attention_mask )
如果输入的 input_ids 看起来包含填充并且没有给出注意力掩码，则显示一次警告。
大型模型加载
在 Transformers 4.20.0 中，from_pretrained() 方法已经重新设计，以适应使用Accelerate的大型模型。这需要 Accelerate >= 0.9.0 和 PyTorch >= 1.9.0。与其在内存中创建完整模型，然后加载预训练权重（这需要模型大小的两倍的内存，一个用于随机初始化模型，一个用于权重），现在有一个选项可以创建模型作为空壳，然后只有在加载预训练权重时才实现其参数。
可以通过 low_cpu_mem_usage=True 激活此选项。模型首先在 Meta 设备上创建（带有空权重），然后状态字典被加载到其中（在分片检查点的情况下逐个分片）。这样，最大使用的 RAM 仅为模型的完整大小。
from transformers import AutoModelForSeq2SeqLM t0pp = AutoModelForSeq2SeqLM.from_pretrained("bigscience/T0pp", low_cpu_mem_usage=True)
此外，如果模型无法完全适应 RAM（目前仅适用于推断），则可以直接将模型放置在不同的设备上。使用device_map="auto"，Accelerate 将确定将每个层放置在哪里以最大化您最快的设备（GPU）的使用，并将其余部分卸载到 CPU，甚至硬盘，如果您没有足够的 GPU RAM（或 CPU RAM）。即使模型分布在多个设备上，它也将按照您通常的预期运行。
在传递device_map时，low_cpu_mem_usage会自动设置为True，因此您无需指定它：
from transformers import AutoModelForSeq2SeqLM t0pp = AutoModelForSeq2SeqLM.from_pretrained("bigscience/T0pp", device_map="auto")
您可以查看hf_device_map属性来查看模型如何分布在设备上：
t0pp.hf_device_map
{'shared': 0, 'decoder.embed_tokens': 0, 'encoder': 0, 'decoder.block.0': 0, 'decoder.block.1': 1, 'decoder.block.2': 1, 'decoder.block.3': 1, 'decoder.block.4': 1, 'decoder.block.5': 1, 'decoder.block.6': 1, 'decoder.block.7': 1, 'decoder.block.8': 1, 'decoder.block.9': 1, 'decoder.block.10': 1, 'decoder.block.11': 1, 'decoder.block.12': 1, 'decoder.block.13': 1, 'decoder.block.14': 1, 'decoder.block.15': 1, 'decoder.block.16': 1, 'decoder.block.17': 1, 'decoder.block.18': 1, 'decoder.block.19': 1, 'decoder.block.20': 1, 'decoder.block.21': 1, 'decoder.block.22': 'cpu', 'decoder.block.23': 'cpu', 'decoder.final_layer_norm': 'cpu', 'decoder.dropout': 'cpu', 'lm_head': 'cpu'}
您还可以按照相同格式编写自己的设备映射（将层名称映射到设备的字典）。它应该将模型的所有参数映射到给定设备，但如果该层完全位于同一设备上，则不必详细说明一个层的所有子模块去哪里。例如，以下设备映射对于 T0pp 将正常工作（只要您有 GPU 内存）：
device_map = {"shared": 0, "encoder": 0, "decoder": 1, "lm_head": 1}
减少模型内存影响的另一种方法是以较低精度 dtype（如torch.float16）实例化模型，或者使用下面描述的直接量化技术。
模型实例化 dtype
在 Pytorch 下，模型通常以torch.float32格式实例化。如果尝试加载权重为 fp16 的模型，则可能会出现问题，因为它将需要两倍的内存。为了克服这个限制，您可以使用torch_dtype参数显式传递所需的dtype：
model = T5ForConditionalGeneration.from_pretrained("t5", torch_dtype=torch.float16)
或者，如果希望模型始终以最佳内存模式加载，可以使用特殊值"auto"，然后dtype将自动从模型的权重中派生：
model = T5ForConditionalGeneration.from_pretrained("t5", torch_dtype="auto")
从头开始实例化的模型也可以指定使用的dtype：
config = T5Config.from_pretrained("t5") model = AutoModel.from_config(config)
由于 Pytorch 设计，此功能仅适用于浮点 dtype。
ModuleUtilsMixin
class transformers.modeling_utils.ModuleUtilsMixin
( )
用作 mixin 的torch.nn.Modules的一些实用程序。
add_memory_hooks
( )
在每个子模块正向传递之前和之后添加内存钩子以记录内存消耗的增加。
内存消耗的增加存储在每个模块的mem_rss_diff属性中，并可以使用model.reset_memory_hooks_state()将其重置为零。
estimate_tokens
( input_dict: Dict ) → export const metadata = 'undefined';int
参数
inputs（dict）— 模型输入。
返回
int
令牌的总数。
用于估计模型输入中总令牌数的辅助函数。
floating_point_ops
( input_dict: Dict exclude_embeddings: bool = True ) → export const metadata = 'undefined';int
参数
batch_size（int）— 正向传递的批量大小。sequence_length（int）— 每个批次行中的令牌数。exclude_embeddings（bool，可选，默认为True）— 是否计算嵌入和 softmax 操作。
返回
int
浮点运算的数量。
使用此转换器模型的批处理的正向和反向传递的浮点操作的数量（可选，非嵌入）。默认近似忽略对令牌数量的二次依赖（如果12 * d_model << sequence_length）如本文第 2.1 节所述。对于具有参数重用的变压器（例如 Albert 或通用变压器）或者如果使用非常高的序列长度进行长距离建模，则应该进行覆盖。
get_extended_attention_mask
( attention_mask: Tensor input_shape: Tuple device: device = None dtype: torch.float32 = None )
参数
attention_mask(torch.Tensor) — 一个掩码，其中的 1 表示要关注的标记，0 表示要忽略的标记。input_shape(Tuple[int]) — 模型的输入形状。
使可广播的注意力和因果掩码，以便将来和掩码的标记被忽略。
get_head_mask
( head_mask: Optional num_hidden_layers: int is_attention_chunked: bool = False )
参数
head_mask(torch.Tensor，形状为[num_heads]或[num_hidden_layers x num_heads]，可选) — 指示我们是否应保留头部的掩码（保留为 1.0，丢弃为 0.0）。num_hidden_layers(int) — 模型中的隐藏层数量。is_attention_chunked(bool, 可选, 默认为False) — 注意力分数是否按块计算。
如果需要，准备头掩码。
invert_attention_mask
( encoder_attention_mask: Tensor ) → export const metadata = 'undefined';torch.Tensor
参数
encoder_attention_mask(torch.Tensor) — 一个注意力掩码。
返回
torch.Tensor
反转的注意力掩码。
反转注意力掩码（例如，切换 0 和 1）。
num_parameters
( only_trainable: bool = False exclude_embeddings: bool = False ) → export const metadata = 'undefined';int
参数
only_trainable(bool, 可选, 默认为False) — 是否只返回可训练参数的数量exclude_embeddings(bool, 可选, 默认为False) — 是否只返回非嵌入参数的数量
返回
int
参数的数量。
获取模块中（可选地，可训练或非嵌入）参数的数量。
reset_memory_hooks_state
( )
重置每个模块的mem_rss_diff属性（参见 add_memory_hooks()）。
Transformers 4.37 中文文档（十四）（6）https://developer.aliyun.com/article/1564960
