Transformers--4-37-中文文档-四十八-

Transformers 4.37 中文文档（四十八）

原文：huggingface.co/docs/transformers

PatchTST

原文链接：huggingface.co/docs/transformers/v4.37.2/en/model_doc/patchtst

概述

PatchTST 模型由 Yuqi Nie、Nam H. Nguyen、Phanwadee Sinthong 和 Jayant Kalagnanam 在A Time Series is Worth 64 Words: Long-term Forecasting with Transformers中提出。

在高层次上，该模型将时间序列向量化为给定大小的补丁，并通过一个 Transformer 对生成的向量序列进行编码，然后通过适当的头部输出预测长度的预测。该模型如下图所示：

论文摘要如下：

我们提出了一种用于多变量时间序列预测和自监督表示学习的基于 Transformer 的模型的高效设计。它基于两个关键组件：(i) 将时间序列分割为子系列级别的补丁，这些补丁作为输入标记提供给 Transformer；(ii) 通道独立性，其中每个通道包含一个单变量时间序列，共享相同的嵌入和 Transformer 权重。补丁设计自然具有三重好处：在嵌入中保留局部语义信息；在给定相同回顾窗口的情况下，注意力图的计算和内存使用量呈二次减少；模型可以关注更长的历史。我们的通道独立补丁时间序列 Transformer（PatchTST）可以显著提高长期预测的准确性，与 SOTA 基于 Transformer 的模型相比。我们还将我们的模型应用于自监督预训练任务，并获得出色的微调性能，优于大型数据集上的监督训练。将一个数据集上的掩码预训练表示转移到其他数据集也会产生 SOTA 的预测准确性。

该模型由namctin、gsinthong、diepi、vijaye12、wmgifford和kashif贡献。原始代码可在此处找到。

使用提示

该模型还可用于时间序列分类和时间序列回归。请参阅相应的 PatchTSTForClassification 和 PatchTSTForRegression 类。

PatchTSTConfig

class transformers.PatchTSTConfig

<来源>

( num_input_channels: int = 1 context_length: int = 32 distribution_output: str = 'student_t' loss: str = 'mse' patch_length: int = 1 patch_stride: int = 1 num_hidden_layers: int = 3 d_model: int = 128 num_attention_heads: int = 4 share_embedding: bool = True channel_attention: bool = False ffn_dim: int = 512 norm_type: str = 'batchnorm' norm_eps: float = 1e-05 attention_dropout: float = 0.0 dropout: float = 0.0 positional_dropout: float = 0.0 path_dropout: float = 0.0 ff_dropout: float = 0.0 bias: bool = True activation_function: str = 'gelu' pre_norm: bool = True positional_encoding_type: str = 'sincos' use_cls_token: bool = False init_std: float = 0.02 share_projection: bool = True scaling: Union = 'std' do_mask_input: Optional = None mask_type: str = 'random' random_mask_ratio: float = 0.5 num_forecast_mask_patches: Union = [2] channel_consistent_masking: Optional = False unmasked_channel_indices: Optional = None mask_value: int = 0 pooling_type: str = 'mean' head_dropout: float = 0.0 prediction_length: int = 24 num_targets: int = 1 output_range: Optional = None num_parallel_samples: int = 100 **kwargs )

参数

• num_input_channels (int, optional, 默认为 1) — 目标变量的大小，默认情况下为单变量目标的 1。在多变量目标的情况下会大于 1。

• context_length (int, optional, 默认为 32) — 输入序列的上下文长度。

• distribution_output (str, optional, 默认为"student_t") — 当损失为“nll”时，模型的分布发射头。可以是"student_t"、“normal”或“negative_binomial”之一。

• loss (str, optional, 默认为"mse") — 与distribution_output头部对应的模型损失函数。对于参数分布，为负对数似然（“nll”），对于点估计，为均方误差"mse"。

• patch_length (int, optional, 默认为 1) — 定义补丁化过程的补丁长度。

• patch_stride (int, optional, 默认为 1) — 定义补丁化过程的步幅。

• num_hidden_layers (int, optional, 默认为 3) — 隐藏层的数量。

• d_model (int, optional, 默认为 128) — Transformer 层的维度。

• num_attention_heads (int, optional, 默认为 4) — Transformer 编码器中每个注意力层的注意力头数。

• share_embedding (bool, optional, 默认为True) — 在所有通道之间共享输入嵌入。

• channel_attention (bool, optional, 默认为False) — 激活 Transformer 中的通道注意力块，允许通道相互关注。

• ffn_dim (int, optional, 默认为 512) — Transformer 编码器中“中间”（通常称为前馈）层的维度。

• norm_type (str , optional, 默认为"batchnorm") — 每个 Transformer 层的归一化。可以是"batchnorm"或"layernorm"。

• norm_eps (float, optional, 默认为 1e-05) — 添加到归一化分母以提高数值稳定性的值。

• attention_dropout (float, optional, 默认为 0.0) — 注意力概率的 dropout 概率。

• dropout (float, optional, 默认为 0.0) — Transformer 中所有全连接层的 dropout 概率。

• positional_dropout (float, optional, 默认为 0.0) — 位置嵌入层中的 dropout 概率。

• path_dropout (float, optional, 默认为 0.0) — 残差块中的路径 dropout。

• ff_dropout (float, optional, 默认为 0.0) — 在前馈网络的两层之间使用的 dropout 概率。

• bias (bool, optional, 默认为True) — 是否在前馈网络中添加偏置。

• activation_function (str, optional, 默认为"gelu") — Transformer 中的非线性激活函数（字符串）。支持"gelu"和"relu"。

• pre_norm (bool, optional, 默认为True) — 如果pre_norm设置为True，则在自注意力之前应用归一化。否则，在残差块之后应用归一化。

• positional_encoding_type (str, optional, 默认为"sincos") — 位置编码。支持选项"random"和"sincos"。

• use_cls_token (bool, optional, 默认为False) — 是否使用 cls 标记。

• init_std (float, optional, 默认为 0.02) — 截断正态权重初始化分布的标准差。

• share_projection (bool, optional, 默认为True) — 在预测头部中跨不同通道共享投影层。

• scaling (Union, optional, 默认为"std") — 是否通过“mean”缩放器、"std"缩放器或如果为None则不缩放来缩放输入目标。如果为True，则缩放器设置为“mean”。

• do_mask_input (bool, optional) — 在预训练期间应用屏蔽。

• mask_type (str, optional, 默认为"random") — 屏蔽类型。目前仅支持"random"和"forecast"。

• random_mask_ratio (float, optional, 默认为 0.5) — 用于在随机预训练期间屏蔽输入数据的屏蔽比例。

• num_forecast_mask_patches (int或list, optional, 默认为[2]) — 每个批次样本末尾要屏蔽的补丁数量。如果是整数，则批次中的所有样本将具有相同数量的屏蔽补丁。如果是列表，则批次中的样本将被随机屏蔽，屏蔽数量由列表中定义。此参数仅用于预测预训练。

• channel_consistent_masking (bool, optional, 默认为False) — 如果通道一致屏蔽为 True，则所有通道将具有相同的屏蔽模式。

• unmasked_channel_indices (list, optional) — 未在预训练期间屏蔽的通道索引。列表中的值为 1 到num_input_channels之间的数字。

• mask_value (int, optional, 默认为 0) — 屏蔽补丁中的值将被mask_value填充。

• pooling_type (str, optional, 默认为"mean") — 嵌入的池化。支持"mean"、"max"和None。

• head_dropout (float, optional, 默认为 0.0) — 头部的 dropout 概率。

• prediction_length（int，可选，默认为 24）— 模型将输出的预测时间范围。

• num_targets（int，可选，默认为 1）— 回归和分类任务的目标数量。对于分类，它是类的数量。

• output_range（list，可选）— 回归任务的输出范围。可以设置输出值的范围以强制模型生成在范围内的值。

• num_parallel_samples（int，可选，默认为 100）— 并行生成的样本数，用于概率预测。

这是配置类，用于存储 PatchTSTModel 的配置。它用于根据指定的参数实例化 PatchTST 模型，定义模型架构。ibm/patchtst 架构。

配置对象继承自 PretrainedConfig 可用于控制模型输出。阅读 PretrainedConfig 的文档以获取更多信息。

>>> from transformers import PatchTSTConfig, PatchTSTModel

>>> # Initializing an PatchTST configuration with 12 time steps for prediction
>>> configuration = PatchTSTConfig(prediction_length=12)

>>> # Randomly initializing a model (with random weights) from the configuration
>>> model = PatchTSTModel(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config

PatchTSTModel

class transformers.PatchTSTModel

< source >

( config: PatchTSTConfig )

参数

• config（PatchTSTConfig）— 具有模型所有参数的模型配置类。使用配置文件初始化不会加载与模型关联的权重，只加载配置。查看 from_pretrained() 方法以加载模型权重。

裸 PatchTST 模型输出原始隐藏状态，没有特定的头。该模型继承自 PreTrainedModel。查看超类文档以了解库为所有模型实现的通用方法（如下载或保存、调整输入嵌入、修剪头等）。

该模型也是 PyTorch torch.nn.Module 的子类。将其用作常规 PyTorch 模块，并参考 PyTorch 文档以获取有关一般用法和行为的所有相关信息。

forward

< source >

( past_values: Tensor past_observed_mask: Optional = None future_values: Optional = None output_hidden_states: Optional = None output_attentions: Optional = None return_dict: Optional = None )

参数

• past_values（形状为 (bs, sequence_length, num_input_channels) 的 torch.Tensor，必需）— 输入序列到模型

• past_observed_mask（形状为 (batch_size, sequence_length, num_input_channels) 的 torch.BoolTensor，可选）— 布尔掩码，指示哪些 past_values 被观察到，哪些是缺失的。掩码值选在 [0, 1]：

  • 1 表示 观察到 的值，

  • 0 表示 缺失 的值（即被零替换的 NaN）。

• future_values（形状为 (batch_size, prediction_length, num_input_channels) 的 torch.BoolTensor，可选）— 与 past_values 相关的未来目标值

• output_hidden_states（bool，可选）— 是否返回所有层的隐藏状态

• output_attentions（bool，可选）— 是否返回所有层的输出注意力

• return_dict（bool，可选）— 是否返回 ModelOutput 而不是普通元组。

示例：

>>> from huggingface_hub import hf_hub_download
>>> import torch
>>> from transformers import PatchTSTModel

>>> file = hf_hub_download(
...     repo_id="hf-internal-testing/etth1-hourly-batch", filename="train-batch.pt", repo_type="dataset"
... )
>>> batch = torch.load(file)

>>> model = PatchTSTModel.from_pretrained("namctin/patchtst_etth1_pretrain")

>>> # during training, one provides both past and future values
>>> outputs = model(
...     past_values=batch["past_values"],
...     future_values=batch["future_values"],
... )

>>> last_hidden_state = outputs.last_hidden_state

PatchTSTForPrediction

class transformers.PatchTSTForPrediction

< source >

( config: PatchTSTConfig )

参数

• config (PatchTSTConfig) — 具有模型所有参数的模型配置类。使用配置文件初始化不会加载与模型相关的权重，只加载配置。查看 from_pretrained()方法以加载模型权重。

用于预测的 PatchTST 模型。该模型继承自 PreTrainedModel。查看超类文档，了解库实现的所有模型的通用方法（如下载或保存、调整输入嵌入、修剪头等）。

该模型也是 PyTorch torch.nn.Module子类。将其用作常规 PyTorch 模块，并参考 PyTorch 文档以获取有关一般用法和行为的所有相关信息。

forward

<来源>

( past_values: Tensor past_observed_mask: Optional = None future_values: Optional = None output_hidden_states: Optional = None output_attentions: Optional = None return_dict: Optional = None )

参数

• past_values (torch.Tensor，形状为(bs, sequence_length, num_input_channels)，required) — 输入序列到模型

• past_observed_mask (torch.BoolTensor，形状为(batch_size, sequence_length, num_input_channels)，optional) — 布尔掩码，指示哪些past_values是观察到的，哪些是缺失的。掩码值选在[0, 1]范围内：

  • 1 表示观察到的值，

  • 0 表示缺失的值（即用零替换的 NaN）。

• future_values (torch.Tensor，形状为(bs, forecast_len, num_input_channels)，optional) — 与past_values相关联的未来目标值

• output_hidden_states (bool, optional) — 是否返回所有层的隐藏状态

• output_attentions (bool, optional) — 是否返回所有层的注意力输出

• return_dict (bool, optional) — 是否返回ModelOutput而不是普通元组。

示例：

>>> from huggingface_hub import hf_hub_download
>>> import torch
>>> from transformers import PatchTSTConfig, PatchTSTForPrediction

>>> file = hf_hub_download(
...     repo_id="hf-internal-testing/etth1-hourly-batch", filename="train-batch.pt", repo_type="dataset"
... )
>>> batch = torch.load(file)

>>> # Prediction task with 7 input channels and prediction length is 96
>>> model = PatchTSTForPrediction.from_pretrained("namctin/patchtst_etth1_forecast")

>>> # during training, one provides both past and future values
>>> outputs = model(
...     past_values=batch["past_values"],
...     future_values=batch["future_values"],
... )

>>> loss = outputs.loss
>>> loss.backward()

>>> # during inference, one only provides past values, the model outputs future values
>>> outputs = model(past_values=batch["past_values"])
>>> prediction_outputs = outputs.prediction_outputs

PatchTSTForClassification

class transformers.PatchTSTForClassification

<来源>

( config: PatchTSTConfig )

参数

• config (PatchTSTConfig) — 具有模型所有参数的模型配置类。使用配置文件初始化不会加载与模型相关的权重，只加载配置。查看 from_pretrained()方法以加载模型权重。

用于分类的 PatchTST 模型。该模型继承自 PreTrainedModel。查看超类文档，了解库实现的所有模型的通用方法（如下载或保存、调整输入嵌入、修剪头等）。

该模型也是 PyTorch torch.nn.Module子类。将其用作常规 PyTorch 模块，并参考 PyTorch 文档以获取有关一般用法和行为的所有相关信息。

forward

<来源>

( past_values: Tensor target_values: Tensor = None past_observed_mask: Optional = None output_hidden_states: Optional = None output_attentions: Optional = None return_dict: Optional = None )

参数

• past_values (torch.Tensor，形状为(bs, sequence_length, num_input_channels)，required) — 输入序列到模型

• target_values (torch.Tensor, optional) — 与past_values相关联的标签

• past_observed_mask (torch.BoolTensor，形状为(batch_size, sequence_length, num_input_channels)，optional) — 布尔掩码，指示哪些past_values是观察到的，哪些是缺失的。掩码值选在[0, 1]范围内：

  • 1 表示值是observed，

  • 对于missing的值（即被零替换的 NaN）为 0。

• output_hidden_states（bool，可选）-是否返回所有层的隐藏状态

• output_attentions（bool，可选）-是否返回所有层的输出注意力

• return_dict（bool，可选）-是否返回ModelOutput而不是普通元组。

示例：

>>> from transformers import PatchTSTConfig, PatchTSTForClassification

>>> # classification task with two input channel2 and 3 classes
>>> config = PatchTSTConfig(
...     num_input_channels=2,
...     num_targets=3,
...     context_length=512,
...     patch_length=12,
...     stride=12,
...     use_cls_token=True,
... )
>>> model = PatchTSTForClassification(config=config)

>>> # during inference, one only provides past values
>>> past_values = torch.randn(20, 512, 2)
>>> outputs = model(past_values=past_values)
>>> labels = outputs.prediction_logits

PatchTSTForPretraining

class transformers.PatchTSTForPretraining

<来源>

( config: PatchTSTConfig )

参数

• config（PatchTSTConfig](/docs/transformers/v4.37.2/en/main_classes/model#transformers.PreTrainedModel.from_pretrained)方法以加载模型权重。

用于预训练模型的 PatchTST。此模型继承自 PreTrainedModel。查看超类文档以了解库为所有模型实现的通用方法（如下载或保存，调整输入嵌入，修剪头等）。

此模型也是 PyTorch torch.nn.Module子类。将其用作常规 PyTorch 模块，并参考 PyTorch 文档以了解所有与一般使用和行为相关的事项。

forward

<来源>

( past_values: Tensor past_observed_mask: Optional = None output_hidden_states: Optional = None output_attentions: Optional = None return_dict: Optional = None )

参数

• past_values（形状为(bs, sequence_length, num_input_channels)的torch.Tensor，必需）-输入序列到模型

• past_observed_mask（形状为(batch_size, sequence_length, num_input_channels)的torch.BoolTensor，可选）-布尔掩码，指示哪些past_values是观察到的，哪些是缺失的。掩码值选在[0, 1]中：

  • 1 表示值是observed，

  • 对于missing的值（即被零替换的 NaN）为 0。

• output_hidden_states（bool，可选）-是否返回所有层的隐藏状态

• output_attentions（bool，可选）-是否返回所有层的输出注意力

• return_dict（bool，可选）-是否返回ModelOutput而不是普通元组。

示例：

>>> from huggingface_hub import hf_hub_download
>>> import torch
>>> from transformers import PatchTSTConfig, PatchTSTForPretraining

>>> file = hf_hub_download(
...     repo_id="hf-internal-testing/etth1-hourly-batch", filename="train-batch.pt", repo_type="dataset"
... )
>>> batch = torch.load(file)

>>> # Config for random mask pretraining
>>> config = PatchTSTConfig(
...     num_input_channels=7,
...     context_length=512,
...     patch_length=12,
...     stride=12,
...     mask_type='random',
...     random_mask_ratio=0.4,
...     use_cls_token=True,
... )
>>> # Config for forecast mask pretraining
>>> config = PatchTSTConfig(
...     num_input_channels=7,
...     context_length=512,
...     patch_length=12,
...     stride=12,
...     mask_type='forecast',
...     num_forecast_mask_patches=5,
...     use_cls_token=True,
... )
>>> model = PatchTSTForPretraining(config)

>>> # during training, one provides both past and future values
>>> outputs = model(past_values=batch["past_values"])

>>> loss = outputs.loss
>>> loss.backward()

PatchTSTForRegression

class transformers.PatchTSTForRegression

<来源>

( config: PatchTSTConfig )

参数

• config（PatchTSTConfig](/docs/transformers/v4.37.2/en/main_classes/model#transformers.PreTrainedModel.from_pretrained)方法以加载模型权重。

用于回归模型的 PatchTST。此模型继承自 PreTrainedModel。查看超类文档以了解库为所有模型实现的通用方法（如下载或保存，调整输入嵌入，修剪头等）。

此模型也是 PyTorch torch.nn.Module子类。将其用作常规 PyTorch 模块，并参考 PyTorch 文档以了解所有与一般使用和行为相关的事项。

forward

<来源>

( past_values: Tensor target_values: Tensor = None past_observed_mask: Optional = None output_hidden_states: Optional = None output_attentions: Optional = None return_dict: Optional = None )

参数

• past_values (torch.Tensor of shape (bs, sequence_length, num_input_channels), required) — 输入模型的序列

• target_values (torch.Tensor of shape (bs, num_input_channels)) — 与past_values相关联的目标值

• past_observed_mask (torch.BoolTensor of shape (batch_size, sequence_length, num_input_channels), optional) — 布尔掩码，指示哪些past_values是观察到的，哪些是缺失的。掩码值选在[0, 1]之间：

  • 1 表示观察到的值，

  • 0 表示缺失的值（即被零替换的 NaN）。

• output_hidden_states (bool, optional) — 是否返回所有层的隐藏状态

• output_attentions (bool, optional) — 是否返回所有层的输出注意力

• return_dict (bool, optional) — 是否返回一个ModelOutput而不是一个普通的元组。

示例：

>>> from transformers import PatchTSTConfig, PatchTSTForRegression

>>> # Regression task with 6 input channels and regress 2 targets
>>> model = PatchTSTForRegression.from_pretrained("namctin/patchtst_etth1_regression")

>>> # during inference, one only provides past values, the model outputs future values
>>> past_values = torch.randn(20, 512, 6)
>>> outputs = model(past_values=past_values)
>>> regression_outputs = outputs.regression_outputs

时间序列 Transformer

原始文本：huggingface.co/docs/transformers/v4.37.2/en/model_doc/time_series_transformer

概述

时间序列 Transformer 模型是用于时间序列预测的基本编码器-解码器 Transformer。此模型由kashif贡献。

使用提示

• 与库中其他模型类似，TimeSeriesTransformerModel 是没有顶部头部的原始 Transformer，而 TimeSeriesTransformerForPrediction 在前者的顶部添加了一个分布头部，可用于时间序列预测。请注意，这是一种所谓的概率预测模型，而不是点预测模型。这意味着模型学习一个分布，可以从中进行采样。该模型不直接输出值。

• TimeSeriesTransformerForPrediction 由 2 个模块组成：编码器，接受时间序列值的context_length作为输入（称为past_values），解码器，预测未来的prediction_length时间序列值（称为future_values）。在训练过程中，需要向模型提供（past_values和future_values）的配对数据。

• 除了原始的（past_values和future_values）之外，通常还向模型提供其他特征。这些可以是以下内容：

  • past_time_features：模型将添加到past_values的时间特征。这些作为 Transformer 编码器的“位置编码”。例如，“月份的日期”，“年份的月份”等作为标量值（然后堆叠在一起形成向量）。例如，如果给定的时间序列值是在 8 月 11 日获得的，则可以将[11, 8]作为时间特征向量（11 代表“月份的日期”，8 代表“年份的月份”）。

  • future_time_features：模型将添加到future_values的时间特征。这些作为 Transformer 解码器的“位置编码”。例如，“月份的日期”，“年份的月份”等作为标量值（然后堆叠在一起形成向量）。例如，如果给定的时间序列值是在 8 月 11 日获得的，则可以将[11, 8]作为时间特征向量（11 代表“月份的日期”，8 代表“年份的月份”）。

  • static_categorical_features：随时间保持不变的分类特征（即所有past_values和future_values具有相同的值）。一个例子是标识给定时间序列的商店 ID 或地区 ID。请注意，这些特征需要对所有数据点（包括未来的数据点）都是已知的。

  • static_real_features：随时间保持不变的实值特征（即所有past_values和future_values具有相同的值）。一个例子是产品的图像表示，您拥有该产品的时间序列值（比如关于鞋子销售的时间序列的 ResNet 嵌入的“鞋子”图片）。请注意，这些特征需要对所有数据点（包括未来的数据点）都是已知的。

• 该模型使用“teacher-forcing”进行训练，类似于 Transformer 用于机器翻译的训练方式。这意味着在训练过程中，将future_values向右移动一个位置作为解码器的输入，前面加上past_values的最后一个值。在每个时间步骤，模型需要预测下一个目标。因此，训练的设置类似于用于语言的 GPT 模型，只是没有decoder_start_token_id的概念（我们只使用上下文的最后一个值作为解码器的初始输入）。

• 在推断时，我们将past_values的最终值作为输入传递给解码器。接下来，我们可以从模型中进行采样，以在下一个时间步骤进行预测，然后将其馈送给解码器以进行下一个预测（也称为自回归生成）。

资源

一系列官方 Hugging Face 和社区（由🌎表示）资源，可帮助您入门。如果您有兴趣提交资源以包含在此处，请随时打开一个 Pull Request，我们将进行审查！资源应该展示一些新内容，而不是重复现有资源。

• 在 HuggingFace 博客中查看时间序列 Transformer 博文：使用🤗 Transformers 进行概率时间序列预测

TimeSeriesTransformerConfig

class transformers.TimeSeriesTransformerConfig

< source >

( prediction_length: Optional = None context_length: Optional = None distribution_output: str = 'student_t' loss: str = 'nll' input_size: int = 1 lags_sequence: List = [1, 2, 3, 4, 5, 6, 7] scaling: Union = 'mean' num_dynamic_real_features: int = 0 num_static_categorical_features: int = 0 num_static_real_features: int = 0 num_time_features: int = 0 cardinality: Optional = None embedding_dimension: Optional = None encoder_ffn_dim: int = 32 decoder_ffn_dim: int = 32 encoder_attention_heads: int = 2 decoder_attention_heads: int = 2 encoder_layers: int = 2 decoder_layers: int = 2 is_encoder_decoder: bool = True activation_function: str = 'gelu' d_model: int = 64 dropout: float = 0.1 encoder_layerdrop: float = 0.1 decoder_layerdrop: float = 0.1 attention_dropout: float = 0.1 activation_dropout: float = 0.1 num_parallel_samples: int = 100 init_std: float = 0.02 use_cache = True **kwargs )

参数

• prediction_length (int) — 解码器的预测长度。换句话说，模型的预测范围。此值通常由数据集决定，我们建议适当设置。

• context_length (int, 可选, 默认为prediction_length) — 编码器的上下文长度。如果为None，上下文长度将与prediction_length相同。

• distribution_output (string, 可选, 默认为"student_t") — 模型的分布发射头。可以是"student_t"、“normal”或“negative_binomial”之一。

• loss (string, 可选, 默认为"nll") — 与distribution_output头对应的模型损失函数。对于参数分布，它是负对数似然（nll）- 目前是唯一支持的损失函数。

• input_size (int, 可选, 默认为 1) — 目标变量的大小，默认情况下对于单变量目标为 1。对于多变量目标，将大于 1。

• scaling (string或bool, 可选, 默认为"mean") — 是否通过"mean"缩放器、“std”缩放器或如果为None则不进行缩放来缩放输入目标。如果为True，则缩放器设置为"mean"。

• lags_sequence (list[int], 可选, 默认为[1, 2, 3, 4, 5, 6, 7]) — 输入时间序列的滞后作为协变量的滞后，通常由数据的频率决定。默认为[1, 2, 3, 4, 5, 6, 7]，但我们建议根据数据集适当地进行更改。

• num_time_features (int, 可选, 默认为 0) — 输入时间序列中的时间特征数量。

• num_dynamic_real_features (int, 可选, 默认为 0) — 动态实值特征的数量。

• num_static_categorical_features (int, 可选, 默认为 0) — 静态分类特征的数量。

• num_static_real_features (int, 可选, 默认为 0) — 静态实值特征的数量。

• cardinality (list[int], 可选) — 每个静态分类特征的基数（不同值的数量）。应该是一个整数列表，长度与num_static_categorical_features相同。如果num_static_categorical_features大于 0，则不能为None。

• embedding_dimension (list[int], 可选) — 每个静态分类特征的嵌入维度。应该是一个整数列表，长度与num_static_categorical_features相同。如果num_static_categorical_features大于 0，则不能为None。

• d_model (int, 可选, 默认为 64) — Transformer 层的维度。

• encoder_layers (int, 可选, 默认为 2) — 编码器层数。

• decoder_layers (int, 可选, 默认为 2) — 解码器层数。

• encoder_attention_heads (int, 可选, 默认为 2) — Transformer 编码器中每个注意力层的注意力头数。

• decoder_attention_heads (int, optional, defaults to 2) — Transformer 解码器中每个注意力层的注意力头数。

• encoder_ffn_dim (int, optional, defaults to 32) — 编码器中“中间”（通常称为前馈）层的维度。

• decoder_ffn_dim (int, optional, defaults to 32) — 解码器中“中间”（通常称为前馈）层的维度。

• activation_function (str or function, optional, defaults to "gelu") — 编码器和解码器中的非线性激活函数（函数或字符串）。如果是字符串，支持"gelu"和"relu"。

• dropout (float, optional, defaults to 0.1) — 编码器和解码器中所有全连接层的 dropout 概率。

• encoder_layerdrop (float, optional, defaults to 0.1) — 每个编码器层的注意力和全连接层的 dropout 概率。

• decoder_layerdrop (float, optional, defaults to 0.1) — 每个解码器层的注意力和全连接层的 dropout 概率。

• attention_dropout (float, optional, defaults to 0.1) — 注意力概率的 dropout 概率。

• activation_dropout (float, optional, defaults to 0.1) — 在前馈网络的两个层之间使用的 dropout 概率。

• num_parallel_samples (int, optional, defaults to 100) — 每个推理时间步生成的并行样本数。

• init_std (float, optional, defaults to 0.02) — 截断正态权重初始化分布的标准差。

• use_cache (bool, optional, defaults to True) — 是否使用过去的键/值注意力（如果适用于模型）以加速解码。

  示例 —

这是用于存储 TimeSeriesTransformerModel 配置的配置类。根据指定的参数实例化一个时间序列 Transformer 模型，定义模型架构。使用默认值实例化配置将产生类似于 Time Series Transformer huggingface/time-series-transformer-tourism-monthly架构的配置。

继承自 PretrainedConfig 的配置对象可用于控制模型输出。阅读 PretrainedConfig 的文档以获取更多信息。

>>> from transformers import TimeSeriesTransformerConfig, TimeSeriesTransformerModel

>>> # Initializing a Time Series Transformer configuration with 12 time steps for prediction
>>> configuration = TimeSeriesTransformerConfig(prediction_length=12)

>>> # Randomly initializing a model (with random weights) from the configuration
>>> model = TimeSeriesTransformerModel(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config

TimeSeriesTransformerModel

class transformers.TimeSeriesTransformerModel

< source >

( config: TimeSeriesTransformerConfig )

参数

• config (TimeSeriesTransformerConfig) — 具有模型所有参数的模型配置类。使用配置文件初始化不会加载与模型关联的权重，只会加载配置。查看 from_pretrained()方法以加载模型权重。

裸的时间序列 Transformer 模型，在顶部没有特定的头输出原始隐藏状态。此模型继承自 PreTrainedModel。查看超类文档以了解库为所有模型实现的通用方法（如下载或保存、调整输入嵌入、修剪头等）。

这个模型也是 PyTorch torch.nn.Module子类。将其用作常规的 PyTorch 模块，并参考 PyTorch 文档以获取与一般用法和行为相关的所有事项。

forward

<来源>

( past_values: Tensor past_time_features: Tensor past_observed_mask: Tensor static_categorical_features: Optional = None static_real_features: Optional = None future_values: Optional = None future_time_features: Optional = None decoder_attention_mask: Optional = None head_mask: Optional = None decoder_head_mask: Optional = None cross_attn_head_mask: Optional = None encoder_outputs: Optional = None past_key_values: Optional = None output_hidden_states: Optional = None output_attentions: Optional = None use_cache: Optional = None return_dict: Optional = None ) → export const metadata = 'undefined';transformers.modeling_outputs.Seq2SeqTSModelOutput or tuple(torch.FloatTensor)

参数

• past_values（形状为(batch_size, sequence_length)或(batch_size, sequence_length, input_size)的torch.FloatTensor）- 时间序列的过去值，作为上下文以预测未来。这个张量的序列大小必须大于模型的context_length，因为模型将使用更大的大小来构建滞后特征，即从过去添加的额外值，以充当“额外上下文”。

  这里的sequence_length等于config.context_length + max(config.lags_sequence)，如果没有配置lags_sequence，则等于config.context_length + 7（因为默认情况下，config.lags_sequence中最大的回溯索引是 7）。属性_past_length返回过去的实际长度。

  past_values 是 Transformer 编码器的输入（可选的附加特征，如static_categorical_features、static_real_features、past_time_features和 lags）。

  可选地，缺失值需要用零替换，并通过past_observed_mask指示。

  对于多变量时间序列，input_size > 1 维是必需的，并且对应于每个时间步中时间序列中的变量数。

• past_time_features（形状为(batch_size, sequence_length, num_features)的torch.FloatTensor）- 模型内部将添加到past_values中的必需时间特征。这些可能是像“年份的月份”、“月份的日期”等编码为向量（例如傅立叶特征）的东西。这些也可以是所谓的“年龄”特征，基本上帮助模型知道时间序列处于“生活中的哪个时刻”。年龄特征对于远处的过去时间步具有较小的值，并且随着我们接近当前时间步而单调增加。假期特征也是时间特征的一个很好的例子。

  这些特征作为输入的“位置编码”。因此，与像 BERT 这样的模型不同，BERT 的位置编码是从头开始内部作为模型的参数学习的，时间序列 Transformer 需要提供额外的时间特征。时间序列 Transformer 仅为static_categorical_features学习额外的嵌入。

  额外的动态实数协变量可以连接到这个张量中，但这些特征必须在预测时已知。

  这里的num_features等于config.num_time_features+config.num_dynamic_real_features。

• past_observed_mask（形状为(batch_size, sequence_length)或(batch_size, sequence_length, input_size)的torch.BoolTensor，可选）- 用于指示哪些past_values是观察到的，哪些是缺失的布尔掩码。掩码值选择在[0, 1]中：

  • 对于observed的值为 1，

  • 对于missing的值（即用零替换的 NaN 值），为 0。

• static_categorical_features（形状为(batch_size, number of static categorical features)的torch.LongTensor，可选）- 模型将学习一个嵌入，将其添加到时间序列值中的可选静态分类特征。

  静态分类特征是所有时间步长上具有相同值的特征（随时间保持不变）。

  静态分类特征的典型示例是时间序列 ID。

• static_real_features（形状为(batch_size, number of static real features)的torch.FloatTensor，可选）- 模型将添加到时间序列值中的可选静态实数特征。

  静态实数特征是所有时间步长上具有相同值的特征（随时间保持不变）。

  静态实际特征的典型示例是促销信息。

• future_values（形状为(batch_size, prediction_length)或(batch_size, prediction_length, input_size)的torch.FloatTensor，可选）— 时间序列的未来值，用作模型的标签。future_values是 Transformer 在训练期间需要学习输出的内容，给定past_values。

  这里的序列长度等于prediction_length。

  有关详细信息，请参阅演示笔记本和代码片段。

  在训练期间，任何缺失值都需要用零替换，并通过future_observed_mask指示。

  对于多变量时间序列，需要input_size > 1 维，并且对应于时间序列中每个时间步的变量数量。

• future_time_features（形状为(batch_size, prediction_length, num_features)的torch.FloatTensor）— 预测窗口所需的时间特征，模型内部将这些特征添加到future_values中。这些特征可以是诸如“年份月份”、“每月日期”等的向量编码（例如傅立叶特征）。这些也可以是所谓的“年龄”特征，基本上帮助模型了解时间序列处于“生命周期的哪个阶段”。年龄特征对于遥远的过去时间步具有较小的值，并且随着我们接近当前时间步，值会单调增加。假期特征也是时间特征的一个很好的例子。

  这些特征作为输入的“位置编码”。与 BERT 等模型不同，BERT 的位置编码是从头开始内部作为模型的参数学习的，时间序列 Transformer 需要提供额外的时间特征。时间序列 Transformer 仅为static_categorical_features学习额外的嵌入。

  可以将额外的动态实际协变量连接到此张量中，但必须在预测时了解这些特征。

  这里的num_features等于config.num_time_features+config.num_dynamic_real_features。

• future_observed_mask（形状为(batch_size, sequence_length)或(batch_size, sequence_length, input_size)的torch.BoolTensor，可选）— 布尔蒙版，指示哪些future_values被观察到，哪些是缺失的。蒙版值选在[0, 1]范围内：

  • 1 表示值被观察到，

  • 对于值为missing（即被零替换的 NaN）的情况。

  此蒙版用于过滤最终损失计算中的缺失值。

• attention_mask（形状为(batch_size, sequence_length)的torch.Tensor，可选）— 用于避免在某些标记索引上执行注意力的蒙版。蒙版值选在[0, 1]范围内：

  • 1 表示未被蒙版的标记，

  • 0 表示被蒙版的标记。

  什么是注意力蒙版？

• decoder_attention_mask（形状为(batch_size, target_sequence_length)的torch.LongTensor，可选）— 用于避免在某些标记索引上执行注意力的蒙版。默认情况下，将使用因果蒙版，以确保模型只能查看以前的输入以预测未来。

• head_mask（形状为(encoder_layers, encoder_attention_heads)的torch.Tensor，可选）— 用于使编码器中注意力模块的特定头部失效的蒙版。蒙版值选在[0, 1]范围内：

  • 1 表示头部未被蒙版，

  • 0 表示头部被蒙版。

• decoder_head_mask（形状为(decoder_layers, decoder_attention_heads)的torch.Tensor，可选）— 用于使解码器中注意力模块的特定头部失效的蒙版。蒙版值选在[0, 1]范围内：

  • 1 表示头部未被蒙版，

  • 0 表示头部被蒙版。

• cross_attn_head_mask（形状为(decoder_layers, decoder_attention_heads)的torch.Tensor，可选）— 用于使交叉注意力模块的特定头部失效的蒙版。蒙版值选在[0, 1]范围内：

  • 1 表示头部未被蒙版，

  • 0 表示头部被蒙版。

• encoder_outputs (tuple(tuple(torch.FloatTensor), optional) — 元组包含last_hidden_state、hidden_states（可选）和attentions（可选）last_hidden_state的形状为(batch_size, sequence_length, hidden_size)（可选），是编码器最后一层输出的隐藏状态序列。用于解码器的交叉注意力。

• past_key_values (tuple(tuple(torch.FloatTensor)), optional, 当传递use_cache=True或config.use_cache=True时返回，类型为tuple(tuple(torch.FloatTensor))，长度为config.n_layers，每个元组包含 2 个形状为(batch_size, num_heads, sequence_length, embed_size_per_head)的张量和 2 个额外的形状为(batch_size, num_heads, encoder_sequence_length, embed_size_per_head)的张量。

  包含预先计算的隐藏状态（自注意力块和交叉注意力块中的键和值），可用于加速顺序解码（参见past_key_values输入）。

  如果使用past_key_values，用户可以选择仅输入形状为(batch_size, 1)的最后一个decoder_input_ids（这些没有将其过去的键值状态提供给此模型）而不是形状为(batch_size, sequence_length)的所有decoder_input_ids。

• inputs_embeds (torch.FloatTensor，形状为(batch_size, sequence_length, hidden_size)，可选） — 可选地，您可以直接传递嵌入表示而不是传递input_ids。如果您想要更多控制如何将input_ids索引转换为相关向量，而不是使用模型的内部嵌入查找矩阵，则这很有用。

• use_cache (bool, optional) — 如果设置为True，则返回past_key_values键值状态，可用于加速解码（参见past_key_values）。

• output_attentions (bool, optional) — 是否返回所有注意力层的注意力张量。有关更多详细信息，请参见返回张量中的attentions。

• output_hidden_states (bool, optional) — 是否返回所有层的隐藏状态。有关更多详细信息，请参见返回张量中的hidden_states。

• return_dict (bool, optional) — 是否返回 ModelOutput 而不是普通元组。

返回

transformers.modeling_outputs.Seq2SeqTSModelOutput 或 tuple(torch.FloatTensor)

transformers.modeling_outputs.Seq2SeqTSModelOutput 或一个torch.FloatTensor元组（如果传递return_dict=False或config.return_dict=False时）包含根据配置（TimeSeriesTransformerConfig）和输入的不同元素。

• last_hidden_state (torch.FloatTensor，形状为(batch_size, sequence_length, hidden_size)) — 模型解码器最后一层的隐藏状态序列。

  如果仅使用past_key_values，则输出形状为(batch_size, 1, hidden_size)的序列的最后一个隐藏状态。

• past_key_values (tuple(tuple(torch.FloatTensor)), optional, returned when use_cache=True is passed or when config.use_cache=True) — 当传递use_cache=True或config.use_cache=True时返回，类型为tuple(tuple(torch.FloatTensor))，长度为config.n_layers，每个元组包含 2 个形状为(batch_size, num_heads, sequence_length, embed_size_per_head)的张量和 2 个额外的形状为(batch_size, num_heads, encoder_sequence_length, embed_size_per_head)的张量。

  包含预先计算的隐藏状态（自注意力块和交叉注意力块中的键和值），可用于加速顺序解码（参见past_key_values输入）。

• decoder_hidden_states (tuple(torch.FloatTensor), 可选, 当传递output_hidden_states=True或config.output_hidden_states=True时返回) — 形状为(batch_size, sequence_length, hidden_size)的torch.FloatTensor元组（如果模型有嵌入层，则为嵌入层的输出+每层的输出）。

  解码器在每一层输出的隐藏状态加上可选的初始嵌入输出。

• decoder_attentions (tuple(torch.FloatTensor), 可选, 当传递output_attentions=True或config.output_attentions=True时返回) — 形状为(batch_size, num_heads, sequence_length, sequence_length)的torch.FloatTensor元组（每层一个）。

  解码器的注意力权重，在注意力 softmax 之后，用于计算自注意力头中的加权平均值。

• cross_attentions (tuple(torch.FloatTensor), 可选, 当传递output_attentions=True或config.output_attentions=True时返回) — 形状为(batch_size, num_heads, sequence_length, sequence_length)的torch.FloatTensor元组（每层一个）。

  解码器的交叉注意力层的注意力权重，在注意力 softmax 之后，用于计算交叉注意力头中的加权平均值。

• encoder_last_hidden_state (形状为(batch_size, sequence_length, hidden_size)的torch.FloatTensor`, 可选) — 模型编码器最后一层的隐藏状态序列。

• encoder_hidden_states (tuple(torch.FloatTensor), 可选, 当传递output_hidden_states=True或config.output_hidden_states=True时返回) — 形状为(batch_size, sequence_length, hidden_size)的torch.FloatTensor元组（如果模型有嵌入层，则为嵌入层的输出+每层的输出）。

  编码器在每一层输出的隐藏状态加上可选的初始嵌入输出。

• encoder_attentions (tuple(torch.FloatTensor), 可选, 当传递output_attentions=True或config.output_attentions=True时返回) — 形状为(batch_size, num_heads, sequence_length, sequence_length)的torch.FloatTensor元组（每层一个）。

  编码器的注意力权重，在注意力 softmax 之后，用于计算自注意力头中的加权平均值。

• loc (形状为(batch_size,)或(batch_size, input_size)的torch.FloatTensor`, 可选) — 每个时间序列的上下文窗口的偏移值，用于给模型输入相同数量级的输入，然后用于将其偏移回原始数量级。

• scale (形状为(batch_size,)或(batch_size, input_size)的torch.FloatTensor`, 可选) — 每个时间序列的上下文窗口的缩放值，用于给模型输入相同数量级的输入，然后用于将其重新缩放回原始数量级。

• static_features (形状为(batch_size, feature size)的torch.FloatTensor`, 可选) — 每个时间序列的静态特征，在推断时复制到协变量中。

TimeSeriesTransformerModel 的前向方法，覆盖了__call__特殊方法。

虽然前向传递的步骤需要在此函数内定义，但应该在此之后调用Module实例，而不是这个，因为前者负责运行预处理和后处理步骤，而后者会默默地忽略它们。

示例：

>>> from huggingface_hub import hf_hub_download
>>> import torch
>>> from transformers import TimeSeriesTransformerModel

>>> file = hf_hub_download(
...     repo_id="hf-internal-testing/tourism-monthly-batch", filename="train-batch.pt", repo_type="dataset"
... )
>>> batch = torch.load(file)

>>> model = TimeSeriesTransformerModel.from_pretrained("huggingface/time-series-transformer-tourism-monthly")

>>> # during training, one provides both past and future values
>>> # as well as possible additional features
>>> outputs = model(
...     past_values=batch["past_values"],
...     past_time_features=batch["past_time_features"],
...     past_observed_mask=batch["past_observed_mask"],
...     static_categorical_features=batch["static_categorical_features"],
...     static_real_features=batch["static_real_features"],
...     future_values=batch["future_values"],
...     future_time_features=batch["future_time_features"],
... )

>>> last_hidden_state = outputs.last_hidden_state

TimeSeriesTransformerForPrediction

class transformers.TimeSeriesTransformerForPrediction

< source >

( config: TimeSeriesTransformerConfig )

参数

• config (TimeSeriesTransformerConfig) — 模型的配置类，包含所有模型的参数。使用配置文件初始化不会加载与模型相关的权重，只会加载配置。查看 from_pretrained()方法以加载模型权重。

带有时间序列预测分布头的时间序列变换器模型。此模型继承自 PreTrainedModel。查看超类文档以获取库为所有模型实现的通用方法（如下载或保存、调整输入嵌入、修剪头等）。

这个模型也是一个 PyTorch torch.nn.Module子类。将其用作常规的 PyTorch 模块，并参考 PyTorch 文档以获取与一般用法和行为相关的所有内容。

forward

<来源>

( past_values: Tensor past_time_features: Tensor past_observed_mask: Tensor static_categorical_features: Optional = None static_real_features: Optional = None future_values: Optional = None future_time_features: Optional = None future_observed_mask: Optional = None decoder_attention_mask: Optional = None head_mask: Optional = None decoder_head_mask: Optional = None cross_attn_head_mask: Optional = None encoder_outputs: Optional = None past_key_values: Optional = None output_hidden_states: Optional = None output_attentions: Optional = None use_cache: Optional = None return_dict: Optional = None ) → export const metadata = 'undefined';transformers.modeling_outputs.Seq2SeqTSModelOutput or tuple(torch.FloatTensor)

参数

• past_values（形状为(batch_size, sequence_length)或(batch_size, sequence_length, input_size)的torch.FloatTensor） — 时间序列的过去值，用作上下文以预测未来。此张量的序列大小必须大于模型的context_length，因为模型将使用较大的大小来构建滞后特征，即从过去添加的额外值，以充当“额外上下文”。

  这里的sequence_length等于config.context_length + max(config.lags_sequence)，如果没有配置lags_sequence，则等于config.context_length + 7（默认情况下，config.lags_sequence中最大的回顾索引为 7）。属性_past_length返回过去的实际长度。

  past_values是 Transformer 编码器作为输入的内容（带有可选的附加特征，如static_categorical_features、static_real_features、past_time_features和滞后）。

  可选地，缺失值需要用零替换，并通过past_observed_mask指示。

  对于多变量时间序列，需要input_size > 1 维，并对应于每个时间步长中时间序列的变量数量。

• past_time_features（形状为(batch_size, sequence_length, num_features)的torch.FloatTensor） — 必需的时间特征，模型内部将其添加到past_values中。这些可能是诸如“年份中的月份”、“月份中的日期”等编码为向量（例如作为傅立叶特征）的内容。这也可以是所谓的“年龄”特征，基本上帮助模型知道时间序列处于“生活中的哪个阶段”。年龄特征对于远处的过去时间步具有较小的值，并且随着我们接近当前时间步而单调增加。假期特征也是时间特征的一个很好的例子。

  这些特征用作输入的“位置编码”。与像 BERT 这样的模型相反，BERT 中的位置编码是从头开始内部作为模型的参数学习的，而时间序列变换器需要提供额外的时间特征。时间序列变换器仅为static_categorical_features学习额外的嵌入。

  可以将额外的动态实际协变量连接到此张量中，但需要注意的是这些特征必须在预测时已知。

  这里的num_features等于config.num_time_features+config.num_dynamic_real_features。

• past_observed_mask (torch.BoolTensor of shape (batch_size, sequence_length) or (batch_size, sequence_length, input_size), optional) — 布尔掩码，指示哪些past_values是观察到的，哪些是缺失的。掩码值选在[0, 1]之间：

  • 1 表示“观察到”的值，

  • 0 表示“缺失”的值（即被零替换的 NaN）。

• static_categorical_features (torch.LongTensor of shape (batch_size, number of static categorical features), optional) — 模型将学习嵌入这些静态分类特征，并将其添加到时间序列的值中。

  静态分类特征是所有时间步的值都相同的特征（随时间保持静态）。

  静态分类特征的典型示例是时间序列 ID。

• static_real_features (torch.FloatTensor of shape (batch_size, number of static real features), optional) — 可选的静态实数特征，模型将把这些特征添加到时间序列的值中。

  静态实数特征是所有时间步的值都相同的特征（随时间保持静态）。

  静态实数特征的典型示例是促销信息。

• future_values (torch.FloatTensor of shape (batch_size, prediction_length) or (batch_size, prediction_length, input_size), optional) — 时间序列的未来值，作为模型的标签。future_values是 Transformer 在训练期间需要学习输出的内容，给定past_values。

  这里的序列长度等于prediction_length。

  有关详细信息，请参阅演示笔记本和代码片段。

  在训练期间，任何缺失值都需要用零替换，并通过future_observed_mask指示。

  对于多变量时间序列，需要input_size > 1 维，并且对应于时间序列每个时间步中的变量数量。

• future_time_features (torch.FloatTensor of shape (batch_size, prediction_length, num_features)) — 模型在内部将这些特征添加到future_values中，这些特征是预测窗口所需的时间特征。这些特征可以是诸如“年份中的月份”、“月份中的日期”等编码为向量（例如傅立叶特征）的内容。这些也可以是所谓的“年龄”特征，基本上帮助模型了解时间序列处于“生命中的哪个阶段”。年龄特征对于远处的过去时间步具有较小的值，并且随着我们接近当前时间步而单调增加。假期特征也是时间特征的一个很好的例子。

  这些特征作为输入的“位置编码”。与 BERT 等模型不同，BERT 的位置编码是从头开始内部作为模型的参数学习的，时间序列 Transformer 需要提供额外的时间特征。时间序列 Transformer 仅为static_categorical_features学习额外的嵌入。

  可以将额外的动态实数协变量连接到这个张量中，但需要注意这些特征必须在预测时已知。

  这里的num_features等于config.num_time_features+config.num_dynamic_real_features。

• future_observed_mask (torch.BoolTensor of shape (batch_size, sequence_length) or (batch_size, sequence_length, input_size), optional) — 布尔掩码，指示哪些future_values是观察到的，哪些是缺失的。掩码值选在[0, 1]之间：

  • 1 表示“观察到”的值，

  • 0 表示“缺失”的值（即被零替换的 NaN）。

  这个掩码用于在最终损失计算中过滤缺失值。

• attention_mask (torch.Tensor of shape (batch_size, sequence_length), optional) — 用于避免在某些标记索引上执行注意力的掩码。掩码值选在[0, 1]之间：

  • 1 表示“未被掩码”的标记，

  • 0 表示“被掩码”的标记。

  什么是注意力掩码？

• decoder_attention_mask (torch.LongTensor of shape (batch_size, target_sequence_length), optional) — 用于避免在某些标记索引上执行注意力的掩码。默认情况下，将使用因果掩码，以确保模型只能查看以前的输入以预测未来。

• head_mask (torch.Tensor of shape (encoder_layers, encoder_attention_heads), optional) — 用于将编码器中注意力模块中选择的头部置零的掩码。掩码值在 [0, 1] 中选择：

  • 1 表示头部未被屏蔽，

  • 0 表示头部被屏蔽。

• decoder_head_mask (torch.Tensor of shape (decoder_layers, decoder_attention_heads), optional) — 用于将解码器中注意力模块中选择的头部置零的掩码。掩码值在 [0, 1] 中选择：

  • 1 表示头部未被屏蔽，

  • 0 表示头部被屏蔽。

• cross_attn_head_mask (torch.Tensor of shape (decoder_layers, decoder_attention_heads), optional) — 用于将交叉注意力模块中选择的头部置零的掩码。掩码值在 [0, 1] 中选择：

  • 1 表示头部未被屏蔽，

  • 0 表示头部被屏蔽。

• encoder_outputs (tuple(tuple(torch.FloatTensor), optional) — 元组包括 last_hidden_state、hidden_states（可选）和 attentions（可选）last_hidden_state 的形状为 (batch_size, sequence_length, hidden_size)（可选）是编码器最后一层的输出的隐藏状态序列。用于解码器的交叉注意力。

• past_key_values (tuple(tuple(torch.FloatTensor)), optional, 当传递 use_cache=True 或 config.use_cache=True 时返回) — 长度为 config.n_layers 的 tuple(torch.FloatTensor) 元组，每个元组包含 2 个形状为 (batch_size, num_heads, sequence_length, embed_size_per_head) 的张量和 2 个额外的形状为 (batch_size, num_heads, encoder_sequence_length, embed_size_per_head) 的张量。

  包含预先计算的隐藏状态（自注意力块和交叉注意力块中的键和值），可用于加速顺序解码（参见 past_key_values 输入）。

  如果使用了 past_key_values，用户可以选择仅输入最后的 decoder_input_ids（这些没有将其过去的键值状态提供给此模型）的形状为 (batch_size, 1)，而不是所有形状为 (batch_size, sequence_length) 的 decoder_input_ids。

• inputs_embeds (torch.FloatTensor of shape (batch_size, sequence_length, hidden_size), optional) — 可选地，可以直接传递嵌入表示，而不是传递 input_ids。如果您想要更多控制权，以便将 input_ids 索引转换为相关向量，而不是模型的内部嵌入查找矩阵，则这很有用。

• use_cache (bool, optional) — 如果设置为 True，则返回 past_key_values 键值状态，可用于加速解码（参见 past_key_values）。

• output_attentions (bool, optional) — 是否返回所有注意力层的注意力张量。有关更多详细信息，请参阅返回张量中的 attentions。

• output_hidden_states (bool, optional) — 是否返回所有层的隐藏状态。有关更多详细信息，请参阅返回张量中的 hidden_states。

• return_dict (bool, optional) — 是否返回 ModelOutput 而不是普通元组。

返回

transformers.modeling_outputs.Seq2SeqTSModelOutput 或 tuple(torch.FloatTensor)

一个 transformers.modeling_outputs.Seq2SeqTSModelOutput 或一个torch.FloatTensor元组（如果传递了return_dict=False或config.return_dict=False时）包含根据配置（TimeSeriesTransformerConfig）和输入的不同元素。

• last_hidden_state（形状为(batch_size, sequence_length, hidden_size)的torch.FloatTensor）- 模型解码器最后一层的隐藏状态序列。

  如果使用past_key_values，则只输出形状为(batch_size, 1, hidden_size)的序列的最后一个隐藏状态。

• past_key_values（tuple(tuple(torch.FloatTensor))，可选，当传递use_cache=True或config.use_cache=True时返回）- 长度为config.n_layers的tuple(torch.FloatTensor)元组，每个元组有 2 个形状为(batch_size, num_heads, sequence_length, embed_size_per_head)的张量和 2 个额外的形状为(batch_size, num_heads, encoder_sequence_length, embed_size_per_head)的张量。

  包含预先计算的隐藏状态（自注意力块和交叉注意力块中的键和值），可用于加速顺序解码（参见past_key_values输入）。

• decoder_hidden_states（tuple(torch.FloatTensor)，可选，当传递output_hidden_states=True或config.output_hidden_states=True时返回）- 形状为(batch_size, sequence_length, hidden_size)的torch.FloatTensor元组（如果模型有嵌入层，则为嵌入输出的一个加上每一层的输出）。

  解码器在每一层的输出的隐藏状态以及可选的初始嵌入输出。

• decoder_attentions（tuple(torch.FloatTensor)，可选，当传递output_attentions=True或config.output_attentions=True时返回）- 形状为(batch_size, num_heads, sequence_length, sequence_length)的torch.FloatTensor元组（每层一个）。

  解码器的注意力权重，在注意力 softmax 之后，用于计算自注意力头中的加权平均值。

• cross_attentions（tuple(torch.FloatTensor)，可选，当传递output_attentions=True或config.output_attentions=True时返回）- 形状为(batch_size, num_heads, sequence_length, sequence_length)的torch.FloatTensor元组（每层一个）。

  解码器的交叉注意力层的注意力权重，在注意力 softmax 之后，用于计算交叉注意力头中的加权平均值。

• encoder_last_hidden_state（形状为(batch_size, sequence_length, hidden_size)的torch.FloatTensor，可选）- 模型编码器最后一层的隐藏状态序列。

• encoder_hidden_states（tuple(torch.FloatTensor)，可选，当传递output_hidden_states=True或config.output_hidden_states=True时返回）- 形状为(batch_size, sequence_length, hidden_size)的torch.FloatTensor元组（如果模型有嵌入层，则为嵌入输出的一个加上每一层的输出）。

  编码器在每一层的输出的隐藏状态以及可选的初始嵌入输出。

• encoder_attentions（tuple(torch.FloatTensor)，可选，当传递output_attentions=True或config.output_attentions=True时返回）- 形状为(batch_size, num_heads, sequence_length, sequence_length)的torch.FloatTensor元组（每层一个）。

  编码器的注意力权重，在注意力 softmax 之后，用于计算自注意力头中的加权平均值。

• loc（形状为(batch_size,)或(batch_size, input_size)的torch.FloatTensor，可选）- 用于将每个时间序列的上下文窗口的值移位，以便为模型提供相同数量级的输入，然后用于将其移位回原始数量级。

• scale（形状为(batch_size,)或(batch_size, input_size)的torch.FloatTensor，可选）- 用于将每个时间序列的上下文窗口的缩放值移位，以便为模型提供相同数量级的输入，然后用于重新缩放回原始数量级。

• static_features（形状为(batch_size, feature size)的torch.FloatTensor，可选）- 每个时间序列在批处理中的静态特征，在推断时将复制到协变量中。

TimeSeriesTransformerForPrediction 的前向方法重写了__call__特殊方法。

虽然前向传递的步骤需要在此函数中定义，但应该在此之后调用Module实例，而不是在此之后调用，因为前者会负责运行预处理和后处理步骤，而后者会默默地忽略它们。

示例：

>>> from huggingface_hub import hf_hub_download
>>> import torch
>>> from transformers import TimeSeriesTransformerForPrediction

>>> file = hf_hub_download(
...     repo_id="hf-internal-testing/tourism-monthly-batch", filename="train-batch.pt", repo_type="dataset"
... )
>>> batch = torch.load(file)

>>> model = TimeSeriesTransformerForPrediction.from_pretrained(
...     "huggingface/time-series-transformer-tourism-monthly"
... )

>>> # during training, one provides both past and future values
>>> # as well as possible additional features
>>> outputs = model(
...     past_values=batch["past_values"],
...     past_time_features=batch["past_time_features"],
...     past_observed_mask=batch["past_observed_mask"],
...     static_categorical_features=batch["static_categorical_features"],
...     static_real_features=batch["static_real_features"],
...     future_values=batch["future_values"],
...     future_time_features=batch["future_time_features"],
... )

>>> loss = outputs.loss
>>> loss.backward()

>>> # during inference, one only provides past values
>>> # as well as possible additional features
>>> # the model autoregressively generates future values
>>> outputs = model.generate(
...     past_values=batch["past_values"],
...     past_time_features=batch["past_time_features"],
...     past_observed_mask=batch["past_observed_mask"],
...     static_categorical_features=batch["static_categorical_features"],
...     static_real_features=batch["static_real_features"],
...     future_time_features=batch["future_time_features"],
... )

>>> mean_prediction = outputs.sequences.mean(dim=1)

图模型

Graphormer

原始文本：huggingface.co/docs/transformers/v4.37.2/en/model_doc/graphormer

概述

Graphormer 模型是由 Chengxuan Ying、Tianle Cai、Shengjie Luo、Shuxin Zheng、Guolin Ke、Di He、Yanming Shen 和 Tie-Yan Liu 在Do Transformers Really Perform Bad for Graph Representation?中提出的。这是一个图形变换器模型，经过修改以允许在图形上进行计算，而不是文本序列，通过在预处理和整理过程中生成感兴趣的嵌入和特征，然后使用修改后的注意力。

论文摘要如下：

变压器架构已经成为许多领域的主要选择，如自然语言处理和计算机视觉。然而，与主流 GNN 变体相比，它在流行的图级预测排行榜上并没有取得竞争性表现。因此，变压器如何在图形表示学习中表现良好仍然是一个谜。在本文中，我们通过提出 Graphormer 来解决这个谜团，它建立在标准 Transformer 架构之上，并且在广泛的图形表示学习任务中取得了出色的结果，特别是在最近的 OGB 大规模挑战赛上。我们利用 Transformer 在图中的关键见解是有效地将图的结构信息编码到模型中。为此，我们提出了几种简单而有效的结构编码方法，以帮助 Graphormer 更好地建模图结构化数据。此外，我们数学地刻画了 Graphormer 的表达能力，并展示了通过我们的方式对图的结构信息进行编码，许多流行的 GNN 变体可以被覆盖为 Graphormer 的特殊情况。

该模型由clefourrier贡献。原始代码可以在这里找到。

使用提示

这个模型在大型图上（超过 100 个节点/边）效果不佳，因为会导致内存爆炸。您可以减小批量大小，增加 RAM，或者减小 algos_graphormer.pyx 中的UNREACHABLE_NODE_DISTANCE参数，但很难超过 700 个节点/边。

该模型不使用分词器，而是在训练过程中使用特殊的整理器。

GraphormerConfig

class transformers.GraphormerConfig

<来源>

( num_classes: int = 1 num_atoms: int = 4608 num_edges: int = 1536 num_in_degree: int = 512 num_out_degree: int = 512 num_spatial: int = 512 num_edge_dis: int = 128 multi_hop_max_dist: int = 5 spatial_pos_max: int = 1024 edge_type: str = 'multi_hop' max_nodes: int = 512 share_input_output_embed: bool = False num_hidden_layers: int = 12 embedding_dim: int = 768 ffn_embedding_dim: int = 768 num_attention_heads: int = 32 dropout: float = 0.1 attention_dropout: float = 0.1 activation_dropout: float = 0.1 layerdrop: float = 0.0 encoder_normalize_before: bool = False pre_layernorm: bool = False apply_graphormer_init: bool = False activation_fn: str = 'gelu' embed_scale: float = None freeze_embeddings: bool = False num_trans_layers_to_freeze: int = 0 traceable: bool = False q_noise: float = 0.0 qn_block_size: int = 8 kdim: int = None vdim: int = None bias: bool = True self_attention: bool = True pad_token_id = 0 bos_token_id = 1 eos_token_id = 2 **kwargs )

参数

• num_classes (int, optional, defaults to 1) — 目标类别或标签的数量，设置为 n 用于 n 个任务的二元分类。

• num_atoms (int, optional, defaults to 512*9) — 图中节点类型的数量。

• num_edges (int, optional, defaults to 512*3) — 图中边的类型数量。

• num_in_degree (int, optional, defaults to 512) — 输入图中的入度类型数量。

• num_out_degree (int, optional, defaults to 512) — 输入图中的出度类型数量。

• num_edge_dis (int, optional, defaults to 128) — 输入图中的边缘 dis 数量。

• multi_hop_max_dist (int, optional, defaults to 20) — 两个节点之间多跳边的最大距离。

• spatial_pos_max (int, optional, defaults to 1024) — 图注意力偏置矩阵中节点之间的最大距离，在预处理和整理过程中使用。

• edge_type (str, optional, defaults to multihop) — 选择的边关系类型。

• max_nodes (int, optional, defaults to 512) — 可以解析的输入图中的最大节点数。

• share_input_output_embed (bool, optional, defaults to False) — 在编码器和解码器之间共享嵌入层 - 注意，True 未实现。

• num_layers (int, optional, defaults to 12) — 层数。

• embedding_dim (int, optional, defaults to 768) — 编码器中嵌入层的维度。

• ffn_embedding_dim (int, optional, defaults to 768) — 编码器中“中间”（通常称为前馈）层的维度。

• num_attention_heads (int, optional, defaults to 32) — 编码器中的注意力头数。

• self_attention (bool, optional, defaults to True) — 模型是自注意的（False 未实现）。

• activation_function (str or function, optional, defaults to "gelu") — 编码器和池化器中的非线性激活函数（函数或字符串）。如果是字符串，支持"gelu"、"relu"、"silu"和"gelu_new"。

• dropout (float, optional, defaults to 0.1) — 嵌入层、编码器和池化器中所有全连接层的 dropout 概率。

• attention_dropout (float, optional, defaults to 0.1) — 注意力权重的 dropout 概率。

• activation_dropout (float, optional, defaults to 0.1) — 线性变换器层激活的 dropout 概率。

• layerdrop (float, optional, defaults to 0.0) — 编码器的 LayerDrop 概率。有关更多详细信息，请参阅 LayerDrop paper)。

• bias (bool, optional, defaults to True) — 在注意力模块中使用偏置 - 目前不支持。

• embed_scale(float, optional, defaults to None) — 节点嵌入的缩放因子。

• num_trans_layers_to_freeze (int, optional, defaults to 0) — 要冻结的 Transformer 层数。

• encoder_normalize_before (bool, optional, defaults to False) — 在对图进行编码之前对特征进行归一化。

• pre_layernorm (bool, optional, defaults to False) — 在自注意力和前馈网络之前应用层归一化。如果没有这个，将使用后层归一化。

• apply_graphormer_init (bool, optional, defaults to False) — 在训练之前对模型应用自定义的 graphormer 初始化。

• freeze_embeddings (bool, optional, defaults to False) — 冻结嵌入层，或者与模型一起训练。

• encoder_normalize_before (bool, optional, defaults to False) — 在每个编码器块之前应用层归一化。

• q_noise (float, optional, defaults to 0.0) — 量化噪声的量（参见“使用量化噪声进行极端模型压缩”）。 （更多细节，请参阅 fairseq 关于 quant_noise 的文档）。

• qn_block_size (int, optional, defaults to 8) — 用于后续 iPQ 量化的块的大小（参见 q_noise）。

• kdim (int, optional, defaults to None) — 注意力中键的维度，如果与其他值不同。

• vdim (int, optional, defaults to None) — 注意力中值的维度，如果与其他值不同。

• use_cache (bool, optional, defaults to True) — 模型是否应返回最后的键/值注意力（并非所有模型都使用）。

• traceable (bool, optional, defaults to False) — 将编码器的 inner_state 的返回值更改为堆叠的张量。

  示例 —

这是一个配置类，用于存储~GraphormerModel 的配置。它用于根据指定的参数实例化一个 Graphormer 模型，定义模型架构。使用默认值实例化配置将产生类似于 Graphormer graphormer-base-pcqm4mv1架构的配置。

配置对象继承自 PretrainedConfig，可用于控制模型输出。阅读 PretrainedConfig 的文档以获取更多信息。

GraphormerModel

class transformers.GraphormerModel

< source >

( config: GraphormerConfig )

Graphormer 模型是一个图编码器模型。

它将一个图转换为其表示。如果您想将模型用于下游分类任务，请改用 GraphormerForGraphClassification。对于任何其他下游任务，请随意添加一个新类，或将此模型与您选择的下游模型结合，按照 GraphormerForGraphClassification 中的示例进行操作。

forward

< source >

( input_nodes: LongTensor input_edges: LongTensor attn_bias: Tensor in_degree: LongTensor out_degree: LongTensor spatial_pos: LongTensor attn_edge_type: LongTensor perturb: Optional = None masked_tokens: None = None return_dict: Optional = None **unused )

GraphormerForGraphClassification

class transformers.GraphormerForGraphClassification

< source >

( config: GraphormerConfig )

这个模型可以用于图级分类或回归任务。

可以在以下链接上进行训练

• 回归（通过将 config.num_classes 设置为 1）；每个图应有一个浮点类型标签

• 单任务分类（通过将 config.num_classes 设置为类别数）；每个图应有一个整数标签

• 二元多任务分类（通过将 config.num_classes 设置为标签数）；每个图应有一个整数标签列表。

forward

< source >

( input_nodes: LongTensor input_edges: LongTensor attn_bias: Tensor in_degree: LongTensor out_degree: LongTensor spatial_pos: LongTensor attn_edge_type: LongTensor labels: Optional = None return_dict: Optional = None **unused )

内部助手

自定义层和实用工具

原文链接：huggingface.co/docs/transformers/v4.37.2/en/internal/modeling_utils

此页面列出了库中使用的所有自定义层，以及为建模提供的实用函数。

大多数情况下，这些只有在研究库中模型的代码时才有用。

Pytorch 自定义模块

class transformers.Conv1D

<源代码>

( nf nx )

参数

• nf（int）- 输出特征的数量。

• nx（int）- 输入特征的数量。

由 Radford 等人为 OpenAI GPT（也用于 GPT-2）定义的一维卷积层。

基本上像一个线性层，但权重是转置的。

class transformers.modeling_utils.PoolerStartLogits

<源代码>

( config: PretrainedConfig )

参数

• config（PretrainedConfig）- 模型使用的配置，将用于获取模型的hidden_size。

从序列隐藏状态计算 SQuAD 开始 logits。

forward

<源代码>

( hidden_states: FloatTensor p_mask: Optional = None ) → export const metadata = 'undefined';torch.FloatTensor

参数

• hidden_states（形状为(batch_size, seq_len, hidden_size)的torch.FloatTensor）- 模型的最终隐藏状态。

• p_mask（形状为(batch_size, seq_len)的torch.FloatTensor，可选）- 用于无效位置的标记的掩码，例如查询和特殊符号（PAD，SEP，CLS）。1.0 表示应该屏蔽标记。

返回

torch.FloatTensor

SQuAD 的开始 logits。

class transformers.modeling_utils.PoolerEndLogits

<源代码>

( config: PretrainedConfig )

参数

• config（PretrainedConfig）- 模型使用的配置，将用于获取模型的hidden_size和要使用的layer_norm_eps。

从序列隐藏状态计算 SQuAD 结束 logits。

forward

<源代码>

( hidden_states: FloatTensor start_states: Optional = None start_positions: Optional = None p_mask: Optional = None ) → export const metadata = 'undefined';torch.FloatTensor

参数

• hidden_states（形状为(batch_size, seq_len, hidden_size)的torch.FloatTensor）- 模型的最终隐藏状态。

• start_states（形状为(batch_size, seq_len, hidden_size)的torch.FloatTensor，可选）- 标记跨度的第一个标记的隐藏状态。

• start_positions（形状为(batch_size,)的torch.LongTensor，可选）- 标记跨度的第一个标记的位置。

• p_mask（形状为(batch_size, seq_len)的torch.FloatTensor，可选）- 用于无效位置的标记的掩码，例如查询和特殊符号（PAD，SEP，CLS）。1.0 表示应该屏蔽标记。

返回

torch.FloatTensor

SQuAD 的结束 logits。

start_states或start_positions中的一个应该不是None。如果两者都设置了，start_positions会覆盖start_states。

class transformers.modeling_utils.PoolerAnswerClass

<源代码>

( config )

参数

• config（PretrainedConfig）- 模型使用的配置，将用于获取模型的hidden_size。

从分类和开始标记的隐藏状态计算 SQuAD 2.0 答案类。

forward

<源代码>

( hidden_states: FloatTensor start_states: Optional = None start_positions: Optional = None cls_index: Optional = None ) → export const metadata = 'undefined';torch.FloatTensor

参数

• hidden_states（形状为(batch_size, seq_len, hidden_size)的torch.FloatTensor）- 模型的最终隐藏状态。

• start_states (torch.FloatTensor of shape (batch_size, seq_len, hidden_size), optional) — 标记范围内第一个标记的隐藏状态。

• start_positions (torch.LongTensor of shape (batch_size,), optional) — 标记范围内第一个标记的位置。

• cls_index (torch.LongTensor of shape (batch_size,), optional) — 每个句子中 CLS 标记的位置。如果为None，则取最后一个标记。

返回

torch.FloatTensor

SQuAD 2.0 答案类。

start_states或start_positions中的一个应该不是None。如果两者都设置了，start_positions会覆盖start_states。

class transformers.modeling_utils.SquadHeadOutput

<来源>

( loss: Optional = None start_top_log_probs: Optional = None start_top_index: Optional = None end_top_log_probs: Optional = None end_top_index: Optional = None cls_logits: Optional = None )

参数

• loss (torch.FloatTensor of shape (1,), optional, 如果提供了start_positions和end_positions则返回) — 分类损失，作为起始标记、结束标记（如果提供了 is_impossible 则包括）分类损失的总和。

• start_top_log_probs (torch.FloatTensor of shape (batch_size, config.start_n_top), optional, 如果未提供start_positions或end_positions则返回) — 前 config.start_n_top 个起始标记可能性的对数概率（beam-search）。

• start_top_index (torch.LongTensor of shape (batch_size, config.start_n_top), optional, 如果未提供start_positions或end_positions则返回) — 前 config.start_n_top 个起始标记可能性的索引（beam-search）。

• end_top_log_probs (torch.FloatTensor of shape (batch_size, config.start_n_top * config.end_n_top), optional, 如果未提供start_positions或end_positions则返回) — 前config.start_n_top * config.end_n_top个结束标记可能性的对数概率（beam-search）。

• end_top_index (torch.LongTensor of shape (batch_size, config.start_n_top * config.end_n_top), optional, 如果未提供start_positions或end_positions则返回) — 前config.start_n_top * config.end_n_top个结束标记可能性的索引（beam-search）。

• cls_logits (torch.FloatTensor of shape (batch_size,), optional, 如果未提供start_positions或end_positions则返回) — 答案的is_impossible标签的对数概率。

用于使用 SQuADHead 的问答模型输出的基类。

class transformers.modeling_utils.SQuADHead

<来源>

( config )

参数

• config (PretrainedConfig) — 模型使用的配置，将用于获取模型的hidden_size和要使用的layer_norm_eps。

受 XLNet 启发的 SQuAD 头部。

forward

<来源>

( hidden_states: FloatTensor start_positions: Optional = None end_positions: Optional = None cls_index: Optional = None is_impossible: Optional = None p_mask: Optional = None return_dict: bool = False ) → export const metadata = 'undefined';transformers.modeling_utils.SquadHeadOutput or tuple(torch.FloatTensor)

参数

• hidden_states (torch.FloatTensor of shape (batch_size, seq_len, hidden_size)) — 模型在序列标记上的最终隐藏状态。

• start_positions (torch.LongTensor of shape (batch_size,), optional) — 标记范围内第一个标记的位置。

• end_positions (torch.LongTensor of shape (batch_size,), optional) — 标记范围内最后一个标记的位置。

• cls_index (torch.LongTensor of shape (batch_size,), optional) — 每个句子中 CLS 标记的位置。如果为None，则取最后一个标记。

• is_impossible (torch.LongTensor of shape (batch_size,), optional) — 问题在段落中是否有可能回答。

• p_mask (torch.FloatTensor of shape (batch_size, seq_len), optional) — 用于无效位置的标记的掩码，例如查询和特殊符号（PAD、SEP、CLS）。1.0 表示应该屏蔽标记。

• return_dict (bool, optional, 默认为False) — 是否返回 ModelOutput 而不是普通元组。

返回

transformers.modeling_utils.SquadHeadOutput 或tuple(torch.FloatTensor)

一个 transformers.modeling_utils.SquadHeadOutput 或一个torch.FloatTensor元组（如果传递了return_dict=False或当config.return_dict=False时）包含根据配置（<class 'transformers.configuration_utils.PretrainedConfig'>）和输入的不同元素。

• loss (torch.FloatTensor of shape (1,), optional, returned if both start_positions and end_positions are provided) — 分类损失，作为开始令牌、结束令牌（如果提供）的分类损失之和。

• start_top_log_probs (torch.FloatTensor of shape (batch_size, config.start_n_top), optional, returned if start_positions or end_positions is not provided) — 前端令牌可能性的前config.start_n_top个的对数概率（波束搜索）。

• start_top_index (torch.LongTensor of shape (batch_size, config.start_n_top), optional, returned if start_positions or end_positions is not provided) — 前config.start_n_top个开始令牌可能性的索引（波束搜索）。

• end_top_log_probs (torch.FloatTensor of shape (batch_size, config.start_n_top * config.end_n_top), optional, returned if start_positions or end_positions is not provided) — 顶部config.start_n_top * config.end_n_top结束令牌可能性的对数概率（波束搜索）。

• end_top_index (torch.LongTensor of shape (batch_size, config.start_n_top * config.end_n_top), optional, returned if start_positions or end_positions is not provided) — 顶部config.start_n_top * config.end_n_top结束令牌可能性的索引（波束搜索）。

• cls_logits (torch.FloatTensor of shape (batch_size,), optional, returned if start_positions or end_positions is not provided) — 答案的is_impossible标签的对数概率。

class transformers.modeling_utils.SequenceSummary

< source >

( config: PretrainedConfig )

参数

• config (PretrainedConfig) — 模型使用的配置。模型的配置类中的相关参数为（请参考您的模型的实际配置类以查看其使用的默认值）：

  • summary_type (str) — 用于制作摘要的方法。接受的值为：

    • "last" — 获取最后一个令牌的隐藏状态（类似于 XLNet）

    • "first" — 获取第一个令牌的隐藏状态（类似于 Bert）

    • "mean" — 取所有令牌隐藏状态的平均值

    • "cls_index" — 提供分类令牌位置的张量（GPT/GPT-2）

    • "attn" — 目前未实现，使用多头注意力

  • summary_use_proj (bool) — 在向量提取后添加一个投影。

  • summary_proj_to_labels (bool) — 如果为True，则投影输出到config.num_labels类（否则为config.hidden_size）。

  • summary_activation (Optional[str]) — 设置为"tanh"以在输出中添加 tanh 激活，另一个字符串或None将不添加激活。

  • summary_first_dropout (float) — 投影和激活之前的可选丢弃概率。

  • summary_last_dropout (float)— 投影和激活后的可选丢弃概率。

计算序列隐藏状态的单个向量摘要。

forward

< source >

( hidden_states: FloatTensor cls_index: Optional = None ) → export const metadata = 'undefined';torch.FloatTensor

参数

• hidden_states（形状为[batch_size, seq_len, hidden_size]的torch.FloatTensor）- 最后一层的隐藏状态。

• cls_index（形状为[batch_size]或[batch_size, ...]的torch.LongTensor，其中…是hidden_states的可选前导维度，可选）- 如果summary_type == "cls_index"，则用于将序列的最后一个标记作为分类标记。

返回

torch.FloatTensor

序列隐藏状态的摘要。

计算序列隐藏状态的单个向量摘要。

PyTorch 辅助函数

transformers.apply_chunking_to_forward

<来源>

( forward_fn: Callable chunk_size: int chunk_dim: int *input_tensors ) → export const metadata = 'undefined';torch.Tensor

参数

• forward_fn（Callable[..., torch.Tensor]）- 模型的前向函数。

• chunk_size（int）- 分块张量的块大小：num_chunks = len(input_tensors[0]) / chunk_size。

• chunk_dim（int）- 应该对input_tensors进行分块的维度。

• input_tensors（Tuple[torch.Tensor]）- forward_fn的输入张量，将被分块

返回

torch.Tensor

一个与应用forward_fn后给出的forward_fn相同形状的张量。

此函数将input_tensors分块为大小为chunk_size的较小输入张量部分，沿着维度chunk_dim。然后独立地对每个块应用层forward_fn以节省内存。

如果forward_fn在chunk_dim上独立，这个函数将产生与直接将forward_fn应用于input_tensors相同的结果。

示例：

# rename the usual forward() fn to forward_chunk()
def forward_chunk(self, hidden_states):
    hidden_states = self.decoder(hidden_states)
    return hidden_states

# implement a chunked forward function
def forward(self, hidden_states):
    return apply_chunking_to_forward(self.forward_chunk, self.chunk_size_lm_head, self.seq_len_dim, hidden_states)

transformers.pytorch_utils.find_pruneable_heads_and_indices

<来源>

( heads: List n_heads: int head_size: int already_pruned_heads: Set ) → export const metadata = 'undefined';Tuple[Set[int], torch.LongTensor]

参数

• heads（List[int]）- 要修剪的头的索引列表。

• n_heads（int）- 模型中头的数量。

• head_size（int）- 每个头的大小。

• already_pruned_heads（Set[int]）- 一个已经修剪的头的集合。

返回

Tuple[Set[int], torch.LongTensor]

一个元组，其中包括要修剪的头的索引（考虑already_pruned_heads）和要在层权重中保留的行/列的索引。

找到头和它们的索引，考虑already_pruned_heads。

transformers.prune_layer

<来源>

( layer: Union index: LongTensor dim: Optional = None ) → export const metadata = 'undefined';torch.nn.Linear or Conv1D

参数

• layer（Union[torch.nn.Linear, Conv1D]）- 要修剪的层。

• index（torch.LongTensor）- 要在层中保留的索引。

• dim（int，可选）- 保留索引的维度。

返回

torch.nn.Linear或 Conv1D

将修剪后的层作为一个新的层，requires_grad=True。

修剪一个 Conv1D 或线性层，只保留索引中的条目。

用于移除头。

transformers.pytorch_utils.prune_conv1d_layer

<来源>

( layer: Conv1D index: LongTensor dim: int = 1 ) → export const metadata = 'undefined';Conv1D

参数

• layer（Conv1D）- 要修剪的层。

• index（torch.LongTensor）- 要在层中保留的索引。

• dim（int，可选，默认为 1）- 保留索引的维度。

返回

Conv1D

将修剪后的层作为一个新的层，requires_grad=True。

修剪一个 Conv1D 层，只保留索引中的条目。Conv1D 作为一个线性层工作（参见例如 BERT），但权重是转置的。

用于移除头。

transformers.pytorch_utils.prune_linear_layer

<来源>

( layer: Linear index: LongTensor dim: int = 0 ) → export const metadata = 'undefined';torch.nn.Linear

参数

• layer（torch.nn.Linear）- 要修剪的层。

• index（torch.LongTensor）- 要在层中保留的索引。

• dim（int，可选，默认为 0）- 保留索引的维度。

返回

torch.nn.Linear

修剪的层作为一个新层，requires_grad=True。

修剪线性层以仅保留索引中的条目。

用于移除头部。

TensorFlow 自定义层

class transformers.modeling_tf_utils.TFConv1D

<来源>

( nf nx initializer_range = 0.02 **kwargs )

参数

• nf（int）— 输出特征的数量。

• nx（int）— 输入特征的数量。

• initializer_range（float，可选，默认为 0.02）— 用于初始化权重的标准差。

• kwargs（Dict[str, Any]，可选）— 传递给tf.keras.layers.Layer的__init__的额外关键字参数。

由 Radford 等人为 OpenAI GPT 定义的一维卷积层（也用于 GPT-2）。

基本上像一个线性层，但权重是转置的。

class transformers.TFSequenceSummary

<来源>

( config: PretrainedConfig initializer_range: float = 0.02 **kwargs )

参数

• config（PretrainedConfig）— 模型使用的配置。模型的配置类中的相关参数为（请参考您的模型的实际配置类以获取其使用的默认值）：

  • summary_type（str）— 用于生成此摘要的方法。接受的值为：

    • "last" — 获取最后一个标记的隐藏状态（类似于 XLNet）

    • "first" — 获取第一个标记的隐藏状态（类似于 Bert）

    • "mean" — 获取所有标记的隐藏状态的平均值

    • "cls_index" — 提供一个分类标记位置的张量（GPT/GPT-2）

    • "attn" — 目前未实现，使用多头注意力

  • summary_use_proj（bool）— 在向量提取后添加投影。

  • summary_proj_to_labels（bool）— 如果为True，则投影输出到config.num_labels类（否则到config.hidden_size）。

  • summary_activation（Optional[str]）— 设置为"tanh"以在输出中添加 tanh 激活，另一个字符串或None将不添加激活。

  • summary_first_dropout（float）— 投影和激活之前的可选丢弃概率。

  • summary_last_dropout（float）— 投影和激活之后的可选丢弃概率。

• initializer_range（float，默认为 0.02）— 用于初始化权重的标准差。

• kwargs（Dict[str, Any]，可选）— 传递给tf.keras.layers.Layer的__init__的额外关键字参数。

计算序列隐藏状态的单个向量摘要。

TensorFlow 损失函数

class transformers.modeling_tf_utils.TFCausalLanguageModelingLoss

<来源>

( )

适用于因果语言建模（CLM）的损失函数，即猜测下一个标记的任务。

任何标签为-100 的将在损失计算中被忽略（以及相应的对数）。

class transformers.modeling_tf_utils.TFMaskedLanguageModelingLoss

<来源>

( )

适用于掩码语言建模（MLM）的损失函数，即猜测掩码标记的任务。

任何标签为-100 的将在损失计算中被忽略（以及相应的对数）。

class transformers.modeling_tf_utils.TFMultipleChoiceLoss

<来源>

( )

适用于多项选择任务的损失函数。

class transformers.modeling_tf_utils.TFQuestionAnsweringLoss

<来源>

( )

适用于问答的损失函数。

class transformers.modeling_tf_utils.TFSequenceClassificationLoss

<来源>

( )

适用于序列分类的损失函数。

class transformers.modeling_tf_utils.TFTokenClassificationLoss

<来源>

( )

适用于标记分类的损失函数。

任何标签为-100 的将在损失计算中被忽略（以及相应的 logits）。

TensorFlow 辅助函数

transformers.modeling_tf_utils.get_initializer

<来源>

( initializer_range: float = 0.02 ) → export const metadata = 'undefined';tf.keras.initializers.TruncatedNormal

参数

• initializer_range（float，默认为 0.02）- 初始化器范围的标准差。

返回

tf.keras.initializers.TruncatedNormal

截断正态初始化器。

使用给定范围创建一个tf.keras.initializers.TruncatedNormal。

transformers.modeling_tf_utils.keras_serializable

<来源>

( )

参数

• cls（一个tf.keras.layers.Layers 子类）- 通常在这个项目中是一个TF.MainLayer类，一般必须接受一个config参数作为其初始化器。

装饰一个 Keras Layer 类以支持 Keras 序列化。

这是通过以下方式完成的：

1. 在get_config中的 Keras 配置字典中添加一个transformers_config字典（由 Keras 在序列化时调用）。

2. 包装__init__以接受transformers_config字典（由 Keras 在反序列化时传递）并将其转换为实际层初始化器的配置对象。

3. 在 Keras 中将类注册为自定义对象（如果 Tensorflow 版本支持），这样在调用tf.keras.models.load_model时就不需要在custom_objects中提供它。

transformers.shape_list

<来源>

( tensor: Union ) → export const metadata = 'undefined';List[int]

参数

• tensor（tf.Tensor或np.ndarray）- 我们想要形状的张量。

返回

List[int]

作为列表的张量形状。

在 tensorflow 中处理动态形状。

管道的实用程序

原文：huggingface.co/docs/transformers/v4.37.2/en/internal/pipelines_utils

此页面列出了库为管道提供的所有实用程序函数。

这些大多数只有在研究库中模型的代码时才有用。

参数处理

class transformers.pipelines.ArgumentHandler

<来源>

( )

处理每个 Pipeline 的参数的基本接口。

class transformers.pipelines.ZeroShotClassificationArgumentHandler

<来源>

( )

通过将每个可能的标签转换为 NLI 前提/假设对来处理零射击文本分类的参数。

class transformers.pipelines.QuestionAnsweringArgumentHandler

<来源>

( )

QuestionAnsweringPipeline 要求用户提供多个参数（即问题和上下文），以映射到内部的 SquadExample。

QuestionAnsweringArgumentHandler 管理从命令行提供的参数创建 SquadExample 的所有可能性。

数据格式

class transformers.PipelineDataFormat

<来源>

( output_path: Optional input_path: Optional column: Optional overwrite: bool = False )

参数

• output_path (str) — 要保存传出数据的位置。

• input_path (str) — 要查找输入数据的位置。

• column (str) — 要读取的列。

• overwrite (bool, 可选, 默认为 False) — 是否覆盖 output_path。

所有管道支持的数据格式的基类，用于读取和写入。当前支持的数据格式包括：

• JSON

• CSV

• stdin/stdout（管道）

PipelineDataFormat 还包括一些实用程序，用于处理多列，例如通过 dataset_kwarg_1=dataset_column_1 格式将数据集列映射到管道关键字参数。

from_str

<来源>

( format: str output_path: Optional input_path: Optional column: Optional overwrite = False ) → export const metadata = 'undefined';PipelineDataFormat

参数

• format (str) — 所需管道的格式。可接受的值为 "json"、"csv" 或 "pipe"。

• output_path (str, 可选) — 要保存传出数据的位置。

• input_path (str, 可选) — 要查找输入数据的位置。

• column (str, 可选) — 要读取的列。

• overwrite (bool, 可选, 默认为 False) — 是否覆盖 output_path。

返回

PipelineDataFormat

适当的数据格式。

根据 format 创建 PipelineDataFormat 的正确子类实例。

save

<来源>

( data: Union )

参数

• data (dict 或 dict 列表) — 要存储的数据。

使用当前 PipelineDataFormat 的表示保存提供的数据对象。

save_binary

<来源>

( data: Union ) → export const metadata = 'undefined';str

参数

• data (dict 或 dict 列表) — 要存储的数据。

返回

str

数据保存的路径。

将提供的数据对象保存为 pickle 格式的二进制数据在磁盘上。

class transformers.CsvPipelineDataFormat

<来源>

( output_path: Optional input_path: Optional column: Optional overwrite = False )

参数

• output_path (str) — 保存传出数据的位置。

• input_path (str) — 查找输入数据的位置。

• column (str) — 要读取的列。

• overwrite (bool, 可选, 默认为 False) — 是否覆盖 output_path。

支持使用 CSV 数据格式的管道。

保存

<来源>

( data: List )

参数

• data (List[dict]) — 要存储的数据。

使用当前的 PipelineDataFormat 表示保存提供的数据对象。

class transformers.JsonPipelineDataFormat

<来源>

( output_path: Optional input_path: Optional column: Optional overwrite = False )

参数

• output_path (str) — 保存传出数据的位置。

• input_path (str) — 查找输入数据的位置。

• column (str) — 要读取的列。

• overwrite (bool, 可选, 默认为 False) — 是否覆盖 output_path。

支持使用 JSON 文件格式的管道。

保存

<来源>

( data: dict )

参数

• data (dict) — 要存储的数据。

将提供的数据对象保存在 json 文件中。

class transformers.PipedPipelineDataFormat

<来源>

( output_path: Optional input_path: Optional column: Optional overwrite: bool = False )

参数

• output_path (str) — 保存传出数据的位置。

• input_path (str) — 查找输入数据的位置。

• column (str) — 要读取的列。

• overwrite (bool, 可选, 默认为 False) — 是否覆盖 output_path。

从管道输入读取数据到 python 进程。对于多列数据，列应该用分隔符分开

如果提供了列，则输出将是一个包含 {column_x: value_x} 的字典

保存

<来源>

( data: dict )

参数

• data (dict) — 要存储的数据。

打印数据。

实用工具

class transformers.pipelines.PipelineException

<来源>

( task: str model: str reason: str )

参数

• task (str) — 管道的任务。

• model (str) — 管道使用的模型。

• reason (str) — 要显示的错误消息。

在处理 call 时由 Pipeline 引发。

分词器实用程序

原始文本：huggingface.co/docs/transformers/v4.37.2/en/internal/tokenization_utils

此页面列出了分词器使用的所有实用函数，主要是实现 PreTrainedTokenizer 和 PreTrainedTokenizerFast 之间的常见方法的类 PreTrainedTokenizerBase 和混合 SpecialTokensMixin。

大多数情况下，这些只有在研究库中的分词器代码时才有用。

PreTrainedTokenizerBase

class transformers.PreTrainedTokenizerBase

< source >

( **kwargs )

参数

• model_max_length (int, 可选) — 输入到变换器模型的最大长度（以标记数计）。当使用 from_pretrained() 加载分词器时，此值将设置为存储在 max_model_input_sizes 中关联模型的值（参见上文）。如果未提供值，将默认为 VERY_LARGE_INTEGER (int(1e30)).

• padding_side (str, 可选) — 模型应该应用填充的一侧。应在 ['right', 'left'] 中选择。默认值从同名类属性中选择。

• truncation_side (str, 可选) — 模型应该应用截断的一侧。应在 ['right', 'left'] 中选择。默认值从同名类属性中选择。

• chat_template (str, 可选) — 用于格式化聊天消息列表的 Jinja 模板字符串。查看 huggingface.co/docs/transformers/chat_templating 获取完整描述。

• model_input_names (List[string], 可选) — 模型前向传递接受的输入列表（如 "token_type_ids" 或 "attention_mask"）。默认值从同名类属性中选择。

• bos_token (str 或 tokenizers.AddedToken, 可选) — 代表句子开头的特殊标记。将与 self.bos_token 和 self.bos_token_id 相关联。

• eos_token (str 或 tokenizers.AddedToken, 可选) — 代表句子结尾的特殊标记。将与 self.eos_token 和 self.eos_token_id 相关联。

• unk_token (str 或 tokenizers.AddedToken, 可选) — 代表一个未知词的特殊标记。将与 self.unk_token 和 self.unk_token_id 相关联。

• sep_token (str 或 tokenizers.AddedToken, 可选) — 用于在同一输入中分隔两个不同句子的特殊标记（例如，BERT 使用）。将与 self.sep_token 和 self.sep_token_id 相关联。

• pad_token (str 或 tokenizers.AddedToken, 可选) — 用于使标记数组大小相同以进行批处理的特殊标记。然后将被注意机制或损失计算忽略。将与 self.pad_token 和 self.pad_token_id 相关联。

• cls_token (str 或 tokenizers.AddedToken, 可选) — 代表输入类别的特殊标记（例如，BERT 使用）。将与 self.cls_token 和 self.cls_token_id 相关联。

• mask_token (str 或 tokenizers.AddedToken, 可选) — 代表一个被屏蔽的标记的特殊标记（用于掩码语言建模预训练目标，如 BERT）。将与 self.mask_token 和 self.mask_token_id 相关联。

• additional_special_tokens（元组或str或tokenizers.AddedToken的列表，可选） — 附加特殊标记的元组或列表。在此处添加它们以确保在skip_special_tokens设置为 True 时解码时跳过它们。如果它们不是词汇的一部分，它们将被添加到词汇的末尾。

• clean_up_tokenization_spaces (bool, 可选，默认为True) — 模型是否应清除在分词过程中拆分输入文本时添加的空格。

• split_special_tokens (bool, 可选，默认为False) — 特殊标记是否应在分词过程中拆分。默认行为是不拆分特殊标记。这意味着如果<s>是bos_token，那么tokenizer.tokenize("<s>") = ['<s>]。否则，如果split_special_tokens=True，那么tokenizer.tokenize("")将给出['<', 's', '>']。目前仅支持slow`分词器支持此参数。

PreTrainedTokenizer 和 PreTrainedTokenizerFast 的基类。

处理这两个类的共享（大部分是样板）方法。

类属性（由派生类覆盖）

• vocab_files_names (Dict[str, str]) — 一个字典，其中键是模型所需的每个词汇文件的__init__关键字名称，关联值是用于保存关联文件的文件名（字符串）。

• pretrained_vocab_files_map (Dict[str, Dict[str, str]]) — 一个字典的字典，高级键是模型所需的每个词汇文件的__init__关键字名称，低级键是预训练模型的short-cut-names，关联值是关联预训练词汇文件的url。

• max_model_input_sizes (Dict[str, Optional[int]]) — 一个字典，其中键是预训练模型的short-cut-names，关联值是该模型的序列输入的最大长度，如果模型没有最大输入大小，则为None。

• pretrained_init_configuration (Dict[str, Dict[str, Any]]) — 预训练模型的short-cut-names作为键，关联值是一个字典，其中包含加载预训练模型时传递给 tokenizer 类的__init__方法的特定参数。

• model_input_names (List[str]) — 模型前向传递中预期的输入列表。

• padding_side (str) — 模型应该应用填充的默认位置。应为'right'或'left'。

• truncation_side (str) — 模型应该应用截断的默认位置。应为'right'或'left'。

__call__

<来源>

( text: Union = None text_pair: Union = None text_target: Union = None text_pair_target: Union = None add_special_tokens: bool = True padding: Union = False truncation: Union = None max_length: Optional = None stride: int = 0 is_split_into_words: bool = False pad_to_multiple_of: Optional = None return_tensors: Union = None return_token_type_ids: Optional = None return_attention_mask: Optional = None return_overflowing_tokens: bool = False return_special_tokens_mask: bool = False return_offsets_mapping: bool = False return_length: bool = False verbose: bool = True **kwargs ) → export const metadata = 'undefined';BatchEncoding

参数

• text (str, List[str], List[List[str]], optional) — 要编码的序列或批量序列。每个序列可以是字符串或字符串列表（预先分词的字符串）。如果提供的序列是字符串列表（预先分词的），必须设置is_split_into_words=True（以消除与批量序列的歧义）。

• text_pair (str, List[str], List[List[str]], optional) — 要编码的序列或批量序列。每个序列可以是字符串或字符串列表（预先分词的字符串）。如果提供的序列是字符串列表（预先分词的），必须设置is_split_into_words=True（以消除与批量序列的歧义）。

• text_target（str，List[str]，List[List[str]]，可选）— 要编码为目标文本的序列或批次。每个序列可以是字符串或字符串列表（预分词字符串）。如果将序列提供为字符串列表（预分词），必须设置is_split_into_words=True（以消除与批次序列的歧义）。

• text_pair_target（str，List[str]，List[List[str]]，可选）— 要编码为目标文本的序列或批次。每个序列可以是字符串或字符串列表（预分词字符串）。如果将序列提供为字符串列表（预分词），必须设置is_split_into_words=True（以消除与批次序列的歧义）。

• add_special_tokens（bool，可选，默认为True）— 在编码序列时是否添加特殊标记。这将使用底层的PretrainedTokenizerBase.build_inputs_with_special_tokens函数，该函数定义了自动添加到输入 id 的标记。如果要自动添加bos或eos标记，则这很有用。

• padding（bool，str或 PaddingStrategy，可选，默认为False）— 激活和控制填充。接受以下值：

  • True或'longest'：填充到批次中最长的序列（如果只提供单个序列，则不填充）。

  • 'max_length': 使用参数max_length指定的最大长度进行填充，或者使用模型的最大可接受输入长度（如果未提供该参数）。

  • False或'do_not_pad'（默认）：无填充（即，可以输出长度不同的序列批次）。

• truncation（bool，str或 TruncationStrategy，可选，默认为False）— 激活和控制截断。接受以下值：

  • True或'longest_first'：使用参数max_length指定的最大长度进行截断，或者使用模型的最大可接受输入长度（如果未提供该参数）。这将逐标记截断，如果提供了一对序列（或一批对序列），则从较长序列中删除一个标记。

  • 'only_first': 使用参数max_length指定的最大长度进行截断，或者使用模型的最大可接受输入长度（如果未提供该参数）。如果提供了一对序列（或一批对序列），则仅截断第一个序列。

  • 'only_second': 使用参数max_length指定的最大长度进行截断，或者使用模型的最大可接受输入长度（如果未提供该参数）。如果提供了一对序列（或一批对序列），则仅截断第二个序列。

  • False或'do_not_truncate'（默认）：无截断（即，可以输出长度大于模型最大可接受输入大小的批次）。

• max_length（int，可选）— 由截断/填充参数之一使用的最大长度。

  如果未设置或设置为None，则将使用预定义的模型最大长度（如果截断/填充参数中需要最大长度）。如果模型没有特定的最大输入长度（如 XLNet），则将禁用截断/填充到最大长度。

• stride（int，可选，默认为 0）— 如果与max_length一起设置为一个数字，则当return_overflowing_tokens=True时返回的溢出标记将包含截断序列末尾的一些标记，以提供截断和溢出序列之间的一些重叠。此参数的值定义了重叠标记的数量。

• is_split_into_words (bool, optional, defaults to False) — 输入是否已经预分词化（例如，已经分成单词）。如果设置为True，分词器会假定输入已经分成单词（例如，通过在空格上分割），然后对其进行分词。这对于 NER 或令牌分类很有用。

• pad_to_multiple_of (int, optional) — 如果设置，将填充序列到提供的值的倍数。需要激活padding。这对于启用具有计算能力>= 7.5（Volta）的 NVIDIA 硬件上的 Tensor Cores 的使用特别有用。

• return_tensors (str或 TensorType, optional) — 如果设置，将返回张量而不是 Python 整数列表。可接受的值为：

  • 'tf': 返回 TensorFlow tf.constant对象。

  • 'pt': 返回 PyTorch torch.Tensor对象。

  • 'np': 返回 Numpy np.ndarray对象。

• return_token_type_ids (bool, optional) — 是否返回令牌类型 ID。如果保持默认设置，将根据特定分词器的默认值返回令牌类型 ID，由return_outputs属性定义。

  什么是 token 类型 ID？

• return_attention_mask (bool, optional) — 是否返回注意力掩码。如果保持默认设置，将根据特定分词器的默认值返回注意力掩码，由return_outputs属性定义。

  什么是注意力掩码？

• return_overflowing_tokens (bool, optional, defaults to False) — 是否返回溢出的令牌序列。如果提供了一对输入 ID 序列（或一批对）并且truncation_strategy = longest_first或True，则会引发错误，而不是返回溢出的令牌。

• return_special_tokens_mask (bool, optional, defaults to False) — 是否返回特殊令牌掩码信息。

• return_offsets_mapping (bool, optional, defaults to False) — 是否返回每个令牌的(char_start, char_end)。

  这仅适用于继承自 PreTrainedTokenizerFast 的快速分词器，如果使用 Python 的分词器，此方法将引发NotImplementedError。

• return_length (bool, optional, defaults to False) — 是否返回编码输入的长度。

• verbose (bool, optional, defaults to True) — 是否打印更多信息和警告。**kwargs — 传递给self.tokenize()方法

返回

BatchEncoding

具有以下字段的 BatchEncoding：

• input_ids — 要馈送给模型的令牌 ID 列表。

  什么是输入 ID？

• token_type_ids — 要馈送给模型的令牌类型 ID 列表（当return_token_type_ids=True或token_type_ids在self.model_input_names中时）。

  什么是 token 类型 ID？

• attention_mask — 指定模型应该关注的令牌的索引列表（当return_attention_mask=True或attention_mask在self.model_input_names中时）。

  什么是注意力掩码？

• overflowing_tokens — 溢出的令牌序列列表（当指定max_length并且return_overflowing_tokens=True时）。

• num_truncated_tokens — 被截断的令牌数量（当指定max_length并且return_overflowing_tokens=True时）。

• special_tokens_mask — 0 和 1 的列表，其中 1 指定添加的特殊令牌，0 指定常规序列令牌（当add_special_tokens=True和return_special_tokens_mask=True时）。

• length — 输入的长度（当return_length=True时）

标记化和为模型准备一个或多个序列或一个或多个序列对的主要方法。

apply_chat_template

<来源>

( conversation: Union chat_template: Optional = None add_generation_prompt: bool = False tokenize: bool = True padding: bool = False truncation: bool = False max_length: Optional = None return_tensors: Union = None **tokenizer_kwargs ) → export const metadata = 'undefined';List[int]

参数

• conversation（Union[List[Dict[str, str]], “Conversation”） — 一个 Conversation 对象或包含“role”和“content”键的字典列表，表示到目前为止的聊天历史。

• chat_template（str，可选） — 用于此转换的 Jinja 模板。如果未传递此参数，则将使用模型的默认聊天模板。

• add_generation_prompt（bool，可选） — 是否以指示助手消息开始的标记结束提示。当您想要从模型生成响应时，这很有用。请注意，此参数将传递给聊天模板，因此必须在模板中支持此参数才能产生任何效果。

• tokenize（bool，默认为True） — 是否对输出进行标记化。如果为False，输出将是一个字符串。

• padding（bool，默认为False） — 是否将序列填充到最大长度。如果 tokenize 为False，则无效。

• truncation（bool，默认为False） — 是否在最大长度处截断序列。如果 tokenize 为False，则无效。

• max_length（int，可选） — 用于填充或截断的最大长度（以标记为单位）。如果未指定，则将使用分词器的max_length属性作为默认值。

• return_tensors（str或 TensorType，可选） — 如果设置，将返回特定框架的张量。如果 tokenize 为False，则无效。可接受的值为：

  • 'tf'：返回 TensorFlow tf.Tensor对象。

  • 'pt'：返回 PyTorch torch.Tensor对象。

  • 'np'：返回 NumPy np.ndarray对象。

  • 'jax'：返回 JAX jnp.ndarray对象。**tokenizer_kwargs — 传递给分词器的额外 kwargs。

返回

List[int]

表示到目前为止标记化聊天的标记 id 列表，包括控制标记。此输出已准备好直接传递给模型，或通过generate()等方法传递。

将 Conversation 对象或包含"role"和"content"键的字典列表转换为标记 id 列表。此方法旨在与聊天模型一起使用，并将读取分词器的 chat_template 属性以确定在转换时要使用的格式和控制标记。当 chat_template 为 None 时，将退回到在类级别指定的 default_chat_template。

as_target_tokenizer

<来源>

( )

临时设置用于编码目标的分词器。对于需要为标签进行稍微不同处理的序列到序列模型相关的分词器非常有用。

batch_decode

<来源>

( sequences: Union skip_special_tokens: bool = False clean_up_tokenization_spaces: bool = None **kwargs ) → export const metadata = 'undefined';List[str]

参数

• sequences (Union[List[int], List[List[int]], np.ndarray, torch.Tensor, tf.Tensor]) — 标记化输入 id 的列表。可以使用__call__方法获得。

• skip_special_tokens（bool，可选，默认为False） — 是否删除解码中的特殊标记。

• clean_up_tokenization_spaces（bool，可选） — 是否清除分词空格。如果为None，将默认为self.clean_up_tokenization_spaces。

• kwargs（额外的关键字参数，可选） — 将传递给底层模型特定的解码方法。

返回

List[str]

解码的句子列表。

将标记 id 列表的列表转换为字符串列表，通过调用解码。

batch_encode_plus

<来源>

( batch_text_or_text_pairs: Union add_special_tokens: bool = True padding: Union = False truncation: Union = None max_length: Optional = None stride: int = 0 is_split_into_words: bool = False pad_to_multiple_of: Optional = None return_tensors: Union = None return_token_type_ids: Optional = None return_attention_mask: Optional = None return_overflowing_tokens: bool = False return_special_tokens_mask: bool = False return_offsets_mapping: bool = False return_length: bool = False verbose: bool = True **kwargs ) → export const metadata = 'undefined';BatchEncoding

参数

• batch_text_or_text_pairs（List[str]，List[Tuple[str, str]]，List[List[str]]，List[Tuple[List[str], List[str]]，以及对于非快速分词器，还有List[List[int]]，List[Tuple[List[int], List[int]]） - 要编码的序列或序列对批次。这可以是字符串/字符串序列/整数序列列表或字符串/字符串序列/整数序列对列表（请参阅encode_plus中的详细信息）。

• add_special_tokens（bool，可选，默认为True） - 在编码序列时是否添加特殊标记。这将使用底层的PretrainedTokenizerBase.build_inputs_with_special_tokens函数，该函数定义了自动添加到输入 id 的标记。如果要自动添加bos或eos标记，则这很有用。

• padding（bool，str或 PaddingStrategy，可选，默认为False） - 激活和控制填充。接受以下值：

  • True或'longest'：填充到批次中最长的序列（如果只提供了单个序列，则不进行填充）。

  • 'max_length': 使用参数max_length指定的最大长度进行填充，或者如果未提供该参数，则使用模型的最大可接受输入长度。

  • False或'do_not_pad'（默认）：不进行填充（即，可以输出长度不同的序列批次）。

• truncation（bool，str或 TruncationStrategy，可选，默认为False） - 激活和控制截断。接受以下值：

  • True或'longest_first': 使用参数max_length指定的最大长度进行截断，或者如果未提供该参数，则使用模型的最大可接受输入长度。这将逐个标记地截断，如果提供了一对序列（或一批序列），则从该对中最长的序列中删除一个标记。

  • 'only_first'：使用参数max_length指定的最大长度进行截断，或者如果未提供该参数，则使用模型的最大可接受输入长度。如果提供了一对序列（或一批序列），则仅截断第一个序列。

  • 'only_second'：使用参数max_length指定的最大长度进行截断，或者如果未提供该参数，则使用模型的最大可接受输入长度。如果提供了一对序列（或一批序列），则仅截断第二个序列。

  • False或'do_not_truncate'（默认）：不进行截断（即，可以输出长度大于模型最大可接受输入大小的序列批次）。

• max_length（int，可选） - 控制截断/填充参数使用的最大长度。

  如果未设置或设置为None，则如果截断/填充参数中的一个需要最大长度，则将使用预定义的模型最大长度。如果模型没有特定的最大输入长度（如 XLNet），则将停用截断/填充到最大长度。

• stride（int，可选，默认为 0） - 如果与max_length一起设置为一个数字，则当return_overflowing_tokens=True时返回的溢出标记将包含从截断序列末尾返回的一些标记，以提供截断和溢出序列之间的一些重叠。此参数的值定义了重叠标记的数量。

• is_split_into_words（bool，可选，默认为False） - 输入是否已经预分词（例如，已经分成单词）。如果设置为True，则分词器会假定输入已经分成单词（例如，通过在空格上分割），然后对其进行分词。这对于 NER 或标记分类很有用。

• pad_to_multiple_of（int，可选） — 如果设置，将序列填充到提供的值的倍数。需要激活padding。这对于在具有计算能力>= 7.5（Volta）的 NVIDIA 硬件上启用 Tensor Cores 特别有用。

• return_tensors（str或 TensorType，可选） — 如果设置，将返回张量而不是 Python 整数列表。可接受的值为：

  • 'tf'：返回 TensorFlow tf.constant对象。

  • 'pt'：返回 PyTorch torch.Tensor对象。

  • 'np'：返回 Numpy np.ndarray对象。

• return_token_type_ids（bool，可选） — 是否返回标记类型 ID。如果保持默认设置，将根据特定分词器的默认值返回标记类型 ID，由return_outputs属性定义。

  什么是 token type IDs？

• return_attention_mask（bool，可选） — 是否返回注意力掩码。如果保持默认设置，将根据特定分词器的默认值返回注意力掩码，由return_outputs属性定义。

  什么是 attention masks？

• return_overflowing_tokens（bool，可选，默认为False） — 是否返回溢出的标记序列。如果提供了一对输入 id 序列（或一批对）并且truncation_strategy = longest_first或True，则会引发错误，而不是返回溢出的标记。

• return_special_tokens_mask（bool，可选，默认为False） — 是否返回特殊标记掩码信息。

• return_offsets_mapping（bool，可选，默认为False） — 是否返回每个标记的(char_start, char_end)。

  仅适用于继承自 PreTrainedTokenizerFast 的快速分词器，如果使用 Python 的分词器，此方法将引发NotImplementedError。

• return_length（bool，可选，默认为False） — 是否返回编码输入的长度。

• verbose（bool，可选，默认为True） — 是否打印更多信息和警告。**kwargs — 传递给self.tokenize()方法

返回

BatchEncoding

具有以下字段的 BatchEncoding：

• input_ids — 要提供给模型的标记 id 列表。

  什么是输入 ID？

• token_type_ids — 要提供给模型的标记类型 id 列表（当return_token_type_ids=True或token_type_ids在self.model_input_names中时）。

  什么是 token type IDs？

• attention_mask — 指定哪些标记应该被模型关注的索引列表（当return_attention_mask=True或attention_mask在self.model_input_names中时）。

  什么是 attention masks？

• overflowing_tokens — 溢出标记序列的列表（当指定max_length和return_overflowing_tokens=True时）。

• num_truncated_tokens — 截断的标记数量（当指定max_length和return_overflowing_tokens=True时）。

• special_tokens_mask — 0 和 1 的列表，其中 1 指定添加的特殊标记，0 指定常规序列标记（当add_special_tokens=True和return_special_tokens_mask=True时）。

• length — 输入的长度（当return_length=True时）

对一组序列或一组序列对进行标记化和准备模型。

此方法已弃用，应改用__call__。

build_inputs_with_special_tokens

<来源>

( token_ids_0: List token_ids_1: Optional = None ) → export const metadata = 'undefined';List[int]

参数

• token_ids_0（List[int]） — 第一个标记化序列。

• token_ids_1（List[int]，可选）—第二个标记化序列。

返回

List[int]

带有特殊标记的模型输入。

通过连接和添加特殊标记，从序列或序列对构建用于序列分类任务的模型输入。

此实现不添加特殊标记，应该在子类中重写此方法。

clean_up_tokenization

<来源>

( out_string: str ) → export const metadata = 'undefined';str

参数

• out_string（str）—要清理的文本。

返回

str

清理后的字符串。

清理一系列简单的英语分词工件，如标点符号前的空格和缩写形式。

convert_tokens_to_string

<来源>

( tokens: List ) → export const metadata = 'undefined';str

参数

• tokens（List[str]）—要连接的标记。

返回

str

连接的标记。

将一系列标记转换为单个字符串。最简单的方法是" ".join(tokens)，但我们经常希望同时删除子词标记化工件。

create_token_type_ids_from_sequences

<来源>

( token_ids_0: List token_ids_1: Optional = None ) → export const metadata = 'undefined';List[int]

参数

• token_ids_0（List[int]）—第一个标记化序列。

• token_ids_1（List[int]，可选）—第二个标记化序列。

返回

List[int]

标记类型 ID。

创建与传递的序列相对应的标记类型 ID。什么是标记类型 ID？

如果模型有特殊的构建方式，则应在子类中重写。

decode

<来源>

( token_ids: Union skip_special_tokens: bool = False clean_up_tokenization_spaces: bool = None **kwargs ) → export const metadata = 'undefined';str

参数

• token_ids（Union[int]，List[int]，np.ndarray，torch.Tensor，tf.Tensor）—标记化输入 ID 的列表。可以使用__call__方法获得。

• skip_special_tokens（bool，可选，默认为False）—是否在解码中删除特殊标记。

• clean_up_tokenization_spaces（bool，可选）—是否清理分词空格。如果为None，将默认为self.clean_up_tokenization_spaces。

• kwargs（额外的关键字参数，可选）—将传递给底层模型特定的解码方法。

返回

str

解码后的句子。

将 ID 序列转换为字符串，使用分词器和词汇表，并提供选项以删除特殊标记和清理分词空格。

类似于执行self.convert_tokens_to_string(self.convert_ids_to_tokens(token_ids))。

encode

<来源>

( text: Union text_pair: Union = None add_special_tokens: bool = True padding: Union = False truncation: Union = None max_length: Optional = None stride: int = 0 return_tensors: Union = None **kwargs ) → export const metadata = 'undefined';List[int], torch.Tensor, tf.Tensor or np.ndarray

参数

• text（str，List[str]或List[int]）—要编码的第一个序列。这可以是一个字符串，一个字符串列表（使用tokenize方法标记化的字符串）或一个整数列表（使用convert_tokens_to_ids方法标记化的字符串 ID）。

• text_pair（str，List[str]或List[int]，可选）—要编码的可选第二序列。这可以是一个字符串，一个字符串列表（使用tokenize方法标记化的字符串）或一个整数列表（使用convert_tokens_to_ids方法标记化的字符串 ID）。

• add_special_tokens（bool，可选，默认为True）—在编码序列时是否添加特殊标记。这将使用底层的PretrainedTokenizerBase.build_inputs_with_special_tokens函数，该函数定义了哪些标记会自动添加到输入 ID 中。如果要自动添加bos或eos标记，则这很有用。

• padding（bool，str或 PaddingStrategy，可选，默认为False）—激活和控制填充。接受以下值：

  • True 或 'longest': 填充到批次中最长的序列（如果只提供了单个序列，则不填充）。

  • 'max_length': 填充到由参数 max_length 指定的最大长度，或者如果未提供该参数，则填充到模型可接受的最大输入长度。

  • False 或 'do_not_pad'（默认）：不填充（即可以输出具有不同长度的序列的批次）。

• truncation (bool, str 或 TruncationStrategy, optional, 默认为 False) — 激活和控制截断。接受以下值：

  • True 或 'longest_first': 截断到由参数 max_length 指定的最大长度，或者如果未提供该参数，则截断到模型可接受的最大输入长度。如果提供了一对序列（或一批序列对），则将逐标记截断，从序列对中最长的序列中删除一个标记。

  • 'only_first': 截断到由参数 max_length 指定的最大长度，或者如果未提供该参数，则截断到模型可接受的最大输入长度。如果提供了一对序列（或一批序列对），则只会截断第一个序列。

  • 'only_second': 截断到由参数 max_length 指定的最大长度，或者如果未提供该参数，则截断到模型可接受的最大输入长度。如果提供了一对序列（或一批序列对），则只会截断第二个序列。

  • False 或 'do_not_truncate'（默认）：不截断（即可以输出长度大于模型最大可接受输入大小的批次）。

• max_length (int, optional) — 控制截断/填充参数使用的最大长度。

  如果未设置或设置为 None，则将使用预定义的模型最大长度（如果截断/填充参数需要最大长度）。如果模型没有特定的最大输入长度（如 XLNet），则将禁用截断/填充到最大长度。

• stride (int, optional, defaults to 0) — 如果设置为一个数字，并且与 max_length 一起使用，当 return_overflowing_tokens=True 时返回的溢出标记将包含截断序列末尾的一些标记，以提供截断和溢出序列之间的一些重叠。该参数的值定义了重叠标记的数量。

• is_split_into_words (bool, optional, 默认为 False) — 输入是否已经预分词化（例如，已经分成单词）。如果设置为 True，则分词器假定输入已经分成单词（例如，通过在空格上分割），它将对其进行分词。这对于 NER 或标记分类很有用。

• pad_to_multiple_of (int, optional) — 如果设置，将序列填充到提供的值的倍数。需要激活 padding。这对于启用具有计算能力 >= 7.5（Volta）的 NVIDIA 硬件上的 Tensor Cores 特别有用。

• return_tensors (str 或 TensorType, optional) — 如果设置，将返回张量而不是 Python 整数列表。可接受的值为：

  • 'tf': 返回 TensorFlow tf.constant 对象。

  • 'pt': 返回 PyTorch torch.Tensor 对象。

  • 'np': 返回 Numpy np.ndarray 对象。

  **kwargs — 传递给 .tokenize() 方法。

返回

List[int], torch.Tensor, tf.Tensor 或 np.ndarray

文本的标记化 id。

将字符串转换为 id（整数）序列，使用分词器和词汇表。

与执行 self.convert_tokens_to_ids(self.tokenize(text)) 相同。

encode_plus

< source >

( text: Union text_pair: Union = None add_special_tokens: bool = True padding: Union = False truncation: Union = None max_length: Optional = None stride: int = 0 is_split_into_words: bool = False pad_to_multiple_of: Optional = None return_tensors: Union = None return_token_type_ids: Optional = None return_attention_mask: Optional = None return_overflowing_tokens: bool = False return_special_tokens_mask: bool = False return_offsets_mapping: bool = False return_length: bool = False verbose: bool = True **kwargs ) → export const metadata = 'undefined';BatchEncoding

参数

• text (str, List[str] 或 List[int]（仅用于非快速分词器）） — 要编码的第一个序列。可以是一个字符串，一个字符串列表（使用 tokenize 方法进行分词），或一个整数列表（使用 convert_tokens_to_ids 方法进行分词）。

• text_pair (str, List[str] 或 List[int], 可选) — 要编码的可选第二个序列。可以是一个字符串，一个字符串列表（使用 tokenize 方法进行分词），或一个整数列表（使用 convert_tokens_to_ids 方法进行分词）。

• add_special_tokens (bool, 可选, 默认为 True) — 在编码序列时是否添加特殊标记。这将使用底层的 PretrainedTokenizerBase.build_inputs_with_special_tokens 函数，该函数定义了自动添加到输入标识的标记。如果要自动添加 bos 或 eos 标记，则这很有用。

• padding (bool, str 或 PaddingStrategy, 可选, 默认为 False) — 激活和控制填充。接受以下值：

  • True 或 'longest'：填充到批次中最长的序列（如果只提供了单个序列，则不进行填充）。

  • 'max_length'：填充到指定的最大长度（使用参数 max_length）或模型可接受的最大输入长度（如果未提供该参数）。

  • False 或 'do_not_pad'（默认）：不进行填充（即，可以输出长度不同的序列批次）。

• truncation (bool, str 或 TruncationStrategy, 可选, 默认为 False) — 激活和控制截断。接受以下值：

  • True 或 'longest_first'：截断到指定的最大长度（使用参数 max_length）或模型可接受的最大输入长度（如果未提供该参数）。这将逐个标记进行截断，如果提供了一对序列（或一批对序列），则从最长序列中删除一个标记。

  • 'only_first'：截断到指定的最大长度（使用参数 max_length）或模型可接受的最大输入长度（如果未提供该参数）。如果提供了一对序列（或一批对序列），则仅截断第一个序列。

  • 'only_second'：截断到指定的最大长度（使用参数 max_length）或模型可接受的最大输入长度（如果未提供该参数）。如果提供了一对序列（或一批对序列），则仅截断第二个序列。

  • False 或 'do_not_truncate'（默认）：不进行截断（即，可以输出长度大于模型最大可接受输入大小的序列批次）。

• max_length (int, 可选) — 由截断/填充参数之一使用的最大长度。

  如果未设置或设置为 None，则将使用预定义的模型最大长度（如果截断/填充参数需要最大长度）。如果模型没有特定的最大输入长度（如 XLNet），则将禁用截断/填充到最大长度。

• stride (int, 可选, 默认为 0) — 如果与 max_length 一起设置为一个数字，则当 return_overflowing_tokens=True 时返回的溢出标记将包含截断序列末尾的一些标记，以提供截断和溢出序列之间的一些重叠。该参数的值定义了重叠标记的数量。

• is_split_into_words (bool, optional, 默认为False) — 输入是否已经预分词化（例如，已分割为单词）。如果设置为True，分词器会假定输入已经分割为单词（例如，通过在空格上分割），然后对其进行分词。这对于 NER 或标记分类很有用。

• pad_to_multiple_of (int, optional) — 如果设置，将序列填充到提供的值的倍数。需要激活padding。这对于启用具有计算能力>= 7.5（Volta）的 NVIDIA 硬件上的 Tensor Cores 特别有用。

• return_tensors (str或 TensorType, optional) — 如果设置，将返回张量而不是 Python 整数列表。可接受的值为：

  • 'tf': 返回 TensorFlow tf.constant对象。

  • 'pt': 返回 PyTorch torch.Tensor对象。

  • 'np': 返回 Numpy np.ndarray对象。

• return_token_type_ids (bool, optional) — 是否返回标记类型 ID。如果保持默认设置，将根据特定分词器的默认值返回标记类型 ID，由return_outputs属性定义。

  什么是标记类型 ID？

• return_attention_mask (bool, optional) — 是否返回注意力掩码。如果保持默认设置，将根据特定分词器的默认值返回注意力掩码，由return_outputs属性定义。

  什么是注意力掩码？

• return_overflowing_tokens (bool, optional, defaults to False) — 是否返回溢出的标记序列。如果提供一对输入 id 序列（或一批对）并且truncation_strategy = longest_first或True，则会引发错误而不是返回溢出的标记。

• return_special_tokens_mask (bool, optional, 默认为False) — 是否返回特殊标记掩码信息。

• return_offsets_mapping (bool, optional, 默认为False) — 是否返回每个标记的(char_start, char_end)。

  这仅适用于继承自 PreTrainedTokenizerFast 的快速分词器，如果使用 Python 的分词器，此方法将引发NotImplementedError。

• return_length (bool, optional, 默认为False) — 是否返回编码输入的长度。

• verbose (bool, optional, 默认为True) — 是否打印更多信息和警告。**kwargs — 传递给self.tokenize()方法

返回

BatchEncoding

具有以下字段的 BatchEncoding：

• input_ids — 要提供给模型的标记 id 列表。

  什么是输入 ID？

• token_type_ids — 要提供给模型的标记类型 id 列表（当return_token_type_ids=True或token_type_ids在self.model_input_names中时）。

  什么是标记类型 ID？

• attention_mask — 指定哪些标记应该被模型关注的索引列表（当return_attention_mask=True或attention_mask在self.model_input_names中时）。

  什么是注意力掩码？

• overflowing_tokens — 溢出标记序列的列表（当指定max_length并且return_overflowing_tokens=True时）。

• num_truncated_tokens — 截断的标记数（当指定max_length并且return_overflowing_tokens=True时）。

• special_tokens_mask — 由 0 和 1 组成的列表，其中 1 指定添加的特殊标记，0 指定常规序列标记（当add_special_tokens=True和return_special_tokens_mask=True时）。

• length — 输入的长度（当return_length=True时）

对一个序列或一对序列进行标记化和准备模型。

此方法已弃用，应改用 __call__。

from_pretrained

<来源>

( pretrained_model_name_or_path: Union *init_inputs cache_dir: Union = None force_download: bool = False local_files_only: bool = False token: Union = None revision: str = 'main' **kwargs )

参数

• pretrained_model_name_or_path (str 或 os.PathLike) — 可以是以下之一：

  • 一个字符串，预定义 tokenizer 的模型 id，托管在 huggingface.co 模型仓库中。有效的模型 id 可以位于根级别，如 bert-base-uncased，也可以位于用户或组织名称下，如 dbmdz/bert-base-german-cased。

  • 一个目录的路径，其中包含了 tokenizer 所需的词汇文件，例如使用 save_pretrained()方法保存的文件，例如 ./my_model_directory/。

  • （已弃用，不适用于所有派生类）一个单个保存的词汇文件的路径或 url（仅当 tokenizer 只需要一个词汇文件时，如 Bert 或 XLNet），例如 ./my_model_directory/vocab.txt。

• cache_dir (str 或 os.PathLike, optional) — 下载的预定义 tokenizer 词汇文件应该缓存在其中的目录路径，如果不应使用标准缓存。

• force_download (bool, optional, 默认为 False) — 是否强制（重新）下载词汇文件并覆盖缓存版本（如果存在）。

• resume_download (bool, optional, 默认为 False) — 是否删除接收不完整的文件。如果存在这样的文件，则尝试恢复下载。

• proxies (Dict[str, str], optional) — 一个按协议或端点使用的代理服务器字典，例如 {'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}。这些代理将在每个请求中使用。

• token (str 或 bool, optional) — 用作远程文件 HTTP bearer 授权的 token。如果为 True，将使用运行 huggingface-cli login 时生成的 token（存储在 ~/.huggingface 中）。

• local_files_only (bool, optional, 默认为 False) — 是否仅依赖本地文件，不尝试下载任何文件。

• revision (str, optional, 默认为 "main") — 要使用的特定模型版本。它可以是分支名称、标签名称或提交 ID，因为我们在 huggingface.co 上使用基于 git 的系统来存储模型和其他工件，所以 revision 可以是 git 允许的任何标识符。

• subfolder (str, optional) — 如果相关文件位于 huggingface.co 模型仓库的子文件夹中（例如 facebook/rag-token-base），请在此处指定。

• inputs（额外的位置参数，optional） — 将传递给 Tokenizer __init__方法。

• kwargs（额外的关键字参数，optional） — 将传递给 Tokenizer __init__方法。可以用于设置特殊 token，如 bos_token、eos_token、unk_token、sep_token、pad_token、cls_token、mask_token、additional_special_tokens。有关更多详细信息，请参阅__init__中的参数。

从预定义 tokenizer 实例化一个 PreTrainedTokenizerBase（或派生类）。

当您想使用私有模型时，需要传递 token=True。

示例：

# We can't instantiate directly the base class *PreTrainedTokenizerBase* so let's show our examples on a derived class: BertTokenizer
# Download vocabulary from huggingface.co and cache.
tokenizer = BertTokenizer.from_pretrained("bert-base-uncased")

# Download vocabulary from huggingface.co (user-uploaded) and cache.
tokenizer = BertTokenizer.from_pretrained("dbmdz/bert-base-german-cased")

# If vocabulary files are in a directory (e.g. tokenizer was saved using *save_pretrained('./test/saved_model/')*)
tokenizer = BertTokenizer.from_pretrained("./test/saved_model/")

# If the tokenizer uses a single vocabulary file, you can point directly to this file
tokenizer = BertTokenizer.from_pretrained("./test/saved_model/my_vocab.txt")

# You can link tokens to special vocabulary when instantiating
tokenizer = BertTokenizer.from_pretrained("bert-base-uncased", unk_token="<unk>")
# You should be sure '<unk>' is in the vocabulary when doing that.
# Otherwise use tokenizer.add_special_tokens({'unk_token': '<unk>'}) instead)
assert tokenizer.unk_token == "<unk>"

get_special_tokens_mask

<来源>

( token_ids_0: List token_ids_1: Optional = None already_has_special_tokens: bool = False ) → export const metadata = 'undefined';A list of integers in the range [0, 1]

参数

• token_ids_0 (List[int]) — 第一个序列的 id 列表。

• token_ids_1 (List[int], optional) — 第二个序列的 id 列表。

• already_has_special_tokens (bool, optional, 默认为 False) — token 列表是否已经包含了模型所需的特殊 token。

返回值

一个整数列表，范围为 [0, 1]

1 代表特殊 token，0 代表序列 token。

从没有添加特殊标记的标记列表中检索序列 id。当使用 tokenizer 的prepare_for_model或encode_plus方法添加特殊标记时，会调用此方法。

get_vocab

<来源>

( ) → export const metadata = 'undefined';Dict[str, int]

返回

Dict[str, int]

词汇表。

将词汇表作为标记到索引的字典返回。

当token在词汇表中时，tokenizer.get_vocab()[token]等同于tokenizer.convert_tokens_to_ids(token)。

pad

<来源>

( encoded_inputs: Union padding: Union = True max_length: Optional = None pad_to_multiple_of: Optional = None return_attention_mask: Optional = None return_tensors: Union = None verbose: bool = True )

参数

• encoded_inputs（BatchEncoding，BatchEncoding 列表，Dict[str, List[int]]，Dict[str, List[List[int]]或List[Dict[str, List[int]]]） — 标记化输入。可以表示一个输入（BatchEncoding 或Dict[str, List[int]]）或一批标记化输入（BatchEncoding 列表，Dict[str, List[List[int]]]或List[Dict[str, List[int]]])，因此您可以在预处理期间以及在 PyTorch Dataloader 收集函数中使用此方法。

  你可以使用张量（numpy 数组，PyTorch 张量或 TensorFlow 张量）代替List[int]，请参考上面的返回类型说明。

• padding（bool，str或 PaddingStrategy，可选，默认为True） — 选择一种策略来填充返回的序列（根据模型的填充方向和填充索引），包括：

  • True或'longest'：填充到批量中最长的序列（如果只提供单个序列，则不填充）。

  • 'max_length': 填充到指定的最大长度，使用参数max_length或者如果未提供该参数，则填充到模型的最大可接受输入长度。

  • False或'do_not_pad'（默认）：无填充（即可以输出具有不同长度序列的批次）。

• max_length（int，可选） — 返回列表的最大长度和可选的填充长度（参见上文）。

• pad_to_multiple_of（int，可选） — 如果设置，将填充序列到提供的值的倍数。

  这对于启用具有计算能力>= 7.5（Volta）的 NVIDIA 硬件上的 Tensor Cores 特别有用。

• return_attention_mask（bool，可选） — 是否返回注意力蒙版。如果保持默认值，将根据特定 tokenizer 的默认值返回注意力蒙版，由return_outputs属性定义。

  注意力蒙版是什么？

• return_tensors（str或 TensorType，可选） — 如果设置，将返回张量而不是 Python 整数列表。可接受的值包括：

  • 'tf'：返回 TensorFlow tf.constant对象。

  • 'pt'：返回 PyTorch torch.Tensor对象。

  • 'np'：返回 Numpy np.ndarray对象。

• verbose（bool，可选，默认为True） — 是否打印更多信息和警告。

将单个编码输入或批量编码输入填充到预定义长度或批量中的最大序列长度。

填充方向（左/右）填充标记 id 在 tokenizer 级别定义（使用self.padding_side，self.pad_token_id和self.pad_token_type_id）。

请注意，使用快速 tokenizer 时，使用__call__方法比使用编码文本的方法再调用pad方法更快。

如果传递的 encoded_inputs 是 numpy 数组、PyTorch 张量或 TensorFlow 张量的字典，则结果将使用相同的类型，除非您使用 return_tensors 提供不同的张量类型。对于 PyTorch 张量，您将丢失张量的特定设备。

prepare_for_model

<来源>

( ids: List pair_ids: Optional = None add_special_tokens: bool = True padding: Union = False truncation: Union = None max_length: Optional = None stride: int = 0 pad_to_multiple_of: Optional = None return_tensors: Union = None return_token_type_ids: Optional = None return_attention_mask: Optional = None return_overflowing_tokens: bool = False return_special_tokens_mask: bool = False return_offsets_mapping: bool = False return_length: bool = False verbose: bool = True prepend_batch_axis: bool = False **kwargs ) → export const metadata = 'undefined';BatchEncoding

参数

• ids（List[int]） — 第一个序列的标记化输入 id。可以通过链接 tokenize 和 convert_tokens_to_ids 方法从字符串中获取。

• pair_ids（List[int]，可选） — 第二个序列的标记化输入 id。可以通过链接 tokenize 和 convert_tokens_to_ids 方法从字符串中获取。

• add_special_tokens（bool，可选，默认为 True） — 在编码序列时是否添加特殊标记。这将使用底层的 PretrainedTokenizerBase.build_inputs_with_special_tokens 函数，该函数定义了自动添加到输入 id 的标记。如果要自动添加 bos 或 eos 标记，这很有用。

• padding（bool、str 或 PaddingStrategy，可选，默认为 False） — 激活和控制填充。接受以下值：

  • True 或 'longest'：填充到批次中最长的序列（如果只提供单个序列，则不填充）。

  • 'max_length'：填充到指定的最大长度，该长度由参数 max_length 指定，或者填充到模型可接受的最大输入长度（如果未提供该参数）。

  • False 或 'do_not_pad'（默认）：不填充（即，可以输出具有不同长度的序列批次）。

• truncation（bool、str 或 TruncationStrategy，可选，默认为 False） — 激活和控制截断。接受以下值：

  • True 或 'longest_first'：截断到指定的最大长度，该长度由参数 max_length 指定，或者截断到模型可接受的最大输入长度（如果未提供该参数）。如果提供了一对序列（或一批对序列），则将逐标记截断，从一对序列中最长的序列中删除一个标记。

  • 'only_first'：截断到指定的最大长度，该长度由参数 max_length 指定，或者截断到模型可接受的最大输入长度（如果未提供该参数）。如果提供了一对序列（或一批对序列），则只会截断第一个序列。

  • 'only_second'：截断到指定的最大长度，该长度由参数 max_length 指定，或者截断到模型可接受的最大输入长度（如果未提供该参数）。如果提供了一对序列（或一批对序列），则只会截断第二个序列。

  • False 或 'do_not_truncate'（默认）：不截断（即，可以输出长度大于模型最大可接受输入大小的批次）。

• max_length（int，可选） — 由截断/填充参数之一使用的最大长度。

  如果未设置或设置为 None，则将使用预定义的模型最大长度，如果截断/填充参数中需要最大长度。如果模型没有特定的最大输入长度（如 XLNet），则将禁用截断/填充到最大长度。

• stride（int，可选，默认为 0） — 如果与 max_length 一起设置为一个数字，则当 return_overflowing_tokens=True 时返回的溢出标记将包含截断序列末尾的一些标记，以提供截断和溢出序列之间的一些重叠。该参数的值定义了重叠标记的数量。

• is_split_into_words (bool, 可选, 默认为 False) — 输入是否已经预分词（例如，已经分成单词）。如果设置为True，分词器会假定输入已经分成单词（例如，通过在空格上分割），然后对其进行分词。这对于 NER 或标记分类很有用。

• pad_to_multiple_of (int, 可选) — 如果设置，将序列填充到提供的值的倍数。需要激活padding。这对于在具有计算能力>= 7.5（Volta）的 NVIDIA 硬件上启用 Tensor Cores 特别有用。

• return_tensors (str 或 TensorType, 可选) — 如果设置，将返回张量而不是 Python 整数列表。可接受的值为：

  • 'tf': 返回 TensorFlow tf.constant对象。

  • 'pt': 返回 PyTorch torch.Tensor对象。

  • 'np': 返回 Numpy np.ndarray对象。

• return_token_type_ids (bool, 可选) — 是否返回 token type IDs。如果保持默认设置，将根据特定分词器的默认设置返回 token type IDs，由return_outputs属性定义。

  什么是 token type IDs？

• return_attention_mask (bool, 可选) — 是否返回 attention mask。如果保持默认设置，将根据特定分词器的默认设置返回 attention mask，由return_outputs属性定义。

  什么是 attention masks？

• return_overflowing_tokens (bool, 可选, 默认为 False) — 是否返回溢出的 token 序列。如果提供一对输入 IDs 序列（或一批对）并且truncation_strategy = longest_first或True，则会引发错误而不是返回溢出的 tokens。

• return_special_tokens_mask (bool, 可选, 默认为 False) — 是否返回特殊 token 的 mask 信息。

• return_offsets_mapping (bool, 可选, 默认为 False) — 是否返回每个 token 的(char_start, char_end)。

  这仅适用于继承自 PreTrainedTokenizerFast 的快速分词器，如果使用 Python 的分词器，此方法将引发NotImplementedError。

• return_length (bool, 可选, 默认为 False) — 是否返回编码输入的长度。

• verbose (bool, 可选, 默认为 True) — 是否打印更多信息和警告。**kwargs — 传递给self.tokenize()方法

返回

BatchEncoding

一个带有以下字段的 BatchEncoding：

• input_ids — 要提供给模型的 token ids 列表。

  什么是输入 IDs？

• token_type_ids — 要提供给模型的 token type ids 列表（当return_token_type_ids=True或token_type_ids在self.model_input_names中）。

  什么是 token type IDs？

• attention_mask — 指定哪些 token 应该被模型关注的索引列表（当return_attention_mask=True或attention_mask在self.model_input_names中）。

  什么是 attention masks？

• overflowing_tokens — 溢出 token 序列的列表（当指定max_length并且return_overflowing_tokens=True时）。

• num_truncated_tokens — 被截断的 token 数量（当指定max_length并且return_overflowing_tokens=True时）。

• special_tokens_mask — 由 0 和 1 组成的列表，其中 1 指定添加的特殊 token，0 指定常规序列 token（当add_special_tokens=True并且return_special_tokens_mask=True时）。

• length — 输入的长度（当return_length=True时）

准备输入 id 的序列，或一对输入 id 的序列，以便模型使用。它添加特殊标记，如果溢出则截断序列，同时考虑特殊标记，并管理一个移动窗口（带有用户定义的步幅）以处理溢出的标记。请注意，对于 pair_ids 不等于 None 且 truncation_strategy = longest_first 或 True，不可能返回溢出的标记。这样的参数组合将引发错误。

prepare_seq2seq_batch

< source >

( src_texts: List tgt_texts: Optional = None max_length: Optional = None max_target_length: Optional = None padding: str = 'longest' return_tensors: str = None truncation: bool = True **kwargs ) → export const metadata = 'undefined';BatchEncoding

参数

• src_texts (List[str]) — 要总结的文档或源语言文本的列表。

• tgt_texts (list, 可选) — 摘要或目标语言文本的列表。

• max_length (int, 可选) — 控制编码器输入（要总结的文档或源语言文本）的最大长度。如果未设置或设置为 None，并且截断/填充参数中需要最大长度，则将使用预定义的模型最大长度。如果模型没有特定的最大输入长度（如 XLNet），则将禁用截断/填充到最大长度。

• max_target_length (int, 可选) — 控制解码器输入（目标语言文本或摘要）的最大长度。如果未设置或设置为 None，将使用 max_length 值。

• padding (bool, str 或 PaddingStrategy, 可选, 默认为 False) — 激活和控制填充。接受以下值：

  • True 或 'longest': 填充到批次中最长的序列（如果只提供了单个序列，则不填充）。

  • 'max_length': 填充到由参数 max_length 指定的最大长度，或者如果未提供该参数，则填充到模型可接受的最大输入长度。

  • False 或 'do_not_pad' (默认): 不填充（即，可以输出长度不同的序列批次）。

• return_tensors (str 或 TensorType, 可选) — 如果设置，将返回张量而不是 Python 整数列表。可接受的值为：

  • 'tf': 返回 TensorFlow tf.constant 对象。

  • 'pt': 返回 PyTorch torch.Tensor 对象。

  • 'np': 返回 Numpy np.ndarray 对象。

• truncation (bool, str 或 TruncationStrategy, 可选, 默认为 True) — 激活和控制截断。接受以下值：

  • True 或 'longest_first': 截断到由参数 max_length 指定的最大长度，或者如果未提供该参数，则截断到模型可接受的最大输入长度。如果提供了一对序列（或一批对），则将逐标记截断，从一对序列中最长的序列中删除一个标记。

  • 'only_first': 截断到由参数 max_length 指定的最大长度，或者如果未提供该参数，则截断到模型可接受的最大输入长度。如果提供了一对序列（或一批对），则仅截断第一个序列。

  • 'only_second': 截断到由参数 max_length 指定的最大长度，或者如果未提供该参数，则截断到模型可接受的最大输入长度。如果提供了一对序列（或一批对），则仅截断第二个序列。

  • False 或 'do_not_truncate' (默认): 不截断（即，可以输出长度大于模型最大可接受输入大小的序列）。**kwargs — 传递给 self.__call__ 的额外关键字参数。

返回

BatchEncoding

具有以下字段的 BatchEncoding：

• input_ids — 要馈送给编码器的标记 id 列表。

• attention_mask — 指定模型应关注的哪些标记的索引列表。

• labels — tgt_texts 的标记 id 列表。

仅当传递了 tgt_texts 时，将返回完整的键集[input_ids, attention_mask, labels]。否则，input_ids，attention_mask将是唯一的键。

为翻译准备模型输入。为了获得最佳性能，请一次翻译一句话。

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 tokenizer"。

• private（bool，可选）— 创建的存储库是否应为私有。

• token（bool或str，可选）— 用作远程文件 HTTP 令牌的令牌。如果为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 的标签列表。

将分词器文件上传到🤗模型 Hub。

示例：

from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("bert-base-cased")

# Push the tokenizer to your namespace with the name "my-finetuned-bert".
tokenizer.push_to_hub("my-finetuned-bert")

# Push the tokenizer to an organization with the name "my-finetuned-bert".
tokenizer.push_to_hub("huggingface/my-finetuned-bert")

register_for_auto_class

<来源>

( auto_class = 'AutoTokenizer' )

参数

• auto_class（str或type，可选，默认为"AutoTokenizer"）— 要将此新分词器注册到的自动类。

使用给定的自动类注册此类。这应仅用于自定义分词器，因为库中的分词器已经与AutoTokenizer映射。

此 API 是实验性的，可能在下一个版本中有一些轻微的破坏性更改。

save_pretrained

<来源>

( save_directory: Union legacy_format: Optional = None filename_prefix: Optional = None push_to_hub: bool = False **kwargs ) → export const metadata = 'undefined';A tuple of str

参数

• save_directory（str或os.PathLike）— 分词器将被保存的目录路径。

• legacy_format（bool，可选）— 仅适用于快速分词器。如果未设置（默认），将以统一的 JSON 格式保存分词器，以及以传统格式保存（如果存在），即具有特定于分词器的词汇表和单独的 added_tokens 文件。

  如果为False，则只会以统一的 JSON 格式保存分词器。该格式与“慢速”分词器（不由tokenizers库提供支持）不兼容，因此无法在相应的“慢速”分词器中加载分词器。

  如果为True，将以传统格式保存分词器。如果“slow”分词器不存在，则会引发值错误。

• filename_prefix (str, 可选) — 要添加到分词器保存的文件名称前缀。

• push_to_hub (bool, 可选, 默认为False) — 保存后是否将模型推送到 Hugging Face 模型中心。您可以使用repo_id指定要推送到的存储库（将默认为您的命名空间中的save_directory名称）。

• kwargs (Dict[str, Any], 可选) — 传递给 push_to_hub()方法的额外关键字参数。

返回

一个str元组

保存的文件。

保存完整的分词器状态。

此方法确保完整的分词器可以使用~tokenization_utils_base.PreTrainedTokenizer.from_pretrained类方法重新加载。

警告，无。这不会保存您在实例化后对分词器应用的修改（例如，在创建后修改tokenizer.do_lower_case）。

save_vocabulary

<来源>

( save_directory: str filename_prefix: Optional = None ) → export const metadata = 'undefined';Tuple(str)

参数

• save_directory (str) — 保存词汇表的目录。

• filename_prefix (str, 可选) — 要添加到保存文件名称的可选前缀。

返回

Tuple(str)

保存的文件路径。

仅保存分词器的词汇表（词汇表+添加的标记）。

此方法不会保存分词器的配置和特殊标记映射。使用_save_pretrained()保存分词器的整个状态。

tokenize

<来源>

( text: str pair: Optional = None add_special_tokens: bool = False **kwargs ) → export const metadata = 'undefined';List[str]

参数

• text (str) — 要编码的序列。

• pair (str, 可选) — 要与第一个序列一起编码的第二个序列。

• add_special_tokens (bool, 可选, 默认为False) — 是否添加与相应模型相关的特殊标记。

• kwargs（额外关键字参数，可选） — 将传递给底层模型特定的编码方法。详细信息请参见call()

返回

List[str]

标记列表。

将字符串转换为标记序列，用unk_token替换未知标记。

truncate_sequences

<来源>

( ids: List pair_ids: Optional = None num_tokens_to_remove: int = 0 truncation_strategy: Union = 'longest_first' stride: int = 0 ) → export const metadata = 'undefined';Tuple[List[int], List[int], List[int]]

参数

• ids (List[int]) — 第一个序列的标记化输入 id。可以通过链接tokenize和convert_tokens_to_ids方法从字符串中获取。

• pair_ids (List[int], 可选) — 第二个序列的标记化输入 id。可以通过链接tokenize和convert_tokens_to_ids方法从字符串中获取。

• num_tokens_to_remove (int, 可选, 默认为 0) — 使用截断策略要移除的标记数。

• truncation_strategy (str或 TruncationStrategy, 可选, 默认为False) — 截断的策略。可以是：

  • 'longest_first': 截断到指定的最大长度（使用参数max_length）或模型的最大可接受输入长度（如果未提供该参数）。这将逐个标记截断，如果提供了一对序列（或一批序列），则从一对序列中最长的序列中删除一个标记。

  • 'only_first': 截断到指定的最大长度（使用参数max_length）或模型的最大可接受输入长度（如果未提供该参数）。如果提供了一对序列（或一批序列），则仅截断第一个序列。

  • 'only_second'：根据参数max_length指定的最大长度截断，或者根据模型的最大可接受输入长度截断。如果未提供该参数，则仅截断一对序列中的第二个序列（或一批序列对）。

  • 'do_not_truncate'（默认）：不截断（即，可以输出长度大于模型最大可接受输入大小的批次）。

• stride（int，可选，默认为 0）— 如果设置为正数，返回的溢出标记将包含来自返回的主序列的一些标记。该参数的值定义了额外标记的数量。

返回

Tuple[List[int], List[int], List[int]]

被截断的ids，被截断的pair_ids和溢出标记的列表。注意：如果提供了一对序列（或一批序列对），则longest_first策略返回空的溢出标记列表。

根据策略就地截断一个序列对。

SpecialTokensMixin

class transformers.SpecialTokensMixin

<来源>

( verbose = False **kwargs )

参数

• bos_token（str或tokenizers.AddedToken，可选）— 代表句子开头的特殊标记。

• eos_token（str或tokenizers.AddedToken，可选）— 代表句子结尾的特殊标记。

• unk_token（str或tokenizers.AddedToken，可选）— 代表一个未知词的特殊标记。

• sep_token（str或tokenizers.AddedToken，可选）— 代表同一输入中两个不同句子之间的特殊标记（例如 BERT 使用）。

• pad_token（str或tokenizers.AddedToken，可选）— 用于使标记数组大小相同以进行批处理的特殊标记。然后将被注意机制或损失计算忽略。

• cls_token（str或tokenizers.AddedToken，可选）— 代表输入类别的特殊标记（例如 BERT 使用）。

• mask_token（str或tokenizers.AddedToken，可选）— 代表被屏蔽的标记的特殊标记（例如 BERT 使用）。

• additional_special_tokens（元组或str或tokenizers.AddedToken的列表，可选）— 一组额外的标记，将被标记为special，这意味着如果skip_special_tokens设置为True，在解码时将被跳过。

由 PreTrainedTokenizer 和 PreTrainedTokenizerFast 派生的 mixin，用于处理与特殊标记相关的特定行为。特别是，这个类保存了可以用于以与模型无关的方式直接访问这些特殊标记的属性，并允许设置和更新特殊标记。

add_special_tokens

<来源>

( special_tokens_dict: Dict replace_additional_special_tokens = True ) → export const metadata = 'undefined';int

参数

• special_tokens_dict（字典str到str或tokenizers.AddedToken）— 键应该在预定义特殊属性列表中：[bos_token、eos_token、unk_token、sep_token、pad_token、cls_token、mask_token、additional_special_tokens]。

  仅当它们不在词汇表中时才会添加标记（通过检查分词器是否将unk_token的索引分配给它们进行测试）。

• replace_additional_special_tokens（bool，可选，默认为True） - 如果为True，则现有的额外特殊标记列表将被special_tokens_dict中提供的列表替换。否则，self._additional_special_tokens只是被扩展。在前一种情况下，这些标记不会从标记器的完整词汇表中删除 - 它们只被标记为非特殊标记。请记住，这只影响解码时跳过哪些标记，而不影响added_tokens_encoder和added_tokens_decoder。这意味着以前的additional_special_tokens仍然是添加的标记，并且不会被模型分割。

返回

int

将特殊标记添加到词汇表中的数量。

将特殊标记的字典（eos、pad、cls 等）添加到编码器中，并将它们链接到类属性。如果特殊标记不在词汇表中，则将它们添加到词汇表中（从当前词汇表的最后索引开始索引）。

在向词汇表中添加新标记时，您应确保还调整模型的标记嵌入矩阵，以使其嵌入矩阵与标记器匹配。

为了实现这一点，请使用 resize_token_embeddings()方法。

使用add_special_tokens将确保您的特殊标记可以以多种方式使用：

• 在解码时可以跳过特殊标记，使用skip_special_tokens = True。

• 特殊标记由标记器仔细处理（它们永远不会被分割），类似于AddedTokens。

• 您可以使用标记器类属性轻松引用特殊标记，如tokenizer.cls_token。这使得开发与模型无关的训练和微调脚本变得容易。

在可能的情况下，为提供的预训练模型已经注册了特殊标记（例如 BertTokenizer cls_token已经注册为：obj’[CLS]’，XLM 的一个也已经注册为'</s>'）。

示例：

# Let's see how to add a new classification token to GPT-2
tokenizer = GPT2Tokenizer.from_pretrained("gpt2")
model = GPT2Model.from_pretrained("gpt2")

special_tokens_dict = {"cls_token": "<CLS>"}

num_added_toks = tokenizer.add_special_tokens(special_tokens_dict)
print("We have added", num_added_toks, "tokens")
# Notice: resize_token_embeddings expect to receive the full size of the new vocabulary, i.e., the length of the tokenizer.
model.resize_token_embeddings(len(tokenizer))

assert tokenizer.cls_token == "<CLS>"

add_tokens

<来源>

( new_tokens: Union special_tokens: bool = False ) → export const metadata = 'undefined';int

参数

• new_tokens（str，tokenizers.AddedToken或str或tokenizers.AddedToken的列表） - 仅当这些标记尚未在词汇表中时才会添加。tokenizers.AddedToken包装了一个字符串标记，让您可以个性化其行为：这个标记是否只匹配一个单词，这个标记是否应该去除左侧的所有潜在空格，这个标记是否应该去除右侧的所有潜在空格等。

• special_tokens（bool，可选，默认为False） - 可用于指定标记是否为特殊标记。这主要会改变标准化行为（例如，特殊标记如 CLS 或[MASK]通常不会被小写）。

  请参阅 HuggingFace tokenizers 库中的tokenizers.AddedToken的详细信息。

返回

int

将特殊标记添加到词汇表中的数量。

向标记器类添加一组新标记。如果新标记不在词汇表中，则将它们添加到词汇表中，索引从当前词汇表的长度开始，并且在应用标记化算法之前将被隔离。因此，标记化算法的添加标记和词汇表中的标记不会以相同的方式处理。

注意，向词汇表中添加新标记时，您应确保还调整模型的标记嵌入矩阵，以使其嵌入矩阵与标记器匹配。

为了实现这一点，请使用 resize_token_embeddings()方法。

示例：

# Let's see how to increase the vocabulary of Bert model and tokenizer
tokenizer = BertTokenizerFast.from_pretrained("bert-base-uncased")
model = BertModel.from_pretrained("bert-base-uncased")

num_added_toks = tokenizer.add_tokens(["new_tok1", "my_new-tok2"])
print("We have added", num_added_toks, "tokens")
# Notice: resize_token_embeddings expect to receive the full size of the new vocabulary, i.e., the length of the tokenizer.
model.resize_token_embeddings(len(tokenizer))

sanitize_special_tokens

<来源>

( )

sanitize_special_tokens 现在已弃用，仅用于向后兼容，并将在 transformers v5 中移除。

枚举和命名元组

class transformers.tokenization_utils_base.TruncationStrategy

< source >

( value names = None module = None qualname = None type = None start = 1 )

在 PreTrainedTokenizerBase.call() 中 truncation 参数的可能取值。在 IDE 中用于制表完成。

class transformers.CharSpan

< source >

( start: int end: int )

参数

• start (int) — 原始字符串中第一个字符的索引。

• end (int) — 原始字符串中最后一个字符后面的字符的索引。

原始字符串中的字符范围。

class transformers.TokenSpan

< source >

( start: int end: int )

参数

• start (int) — span 中第一个标记的索引。

• end (int) — span 中最后一个标记后面的标记的索引。

编码字符串中的标记范围（标记列表）。

Trainer 的实用程序

原始文本：huggingface.co/docs/transformers/v4.37.2/en/internal/trainer_utils

此页面列出了由 Trainer 使用的所有实用函数。

这些大多数只有在研究库中 Trainer 的代码时才有用。

实用程序

class transformers.EvalPrediction

<来源>

( predictions: Union label_ids: Union inputs: Union = None )

参数

• predictions (np.ndarray) — 模型的预测。

• label_ids (np.ndarray) — 要匹配的目标。

• inputs (np.ndarray, 可选) —

评估输出（始终包含标签），用于计算指标。

class transformers.IntervalStrategy

<来源>

( value names = None module = None qualname = None type = None start = 1 )

一个枚举。

transformers.enable_full_determinism

<来源>

( seed: int warn_only: bool = False )

用于在分布式训练期间获得可重复行为的辅助函数。参见

• pytorch.org/docs/stable/notes/randomness.html 适用于 pytorch

• www.tensorflow.org/api_docs/python/tf/config/experimental/enable_op_determinism 适用于 tensorflow

transformers.set_seed

<来源>

( seed: int )

参数

• seed (int) — 要设置的种子。

用于在random、numpy、torch和/或tf（如果已安装）中设置种子以获得可重复的行为的辅助函数。

transformers.torch_distributed_zero_first

<来源>

( local_rank: int )

参数

• local_rank (int) — 本地进程的等级。

装饰器，使分布式训练中的所有进程等待每个本地主机执行某些操作。

回调内部

class transformers.trainer_callback.CallbackHandler

<来源>

( callbacks model tokenizer optimizer lr_scheduler )

内部类，按顺序调用回调列表。

分布式评估

class transformers.trainer_pt_utils.DistributedTensorGatherer

<来源>

( world_size num_samples make_multiple_of = None padding_index = -100 )

参数

• world_size (int) — 分布式训练中使用的进程数。

• num_samples (int) — 数据集中的样本数量。

• make_multiple_of (int, 可选) — 如果传递，类会假定传递给每个进程的数据集是该参数的倍数（通过添加样本）。

• padding_index (int, 可选, 默认为-100) — 如果数组的序列长度不相同时要使用的填充索引。

一个负责通过块在 CPU 上正确聚合张量（或嵌套的列表/元组张量）的类。

如果我们的数据集有 16 个样本，每个进程上有 3 个进程的批量大小为 2，并且我们在每一步都进行聚合然后传输到 CPU，我们的采样器将生成以下索引：

[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 0, 1]

为了获得大小为 3 的倍数的数据（以便每个进程获得相同的数据集长度）。然后进程 0、1 和 2 将负责为以下样本进行预测：

• P0: [0, 1, 2, 3, 4, 5]

• P1: [6, 7, 8, 9, 10, 11]

• P2: [12, 13, 14, 15, 0, 1]

每个进程上处理的第一批将是

• P0: [0, 1]

• P1: [6, 7]

• P2: [12, 13]

因此，如果我们在第一批结束时进行聚合，我们将获得一个张量（嵌套的列表/元组张量），对应以下索引：

[0, 1, 6, 7, 12, 13]

如果我们直接连接我们的结果而不采取任何预防措施，用户将在预测循环结束时按此顺序获得索引的预测：

[0, 1, 6, 7, 12, 13, 2, 3, 8, 9, 14, 15, 4, 5, 10, 11, 0, 1]

由于某种原因，这不会引起他们的兴趣。这个类就是为了解决这个问题。

add_arrays

<来源>

( arrays )

将arrays添加到内部存储，将在第一次传递数组时将存储初始化为完整大小，以便如果我们绑定要发生 OOM，它会在开始时发生。

finalize

<来源>

( )

返回正确收集的数组并截断到样本数量（因为采样器添加了一些额外的内容，以使每个进程的数据集长度相同）。

Trainer 参数解析器

class transformers.HfArgumentParser

<来源>

( dataclass_types: Union **kwargs )

这个argparse.ArgumentParser的子类使用数据类的类型提示生成参数。

该类设计用于与原生 argparse 很好地配合。特别是，在初始化后可以向解析器添加更多（非数据类支持的）参数，解析后将作为额外的命名空间返回。可选：要创建子参数组，请在数据类中使用_argument_group_name属性。

parse_args_into_dataclasses

<来源>

( args = None return_remaining_strings = False look_for_args_file = True args_filename = None args_file_flag = None ) → export const metadata = 'undefined';Tuple consisting of

返回

由以下内容组成的元组

• 以与它们传递给初始化程序时相同的顺序的数据类实例。abspath

• 如果适用，用于在初始化后向解析器添加更多（非数据类支持的）参数的额外命名空间。

• 剩余参数字符串的潜在列表。（与 argparse.ArgumentParser.parse_known_args 相同）

将命令行参数解析为指定数据类类型的实例。

这依赖于 argparse 的ArgumentParser.parse_known_args。请参阅文档：docs.python.org/3.7/library/argparse.html#argparse.ArgumentParser.parse_args

parse_dict

<来源>

( args: Dict allow_extra_keys: bool = False ) → export const metadata = 'undefined';Tuple consisting of

参数

• args（dict）—包含配置值的字典

• allow_extra_keys（bool，可选，默认为False）—默认为 False。如果为 False，则如果字典包含未解析的键，则会引发异常。

返回

由以下内容组成的元组

• 以与它们传递给初始化程序时相同的顺序的数据类实例。

另一个不使用argparse的辅助方法，而是使用字典并填充数据类类型。

parse_json_file

<来源>

( json_file: str allow_extra_keys: bool = False ) → export const metadata = 'undefined';Tuple consisting of

参数

• json_file（str或os.PathLike）—要解析的 json 文件的文件名

• allow_extra_keys（bool，可选，默认为False）—默认为 False。如果为 False，则如果 json 文件包含未解析的键，则会引发异常。

返回

由以下内容组成的元组

• 以与它们传递给初始化程序时相同的顺序的数据类实例。

另一个不使用argparse的辅助方法，而是加载一个 json 文件并填充数据类类型。

parse_yaml_file

<来源>

( yaml_file: str allow_extra_keys: bool = False ) → export const metadata = 'undefined';Tuple consisting of

参数

• yaml_file（str或os.PathLike）—要解析的 yaml 文件的文件名

• allow_extra_keys（bool，可选，默认为False）—默认为 False。如果为 False，则如果 json 文件包含未解析的键，则会引发异常。

返回

由以下内容组成的元组

• 以与它们传递给初始化程序时相同的顺序的数据类实例。

另一种不使用argparse的辅助方法，而是加载一个 yaml 文件并填充数据类类型。

调试工具

class transformers.debug_utils.DebugUnderflowOverflow

<来源>

( model max_frames_to_save = 21 trace_batch_nums = [] abort_after_batch_num = None )

参数

• model (nn.Module) — 要调试的模型。

• max_frames_to_save (int，可选，默认为 21) — 记录多少帧以前

• trace_batch_nums(List[int], 可选，默认为[]) — 要跟踪的批次号（关闭检测）

• abort_after_batch_num (int，可选) — 是否在某个批次号完成后中止

此调试类有助于检测和理解模型何时开始变得非常大或非常小，更重要的是nan或inf权重和激活元素。

有 2 种工作模式：

1. 下溢/溢出检测（默认）

2. 没有检测的特定批次绝对最小/最大跟踪

模式 1：下溢/溢出检测

激活下溢/溢出检测，使用以下模型初始化对象：

debug_overflow = DebugUnderflowOverflow(model)

然后像平常一样运行训练，如果在权重、输入或输出元素中至少有一个检测到nan或inf，此模块将抛出异常，并打印导致此事件的max_frames_to_save帧，每帧报告

1. 完全限定的模块名称加上运行其forward的类名

2. 每个模块权重的所有元素的绝对最小值和最大值，以及输入和输出

例如，这是在 fp16 中运行的google/mt5-small的检测报告中的标题和最后几帧

混合精度：

Detected inf/nan during batch_number=0
Last 21 forward frames:
abs min  abs max  metadata [...]
                  encoder.block.2.layer.1.DenseReluDense.wi_0 Linear
2.17e-07 4.50e+00 weight
1.79e-06 4.65e+00 input[0]
2.68e-06 3.70e+01 output
                  encoder.block.2.layer.1.DenseReluDense.wi_1 Linear
8.08e-07 2.66e+01 weight
1.79e-06 4.65e+00 input[0]
1.27e-04 2.37e+02 output
                  encoder.block.2.layer.1.DenseReluDense.wo Linear
1.01e-06 6.44e+00 weight
0.00e+00 9.74e+03 input[0]
3.18e-04 6.27e+04 output
                  encoder.block.2.layer.1.DenseReluDense T5DenseGatedGeluDense
1.79e-06 4.65e+00 input[0]
3.18e-04 6.27e+04 output
                  encoder.block.2.layer.1.dropout Dropout
3.18e-04 6.27e+04 input[0]
0.00e+00      inf output

您可以在这里看到，T5DenseGatedGeluDense.forward 的输出激活结果，其绝对最大值约为 62.7K，非常接近 fp16 的 64K 上限。在下一帧中，我们有Dropout，它重新规范化权重，在将一些元素归零后，将绝对最大值推到超过 64K，导致溢出。

正如您所看到的，当数字开始变得非常大时，我们需要查看之前的帧以了解 fp16 数字。

跟踪是在前向挂钩中完成的，该挂钩在forward完成后立即调用。

默认情况下，将打印最后 21 帧。您可以更改默认值以适应您的需求。例如：

debug_overflow = DebugUnderflowOverflow(model, max_frames_to_save=100)

为了验证您已正确设置此调试功能，并且您打算在可能需要几个小时才能完成的训练中使用它，首先使用正常跟踪启用运行一些批次，如下一节所述。

模式 2. 没有检测的特定批次绝对最小/最大跟踪

第二种工作模式是批次跟踪，关闭下溢/溢出检测功能。

假设您想观察每个forward调用的所有成分的绝对最小值和最大值

给定批次，并且仅对第 1 和第 3 批次执行此操作。然后，实例化此类：

debug_overflow = DebugUnderflowOverflow(model, trace_batch_nums=[1, 3])

现在完整的第 1 和第 3 批次将使用与上述相同的格式进行跟踪。批次从 0 开始索引。

如果您知道程序在某个批次号之后开始表现不佳，那么您可以直接快进到该区域。

提前停止：

您还可以指定在哪个批次号之后停止训练，使用：

debug_overflow = DebugUnderflowOverflow(model, trace_batch_nums=[1, 3], abort_after_batch_num=3)

此功能主要在跟踪模式下有用，但您可以在任何模式下使用它。

性能：

由于此模块在每次前向传播时测量模型的每个权重的绝对min/max，因此会减慢训练速度。因此，请记住在满足调试需求后将其关闭。

生成工具

原始文本：huggingface.co/docs/transformers/v4.37.2/en/internal/generation_utils

此页面列出了 generate()、greedy_search()、contrastive_search()、sample()、beam_search()、beam_sample()、group_beam_search() 和 constrained_beam_search() 使用的所有实用函数。

大多数情况下，这些只有在研究库中生成方法的代码时才有用。

生成输出

generate() 的输出是 ModelOutput 的子类实例。这个输出是一个数据结构，包含了 generate() 返回的所有信息，但也可以用作元组或字典。

这里有一个例子：

from transformers import GPT2Tokenizer, GPT2LMHeadModel

tokenizer = GPT2Tokenizer.from_pretrained("gpt2")
model = GPT2LMHeadModel.from_pretrained("gpt2")

inputs = tokenizer("Hello, my dog is cute and ", return_tensors="pt")
generation_output = model.generate(**inputs, return_dict_in_generate=True, output_scores=True)

generation_output 对象是一个 GenerateDecoderOnlyOutput，正如我们在下面该类的文档中所看到的，它具有以下属性：

• sequences：生成的 token 序列

• scores（可选）：语言建模头的预测分数，每个生成步骤

• hidden_states（可选）：模型的隐藏状态，每个生成步骤

• attentions（可选）：模型的注意力权重，每个生成步骤

这里我们有 scores，因为我们传递了 output_scores=True，但我们没有 hidden_states 和 attentions，因为我们没有传递 output_hidden_states=True 或 output_attentions=True。

您可以像通常那样访问每个属性，如果该属性未被模型返回，您将得到 None。在这里，例如 generation_output.scores 是语言建模头生成的所有预测分数，而 generation_output.attentions 是 None。

当将我们的 generation_output 对象用作元组时，它只保留那些没有 None 值的属性。在这里，例如，它有两个元素，loss 然后 logits，所以

generation_output[:2]

例如，将返回元组 (generation_output.sequences, generation_output.scores)。

当将我们的 generation_output 对象用作字典时，它只保留那些没有 None 值的属性。在这里，例如，它有两个键，分别是 sequences 和 scores。

我们在这里记录所有输出类型。

PyTorch

class transformers.generation.GenerateDecoderOnlyOutput

< source >

( sequences: LongTensor = None scores: Optional = None attentions: Optional = None hidden_states: Optional = None past_key_values: Optional = None )

参数

• sequences（形状为 (batch_size, sequence_length) 的 torch.LongTensor） — 生成的序列。第二维（sequence_length）要么等于 max_length，要么如果所有批次由于 eos_token_id 提前结束，则要短一些。

• scores（tuple(torch.FloatTensor) 可选，当传递output_scores=True或config.output_scores=True时返回）— 在每个生成步骤中语言建模头的处理预测分数（SoftMax 之前每个词汇标记的分数）。元组torch.FloatTensor，最多包含max_new_tokens个元素（每个生成的标记一个元素），每个张量的形状为(batch_size, config.vocab_size)。

• attentions（tuple(tuple(torch.FloatTensor))，可选，当传递output_attentions=True或config.output_attentions=True时返回）— 元组（每个生成的标记一个元素）的元组（解码器的每一层一个元素）的torch.FloatTensor，形状为(batch_size, num_heads, generated_length, sequence_length)。

• hidden_states（tuple(tuple(torch.FloatTensor))，可选，当传递output_hidden_states=True或config.output_hidden_states=True时返回）— 元组（每个生成的标记一个元素）的元组（解码器的每一层一个元素）的torch.FloatTensor，形状为(batch_size, generated_length, hidden_size)。

• past_key_values（tuple(tuple(torch.FloatTensor))，可选，当传递use_cache=True或config.use_cache=True时返回）— 注意：一些模型具有不同的past_key_values格式，请查阅模型的文档进行确认。通常是一个元组（解码器的每一层一个元素）的元组（两个元素，键张量和值张量）。第一个元组的长度为config.n_layers，每个元组有 2 个形状为(batch_size, num_heads, sequence_length, embed_size_per_head)的张量，如果config.is_encoder_decoder=True，还有 2 个额外的形状为(batch_size, num_heads, encoder_sequence_length, embed_size_per_head)的张量。

解码器生成模型的输出，在使用非 beam 方法时。

class transformers.generation.GenerateEncoderDecoderOutput

<来源>

( sequences: LongTensor = None scores: Optional = None encoder_attentions: Optional = None encoder_hidden_states: Optional = None decoder_attentions: Optional = None cross_attentions: Optional = None decoder_hidden_states: Optional = None past_key_values: Optional = None )

参数

• sequences（形状为(batch_size, sequence_length)的torch.LongTensor）— 生成的序列。第二维（sequence_length）要么等于max_length，要么如果所有批次由于eos_token_id而提前完成，则要短。

• scores（tuple(torch.FloatTensor) 可选，当传递output_scores=True或config.output_scores=True时返回）— 在每个生成步骤中语言建模头的处理预测分数（SoftMax 之前每个词汇标记的分数）。元组torch.FloatTensor，最多包含max_new_tokens个元素（每个生成的标记一个元素），每个张量的形状为(batch_size, config.vocab_size)。

• encoder_attentions（tuple(torch.FloatTensor)，可选，当传递output_attentions=True或config.output_attentions=True时返回）— 元组的torch.FloatTensor（解码器的每一层一个）的形状为(batch_size, num_heads, sequence_length, sequence_length)。

• encoder_hidden_states（tuple(torch.FloatTensor)，可选，当传递output_hidden_states=True或config.output_hidden_states=True时返回）— 元组的torch.FloatTensor（嵌入的输出一个加上每一层的输出一个）的形状为(batch_size, sequence_length, hidden_size)。

• decoder_attentions（tuple(tuple(torch.FloatTensor))，可选，当传递output_attentions=True或config.output_attentions=True时返回）— 元组（每个生成的标记一个元素）的元组（解码器的每一层一个元素）的torch.FloatTensor，形状为(batch_size, num_heads, generated_length, sequence_length)。

• cross_attentions (tuple(tuple(torch.FloatTensor)))，可选，当传递output_attentions=True或config.output_attentions=True时返回 — 每个生成的令牌的元组（每个解码器层一个元素）的torch.FloatTensor，形状为(batch_size, num_heads, generated_length, sequence_length)。

• decoder_hidden_states (tuple(tuple(torch.FloatTensor)))，可选，当传递output_hidden_states=True或config.output_hidden_states=True时返回 — 每个生成的令牌的元组（每个解码器层一个元素）的torch.FloatTensor的元组，形状为(batch_size, generated_length, hidden_size)。

• past_key_values (tuple(tuple(torch.FloatTensor)))，可选，当传递use_cache=True或config.use_cache=True时返回 — 注意：一些模型具有不同的past_key_values格式，请查阅模型文档确认。通常是一个元组（解码器每一层一个元素）的元组（两个元素，键张量和值张量）。第一个元组的长度为config.n_layers，每个元组有 2 个形状为(batch_size, num_heads, sequence_length, embed_size_per_head)的张量，并且如果config.is_encoder_decoder=True，还有 2 个额外的形状为(batch_size, num_heads, encoder_sequence_length, embed_size_per_head)的张量。

在使用非 beam 方法时的编码器-解码器生成模型的输出。

class transformers.generation.GenerateBeamDecoderOnlyOutput

< source >

( sequences: LongTensor = None sequences_scores: Optional = None scores: Optional = None beam_indices: Optional = None attentions: Optional = None hidden_states: Optional = None past_key_values: Optional = None )

参数

• sequences (torch.LongTensor，形状为(batch_size*num_return_sequences, sequence_length)) — 生成的序列。第二维（sequence_length）要么等于max_length，要么如果所有批次由于eos_token_id而提前结束，则较短。

• sequences_scores (torch.FloatTensor，形状为(batch_size*num_return_sequences))，可选，当传递output_scores=True或config.output_scores=True时返回 — 生成sequences的最终 beam 分数。

• scores (tuple(torch.FloatTensor)，可选，当传递output_scores=True或config.output_scores=True时返回 — 每一代步每个词汇令牌的 beam 转移分数。beam 转移分数由 tokens 的对数概率条件于该 beam 中先前生成的 tokens 的对数 softmax 组成。具有最多max_new_tokens元素的torch.FloatTensor元组（每个生成的令牌一个元素），每个张量的形状为(batch_size*num_beams*num_return_sequences, config.vocab_size)。

• beam_indices (torch.LongTensor)，可选，当传递output_scores=True或config.output_scores=True时返回 — 每一代步生成的令牌 id 的 beam 索引。形状为(batch_size*num_return_sequences, sequence_length)的torch.LongTensor。

• attentions (tuple(tuple(torch.FloatTensor)))，可选，当传递output_attentions=True或config.output_attentions=True时返回 — 每个生成的令牌的元组（每个解码器层一个元素）的torch.FloatTensor的元组，形状为(batch_size*num_beams, num_heads, generated_length, sequence_length)。

• hidden_states (tuple(tuple(torch.FloatTensor)))，可选，当传递output_hidden_states=True或config.output_hidden_states=True时返回 — 每个生成的令牌的元组（每个解码器层一个元素）的torch.FloatTensor，形状为(batch_size*num_beams*num_return_sequences, generated_length, hidden_size)。

• past_key_values（tuple(tuple(torch.FloatTensor)))，可选，当传递use_cache=True或config.use_cache=True时返回）— 注意：一些模型具有不同的past_key_values格式，请查阅模型的文档。通常是一个元组（解码器每一层一个）的元组（两个元素，键张量和值张量）。第一个元组的长度为config.n_layers，每个元组有 2 个形状为(batch_size, num_heads, sequence_length, embed_size_per_head)的张量，如果config.is_encoder_decoder=True，还有 2 个额外的形状为(batch_size, num_heads, encoder_sequence_length, embed_size_per_head)的张量。

在使用 beam 方法时，仅解码器生成模型的输出。

class transformers.generation.GenerateBeamEncoderDecoderOutput

<来源>

( sequences: LongTensor = None sequences_scores: Optional = None scores: Optional = None beam_indices: Optional = None encoder_attentions: Optional = None encoder_hidden_states: Optional = None decoder_attentions: Optional = None cross_attentions: Optional = None decoder_hidden_states: Optional = None past_key_values: Optional = None )

参数

• sequences（torch.LongTensor，形状为(batch_size*num_return_sequences, sequence_length)）— 生成的序列。第二维（sequence_length）要么等于max_length，要么如果所有批次由于eos_token_id而提前结束，则较短。

• sequences_scores（torch.FloatTensor，形状为(batch_size*num_return_sequences)，可选，当传递output_scores=True或config.output_scores=True时返回）— 生成的sequences的最终 beam 分数。

• scores（tuple(torch.FloatTensor)，可选，当传递output_scores=True或config.output_scores=True时返回）— 每一代步骤中每个词汇标记的 beam 转移分数。Beam 转移分数由 tokens 的 log 概率组成，条件是该 beam 中先前生成的 tokens 的 log softmax。torch.FloatTensor的元组，最多有max_new_tokens个元素（每个生成的 token 一个元素），每个张量的形状为(batch_size*num_beams, config.vocab_size)。

• beam_indices（torch.LongTensor，可选，当传递output_scores=True或config.output_scores=True时返回）— 每一代步骤中生成的 token id 的 beam 索引。形状为(batch_size*num_return_sequences, sequence_length)的torch.LongTensor。

• encoder_attentions（tuple(torch.FloatTensor)，可选，当传递output_attentions=True或config.output_attentions=True时返回）— 形状为(batch_size, num_heads, sequence_length, sequence_length)的torch.FloatTensor元组（解码器每一层一个）。

• encoder_hidden_states（tuple(torch.FloatTensor)，可选，当传递output_hidden_states=True或config.output_hidden_states=True时返回）— 形状为(batch_size*num_beams*num_return_sequences, sequence_length, hidden_size)的torch.FloatTensor元组（一个用于嵌入的输出 + 一个用于每一层的输出）。

• decoder_attentions（tuple(tuple(torch.FloatTensor))，可选，当传递output_attentions=True或config.output_attentions=True时返回）— 元组（每个生成的 token 一个元素）的元组（解码器每一层一个）的torch.FloatTensor，形状为(batch_size*num_beams*num_return_sequences, num_heads, generated_length, sequence_length)。

• cross_attentions（tuple(tuple(torch.FloatTensor))，可选，当传递output_attentions=True或config.output_attentions=True时返回）— 元组（每个生成的 token 一个元素）的元组（解码器每一层一个）的torch.FloatTensor，形状为(batch_size, num_heads, generated_length, sequence_length)。

• decoder_hidden_states（tuple(tuple(torch.FloatTensor))，可选，当传递output_hidden_states=True或config.output_hidden_states=True时返回）— 元组（每个生成的 token 一个元素）的元组（解码器每一层一个）的torch.FloatTensor，形状为(batch_size*num_beams*num_return_sequences, generated_length, hidden_size)。

• past_key_values (tuple(tuple(torch.FloatTensor))), optional, 当传递use_cache=True或config.use_cache=True时返回) — 注意：一些模型具有不同的past_key_values格式，请查阅模型文档。通常是一个元组（解码器每层一个元素）的元组（两个元素，键张量和值张量）。第一个元组的长度为config.n_layers，每个元组有 2 个形状为(batch_size, num_heads, sequence_length, embed_size_per_head)的张量，如果config.is_encoder_decoder=True，还有 2 个额外的形状为(batch_size, num_heads, encoder_sequence_length, embed_size_per_head)的张量。

在使用 beam 方法时，编码器-解码器生成模型的输出。

TensorFlow

class transformers.generation.TFGreedySearchEncoderDecoderOutput

<来源>

( sequences: Tensor = None scores: Optional = None encoder_attentions: Optional = None encoder_hidden_states: Optional = None decoder_attentions: Optional = None cross_attentions: Optional = None decoder_hidden_states: Optional = None )

参数

• sequences (tf.Tensor，形状为(batch_size, sequence_length)) — 生成的序列。第二维（sequence_length）要么等于max_length，要么如果所有批次由于eos_token_id而提前完成，则要短一些。

• scores (tuple(tf.Tensor) optional, 当传递output_scores=True或config.output_scores=True时返回) — 语言建模头的处理预测分数（SoftMax 之前每个词汇标记的分数）在每个生成步骤。tf.Tensor的元组，最多有max_new_tokens个元素（每个生成的标记一个元素），每个张量的形状为(batch_size, config.vocab_size)。

• encoder_attentions (tuple(tf.Tensor), optional, 当传递output_attentions=True或config.output_attentions=True时返回) — 元组（解码器每层一个元素）的tf.Tensor，形状为(batch_size, num_heads, sequence_length, sequence_length)。

• encoder_hidden_states (tuple(tf.Tensor), optional, 当传递output_hidden_states=True或config.output_hidden_states=True时返回) — 形状为(batch_size, sequence_length, hidden_size)的tf.Tensor元组（一个用于嵌入的输出 + 一个用于每个层的输出）。

• decoder_attentions (tuple(tuple(tf.Tensor)), optional, 当传递output_attentions=True或config.output_attentions=True时返回) — 元组（每个生成的标记一个元素）的元组（解码器每层一个元素）的tf.Tensor，形状为(batch_size, num_heads, generated_length, sequence_length)。

• cross_attentions (tuple(tuple(tf.Tensor)), optional, 当传递output_attentions=True或config.output_attentions=True时返回) — 元组（每个生成的标记一个元素）的元组（解码器每层一个元素）的tf.Tensor，形状为(batch_size, num_heads, generated_length, sequence_length)。

• decoder_hidden_states (tuple(tuple(tf.Tensor)), optional, 当传递output_hidden_states=True或config.output_hidden_states=True时返回) — 元组（每个生成的标记一个元素）的元组（解码器每层一个元素）的tf.Tensor，形状为(batch_size, generated_length, hidden_size)。

使用贪婪搜索的编码器-解码器生成模型的输出的基类。可以通过encoder_attentions和encoder_hidden_states属性（或decoder_attentions和decoder_hidden_states属性）访问解码器（或编码器）的隐藏状态和注意力权重。

class transformers.generation.TFGreedySearchDecoderOnlyOutput

<来源>

( sequences: Tensor = None scores: Optional = None attentions: Optional = None hidden_states: Optional = None )

参数

• sequences (tf.Tensor，形状为(batch_size, sequence_length)) — 生成的序列。第二维（sequence_length）要么等于max_length，要么如果所有批次由于eos_token_id而提前完成，则要短一些。

• scores (tuple(tf.Tensor) optional, 当传递output_scores=True或config.output_scores=True时返回) — 每个生成步骤的语言建模头的处理预测分数（SoftMax 之前每个词汇标记的分数）。具有最多max_new_tokens元素的tf.Tensor元组（每个生成的标记一个元素），每个张量的形状为(batch_size, config.vocab_size)。

• attentions (tuple(tuple(tf.Tensor)), optional, 当传递output_attentions=True或config.output_attentions=True时返回) — 元组（每个生成的标记一个元素）的元组（解码器每一层一个元素）的tf.Tensor，形状为(batch_size, num_heads, generated_length, sequence_length)。

• hidden_states (tuple(tuple(tf.Tensor)), optional, 当传递output_hidden_states=True或config.output_hidden_states=True时返回) — 元组（每个生成的标记一个元素）的元组（解码器每一层一个元素）的tf.Tensor，形状为(batch_size, generated_length, hidden_size)。

仅解码器生成模型使用贪婪搜索的输出的基类。

class transformers.generation.TFSampleEncoderDecoderOutput

<来源>

( sequences: Tensor = None scores: Optional = None encoder_attentions: Optional = None encoder_hidden_states: Optional = None decoder_attentions: Optional = None cross_attentions: Optional = None decoder_hidden_states: Optional = None )

参数

• sequences (tf.Tensor，形状为(batch_size*num_return_sequences, sequence_length)) — 生成的序列。第二维（sequence_length）要么等于max_length，要么如果所有批次由于eos_token_id而提前完成，则较短。

• scores (tuple(tf.Tensor) optional, 当传递output_scores=True或config.output_scores=True时返回) — 每个生成步骤的语言建模头的处理预测分数（SoftMax 之前每个词汇标记的分数）。具有最多max_new_tokens元素的tf.Tensor元组（每个生成的标记一个元素），每个张量的形状为(batch_size*num_return_sequences, config.vocab_size)。

• encoder_attentions (tuple(tf.Tensor), optional, 当传递output_attentions=True或config.output_attentions=True时返回) — 形状为(batch_size*num_return_sequences, num_heads, sequence_length, sequence_length)的tf.Tensor元组（每个解码器层一个）。

• encoder_hidden_states (tuple(tf.Tensor), optional, 当传递output_hidden_states=True或config.output_hidden_states=True时返回) — 形状为(batch_size*num_return_sequences, sequence_length, hidden_size)的tf.Tensor元组（一个用于嵌入的输出 + 一个用于每个层的输出）。

• decoder_attentions (tuple(tuple(tf.Tensor)), optional, 当传递output_attentions=True或config.output_attentions=True时返回) — 元组（每个生成的标记一个元素）的元组（解码器每一层一个元素）的tf.Tensor，形状为(batch_size*num_return_sequences, num_heads, generated_length, sequence_length)。

• cross_attentions (tuple(tuple(tf.Tensor)), optional, 当传递output_attentions=True或config.output_attentions=True时返回) — 元组（每个生成的标记一个元素）的元组（解码器每一层一个元素）的tf.Tensor，形状为(batch_size, num_heads, generated_length, sequence_length)。

• decoder_hidden_states (tuple(tuple(tf.Tensor)), optional, 当传递output_hidden_states=True或config.output_hidden_states=True时返回) — 元组（每个生成的标记一个元素）的元组（解码器每一层一个元素）的tf.Tensor，形状为(batch_size*num_return_sequences, generated_length, hidden_size)。

使用采样的编码器-解码器生成模型的输出的基类。可以通过encoder_attentions和encoder_hidden_states属性（或decoder_attentions和decoder_hidden_states属性）访问解码器（或编码器）的隐藏状态和注意力权重。

class transformers.generation.TFSampleDecoderOnlyOutput

<来源>

( sequences: Tensor = None scores: Optional = None attentions: Optional = None hidden_states: Optional = None )

参数

• sequences (tf.Tensor，形状为(batch_size*num_return_sequences, sequence_length)) — 生成的序列。第二维（sequence_length）要么等于max_length，要么如果所有批次由于eos_token_id而提前完成，则要短。

• scores (tuple(tf.Tensor)，optional, 当传递output_scores=True或config.output_scores=True时返回) — 语言建模头的预测分数（SoftMax 之前的每个词汇标记的分数）在每个生成步骤。tf.Tensor的元组，最多有max_new_tokens个元素（每个生成的标记一个元素），每个张量的形状为(batch_size*num_return_sequences, config.vocab_size)。

• attentions (tuple(tuple(tf.Tensor)), optional, 当传递output_attentions=True或config.output_attentions=True时返回) — 元组（每个生成的标记一个元素）的元组（解码器每一层一个元素）的tf.Tensor，形状为(num_return_sequences*batch_size, num_heads, generated_length, sequence_length)。

• hidden_states (tuple(tuple(tf.Tensor)), optional, 当传递output_hidden_states=True或config.output_hidden_states=True时返回) — 元组（每个生成的标记一个元素）的元组（解码器每一层一个元素）的tf.Tensor，形状为(num_return_sequences*batch_size, generated_length, hidden_size)。

用于仅使用采样的解码器生成模型的输出的基类。

class transformers.generation.TFBeamSearchEncoderDecoderOutput

<来源>

( sequences: Tensor = None sequences_scores: Optional = None scores: Optional = None beam_indices: Optional = None encoder_attentions: Optional = None encoder_hidden_states: Optional = None decoder_attentions: Optional = None cross_attentions: Optional = None decoder_hidden_states: Optional = None )

参数

• sequences (tf.Tensor，形状为(batch_size*num_return_sequences, sequence_length)) — 生成的序列。第二维（sequence_length）要么等于max_length，要么如果所有批次由于eos_token_id而提前完成，则要短。

• sequences_scores (tf.Tensor，形状为(batch_size*num_return_sequences)，optional, 当传递output_scores=True或config.output_scores=True时返回) — 生成的sequences的最终 beam 分数。

• scores (tuple(tf.Tensor)，optional, 当传递output_scores=True或config.output_scores=True时返回) — 每个生成步骤中每个词汇标记的处理过的 beam 分数。beam 分数由每个词汇标记的 log softmax 分数和此 beam 中先前生成标记的 log softmax 之和组成。tf.Tensor的元组，最多有max_new_tokens个元素（每个生成的标记一个元素），每个张量的形状为(batch_size*num_beams, config.vocab_size)。

• beam_indices (tf.Tensor，optional, 当传递output_scores=True或config.output_scores=True时返回) — 每个生成步骤中生成的标记 id 的 beam 索引。形状为(batch_size*num_return_sequences, sequence_length)的tf.Tensor。

• encoder_attentions (tuple(tf.Tensor), optional, 当传递output_attentions=True或config.output_attentions=True时返回) — 形状为(batch_size, num_heads, sequence_length, sequence_length)的tf.Tensor元组（解码器每一层一个）。

• encoder_hidden_states (tuple(tf.Tensor), optional, 当传递output_hidden_states=True或config.output_hidden_states=True时返回) — 形状为(batch_size*num_beams*num_return_sequences, sequence_length, hidden_size)的tf.Tensor元组（一个用于嵌入的输出 + 一个用于每个层的输出）。

• decoder_attentions（tuple(tuple(tf.Tensor))，可选，当传递output_attentions=True或config.output_attentions=True时返回）— 元组（每个生成的 token 一个元素）的元组（解码器每层一个元素）的tf.Tensor，形状为(batch_size*num_beams*num_return_sequences, num_heads, generated_length, sequence_length)。

• cross_attentions（tuple(tuple(tf.Tensor))，可选，当传递output_attentions=True或config.output_attentions=True时返回）— 元组（每个生成的 token 一个元素）的元组（解码器每层一个元素）的tf.Tensor，形状为(batch_size, num_heads, generated_length, sequence_length)。

• decoder_hidden_states（tuple(tuple(tf.Tensor))，可选，当传递output_hidden_states=True或config.output_hidden_states=True时返回）— 元组（每个生成的 token 一个元素）的元组（解码器每层一个元素）的tf.Tensor，形状为(batch_size*num_beams*num_return_sequences, generated_length, hidden_size)。

基类，用于使用 beam 搜索的编码器-解码器生成模型的输出。可以通过encoder_attentions和encoder_hidden_states属性（分别是decoder_attentions和decoder_hidden_states属性）访问解码器（或编码器）的隐藏状态和注意力权重。

class transformers.generation.TFBeamSearchDecoderOnlyOutput

<来源>

( sequences: Tensor = None sequences_scores: Optional = None scores: Optional = None beam_indices: Optional = None attentions: Optional = None hidden_states: Optional = None )

参数

• sequences（形状为(batch_size*num_return_sequences, sequence_length)的tf.Tensor）— 生成的序列。第二维（sequence_length）要么等于max_length，要么如果所有批次由于eos_token_id而提前完成，则要短。

• sequences_scores（形状为(batch_size*num_return_sequences)的tf.Tensor，可选，当传递output_scores=True或config.output_scores=True时返回）— 生成的sequences的最终 beam 分数。

• scores（tuple(tf.Tensor) 可选，当传递output_scores=True或config.output_scores=True时返回）— 每个生成步骤中每个词汇标记的处理过的 beam 分数。beam 分数由每个词汇标记的 log softmax 分数和此 beam 中先前生成的标记的 log softmax 之和组成。具有最多max_new_tokens元素的tf.Tensor元组（每个生成的 token 一个元素），每个张量的形状为(batch_size*num_beams*num_return_sequences, config.vocab_size)。

• beam_indices（tf.Tensor，可选，当传递output_scores=True或config.output_scores=True时返回）— 每个生成步骤中生成的 token id 的 beam 索引。形状为(batch_size*num_return_sequences, sequence_length)的tf.Tensor。

• attentions（tuple(tuple(tf.Tensor))，可选，当传递output_attentions=True或config.output_attentions=True时返回）— 元组（每个生成的 token 一个元素）的元组（解码器每层一个元素）的tf.Tensor，形状为(batch_size*num_beams, num_heads, generated_length, sequence_length)。

• hidden_states（tuple(tuple(tf.Tensor))，可选，当传递output_hidden_states=True或config.output_hidden_states=True时返回）— 元组（每个生成的 token 一个元素）的元组（解码器每层一个元素）的tf.Tensor，形状为(batch_size*num_beams*num_return_sequences, generated_length, hidden_size)。

用于使用 beam 搜索的解码器生成模型的输出的基类。

class transformers.generation.TFBeamSampleEncoderDecoderOutput

<来源>

( sequences: Tensor = None sequences_scores: Optional = None scores: Optional = None beam_indices: Optional = None encoder_attentions: Optional = None encoder_hidden_states: Optional = None decoder_attentions: Optional = None cross_attentions: Optional = None decoder_hidden_states: Optional = None )

参数

• sequences (tf.Tensor，形状为(batch_size*num_beams, sequence_length)) — 生成的序列。第二维（sequence_length）要么等于max_length，要么如果所有批次由于eos_token_id而提前完成，则较短。

• sequences_scores (tf.Tensor，形状为(batch_size * num_return_sequence)，optional，当传递output_scores=True或config.output_scores=True时返回) — 生成的sequences的最终 beam 分数。

• scores (tuple(tf.Tensor)，optional，当传递output_scores=True或config.output_scores=True时返回) — 每个生成步骤中每个词汇标记的处理 beam 分数。beam 分数由每个词汇标记的 log softmax 分数和此 beam 中先前生成标记的 log softmax 之和组成。具有最多max_new_tokens元素的tf.Tensor元组（每个生成的标记一个元素），每个张量形状为(batch_size*num_beams, config.vocab_size)。

• beam_indices (tf.Tensor，optional，当传递output_scores=True或config.output_scores=True时返回) — 每个生成步骤中生成的标记 id 的 beam 索引。形状为(batch_size*num_return_sequences, sequence_length)的tf.Tensor。

• encoder_attentions (tuple(tf.Tensor), optional, 当传递output_attentions=True或config.output_attentions=True时返回) — 形状为(batch_size, num_heads, sequence_length, sequence_length)的tf.Tensor元组（每个解码器层一个）。

• encoder_hidden_states (tuple(tf.Tensor)，optional，当传递output_hidden_states=True或config.output_hidden_states=True时返回) — 形状为(batch_size*num_beams, sequence_length, hidden_size)的tf.Tensor元组（嵌入输出和每个层输出各一个）。

• decoder_attentions (tuple(tuple(tf.Tensor)), optional, 当传递output_attentions=True或config.output_attentions=True时返回) — 元组（每个生成的标记一个元素）的元组（每个解码器层一个）的tf.Tensor，形状为(batch_size*num_beams, num_heads, generated_length, sequence_length)。

• cross_attentions (tuple(tuple(tf.Tensor))，optional，当传递output_attentions=True或config.output_attentions=True时返回) — 元组（每个生成的标记一个元素）的元组（每个解码器层一个）的tf.Tensor，形状为(batch_size, num_heads, generated_length, sequence_length)。

• decoder_hidden_states (tuple(tuple(tf.Tensor))，optional，当传递output_hidden_states=True或config.output_hidden_states=True时返回) — 元组（每个生成的标记一个元素）的元组（每个解码器层一个）的tf.Tensor，形状为(batch_size*num_beams, generated_length, hidden_size)。

用于使用 beam 采样的编码器-解码器生成模型输出的基类。可以通过encoder_attentions和encoder_hidden_states属性（分别为decoder_attentions和decoder_hidden_states属性）访问解码器（或编码器）的隐藏状态和注意力权重。

class transformers.generation.TFBeamSampleDecoderOnlyOutput

<来源>

( sequences: Tensor = None sequences_scores: Optional = None scores: Optional = None beam_indices: Optional = None attentions: Optional = None hidden_states: Optional = None )

参数

• sequences (tf.Tensor，形状为(batch_size*num_return_sequences, sequence_length)) — 生成的序列。第二维（sequence_length）要么等于max_length，要么如果所有批次由于eos_token_id而提前完成，则较短。

• sequences_scores (tf.Tensor，形状为(batch_size * num_return_sequence)，optional，当传递output_scores=True或config.output_scores=True时返回) — 生成的sequences的最终 beam 分数。

• scores (tuple(tf.Tensor) optional, 当传递output_scores=True或config.output_scores=True时返回) — 每个生成步骤中每个词汇标记的处理 beam 分数。beam 分数由每个词汇标记的 log softmax 分数和此 beam 中先前生成的标记的 log softmax 之和组成。具有最多max_new_tokens元素的tf.Tensor元组（每个生成的标记一个元素），每个张量的形状为(batch_size*num_beams*num_return_sequences, config.vocab_size)。

• beam_indices (tf.Tensor, optional, 当传递output_scores=True或config.output_scores=True时返回) — 每个生成步骤中生成的标记 id 的 beam 索引。形状为(batch_size*num_return_sequences, sequence_length)的tf.Tensor。

• attentions (tuple(tuple(tf.Tensor)), optional, 当传递output_attentions=True或config.output_attentions=True时返回) — 元组（每个生成的标记一个元素）的元组（解码器每层一个元素）的tf.Tensor，形状为(batch_size*num_beams, num_heads, generated_length, sequence_length)。

• hidden_states (tuple(tuple(tf.Tensor)), optional, 当传递output_hidden_states=True或config.output_hidden_states=True时返回) — 元组（每个生成的标记一个元素）的元组（解码器每层一个元素）的tf.Tensor，形状为(batch_size*num_beams, generated_length, hidden_size)。

用于使用 beam sample 的仅解码器生成模型的输出的基类。

class transformers.generation.TFContrastiveSearchEncoderDecoderOutput

<来源>

( sequences: Tensor = None scores: Optional = None encoder_attentions: Optional = None encoder_hidden_states: Optional = None decoder_attentions: Optional = None cross_attentions: Optional = None decoder_hidden_states: Optional = None )

参数

• sequences (tf.Tensor，形状为(batch_size, sequence_length)) — 生成的序列。第二维（sequence_length）要么等于max_length，要么如果所有批次由于eos_token_id而提前完成，则要短。

• scores (tuple(tf.Tensor) optional, 当传递output_scores=True或config.output_scores=True时返回) — 在每个生成步骤中语言建模头的处理预测分数（SoftMax 之前每个词汇标记的分数）。具有最多max_new_tokens元素的tf.Tensor元组（每个生成的标记一个元素），每个张量的形状为(batch_size, config.vocab_size)。

• encoder_attentions (tuple(tf.Tensor), optional, 当传递output_attentions=True或config.output_attentions=True时返回) — 元组（解码器每层一个元素）的tf.Tensor，形状为(batch_size, num_heads, sequence_length, sequence_length)。

• encoder_hidden_states (tuple(tf.Tensor), optional, 当传递output_hidden_states=True或config.output_hidden_states=True时返回) — 形状为(batch_size, sequence_length, hidden_size)的tf.Tensor元组（一个用于嵌入的输出 + 一个用于每个层的输出）。

• decoder_attentions (tuple(tuple(tf.Tensor)), optional, 当传递output_attentions=True或config.output_attentions=True时返回) — 元组（每个生成的标记一个元素）的元组（解码器每层一个元素）的tf.Tensor，形状为(batch_size, num_heads, generated_length, sequence_length)。

• cross_attentions (tuple(tuple(tf.Tensor)), optional, 当传递output_attentions=True或config.output_attentions=True时返回) — 元组（每个生成的标记一个元素）的元组（解码器每层一个元素）的tf.Tensor，形状为(batch_size, num_heads, generated_length, sequence_length)。

• decoder_hidden_states (tuple(tuple(tf.Tensor)), optional, 当传递output_hidden_states=True或config.output_hidden_states=True时返回) — 元组（每个生成的标记一个元素）的元组（解码器每层一个元素）的tf.Tensor，形状为(batch_size, generated_length, hidden_size)。

用于使用对比搜索的编码器-解码器生成模型的输出的基类。可以通过encoder_attentions和encoder_hidden_states属性（分别是decoder_attentions和decoder_hidden_states属性）访问解码器（或编码器）的隐藏状态和注意力权重。

class transformers.generation.TFContrastiveSearchDecoderOnlyOutput

<来源>

( sequences: Tensor = None scores: Optional = None attentions: Optional = None hidden_states: Optional = None )

参数

• sequences（形状为(batch_size, sequence_length)的tf.Tensor）— 生成的序列。第二维（sequence_length）要么等于max_length，要么如果所有批次由于eos_token_id而提前结束，则要短。

• scores（tuple(tf.Tensor) 可选，当传递output_scores=True或config.output_scores=True时返回）— 语言建模头的处理预测分数（SoftMax 之前每个词汇标记的分数）在每个生成步骤。每个生成标记一个元素，每个张量形状为(batch_size, config.vocab_size)的tf.Tensor的元组，最多有max_new_tokens个元素。

• attentions（tuple(tuple(tf.Tensor))，可选，当传递output_attentions=True或config.output_attentions=True时返回）— 元组（每个生成的标记一个元素）的元组（解码器每层一个元素）的形状为(batch_size, num_heads, generated_length, sequence_length)的tf.Tensor。

• hidden_states（tuple(tuple(tf.Tensor))，可选，当传递output_hidden_states=True或config.output_hidden_states=True时返回）— 元组（每个生成的标记一个元素）的元组（解码器每层一个元素）的形状为(batch_size, generated_length, hidden_size)的tf.Tensor。

用于仅使用对比搜索生成模型的输出的基类。

FLAX

class transformers.generation.FlaxSampleOutput

<来源>

( sequences: Array = None )

参数

• sequences（形状为(batch_size, max_length)的jnp.ndarray）— 生成的序列。

Flax 基类，用于仅使用抽样生成模型的输出。

替换

<来源>

( **updates )

“返回一个用新值替换指定字段的新对象。

class transformers.generation.FlaxGreedySearchOutput

<来源>

( sequences: Array = None )

参数

• sequences（形状为(batch_size, max_length)的jnp.ndarray）— 生成的序列。

Flax 基类，用于仅使用贪婪搜索生成模型的输出。

替换

<来源>

( **updates )

“返回一个用新值替换指定字段的新对象。

class transformers.generation.FlaxBeamSearchOutput

<来源>

( sequences: Array = None scores: Array = None )

参数

• sequences（形状为(batch_size, max_length)的jnp.ndarray）— 生成的序列。

• scores（形状为(batch_size,)的jnp.ndarray）— 生成序列的分数（对数概率）。

Flax 基类，用于仅使用贪婪搜索生成模型的输出。

替换

<来源>

( **updates )

“返回一个用新值替换指定字段的新对象。

LogitsProcessor

LogitsProcessor 可以用于修改语言模型头的预测分数以进行生成。

PyTorch

class transformers.AlternatingCodebooksLogitsProcessor

<来源>

( input_start_len: int semantic_vocab_size: int codebook_size: int )

参数

• input_start_len（int）— 初始输入序列的长度。

• semantic_vocab_size（int）— 语义部分的词汇表大小，即与语义词汇表相关联的标记数。

• codebook_size（int）— 与代码簿相关联的标记数。

LogitsProcessor 强制在 Bark 的两个代码簿之间交替生成。

此对数处理器仅与Bark的精细子模型兼容。请参阅模型文档以获取示例。

__call__

<来源>

( input_ids: LongTensor scores: FloatTensor )

class transformers.ClassifierFreeGuidanceLogitsProcessor

<来源>

( guidance_scale )

参数

• guidance_scale（浮点数）— 用于分类器自由引导（CFG）的引导比例。通过设置guidance_scale > 1来启用 CFG。更高的引导比例鼓励模型生成与输入提示更紧密相关的样本，通常以牺牲质量为代价。

LogitsProcessor 用于分类器自由引导（CFG）。分数在批处理维度上分割，其中前半部分对应条件对数（从输入提示预测），后半部分对应无条件对数（从空或“null”提示预测）。处理器计算条件和无条件对数之间的加权平均值，由guidance_scale参数化。

有关更多信息，请参阅论文。

此对数处理器仅与MusicGen兼容

示例：

>>> from transformers import AutoProcessor, MusicgenForConditionalGeneration

>>> processor = AutoProcessor.from_pretrained("facebook/musicgen-small")
>>> model = MusicgenForConditionalGeneration.from_pretrained("facebook/musicgen-small")

>>> inputs = processor(
...     text=["80s pop track with bassy drums and synth", "90s rock song with loud guitars and heavy drums"],
...     padding=True,
...     return_tensors="pt",
... )
>>> audio_values = model.generate(**inputs, do_sample=True, guidance_scale=3, max_new_tokens=256)

__call__

<来源>

( input_ids: LongTensor scores: FloatTensor ) → export const metadata = 'undefined';torch.FloatTensor of shape (batch_size, config.vocab_size)

参数

• input_ids（形状为(batch_size, sequence_length)的torch.LongTensor）— 词汇表中输入序列标记的索引。什么是输入 ID？

• scores（形状为(batch_size, config.vocab_size)的torch.FloatTensor）— 语言建模头的预测分数。当不使用波束搜索时，这些可以是每个词汇表的对数，或者在使用波束搜索时，可以是每个词汇表标记的对数 softmax

返回

torch.FloatTensor的形状为(batch_size, config.vocab_size)

处理后的预测分数。

class transformers.EncoderNoRepeatNGramLogitsProcessor

<来源>

( encoder_ngram_size: int encoder_input_ids: LongTensor )

参数

• encoder_ngram_size（int）— 所有大小为ngram_size的 ngram 只能出现在编码器输入 ID 中。

• encoder_input_ids（int）— 不应在解码器 ID 中重复的编码器输入 ID。

LogitsProcessor，其工作方式类似于 NoRepeatNGramLogitsProcessor，但专门用于防止在提示中重复出现的 n-gram。

它旨在通过阻止生成先前对话轮中存在的 n-gram 来促进语言模型中的喋喋不休。

示例：

>>> from transformers import AutoTokenizer, AutoModelForCausalLM

>>> model = AutoModelForCausalLM.from_pretrained("bigscience/bloomz-560m")
>>> tokenizer = AutoTokenizer.from_pretrained("bigscience/bloomz-560m")

>>> inputs = tokenizer("Alice: I love cats. What do you love?\nBob:", return_tensors="pt")

>>> # With greedy decoding, we see Bob repeating Alice's opinion. If Bob was a chatbot, it would be a poor one.
>>> outputs = model.generate(**inputs)
>>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True)[0])
Alice: I love cats. What do you love?
Bob: I love cats. What do you

>>> # With this logits processor, we can prevent Bob from repeating Alice's opinion.
>>> outputs = model.generate(**inputs, encoder_no_repeat_ngram_size=2)
>>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True)[0])
Alice: I love cats. What do you love?
Bob: My cats are very cute.

__call__

<来源>

( input_ids: LongTensor scores: FloatTensor ) → export const metadata = 'undefined';torch.FloatTensor of shape (batch_size, config.vocab_size)

参数

• input_ids (torch.LongTensor，形状为 (batch_size, sequence_length)) — 词汇表中输入序列标记的索引。什么是输入标识？

• scores (torch.FloatTensor，形状为 (batch_size, config.vocab_size)) — 语言建模头的预测分数。当不使用波束搜索时，这些可以是每个词汇表的对数，或者在使用波束搜索时，可以是每个词汇表标记的对数 softmax

返回

torch.FloatTensor，形状为 (batch_size, config.vocab_size)

处理后的预测分数。

class transformers.EncoderRepetitionPenaltyLogitsProcessor

< source >

( penalty: float encoder_input_ids: LongTensor )

参数

• penalty (float) — 重复惩罚的参数。1.0 表示没有惩罚。大于 1.0 奖励提示标记。在 0.0 和 1.0 之间惩罚提示标记。

• encoder_input_ids (torch.LongTensor) — 应在解码器标识中重复的编码器输入标识。

LogitsProcessor 与 RepetitionPenaltyLogitsProcessor 类似，但应用于提示中存在的标记的反向惩罚。换句话说，大于 1.0 的惩罚增加了选择提示中存在的标记的几率。

它旨在避免输入驱动任务中的幻觉，如摘要。虽然最初是为编码器-解码器模型设计的，但也可以与仅解码器模型（如 LLMs）一起使用。

示例：

>>> from transformers import AutoModelForCausalLM, AutoTokenizer

>>> tokenizer = AutoTokenizer.from_pretrained("bigscience/bloomz-560m")
>>> model = AutoModelForCausalLM.from_pretrained("bigscience/bloomz-560m")

>>> inputs = tokenizer(["Alice and Bob. The third member's name was"], return_tensors="pt")
>>> gen_out = model.generate(**inputs)
>>> print(tokenizer.batch_decode(gen_out, skip_special_tokens=True)[0])
Alice and Bob. The third member's name was not mentioned.

>>> # With the `encoder_repetition_penalty` argument we can trigger this logits processor in `generate`, which can
>>> # promote the use of prompt tokens ("Bob" in this example)
>>> gen_out = model.generate(**inputs, encoder_repetition_penalty=1.2)
>>> print(tokenizer.batch_decode(gen_out, skip_special_tokens=True)[0])
Alice and Bob. The third member's name was Bob. The third member's name was Bob.

__call__

< source >

( input_ids: LongTensor scores: FloatTensor ) → export const metadata = 'undefined';torch.FloatTensor of shape (batch_size, config.vocab_size)

参数

• input_ids (torch.LongTensor，形状为 (batch_size, sequence_length)) — 词汇表中输入序列标记的索引。什么是输入标识？

• scores (torch.FloatTensor，形状为 (batch_size, config.vocab_size)) — 语言建模头的预测分数。当不使用波束搜索时，这些可以是每个词汇表的对数，或者在使用波束搜索时，可以是每个词汇表标记的对数 softmax

返回

torch.FloatTensor，形状为 (batch_size, config.vocab_size)

处理后的预测分数。

class transformers.EpsilonLogitsWarper

< source >

( epsilon: float filter_value: float = -inf min_tokens_to_keep: int = 1 )

参数

• epsilon (float) — 如果设置为 > 0，则只保留概率大于 epsilon 的最多的标记用于生成。

• filter_value (float，可选，默认为 -inf) — 所有过滤值将设置为此浮点值。

• min_tokens_to_keep (int，可选，默认为 1) — 不能被过滤的最小标记数。

LogitsWarper 执行 epsilon-sampling，即限制到概率 prob >= epsilon 的标记。如果没有标记满足此约束，则取最大的 min_tokens_to_keep 个标记。有关更多信息，请参阅截断抽样作为语言模型去平滑。

示例：

>>> from transformers import AutoTokenizer, AutoModelForCausalLM, set_seed

>>> set_seed(0)
>>> model = AutoModelForCausalLM.from_pretrained("distilgpt2")
>>> tokenizer = AutoTokenizer.from_pretrained("distilgpt2")

>>> inputs = tokenizer("A sequence: 1, 2", return_tensors="pt")

>>> # With sampling, the output is unexpected -- sometimes too unexpected.
>>> outputs = model.generate(**inputs, do_sample=True)
>>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True)[0])
A sequence: 1, 2, 0, 2, 2. 2, 2, 2, 2

>>> # With epsilon sampling, the output gets restricted to high-probability tokens. Note that this is similar to
>>> # Top P sampling, which restricts tokens based on their cumulative probability.
>>> # Pro tip: The paper recomends using `epsilon_cutoff` values between 3e-4 and 9e-4
>>> outputs = model.generate(**inputs, do_sample=True, epsilon_cutoff=0.1)
>>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True)[0])
A sequence: 1, 2, 3, 4, 5, 6, 7, 8, 9

__call__

< source >

( input_ids: LongTensor scores: FloatTensor ) → export const metadata = 'undefined';torch.FloatTensor of shape (batch_size, config.vocab_size)

参数

• input_ids (torch.LongTensor，形状为 (batch_size, sequence_length)) — 词汇表中输入序列标记的索引。什么是输入标识？

• scores (torch.FloatTensor，形状为 (batch_size, config.vocab_size)) — 语言建模头的预测分数。当不使用波束搜索时，这些可以是每个词汇表的对数，或者在使用波束搜索时，可以是每个词汇表标记的对数 softmax

返回

torch.FloatTensor，形状为 (batch_size, config.vocab_size)

处理后的预测分数。

class transformers.EtaLogitsWarper

<来源>

( epsilon: float filter_value: float = -inf min_tokens_to_keep: int = 1 )

参数

• epsilon (float) — 在范围(0, 1)内的浮点值。用于计算动态截断值eta的超参数。根据论文，建议的值范围为 3e-4 到 4e-3，具体取决于模型的大小。

• filter_value (float，可选，默认为-inf) — 所有低于动态截断值eta的值都设置为此浮点值。当需要修改 logits 以排除生成过程中应完全排除的概率非常低的标记时，此参数很有用。

• min_tokens_to_keep (int，可选，默认为 1) — 指定必须保留的最小标记数，无论它们的概率如何。例如，如果将min_tokens_to_keep设置为 1，则始终会保留至少一个标记用于生成，即使所有标记的概率都低于截断eta。

LogitsWarper 执行 eta 采样，一种过滤掉概率低于动态截断值eta的标记的技术，该值是基于超参数epsilon和标记概率的熵的组合计算得出的，即eta := min(epsilon, sqrt(epsilon * e^-entropy(probabilities)))。如果没有标记满足此约束，则保留最大的min_tokens_to_keep个标记。它解决了由神经语言模型生成的长文本样本中存在的质量差问题，从而生成更连贯和流畅的文本。有关更多信息，请参阅截断采样作为语言模型去平滑。注意：必须将do_sample设置为True，才能使此LogitsWarper正常工作。

示例：

>>> from transformers import AutoTokenizer, AutoModelForCausalLM, set_seed

>>> set_seed(0)
>>> model = AutoModelForCausalLM.from_pretrained("distilgpt2")
>>> tokenizer = AutoTokenizer.from_pretrained("distilgpt2")

>>> inputs = tokenizer("A sequence: 1, 2", return_tensors="pt")

>>> # With sampling, the output is unexpected -- sometimes too unexpected.
>>> outputs = model.generate(**inputs, do_sample=True)
>>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True)[0])
A sequence: 1, 2, 0, 2, 2. 2, 2, 2, 2

>>> # With eta sampling, the output gets restricted to high-probability tokens. You can see it as a dynamic form of
>>> # epsilon sampling that adapts its cutoff probability based on the entropy (high entropy = lower cutoff).
>>> # Pro tip: The paper recomends using `eta_cutoff` values between 3e-4 to 4e-3
>>> outputs = model.generate(**inputs, do_sample=True, eta_cutoff=0.1)
>>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True)[0])
A sequence: 1, 2, 3, 4, 5, 6, 7, 8, 9

__call__

<来源>

( input_ids: LongTensor scores: FloatTensor ) → export const metadata = 'undefined';torch.FloatTensor of shape (batch_size, config.vocab_size)

参数

• input_ids (torch.LongTensor，形状为(batch_size, sequence_length)) — 词汇表中输入序列标记的索引。什么是输入 ID？

• scores (torch.FloatTensor，形状为(batch_size, config.vocab_size)) — 语言建模头的预测分数。当不使用波束搜索时，这些可以是每个词汇的 logits，或者在使用波束搜索时，可以是每个词汇标记的 log softmax

返回

形状为(batch_size, config.vocab_size)的torch.FloatTensor

处理后的预测分数。

class transformers.ExponentialDecayLengthPenalty

<来源>

( exponential_decay_length_penalty: Tuple eos_token_id: Union input_ids_seq_length: int )

参数

• exponential_decay_length_penalty (tuple(int, float)) — 此元组应包含：(start_index, decay_factor)，其中start_index表示惩罚开始的位置，decay_factor表示指数衰减的因子

• eos_token_id (Union[int, List[int]]) — 序列结束标记的 ID。可选择使用列表设置多个序列结束标记。

• input_ids_seq_length (int) — 输入序列的长度。

LogitsProcessor 在达到start_index后指数增加eos_token_id的分数。这允许生成较短的序列而不会有硬性截断，从而使eos_token能够在有意义的位置被预测。

示例：

>>> from transformers import AutoTokenizer, AutoModelForCausalLM, set_seed

>>> model = AutoModelForCausalLM.from_pretrained("gpt2")
>>> tokenizer = AutoTokenizer.from_pretrained("gpt2")

>>> text = "Just wanted to let you know, I"
>>> inputs = tokenizer(text, return_tensors="pt")

>>> # Let's consider that we want short sentences, so we limit `max_length=30`. However, we observe that the answer
>>> # tends to end abruptly.
>>> set_seed(1)
>>> outputs = model.generate(**inputs, do_sample=True, temperature=0.9, max_length=30, pad_token_id=50256)
>>> print(tokenizer.batch_decode(outputs)[0])
Just wanted to let you know, I received a link to an ebook, the book How To Start A Social Network which was
published in 2010. Although

>>> # To promote the appearance of the EOS token at the right time, we add the `exponential_decay_length_penalty =
>>> # (start_index, decay_factor)`. Instead of cutting at max_tokens, the output comes to an end before and usually
>>> # with more meaning. What happens is that starting from `start_index` the EOS token score will be increased
>>> # by `decay_factor` exponentially. However, if you set a high decay factor, you may also end up with abruptly
>>> # ending sequences.
>>> set_seed(1)
>>> outputs = model.generate(
...     **inputs,
...     do_sample=True,
...     temperature=0.9,
...     max_length=30,
...     pad_token_id=50256,
...     exponential_decay_length_penalty=(15, 1.6),
... )
>>> print(tokenizer.batch_decode(outputs)[0])
Just wanted to let you know, I received a link to an ebook, the book How To Start A Social Network
which<|endoftext|>

>>> # With a small decay factor, you will have a higher chance of getting a meaningful sequence.
>>> set_seed(1)
>>> outputs = model.generate(
...     **inputs,
...     do_sample=True,
...     temperature=0.9,
...     max_length=30,
...     pad_token_id=50256,
...     exponential_decay_length_penalty=(15, 1.01),
... )
>>> print(tokenizer.batch_decode(outputs)[0])
Just wanted to let you know, I received a link to an ebook, the book How To Start A Social Network which was
published in 2010.<|endoftext|>

__call__

<来源>

( input_ids: LongTensor scores: FloatTensor ) → export const metadata = 'undefined';torch.FloatTensor of shape (batch_size, config.vocab_size)

参数

• input_ids (torch.LongTensor，形状为(batch_size, sequence_length)) — 词汇表中输入序列标记的索引。什么是输入 ID？

• scores (torch.FloatTensor，形状为(batch_size, config.vocab_size)) — 语言建模头的预测分数。当不使用波束搜索时，这些可以是每个词汇的 logits，或者在使用波束搜索时，可以是每个词汇标记的 log softmax。

返回

torch.FloatTensor，形状为(batch_size, config.vocab_size)

处理后的预测分数。

class transformers.ForcedBOSTokenLogitsProcessor

< source >

( bos_token_id: int )

参数

• bos_token_id (int) — 强制作为第一个生成的标记的标记 ID。

LogitsProcessor 会强制指定的标记作为第一个生成的标记。与编码器-解码器模型一起使用。

示例：

>>> from transformers import AutoTokenizer, AutoModelForSeq2SeqLM

>>> model = AutoModelForSeq2SeqLM.from_pretrained("google/flan-t5-small")
>>> tokenizer = AutoTokenizer.from_pretrained("google/flan-t5-small")

>>> inputs = tokenizer("Translate from English to German: I love cats.", return_tensors="pt")

>>> # By default, it continues generating according to the model's logits
>>> outputs = model.generate(**inputs, max_new_tokens=10)
>>> print(tokenizer.batch_decode(outputs)[0])
<pad> Ich liebe Kitty.</s>

>>> # We can use `forced_bos_token_id` to force the start of generation with an encoder-decoder model
>>> # (including forcing it to end straight away with an EOS token)
>>> outputs = model.generate(**inputs, max_new_tokens=10, forced_bos_token_id=tokenizer.eos_token_id)
>>> print(tokenizer.batch_decode(outputs)[0])
<pad></s>

__call__

< source >

( input_ids: LongTensor scores: FloatTensor ) → export const metadata = 'undefined';torch.FloatTensor of shape (batch_size, config.vocab_size)

参数

• input_ids (torch.LongTensor，形状为(batch_size, sequence_length)) — 输入序列标记在词汇表中的索引。什么是输入 ID？

• scores (torch.FloatTensor，形状为(batch_size, config.vocab_size)) — 语言建模头的预测分数。当不使用波束搜索时，这些可以是每个词汇的 logits，或者在使用波束搜索时，可以是每个词汇标记的 log softmax。

返回

torch.FloatTensor，形状为(batch_size, config.vocab_size)

处理后的预测分数。

class transformers.ForcedEOSTokenLogitsProcessor

< source >

( max_length: int eos_token_id: Union )

参数

• max_length (int) — 要生成的序列的最大长度。

• eos_token_id (Union[int, List[int]]) — 当达到max_length时，强制指定的标记作为最后生成的标记。可选择使用列表设置多个序列结束标记。

LogitsProcessor 会在达到max_length时强制指定的标记作为最后生成的标记。

示例：

>>> from transformers import AutoTokenizer, AutoModelForCausalLM

>>> model = AutoModelForCausalLM.from_pretrained("distilgpt2")
>>> tokenizer = AutoTokenizer.from_pretrained("distilgpt2")

>>> inputs = tokenizer("A sequence: 1, 2, 3", return_tensors="pt")

>>> # By default, it continues generating according to the model's logits
>>> outputs = model.generate(**inputs, max_new_tokens=10)
>>> print(tokenizer.batch_decode(outputs)[0])
A sequence: 1, 2, 3, 4, 5, 6, 7, 8

>>> # `forced_eos_token_id` ensures the generation ends with a EOS token
>>> outputs = model.generate(**inputs, max_new_tokens=10, forced_eos_token_id=tokenizer.eos_token_id)
>>> print(tokenizer.batch_decode(outputs)[0])
A sequence: 1, 2, 3, 4, 5, 6, 7,<|endoftext|>

__call__

< source >

( input_ids: LongTensor scores: FloatTensor ) → export const metadata = 'undefined';torch.FloatTensor of shape (batch_size, config.vocab_size)

参数

• input_ids (torch.LongTensor，形状为(batch_size, sequence_length)) — 输入序列标记在词汇表中的索引。什么是输入 ID？

• scores (torch.FloatTensor，形状为(batch_size, config.vocab_size)) — 语言建模头的预测分数。当不使用波束搜索时，这些可以是每个词汇的 logits，或者在使用波束搜索时，可以是每个词汇标记的 log softmax。

返回

torch.FloatTensor，形状为(batch_size, config.vocab_size)

处理后的预测分数。

class transformers.ForceTokensLogitsProcessor

< source >

( force_token_map: List )

这个处理器接受一对整数的列表，指示从生成索引到强制生成之前的标记索引的映射。处理器将它们的 log 概率设置为inf，以便在相应的索引处对它们进行采样。最初为Whisper创建。

示例：

>>> from transformers import AutoProcessor, WhisperForConditionalGeneration
>>> from datasets import load_dataset

>>> processor = AutoProcessor.from_pretrained("openai/whisper-tiny.en")
>>> model = WhisperForConditionalGeneration.from_pretrained("openai/whisper-tiny.en")
>>> ds = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")
>>> inputs = processor(ds[0]["audio"]["array"], return_tensors="pt")

>>> # This Whisper model forces the generation to start with `50362` at the first position by default, i.e.
>>> # `"forced_decoder_ids": [[1, 50362]]`. This means all other tokens are masked out.
>>> outputs = model.generate(**inputs, return_dict_in_generate=True, output_scores=True)
>>> print(
...     all(outputs.scores[0][0, i] == float("-inf") for i in range(processor.tokenizer.vocab_size) if i != 50362)
... )
True
>>> print(outputs.scores[0][0, 50362])
tensor(0.)

>>> # If we disable `forced_decoder_ids`, we stop seeing that effect
>>> outputs = model.generate(**inputs, return_dict_in_generate=True, output_scores=True, forced_decoder_ids=None)
>>> print(
...     all(outputs.scores[0][0, i] == float("-inf") for i in range(processor.tokenizer.vocab_size) if i != 50362)
... )
False
>>> print(outputs.scores[0][0, 50362])
tensor(19.3140)

__call__

< source >

( input_ids: LongTensor scores: FloatTensor ) → export const metadata = 'undefined';torch.FloatTensor of shape (batch_size, config.vocab_size)

参数

• input_ids (torch.LongTensor，形状为(batch_size, sequence_length)) — 输入序列标记在词汇表中的索引。什么是输入 ID？

• scores (torch.FloatTensor，形状为(batch_size, config.vocab_size)) — 语言建模头的预测分数。当不使用波束搜索时，这些可以是每个词汇的 logits，或者在使用波束搜索时，可以是每个词汇标记的 log softmax。

返回

形状为 (batch_size, config.vocab_size) 的 torch.FloatTensor

处理后的预测分数。

class transformers.HammingDiversityLogitsProcessor

<来源>

( diversity_penalty: float num_beams: int num_beam_groups: int )

参数

• diversity_penalty (float) — 如果一个 beam 在特定时间生成与其他组中的任何 beam 相同的标记，则从该 beam 的分数中减去此值。较高的 diversity_penalty 将强制在 beam 之间实现更大的多样性。调整此值可以帮助在多样性和自然可能性之间取得平衡。

• num_beams (int) — beam 搜索的数量。1 表示没有 beam 搜索。

• num_beam_groups (int) — 将 num_beams 分成多少组，以确保不同组的 beam 之间的多样性。此论文 了解更多细节。

LogitsProcessor 用于强制进行多样性 beam 搜索。

请注意，此 logits 处理器仅对 PreTrainedModel.group_beam_search() 有效。有关更多细节，请参阅 Diverse Beam Search: Decoding Diverse Solutions from Neural Sequence Models。

传统的 beam 搜索经常在不同 beam 之间生成非常相似的序列。HammingDiversityLogitsProcessor 通过惩罚在同一时间步生成已被其他 beam 选择的标记的 beam 来解决这个问题。

示例:

>>> from transformers import AutoTokenizer, AutoModelForSeq2SeqLM
>>> import torch

>>> # Initialize the model and tokenizer
>>> tokenizer = AutoTokenizer.from_pretrained("t5-base")
>>> model = AutoModelForSeq2SeqLM.from_pretrained("t5-base")

>>> # A long text about the solar system
>>> text = (
...     "The Solar System is a gravitationally bound system comprising the Sun and the objects that orbit it, "
...     "either directly or indirectly. Of the objects that orbit the Sun directly, the largest are the eight "
...     "planets, with the remainder being smaller objects, such as the five dwarf planets and small Solar System "
...     "bodies. The Solar System formed 4.6 billion years ago from the gravitational collapse of a giant "
...     "interstellar molecular cloud."
... )
>>> inputs = tokenizer("summarize: " + text, return_tensors="pt")

>>> # Generate diverse summary
>>> outputs_diverse = model.generate(
...     **inputs,
...     num_beam_groups=2,
...     diversity_penalty=10.0,
...     max_length=100,
...     num_beams=4,
...     num_return_sequences=2,
... )
>>> summaries_diverse = tokenizer.batch_decode(outputs_diverse, skip_special_tokens=True)

>>> # Generate non-diverse summary
>>> outputs_non_diverse = model.generate(
...     **inputs,
...     max_length=100,
...     num_beams=4,
...     num_return_sequences=2,
... )
>>> summary_non_diverse = tokenizer.batch_decode(outputs_non_diverse, skip_special_tokens=True)

>>> # With `diversity_penalty`, the resulting beams are much more diverse
>>> print(summary_non_diverse)
['the solar system formed 4.6 billion years ago from the collapse of a giant interstellar molecular cloud. of the objects that orbit the Sun directly, the largest are the eight planets.',
'the Solar System formed 4.6 billion years ago from the collapse of a giant interstellar molecular cloud. of the objects that orbit the Sun directly, the largest are the eight planets.']

>>> print(summaries_diverse)
['the solar system formed 4.6 billion years ago from the collapse of a giant interstellar molecular cloud. of the objects that orbit the Sun directly, the largest are the eight planets.',
'the solar system formed 4.6 billion years ago from the collapse of a giant interstellar molecular cloud. of the objects that orbit the Sun directly, the largest are the eight planets. the rest of the objects are smaller objects, such as the five dwarf planets and small solar system bodies.']

__call__

<来源>

( input_ids: LongTensor scores: FloatTensor current_tokens: LongTensor beam_group_idx: int ) → export const metadata = 'undefined';torch.FloatTensor of shape (batch_size, config.vocab_size)

参数

• input_ids (torch.LongTensor，形状为 (batch_size, sequence_length)) — 输入序列标记在词汇表中的索引。什么是输入 ID？

• scores (torch.FloatTensor，形状为 (batch_size, config.vocab_size)) — 语言建模头的预测分数。当不使用 beam 搜索时，这些可以是每个词汇表的 logits，或者在使用 beam 搜索时，可以是每个词汇表标记的 log softmax

• current_tokens (torch.LongTensor，形状为 (batch_size)) — 输入序列标记在词汇表中的索引，对应于当前生成步骤中其他 beam 组选择的标记。

• beam_group_idx (int) — 当前正在处理的 beam 组的索引。

返回

形状为 (batch_size, config.vocab_size) 的 torch.FloatTensor

处理后的预测分数。

class transformers.InfNanRemoveLogitsProcessor

<来源>

( )

LogitsProcessor 用于移除所有的 nan 和 inf 值，以避免生成方法失败。请注意，只有在必要时才应该使用 logits 处理器，因为它可能会减慢生成方法的速度。

这个 logits 处理器没有 generate 示例，因为不应该有正确的标志组合来保证其使用。

__call__

<来源>

( input_ids: LongTensor scores: FloatTensor ) → export const metadata = 'undefined';torch.FloatTensor of shape (batch_size, config.vocab_size)

参数

• input_ids (torch.LongTensor，形状为 (batch_size, sequence_length)) — 输入序列标记在词汇表中的索引。什么是输入 ID？

• scores (torch.FloatTensor，形状为 (batch_size, config.vocab_size)) — 语言建模头的预测分数。当不使用 beam 搜索时，这些可以是每个词汇表的 logits，或者在使用 beam 搜索时，可以是每个词汇表标记的 log softmax

返回值

形状为 (batch_size, config.vocab_size) 的 torch.FloatTensor

处理后的预测分数。

class transformers.LogitNormalization

<来源>

( )

LogitsWarper 和 LogitsProcessor 用于使用 log-softmax 对分数进行归一化。在应用 logits 处理器或 warper 后，在波束搜索期间对分数进行归一化是很重要的，因为此库中使用的搜索算法不会这样做（它只在之前这样做，但它们可能需要重新归一化），但它仍然假设在比较假设时分数已经归一化。

示例：

>>> from transformers import AutoTokenizer, AutoModelForCausalLM
>>> import torch

>>> model = AutoModelForCausalLM.from_pretrained("distilgpt2")
>>> tokenizer = AutoTokenizer.from_pretrained("distilgpt2")

>>> inputs = tokenizer("A sequence: 1, 2, 3", return_tensors="pt")

>>> # By default, the scores are not normalized -- the sum of their exponentials is NOT a normalized probability
>>> # distribution, summing to 1
>>> outputs = model.generate(**inputs, return_dict_in_generate=True, output_scores=True)
>>> print(torch.sum(torch.exp(outputs.scores[-1])))
tensor(816.3250)

>>> # Normalizing them may have a positive impact on beam methods, or when using the scores on your application
>>> outputs = model.generate(**inputs, renormalize_logits=True, return_dict_in_generate=True, output_scores=True)
>>> print(torch.sum(torch.exp(outputs.scores[-1])))
tensor(1.0000)

__call__

<来源>

( input_ids: LongTensor scores: FloatTensor ) → export const metadata = 'undefined';torch.FloatTensor of shape (batch_size, config.vocab_size)

参数

• input_ids (torch.LongTensor，形状为(batch_size, sequence_length)) — 输入序列标记在词汇表中的索引。什么是输入 ID？

• scores (torch.FloatTensor，形状为(batch_size, config.vocab_size)) — 语言建模头的预测分数。当不使用波束搜索时，这些可以是每个词汇的 logits，或者在使用波束搜索时，可以是每个词汇标记的 log softmax。

返回

torch.FloatTensor，形状为(batch_size, config.vocab_size)

处理后的预测分数。

class transformers.LogitsProcessor

<来源>

( )

所有在生成过程中可以应用的 logit 处理器的抽象基类。

__call__

<来源>

( input_ids: LongTensor scores: FloatTensor ) → export const metadata = 'undefined';torch.FloatTensor of shape (batch_size, config.vocab_size)

参数

• input_ids (torch.LongTensor，形状为(batch_size, sequence_length)) — 输入序列标记在词汇表中的索引。什么是输入 ID？

• scores (torch.FloatTensor，形状为(batch_size, config.vocab_size)) — 语言建模头的预测分数。当不使用波束搜索时，这些可以是每个词汇的 logits，或者在使用波束搜索时，可以是每个词汇标记的 log softmax。

返回

torch.FloatTensor，形状为(batch_size, config.vocab_size)

处理后的预测分数。

class transformers.LogitsProcessorList

<来源>

( iterable = () )

这个类可以用来创建一个 LogitsProcessor 或 LogitsWarper 列表，以后处理scores输入张量。这个类继承自列表，并添加了一个特定的call方法来应用每个 LogitsProcessor 或 LogitsWarper 到输入中。

__call__

<来源>

( input_ids: LongTensor scores: FloatTensor **kwargs ) → export const metadata = 'undefined';torch.FloatTensor of shape (batch_size, config.vocab_size)

参数

• input_ids (torch.LongTensor，形状为(batch_size, sequence_length)) — 输入序列标记在词汇表中的索引。什么是输入 ID？

• scores (torch.FloatTensor，形状为(batch_size, config.vocab_size)) — 语言建模头的预测分数。当不使用波束搜索时，这些可以是每个词汇的 logits，或者在使用波束搜索时，可以是每个词汇标记的 log softmax

• kwargs (Dict[str, Any]，可选) — 特定于 logits 处理器的其他 kwargs。

返回

torch.FloatTensor，形状为(batch_size, config.vocab_size)

处理后的预测分数。

class transformers.LogitsWarper

<来源>

( )

所有可以在使用多项式采样进行生成时应用的对数变换器的抽象基类。

__call__

<来源>

( input_ids: LongTensor scores: FloatTensor ) → export const metadata = 'undefined';torch.FloatTensor of shape (batch_size, config.vocab_size)

参数

• input_ids（形状为(batch_size, sequence_length)的torch.LongTensor）— 词汇表中输入序列标记的索引。什么是输入 ID？

• scores（形状为(batch_size, config.vocab_size)的torch.FloatTensor）— 语言建模头的预测分数。当不使用波束搜索时，这些可以是每个词汇表的对数，或者在使用波束搜索时，可以是每个词汇表标记的对数 softmax

返回

形状为(batch_size, config.vocab_size)的torch.FloatTensor

处理后的预测分数。

class transformers.MinLengthLogitsProcessor

<来源>

( min_length: int eos_token_id: Union )

参数

• min_length（int）— 小于此长度时，eos_token_id的分数将设置为-float("Inf")。

• eos_token_id（Union[int, List[int]]）— end-of-sequence标记的 ID。可选地，使用列表设置多个end-of-sequence标记。

LogitsProcessor 通过将 EOS 概率设置为 0 来强制最小长度。请注意，对于像大多数 LLMs 这样的仅解码器模型，长度包括提示。

示例：

>>> from transformers import AutoModelForCausalLM, AutoTokenizer

>>> tokenizer = AutoTokenizer.from_pretrained("bigscience/bloomz-560m")
>>> model = AutoModelForCausalLM.from_pretrained("bigscience/bloomz-560m")

>>> inputs = tokenizer("A number:", return_tensors="pt")
>>> gen_out = model.generate(**inputs)
>>> print(tokenizer.batch_decode(gen_out, skip_special_tokens=True)[0])
A number: one

>>> # setting `min_length` to a value smaller than the uncontrolled output length has no impact
>>> gen_out = model.generate(**inputs, min_length=3)
>>> print(tokenizer.batch_decode(gen_out, skip_special_tokens=True)[0])
A number: one

>>> # setting a larger `min_length` will force the model to generate beyond its natural ending point, which is not
>>> # necessarily incorrect
>>> gen_out = model.generate(**inputs, min_length=10)
>>> print(tokenizer.batch_decode(gen_out, skip_special_tokens=True)[0])
A number: one thousand, nine hundred and ninety-four

__call__

<来源>

( input_ids: LongTensor scores: FloatTensor ) → export const metadata = 'undefined';torch.FloatTensor of shape (batch_size, config.vocab_size)

参数

• input_ids（形状为(batch_size, sequence_length)的torch.LongTensor）— 词汇表中输入序列标记的索引。什么是输入 ID？

• scores（形状为(batch_size, config.vocab_size)的torch.FloatTensor）— 语言建模头的预测分数。当不使用波束搜索时，这些可以是每个词汇表的对数，或者在使用波束搜索时，可以是每个词汇表标记的对数 softmax

返回

形状为(batch_size, config.vocab_size)的torch.FloatTensor

处理后的预测分数。

class transformers.MinNewTokensLengthLogitsProcessor

<来源>

( prompt_length_to_skip: int min_new_tokens: int eos_token_id: Union )

参数

• prompt_length_to_skip（int）— 输入标记的长度。当与generate一起使用时，这不是一个有效的参数，因为它会自动分配输入长度。

• min_new_tokens（int）— 小于此长度时，eos_token_id的分数将设置为-float("Inf")。

• eos_token_id（Union[int, List[int]]）— end-of-sequence标记的 ID。可选地，使用列表设置多个end-of-sequence标记。

LogitsProcessor 通过将 EOS（序列结束）标记的概率设置为 0 来强制新标记的最小长度。与 MinLengthLogitsProcessor 相反，此处理器忽略提示。

示例：

>>> from transformers import AutoModelForCausalLM, AutoTokenizer

>>> tokenizer = AutoTokenizer.from_pretrained("bigscience/bloomz-560m")
>>> model = AutoModelForCausalLM.from_pretrained("bigscience/bloomz-560m")

>>> inputs = tokenizer(["A number:"], return_tensors="pt")
>>> gen_out = model.generate(**inputs)
>>> print(tokenizer.batch_decode(gen_out, skip_special_tokens=True)[0])
A number: one

>>> # setting `min_new_tokens` will force the model to generate beyond its natural ending point, which is not
>>> # necessarily incorrect
>>> gen_out = model.generate(**inputs, min_new_tokens=2)
>>> print(tokenizer.batch_decode(gen_out, skip_special_tokens=True)[0])
A number: one thousand

__call__

<来源>

( input_ids: LongTensor scores: FloatTensor ) → export const metadata = 'undefined';torch.FloatTensor of shape (batch_size, config.vocab_size)

参数

• input_ids（形状为(batch_size, sequence_length)的torch.LongTensor）— 词汇表中输入序列标记的索引。什么是输入 ID？

• scores（形状为(batch_size, config.vocab_size)的torch.FloatTensor）— 语言建模头的预测分数。当不使用波束搜索时，这些可以是每个词汇表的对数，或者在使用波束搜索时，可以是每个词汇表标记的对数 softmax

返回

形状为(batch_size, config.vocab_size)的torch.FloatTensor

处理后的预测分数。

class transformers.NoBadWordsLogitsProcessor

<来源>

( bad_words_ids: List eos_token_id: Union )

参数

• bad_words_ids (List[List[int]]) — 不允许生成的标记 ID 列表。

• eos_token_id (Union[int, List[int]]) — 结束序列标记的 ID。可选地，使用列表设置多个结束序列标记。

LogitsProcessor，强制指定的序列永远不会被选中。

为了获取不应出现在生成文本中的单词的标记 ID，请确保在初始化分词器时设置add_prefix_space=True，并使用tokenizer(bad_words, add_special_tokens=False).input_ids。add_prefix_space参数仅支持一些慢速分词器，因为快速分词器的前缀行为来自pre tokenizers。在这里阅读更多信息(https://huggingface.co/docs/tokenizers/api/pre-tokenizers)。

示例：

>>> from transformers import AutoTokenizer, AutoModelForCausalLM

>>> model = AutoModelForCausalLM.from_pretrained("gpt2")
>>> tokenizer = AutoTokenizer.from_pretrained("gpt2")
>>> inputs = tokenizer(["In a word, the cake is a"], return_tensors="pt")

>>> output_ids = model.generate(inputs["input_ids"], max_new_tokens=5, pad_token_id=tokenizer.eos_token_id)
>>> print(tokenizer.batch_decode(output_ids, skip_special_tokens=True)[0])
In a word, the cake is a bit of a mess.

>>> # Now let's take the bad words out. Please note that the tokenizer is initialized differently
>>> tokenizer_with_prefix_space = AutoTokenizer.from_pretrained("gpt2", add_prefix_space=True)

>>> def get_tokens_as_list(word_list):
...     "Converts a sequence of words into a list of tokens"
...     tokens_list = []
...     for word in word_list:
...         tokenized_word = tokenizer_with_prefix_space([word], add_special_tokens=False).input_ids[0]
...         tokens_list.append(tokenized_word)
...     return tokens_list

>>> bad_words_ids = get_tokens_as_list(word_list=["mess"])
>>> output_ids = model.generate(
...     inputs["input_ids"], max_new_tokens=5, bad_words_ids=bad_words_ids, pad_token_id=tokenizer.eos_token_id
... )
>>> print(tokenizer.batch_decode(output_ids, skip_special_tokens=True)[0])
In a word, the cake is a bit of a surprise.

__call__

<来源>

( input_ids: LongTensor scores: FloatTensor ) → export const metadata = 'undefined';torch.FloatTensor of shape (batch_size, config.vocab_size)

参数

• input_ids (torch.LongTensor of shape (batch_size, sequence_length)) — 词汇表中输入序列标记的索引。什么是输入 ID？

• scores (torch.FloatTensor of shape (batch_size, config.vocab_size)) — 语言建模头的预测分数。当不使用波束搜索时，这些可以是每个词汇表的 logits，或者在使用波束搜索时，可以是每个词汇表标记的 log softmax

返回

torch.FloatTensor of shape (batch_size, config.vocab_size)

处理后的预测分数。

class transformers.NoRepeatNGramLogitsProcessor

<来源>

( ngram_size: int )

参数

• ngram_size (int) — 所有大小为ngram_size的 ngrams 只能出现一次。

N-grams 是从文本序列中获取的“n”个连续单词、字符或标记的组合。给定句子：“她跑得快”，二元组（n=2）将是（“她”，“跑”）和（“跑”，“快”）。在文本生成中，避免单词序列的重复提供了更多样化的输出。这个 LogitsProcessor 通过将被禁止的标记的分数设置为负无穷来强制不重复 n-grams，从而消除了这些标记在进一步处理分数时的考虑。请注意，对于大多数仅解码器模型（如大多数 LLMs），提示也被视为获取 n-grams。Fairseq。

谨慎使用 n-gram 惩罚。例如，在关于纽约市的文章中惩罚 2-gram（二元组）可能导致不良结果，其中城市的名称仅出现一次在整个文本中。参考

示例：

>>> from transformers import AutoTokenizer, AutoModelForCausalLM

>>> model = AutoModelForCausalLM.from_pretrained("distilgpt2")
>>> tokenizer = AutoTokenizer.from_pretrained("distilgpt2")
>>> inputs = tokenizer(["Today I"], return_tensors="pt")

>>> output = model.generate(**inputs)
>>> print(tokenizer.decode(output[0], skip_special_tokens=True))
Today I’m not sure if I’m going to be able to do it.

>>> # Now let's add ngram size using `no_repeat_ngram_size`. This stops the repetitions ("I’m") in the output.
>>> output = model.generate(**inputs, no_repeat_ngram_size=2)
>>> print(tokenizer.decode(output[0], skip_special_tokens=True))
Today I’m not sure if I can get a better understanding of the nature of this issue

__call__

<来源>

( input_ids: LongTensor scores: FloatTensor ) → export const metadata = 'undefined';torch.FloatTensor of shape (batch_size, config.vocab_size)

参数

• input_ids (torch.LongTensor of shape (batch_size, sequence_length)) — 词汇表中输入序列标记的索引。什么是输入 ID？

• scores (torch.FloatTensor of shape (batch_size, config.vocab_size)) — 语言建模头的预测分数。当不使用波束搜索时，这些可以是每个词汇表的 logits，或者在使用波束搜索时，可以是每个词汇表标记的 log softmax

返回

torch.FloatTensor of shape (batch_size, config.vocab_size)

处理后的预测分数。

class transformers.PrefixConstrainedLogitsProcessor

<来源>

( prefix_allowed_tokens_fn: Callable num_beams: int )

参数

• prefix_allowed_tokens_fn (Callable[[int, torch.Tensor], List[int]]) — 此函数将波束搜索限制为每个步骤仅允许的标记。此函数接受 2 个参数inputs_ids和批次 IDbatch_id。它必须返回一个列表，其中包含下一代步骤的允许标记，条件是先前生成的标记inputs_ids和批次 IDbatch_id。

LogitsProcessor 强制执行受限制的生成，对于前缀条件的受限制生成很有用。有关更多信息，请参阅自回归实体检索。

示例：

>>> from transformers import AutoTokenizer, AutoModelForCausalLM

>>> model = AutoModelForCausalLM.from_pretrained("bigscience/bloomz-560m")
>>> tokenizer = AutoTokenizer.from_pretrained("bigscience/bloomz-560m")

>>> inputs = tokenizer("Alice and Bob", return_tensors="pt")

>>> # By default, it continues generating according to the model's logits
>>> outputs = model.generate(**inputs, max_new_tokens=5)
>>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True)[0])
Alice and Bob are friends

>>> # We can contrain it with `prefix_allowed_tokens_fn` to force a certain behavior based on a prefix.
>>> # For instance, we can force an entire entity to be generated when its beginning is detected.
>>> entity =  tokenizer(" Bob Marley", return_tensors="pt").input_ids[0]  # 3 tokens
>>> def prefix_allowed_tokens_fn(batch_id, input_ids):
...     '''
...     Attempts to generate 'Bob Marley' when 'Bob' is detected.
...     In this case, `batch_id` is not used, but you can set rules for each batch member.
...     '''
...     if input_ids[-1] == entity[0]:
...         return entity[1]
...     elif input_ids[-2] == entity[0] and input_ids[-1] == entity[1]:
...         return entity[2]
...     return list(range(tokenizer.vocab_size))  # If no match, allow all tokens

>>> outputs = model.generate(**inputs, max_new_tokens=5, prefix_allowed_tokens_fn=prefix_allowed_tokens_fn)
>>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True)[0])
Alice and Bob Marley

__call__

<来源>

( input_ids: LongTensor scores: FloatTensor ) → export const metadata = 'undefined';torch.FloatTensor of shape (batch_size, config.vocab_size)

参数

• input_ids (torch.LongTensor，形状为(batch_size, sequence_length)) — 词汇表中输入序列标记的索引。什么是输入 ID？

• scores (torch.FloatTensor，形状为(batch_size, config.vocab_size)) — 语言建模头的预测分数。当不使用波束搜索时，这些可以是每个词汇的 logits，或者在使用波束搜索时，可以是每个词汇标记的 log softmax。

返回值

torch.FloatTensor，形状为(batch_size, config.vocab_size)

处理后的预测分数。

class transformers.RepetitionPenaltyLogitsProcessor

<来源>

( penalty: float )

参数

• penalty (float) — 重复惩罚的参数。1.0 表示没有惩罚。大于 1.0 会惩罚先前生成的标记。在 0.0 和 1.0 之间会奖励先前生成的标记。

LogitsProcessor 通过惩罚防止先前标记的重复。此惩罚最多每个标记应用一次。请注意，对于大多数仅解码器模型（如大多数 LLMs），考虑的标记包括提示。

在原始论文中，作者建议使用约 1.2 的惩罚来实现真实生成和减少重复之间的良好平衡。为了惩罚和减少重复，使用大于 1.0 的penalty值，其中较高的值会更强烈地惩罚。为了奖励和鼓励重复，使用 0.0 和 1.0 之间的penalty值，较低的值会更强烈地奖励。

示例：

>>> from transformers import AutoTokenizer, AutoModelForCausalLM

>>> # Initializing the model and tokenizer for it
>>> model = AutoModelForCausalLM.from_pretrained("distilgpt2")
>>> tokenizer = AutoTokenizer.from_pretrained("distilgpt2")
>>> inputs = tokenizer(["I'm not going to"], return_tensors="pt")

>>> # This shows a normal generate without any specific parameters
>>> summary_ids = model.generate(**inputs)
>>> print(tokenizer.batch_decode(summary_ids, skip_special_tokens=True)[0])
I'm not going to be able to do that. I'm going to be able to do that

>>> # This generates a penalty for repeated tokens
>>> penalized_ids = model.generate(**inputs, repetition_penalty=1.1)
>>> print(tokenizer.batch_decode(penalized_ids, skip_special_tokens=True)[0])
I'm not going to be able to do that. I'll just have to go out and play

__call__

<来源>

( input_ids: LongTensor scores: FloatTensor ) → export const metadata = 'undefined';torch.FloatTensor of shape (batch_size, config.vocab_size)

参数

• input_ids (torch.LongTensor，形状为(batch_size, sequence_length)) — 词汇表中输入序列标记的索引。什么是输入 ID？

• scores (torch.FloatTensor，形状为(batch_size, config.vocab_size)) — 语言建模头的预测分数。当不使用波束搜索时，这些可以是每个词汇的 logits，或者在使用波束搜索时，可以是每个词汇标记的 log softmax。

返回值

torch.FloatTensor，形状为(batch_size, config.vocab_size)

处理后的预测分数。

class transformers.SequenceBiasLogitsProcessor

<来源>

( sequence_bias: Dict )

参数

• sequence_bias (Dict[Tuple[int], float]) — 将标记序列映射到其偏差项的字典。正偏差增加选择该序列的几率，而负偏差则相反。如果序列长度为 1，则其偏差将始终应用。否则，仅当所讨论的序列即将完成时（在应用此处理器后的标记选择步骤中）才会应用偏差。

LogitsProcessor 应用于序列的附加偏置。当下一个生成的标记可以完成序列时，将偏置应用于序列的最后一个标记。因此，为了充分利用对具有多个标记的序列进行偏置，考虑使用波束方法（以优雅地解决部分完成的序列具有负偏差的问题）并将偏置应用于它们的前缀（以确保较早地应用偏置）。

为了获取您想要偏置的序列的标记 ID，请确保在初始化分词器时设置add_prefix_space=True，并使用tokenizer(bad_words, add_special_tokens=False).input_ids。add_prefix_space参数仅支持一些慢速分词器，因为快速分词器的前缀行为来自pre tokenizers。在这里阅读更多。

示例：

>>> from transformers import AutoTokenizer, AutoModelForCausalLM

>>> model = AutoModelForCausalLM.from_pretrained("gpt2")
>>> tokenizer = AutoTokenizer.from_pretrained("gpt2")
>>> inputs = tokenizer(["The full name of Donald is Donald"], return_tensors="pt")

>>> summary_ids = model.generate(inputs["input_ids"], max_new_tokens=4)
>>> print(tokenizer.batch_decode(summary_ids, skip_special_tokens=True)[0])
The full name of Donald is Donald J. Trump Jr

>>> # Now let's control generation through a bias. Please note that the tokenizer is initialized differently!
>>> tokenizer_with_prefix_space = AutoTokenizer.from_pretrained("gpt2", add_prefix_space=True)

>>> def get_tokens_as_tuple(word):
...     return tuple(tokenizer_with_prefix_space([word], add_special_tokens=False).input_ids[0])

>>> # If we add a negative bias without beam search, it may become "stuck" in a prefix without good continuations
>>> sequence_bias = {get_tokens_as_tuple("Trump"): -10.0}
>>> biased_ids = model.generate(inputs["input_ids"], max_new_tokens=4, sequence_bias=sequence_bias)
>>> print(tokenizer.batch_decode(biased_ids, skip_special_tokens=True)[0])
The full name of Donald is Donald J. Donald,

>>> biased_ids = model.generate(inputs["input_ids"], max_new_tokens=4, num_beams=4, sequence_bias=sequence_bias)
>>> print(tokenizer.batch_decode(biased_ids, skip_special_tokens=True)[0])
The full name of Donald is Donald Rumsfeld,

>>> # We can also add a positive bias to nudge the model towards specific tokens or continuations
>>> sequence_bias = {get_tokens_as_tuple("Donald Duck"): 10.0}
>>> biased_ids = model.generate(inputs["input_ids"], max_new_tokens=4, num_beams=4, sequence_bias=sequence_bias)
>>> print(tokenizer.batch_decode(biased_ids, skip_special_tokens=True)[0])
The full name of Donald is Donald Duck.

__call__

<来源>

( input_ids: LongTensor scores: FloatTensor ) → export const metadata = 'undefined';torch.FloatTensor of shape (batch_size, config.vocab_size)

参数

• input_ids (torch.LongTensor，形状为(batch_size, sequence_length)) — 词汇表中输入序列标记的索引。什么是输入 ID？

• scores (torch.FloatTensor，形状为(batch_size, config.vocab_size)) — 语言建模头的预测分数。当不使用波束搜索时，这些可以是每个词汇表的 logits，或者在使用波束搜索时，可以是每个词汇表标记的 log softmax

返回

torch.FloatTensor，形状为(batch_size, config.vocab_size)

处理后的预测分数。

class transformers.SuppressTokensAtBeginLogitsProcessor

<来源>

( begin_suppress_tokens begin_index )

SuppressTokensAtBeginLogitsProcessor 在generate函数开始生成时立即抑制一系列标记，使用begin_index标记。这应该确保由begin_suppress_tokens定义的标记在开始时不会被生成。最初为Whisper创建。

示例：

>>> from transformers import AutoProcessor, WhisperForConditionalGeneration
>>> from datasets import load_dataset

>>> processor = AutoProcessor.from_pretrained("openai/whisper-tiny.en")
>>> model = WhisperForConditionalGeneration.from_pretrained("openai/whisper-tiny.en")
>>> ds = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")
>>> inputs = processor(ds[0]["audio"]["array"], return_tensors="pt")

>>> # Whisper has `begin_suppress_tokens` set by default (= `[220, 50256]`). 50256 is the EOS token, so this means
>>> # it can't generate and EOS token in the first iteration, but it can in the others.
>>> outputs = model.generate(**inputs, return_dict_in_generate=True, output_scores=True)
>>> print(outputs.scores[1][0, 50256])  # 1 (and not 0) is the first freely generated token
tensor(-inf)
>>> print(outputs.scores[-1][0, 50256])  # in other places we can see some probability mass for EOS
tensor(29.9010)

>>> # If we disable `begin_suppress_tokens`, we can generate EOS in the first iteration.
>>> outputs = model.generate(
...     **inputs, return_dict_in_generate=True, output_scores=True, begin_suppress_tokens=None
... )
>>> print(outputs.scores[1][0, 50256])
tensor(11.2027)

__call__

<来源>

( input_ids: LongTensor scores: FloatTensor ) → export const metadata = 'undefined';torch.FloatTensor of shape (batch_size, config.vocab_size)

参数

• input_ids (torch.LongTensor，形状为(batch_size, sequence_length)) — 词汇表中输入序列标记的索引。什么是输入 ID？

• scores (torch.FloatTensor，形状为(batch_size, config.vocab_size)) — 语言建模头的预测分数。当不使用波束搜索时，这些可以是每个词汇表的 logits，或者在使用波束搜索时，可以是每个词汇表标记的 log softmax

返回

torch.FloatTensor，形状为(batch_size, config.vocab_size)

处理后的预测分数。

class transformers.SuppressTokensLogitsProcessor

<来源>

( suppress_tokens )

此处理器可用于抑制一系列标记。处理器将将它们的对数概率设置为-inf，以便它们不会被生成。最初为Whisper创建。

示例：

>>> from transformers import AutoProcessor, WhisperForConditionalGeneration
>>> from datasets import load_dataset

>>> processor = AutoProcessor.from_pretrained("openai/whisper-tiny.en")
>>> model = WhisperForConditionalGeneration.from_pretrained("openai/whisper-tiny.en")
>>> ds = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")
>>> inputs = processor(ds[0]["audio"]["array"], return_tensors="pt")

>>> # Whisper has a long list of suppressed tokens. For instance, in this case, the token 1 is suppressed by default.
>>> outputs = model.generate(**inputs, return_dict_in_generate=True, output_scores=True)
>>> print(outputs.scores[1][0, 1])  # 1 (and not 0) is the first freely generated token
tensor(-inf)

>>> # If we disable `suppress_tokens`, we can generate it.
>>> outputs = model.generate(**inputs, return_dict_in_generate=True, output_scores=True, suppress_tokens=None)
>>> print(outputs.scores[1][0, 1])
tensor(5.7738)

__call__

<来源>

( input_ids: LongTensor scores: FloatTensor ) → export const metadata = 'undefined';torch.FloatTensor of shape (batch_size, config.vocab_size)

参数

• input_ids (torch.LongTensor，形状为(batch_size, sequence_length)) — 词汇表中输入序列标记的索引。什么是输入 ID？

• scores (torch.FloatTensor，形状为(batch_size, config.vocab_size)) — 语言建模头的预测分数。当不使用波束搜索时，这些可以是每个词汇表的 logits，或者在使用波束搜索时，可以是每个词汇表标记的 log softmax

返回

torch.FloatTensor of shape (batch_size, config.vocab_size)

处理后的预测分数。

class transformers.TemperatureLogitsWarper

< source >

( temperature: float )

参数

• temperature (float) — 用于调节 logits 分布的严格正值浮点值。小于 1 的值会减少随机性（反之亦然），0 相当于将所有概率质量转移到最可能的标记。

LogitsWarper 用于温度（指数缩放输出概率分布），这有效地意味着它可以控制预测标记的随机性。通常与 TopPLogitsWarper 和 TopKLogitsWarper 一起使用。

确保在 generate 参数中包含 do_sample=True，否则温度值将不会产生任何效果。

示例：

>>> import torch
>>> from transformers import AutoTokenizer, AutoModelForCausalLM, set_seed

>>> set_seed(0)  # for reproducibility

>>> tokenizer = AutoTokenizer.from_pretrained("gpt2")
>>> model = AutoModelForCausalLM.from_pretrained("gpt2")
>>> model.config.pad_token_id = model.config.eos_token_id
>>> inputs = tokenizer(["Hugging Face Company is"], return_tensors="pt")

>>> # With temperature=1.0, the default, we consistently get random outputs due to random sampling.
>>> generate_kwargs = {"max_new_tokens": 10, "do_sample": True, "temperature": 1.0, "num_return_sequences": 2}
>>> outputs = model.generate(**inputs, **generate_kwargs)
>>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True))
['Hugging Face Company is a joint venture between GEO Group, one of',
'Hugging Face Company is not an exact science – but what we believe does']

>>> # However, with temperature close to 0, it approximates greedy decoding strategies (invariant)
>>> generate_kwargs["temperature"] = 0.0001
>>> outputs = model.generate(**inputs, **generate_kwargs)
>>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True))
['Hugging Face Company is a company that has been around for over 20 years',
'Hugging Face Company is a company that has been around for over 20 years']

__call__

< source >

( input_ids: LongTensor scores: FloatTensor ) → export const metadata = 'undefined';torch.FloatTensor of shape (batch_size, config.vocab_size)

参数

• input_ids (torch.LongTensor of shape (batch_size, sequence_length)) — 输入序列标记在词汇表中的索引。什么是输入 ID？

• scores (torch.FloatTensor of shape (batch_size, config.vocab_size)) — 语言建模头的预测分数。当不使用波束搜索时，这些可以是每个词汇的 logits，或者在使用波束搜索时，可以是每个词汇标记的 log softmax

返回

torch.FloatTensor of shape (batch_size, config.vocab_size)

处理后的预测分数。

class transformers.TopKLogitsWarper

< source >

( top_k: int filter_value: float = -inf min_tokens_to_keep: int = 1 )

参数

• top_k (int) — 要保留的最高概率词汇标记的数量。

• filter_value (float, 可选, 默认为 -inf) — 所有过滤值将被设置为此浮点值。

• min_tokens_to_keep (int, 可选, 默认为 1) — 不能被过滤的最小标记数量。

LogitsWarper 执行 top-k，即限制为最高概率元素 k。通常与 TemperatureLogitsWarper 和 TopPLogitsWarper 一起使用。

示例：

>>> from transformers import AutoTokenizer, AutoModelForCausalLM, set_seed

>>> set_seed(0)
>>> model = AutoModelForCausalLM.from_pretrained("distilgpt2")
>>> tokenizer = AutoTokenizer.from_pretrained("distilgpt2")

>>> inputs = tokenizer("A sequence: A, B, C, D", return_tensors="pt")

>>> # With sampling, the output is unexpected -- sometimes too unexpected.
>>> outputs = model.generate(**inputs, do_sample=True)
>>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True)[0])
A sequence: A, B, C, D, G, H, I. A, M

>>> # With `top_k` sampling, the output gets restricted the k most likely tokens.
>>> # Pro tip: In practice, LLMs use `top_k` in the 5-50 range.
>>> outputs = model.generate(**inputs, do_sample=True, top_k=2)
>>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True)[0])
A sequence: A, B, C, D, E, F, G, H, I

__call__

< source >

( input_ids: LongTensor scores: FloatTensor ) → export const metadata = 'undefined';torch.FloatTensor of shape (batch_size, config.vocab_size)

参数

• input_ids (torch.LongTensor of shape (batch_size, sequence_length)) — 输入序列标记在词汇表中的索引。什么是输入 ID？

• scores (torch.FloatTensor of shape (batch_size, config.vocab_size)) — 语言建模头的预测分数。当不使用波束搜索时，这些可以是每个词汇的 logits，或者在使用波束搜索时，可以是每个词汇标记的 log softmax

返回

torch.FloatTensor of shape (batch_size, config.vocab_size)

处理后的预测分数。

class transformers.TopPLogitsWarper

< source >

( top_p: float filter_value: float = -inf min_tokens_to_keep: int = 1 )

参数

• top_p (float) — 如果设置为 < 1，则仅保留概率相加达到 top_p 或更高的最可能标记集合用于生成。

• filter_value (float, 可选, 默认为 -inf) — 所有过滤值将被设置为此浮点值。

• min_tokens_to_keep (int, 可选, 默认为 1) — 不能被过滤的最小标记数量。

LogitsWarper 执行 top-p，即限制总和小于等于 prob_cut_off 的前几个标记。通常与 TemperatureLogitsWarper 和 TopKLogitsWarper 一起使用。

示例：

>>> from transformers import AutoTokenizer, AutoModelForCausalLM, set_seed

>>> set_seed(0)
>>> model = AutoModelForCausalLM.from_pretrained("distilgpt2")
>>> tokenizer = AutoTokenizer.from_pretrained("distilgpt2")

>>> inputs = tokenizer("A sequence: 1, 2", return_tensors="pt")

>>> # With sampling, the output is unexpected -- sometimes too unexpected.
>>> outputs = model.generate(**inputs, do_sample=True)
>>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True)[0])
A sequence: 1, 2, 0, 2, 2. 2, 2, 2, 2

>>> # With `top_p` sampling, the output gets restricted to high-probability tokens.
>>> # Pro tip: In practice, LLMs use `top_p` in the 0.9-0.95 range.
>>> outputs = model.generate(**inputs, do_sample=True, top_p=0.1)
>>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True)[0])
A sequence: 1, 2, 3, 4, 5, 6, 7, 8, 9

__call__

<来源>

( input_ids: LongTensor scores: FloatTensor ) → export const metadata = 'undefined';torch.FloatTensor of shape (batch_size, config.vocab_size)

参数

• input_ids (torch.LongTensor，形状为(batch_size, sequence_length)) — 词汇表中输入序列标记的索引。什么是输入 ID？

• scores (torch.FloatTensor，形状为(batch_size, config.vocab_size)) — 语言建模头的预测分数。当不使用波束搜索时，这些可以是每个词汇表的 logits，或者在使用波束搜索时，可以是每个词汇表标记的 log softmax。

返回

torch.FloatTensor，形状为(batch_size, config.vocab_size)

处理后的预测分数。

class transformers.TypicalLogitsWarper

<来源>

( mass: float = 0.9 filter_value: float = -inf min_tokens_to_keep: int = 1 )

参数

• mass (float, 可选, 默认为 0.9) — 典型 p 值在 0 到 1 之间，默认为 0.9。

• filter_value (float，可选，默认为-inf) — 所有被过滤的值将被设置为此浮点值。

• min_tokens_to_keep (int，可选，默认为 1) — 不能被过滤的最小标记数。

LogitsWarper 执行典型解码。受到人类如何使用语言的启发，它优先考虑对数概率接近标记概率分布的熵的标记。这意味着在过程中可能会丢弃最有可能的标记。

查看自然语言生成的典型解码获取更多信息。

示例：

>>> from transformers import AutoTokenizer, AutoModelForCausalLM, set_seed

>>> model = AutoModelForCausalLM.from_pretrained("bigscience/bloomz-560m")
>>> tokenizer = AutoTokenizer.from_pretrained("bigscience/bloomz-560m")

>>> inputs = tokenizer("1, 2, 3", return_tensors="pt")

>>> # We can see that greedy decoding produces a sequence of numbers
>>> outputs = model.generate(**inputs)
>>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True)[0])
1, 2, 3, 4, 5, 6, 7, 8, 9, 10,

>>> # For this particular seed, we can see that sampling produces nearly the same low-information (= low entropy)
>>> # sequence
>>> set_seed(18)
>>> outputs = model.generate(**inputs, do_sample=True)
>>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True)[0])
1, 2, 3, 4, 5, 6, 7, 8, 9 and 10

>>> # With `typical_p` set, the most obvious sequence is no longer produced, which may be good for your problem
>>> set_seed(18)
>>> outputs = model.generate(
...     **inputs, do_sample=True, typical_p=0.1, return_dict_in_generate=True, output_scores=True
... )
>>> print(tokenizer.batch_decode(outputs.sequences, skip_special_tokens=True)[0])
1, 2, 3 and 5

>>> # We can see that the token corresponding to "4" (token 934) in the second position, the most likely token
>>> # as seen with greedy decoding, was entirely blocked out
>>> print(outputs.scores[1][0, 934])
tensor(-inf)

__call__

<来源>

( input_ids: LongTensor scores: FloatTensor ) → export const metadata = 'undefined';torch.FloatTensor of shape (batch_size, config.vocab_size)

参数

• input_ids (torch.LongTensor，形状为(batch_size, sequence_length)) — 词汇表中输入序列标记的索引。什么是输入 ID？

• scores (torch.FloatTensor，形状为(batch_size, config.vocab_size)) — 语言建模头的预测分数。当不使用波束搜索时，这些可以是每个词汇表的 logits，或者在使用波束搜索时，可以是每个词汇表标记的 log softmax。

返回

torch.FloatTensor，形状为(batch_size, config.vocab_size)

处理后的预测分数。

class transformers.UnbatchedClassifierFreeGuidanceLogitsProcessor

<来源>

( guidance_scale: float model unconditional_ids: Optional = None unconditional_attention_mask: Optional = None use_cache: Optional = True )

参数

• guidance_scale (float) — 分类器自由引导（CFG）的引导比例。通过设置guidance_scale != 1来启用 CFG。较高的引导比例鼓励模型生成与输入提示更紧密相关的样本，通常以牺牲质量为代价。小于 1 的值具有相反的效果，同时使得与负面提示提供的负面提示 ID（如果有）作为正面提示。

• model (PreTrainedModel) — 计算无条件分数的模型。假设与计算条件分数的模型相同。两个模型必须使用相同的分词器。

• unconditional_ids (torch.LongTensor，形状为(batch_size, sequence_length)，可选) — 无条件分支中词汇表中输入序列标记的索引。如果未设置，将默认为提示的最后一个标记。

• unconditional_attention_mask (torch.LongTensor，形状为(batch_size, sequence_length)，可选) — 用于无条件 ID 的注意力掩码。

• use_cache（bool，可选，默认为True）— 是否在负 prompt 前向传递期间缓存键/值。

用于无分类器引导（CFG）的 Logits 处理器。处理器通过guidance_scale参数化的 prompt 条件和 prompt 无条件（或负）logits 的分数进行加权平均。无条件分数是通过提示model使用unconditional_ids分支内部计算的。

有关更多信息，请参阅论文。

示例：

>>> from transformers import AutoTokenizer, AutoModelForCausalLM

>>> model = AutoModelForCausalLM.from_pretrained("gpt2")
>>> tokenizer = AutoTokenizer.from_pretrained("gpt2")
>>> inputs = tokenizer(["Today, a dragon flew over Paris, France,"], return_tensors="pt")
>>> out = model.generate(inputs["input_ids"], guidance_scale=1.5)
>>> tokenizer.batch_decode(out, skip_special_tokens=True)[0]
'Today, a dragon flew over Paris, France, killing at least 50 people and injuring more than 100'

>>> # with a negative prompt
>>> neg_inputs = tokenizer(["A very happy event happened,"], return_tensors="pt")
>>> out = model.generate(inputs["input_ids"], guidance_scale=2, negative_prompt_ids=neg_inputs["input_ids"])
>>> tokenizer.batch_decode(out, skip_special_tokens=True)[0]
'Today, a dragon flew over Paris, France, killing at least 130 people. French media reported that'

>>> # with a positive prompt
>>> neg_inputs = tokenizer(["A very happy event happened,"], return_tensors="pt")
>>> out = model.generate(inputs["input_ids"], guidance_scale=0, negative_prompt_ids=neg_inputs["input_ids"])
>>> tokenizer.batch_decode(out, skip_special_tokens=True)[0]
"Today, a dragon flew over Paris, France, and I'm very happy to be here. I"

__call__

<来源>

( input_ids scores )

class transformers.WhisperTimeStampLogitsProcessor

<来源>

( generate_config begin_index: Optional = None _detect_timestamp_from_logprob: Optional = None )

参数

• generate_config（GenerateConfig）--用于生成输出的生成配置。需要以下参数：eos_token_id（int，optional，默认为 50257）：sequence结束标记的 id。no_timestamps_token_id（int，optional，默认 50363）："<|notimestamps|>"令牌。max_initial_timestamp_index（int，optional，默认 1）的 id：用于设置初始时间戳的最大值。这用于防止模型预测未来太远的时间戳。

• begin_index（Optional，可选）— 模型生成的第一个标记的标记索引。

• _detect_timestamp_from_logprob（bool，可选）— 是否可以从所有时间戳的 logprobs 中预测时间戳。

LogitsProcessor 用于修改时间戳生成中的 logits。当输入标记达到特定阈值时，处理器将分数设置为负无穷大。处理器确保时间戳标记成对出现，通过屏蔽会破坏这种配对模式的 logits。这样做是为了保持生成的时间戳的一致性和结构。它还确保当预测任何时间戳标记的采样概率大于任何单个非时间戳标记时，这些非时间戳 logits 被设置为负无穷大。这样做是为了确保生成时间戳而不是其他潜在标记。

有关更多信息，请参阅论文。

示例：

>>> import torch
>>> from transformers import AutoProcessor, WhisperForConditionalGeneration, GenerationConfig
>>> from datasets import load_dataset

>>> processor = AutoProcessor.from_pretrained("openai/whisper-tiny.en")
>>> model = WhisperForConditionalGeneration.from_pretrained("openai/whisper-tiny.en")
>>> ds = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")
>>> inputs = processor(ds[3]["audio"]["array"], return_tensors="pt")
>>> input_features = inputs.input_features

>>> #Displaying timestamps
>>> generated_ids = model.generate(inputs=input_features, return_timestamps=True)
>>> transcription = processor.batch_decode(generated_ids, decode_with_timestamps=True)[0]
>>> print("Transcription:", transcription)
Transcription: <|startoftranscript|><|0.00|> He has grave doubts whether Sir Frederick Layton's work is really Greek after all, and can<|6.44|><|6.44|> discover in it but little of rocky Ithaca.<|9.44|><|endoftext|>

>>> #No timestamps & change EOS:
>>> #This allows the user to select a specific token to terminate the sequence on, in this case it's the word "can"(460)
>>> model.generation_config.eos_token_id = 460
>>> generated_ids = model.generate(inputs=input_features,return_timestamps=False)
>>> transcription = processor.batch_decode(generated_ids, skip_special_tokens=True)[0]
>>> print("Transcription:", transcription)
Transcription:  He has grave doubts whether Sir Frederick Layton's work is really Greek after all and can

__call__

<来源>

( input_ids: LongTensor scores: FloatTensor ) → export const metadata = 'undefined';torch.FloatTensor of shape (batch_size, config.vocab_size)

参数

• input_ids（形状为(batch_size, sequence_length)的torch.LongTensor）— 词汇表中输入序列标记的索引。什么是输入 ID？

• scores（形状为(batch_size, config.vocab_size)的torch.FloatTensor）— 语言建模头的预测分数。当不使用波束搜索时，这些可以是每个词汇的 logits，或者在使用波束搜索时，可以是每个词汇标记的 log softmax

返回

torch.FloatTensor的形状为(batch_size, config.vocab_size)

处理后的预测分数。

TensorFlow

class transformers.TFForcedBOSTokenLogitsProcessor

<来源>

( bos_token_id: int )

参数

• bos_token_id（int）— 强制作为第一个生成的标记的标记 ID。

TFLogitsProcessor 强制指定的标记作为第一个生成的标记。

__call__

<来源>

( input_ids: Tensor scores: Tensor cur_len: int )

class transformers.TFForcedEOSTokenLogitsProcessor

<来源>

( max_length: int eos_token_id: int )

参数

• max_length（int）— 要生成的序列的最大长度。

• eos_token_id（int）— 在达到max_length时强制作为最后生成的标记的标记 ID。

TFLogitsProcessor 强制指定的标记作为达到max_length时的最后生成的标记。

__call__

<来源>

( input_ids: Tensor scores: Tensor cur_len: int )

class transformers.TFForceTokensLogitsProcessor

<来源>

( force_token_map: List )

这个处理器接受一对整数的列表，指示从生成索引到标记索引的映射，这些将在采样之前被强制。处理器将它们的 log 概率设置为0，并将所有其他标记设置为-inf，以便在相应的索引处对它们进行采样。

__call__

<来源>

( input_ids: Tensor scores: Tensor cur_len: int )

class transformers.TFLogitsProcessor

<来源>

( )

用于在生成过程中应用的所有 logit 处理器的抽象基类。

__call__

<来源>

( input_ids: Tensor scores: Tensor cur_len: int ) → export const metadata = 'undefined';tf.Tensor of shape (batch_size, config.vocab_size)

参数

• input_ids (tf.Tensor，形状为(batch_size, sequence_length)) — 词汇表中输入序列标记的索引。

  可以使用 PreTrainedTokenizer 获取索引。详情请参见 PreTrainedTokenizer.encode()和 PreTrainedTokenizer.call()。

  什么是输入 ID？

• scores (tf.Tensor，形状为(batch_size, config.vocab_size)) — 语言建模头的预测分数。当不使用 beam search 时，这些可以是每个词汇表的 logits，或者在使用 beam search 时，可以是每个词汇表标记的 log softmax。

• cur_len (int) — 有效输入序列标记的当前长度。在 TF 实现中，input_ids 的序列长度是生成器可以生成的最大长度，我们需要知道哪些标记是有效的。

• kwargs (Dict[str, Any]，可选) — 其他 logits 处理器特定的 kwargs。

返回

tf.Tensor，形状为(batch_size, config.vocab_size)

处理后的预测分数。

处理 logits 的 TF 方法。

class transformers.TFLogitsProcessorList

<来源>

( iterable = () )

这个类可用于创建一个 TFLogitsProcessor 列表，以后处理scores输入张量。该类继承自列表，并添加了一个特定的call方法，以应用每个 TFLogitsProcessor 到输入。

__call__

<来源>

( input_ids: Tensor scores: Tensor cur_len: int **kwargs ) → export const metadata = 'undefined';tf.Tensor of shape (batch_size, config.vocab_size)

参数

• input_ids (tf.Tensor，形状为(batch_size, sequence_length)) — 词汇表中输入序列标记的索引。

  可以使用 PreTrainedTokenizer 获取索引。详情请参见 PreTrainedTokenizer.encode()和 PreTrainedTokenizer.call()。

  什么是输入 ID？

• scores (tf.Tensor，形状为(batch_size, config.vocab_size)) — 语言建模头的预测分数。当不使用 beam search 时，这些可以是每个词汇表的 logits，或者在使用 beam search 时，可以是每个词汇表标记的 log softmax。

• cur_len (int) — 有效输入序列标记的当前长度。在 TF 实现中，input_ids 的序列长度是生成的最大长度，我们需要知道哪些标记是有效的。

• kwargs (Dict[str, Any], 可选) — 额外的 logits 处理器特定 kwargs。

返回

形状为 (batch_size, config.vocab_size) 的 tf.Tensor

处理后的预测分数。

class transformers.TFLogitsWarper

< source >

( )

用于在多项式采样生成期间应用的所有 logits 扭曲的抽象基类。

__call__

< source >

( input_ids: Tensor scores: Tensor cur_len: int ) → export const metadata = 'undefined';tf.Tensor of shape (batch_size, config.vocab_size)

参数

• input_ids (tf.Tensor，形状为 (batch_size, sequence_length)) — 词汇表中输入序列标记的索引。

  可以使用 PreTrainedTokenizer 获取索引。有关详细信息，请参阅 PreTrainedTokenizer.encode() 和 PreTrainedTokenizer.call()。

  什么是输入 ID？

• scores (tf.Tensor，形状为 (batch_size, config.vocab_size)) — 语言建模头的预测分数。当不使用波束搜索时，这些可以是每个词汇的 logits，或者在使用波束搜索时，可以是每个词汇标记的 log softmax。

• cur_len (int) — 有效输入序列标记的当前长度。在 TF 实现中，input_ids 的序列长度是生成的最大长度，我们需要知道哪些标记是有效的。

• kwargs (Dict[str, Any], 可选) — 额外的 logits 处理器特定 kwargs。

返回

形状为 (batch_size, config.vocab_size) 的 tf.Tensor

处理后的预测分数。

用于扭曲 logits 的 TF 方法。

class transformers.TFMinLengthLogitsProcessor

< source >

( min_length: int eos_token_id: int )

参数

• min_length (int) — 将 eos_token_id 的分数设置为 -float("Inf") 的最小长度。

• eos_token_id (int) — 序列结束 标记的 id。

TFLogitsProcessor 通过将 EOS 概率设置为 0 来强制最小长度。

__call__

< source >

( input_ids: Tensor scores: Tensor cur_len: int )

class transformers.TFNoBadWordsLogitsProcessor

< source >

( bad_words_ids: List eos_token_id: int )

参数

• bad_words_ids (List[List[int]]) — 不允许生成的标记 id 的列表。为了获取不应出现在生成文本中的单词的标记，请确保在初始化分词器时设置 add_prefix_space=True，并使用 tokenizer(bad_words, add_special_tokens=False).input_ids。add_prefix_space 参数仅支持某些慢速分词器，因为快速分词器的前缀行为来自 pre tokenizers。更多信息请阅读这里。

• eos_token_id (int) — 序列结束 标记的 id。

TFLogitsProcessor 强制指定序列永远不会被采样。

__call__

< source >

( input_ids: Tensor scores: Tensor cur_len: int )

class transformers.TFNoRepeatNGramLogitsProcessor

<来源>

( ngram_size: int )

参数

• ngram_size (int) — 所有大小为ngram_size的 n-gram 只能出现一次。

TFLogitsProcessor 强制不重复 n-gram。参见Fairseq。

__call__

<来源>

( input_ids: Tensor scores: Tensor cur_len: int )

class transformers.TFRepetitionPenaltyLogitsProcessor

<来源>

( penalty: float )

参数

• repetition_penalty (float) — 重复惩罚的参数。1.0 表示没有惩罚。更多细节请参阅这篇论文。

TFLogitsProcessor 对重复序列施加指数惩罚。

__call__

<来源>

( input_ids: Tensor scores: Tensor cur_len: int )

class transformers.TFSuppressTokensAtBeginLogitsProcessor

<来源>

( begin_suppress_tokens begin_index )

TFSuppressTokensAtBeginLogitsProcessor 在generate函数开始生成时立即抑制一组标记。这应该确保在生成开始时不会抽样到由begin_suppress_tokens定义的标记。

__call__

<来源>

( input_ids: Tensor scores: Tensor cur_len: int )

class transformers.TFSuppressTokensLogitsProcessor

<来源>

( suppress_tokens )

这个处理器可以用来抑制一组标记。处理器将把它们的对数概率设置为-inf，以便它们不被抽样。

__call__

<来源>

( input_ids: Tensor scores: Tensor cur_len: int )

class transformers.TFTemperatureLogitsWarper

<来源>

( temperature: float )

参数

• temperature (float) — 用于调节 logits 分布的值。

TFLogitsWarper 用于温度（指数缩放输出概率分布）。

__call__

<来源>

( input_ids: Tensor scores: Tensor cur_len: int )

class transformers.TFTopKLogitsWarper

<来源>

( top_k: int filter_value: float = -inf min_tokens_to_keep: int = 1 )

参数

• top_k (int) — 保留的最高概率词汇标记数。

• filter_value (float, 可选, 默认为-inf) — 所有被过滤的值将被设置为这个浮点值。

• min_tokens_to_keep (int, 可选, 默认为 1) — 不能被过滤的最小标记数。

TFLogitsWarper 执行 top-k，即限制为概率最高的 k 个元素。

__call__

<来源>

( input_ids: Tensor scores: Tensor cur_len: int )

class transformers.TFTopPLogitsWarper

<来源>

( top_p: float filter_value: float = -inf min_tokens_to_keep: int = 1 )

参数

• top_p (float) — 如果设置为<1，则仅保留概率相加大于top_p或更高的最可能标记集。

• filter_value (float, 可选, 默认为-inf) — 所有被过滤的值将被设置为这个浮点值。

• min_tokens_to_keep (int, 可选, 默认为 1) — 不能被过滤的最小标记数。

TFLogitsWarper 执行 top-p，即限制总和小于等于 prob_cut_off 的顶级标记。

__call__

<来源>

( input_ids: Tensor scores: Tensor cur_len: int )

FLAX

class transformers.FlaxForcedBOSTokenLogitsProcessor

<来源>

( bos_token_id: int )

参数

• bos_token_id (int) — 强制作为第一个生成的标记的标记 id。

FlaxLogitsProcessor 将指定的标记作为第一个生成的标记。

__call__

<来源>

( input_ids: Array scores: Array cur_len: int )

class transformers.FlaxForcedEOSTokenLogitsProcessor

<来源>

( max_length: int eos_token_id: int )

参数

• max_length (int) — 要生成的序列的最大长度。

• eos_token_id (int) — 当达到max_length时，强制作为最后生成的标记的标记 id。

FlaxLogitsProcessor 在达到max_length时将指定的标记强制为最后生成的标记。

__call__

<来源>

( input_ids: Array scores: Array cur_len: int )

class transformers.FlaxForceTokensLogitsProcessor

<来源>

( force_token_map )

参数

• force_token_map (list) — 给出标记 id 和它们将被强制采样的索引的映射。

FlaxLogitsProcessor 接受一对整数的列表，指示从生成索引到标记索引的映射，这些标记将在采样之前被强制。处理器将它们的对数概率设置为 0，将所有其他标记设置为-inf，以便它们在相应的索引处被采样。

__call__

<来源>

( input_ids: Array scores: Array cur_len: int )

class transformers.FlaxLogitsProcessor

<来源>

( )

所有在生成期间可以应用的 logit 处理器的抽象基类。

__call__

<来源>

( input_ids: Array scores: Array ) → export const metadata = 'undefined';jnp.ndarray of shape (batch_size, config.vocab_size)

参数

• input_ids (jnp.ndarray，形状为(batch_size, sequence_length)) — 词汇表中输入序列标记的索引。

  可以使用 PreTrainedTokenizer 获取索引。有关详细信息，请参阅 PreTrainedTokenizer.encode()和 PreTrainedTokenizer.call()。

  什么是输入 ID？

• scores (jnp.ndarray的形状为(batch_size, config.vocab_size)) — 语言建模头的预测分数。当不使用 beam search 时，这些可以是每个词汇的 logits，或者在使用 beam search 时，可以是每个词汇标记的 log softmax

• kwargs (Dict[str, Any], optional) — 特定于 logits 处理器的额外 kwargs。

返回

jnp.ndarray的形状为(batch_size, config.vocab_size)

处理后的预测分数。

Flax 处理 logits 的方法。

class transformers.FlaxLogitsProcessorList

<来源>

( iterable = () )

此类可用于创建 FlaxLogitsProcessor 或 FlaxLogitsWarper 的列表，以随后处理scores输入张量。此类继承自列表，并添加了一个特定的call方法来应用每个 FlaxLogitsProcessor 或 FlaxLogitsWarper 到输入中。

__call__

<来源>

( input_ids: Array scores: Array cur_len: int **kwargs ) → export const metadata = 'undefined';jnp.ndarray of shape (batch_size, config.vocab_size)

参数

• input_ids (jnp.ndarray的形状为(batch_size, sequence_length)) — 词汇表中输入序列标记的索引。

  可以使用 PreTrainedTokenizer 来获取索引。有关详细信息，请参阅 PreTrainedTokenizer.encode()和 PreTrainedTokenizer.call()。

  什么是输入 ID？

• scores (jnp.ndarray的形状为(batch_size, config.vocab_size)) — 语言建模头的预测分数。当不使用 beam search 时，这些可以是每个词汇的 logits，或者在使用 beam search 时，可以是每个词汇标记的 log softmax

• kwargs (Dict[str, Any], optional) — 特定于 logits 处理器的额外 kwargs。

返回

jnp.ndarray的形状为(batch_size, config.vocab_size)

处理后的预测分数。

class transformers.FlaxLogitsWarper

<来源>

( )

用于在生成过程中应用多项式采样的所有 logit 扭曲器的抽象基类。

__call__

<来源>

( input_ids: Array scores: Array ) → export const metadata = 'undefined';jnp.ndarray of shape (batch_size, config.vocab_size)

参数

• input_ids (jnp.ndarray的形状为(batch_size, sequence_length)) — 词汇表中输入序列标记的索引。

  可以使用 PreTrainedTokenizer 来获取索引。有关详细信息，请参阅 PreTrainedTokenizer.encode()和 PreTrainedTokenizer.call()。

  什么是输入 ID？

• scores (jnp.ndarray的形状为(batch_size, config.vocab_size)) — 语言建模头的预测分数。当不使用 beam search 时，这些可以是每个词汇的 logits，或者在使用 beam search 时，可以是每个词汇标记的 log softmax

• kwargs (Dict[str, Any], optional) — 特定于 logits 处理器的额外 kwargs。

返回

jnp.ndarray的形状为(batch_size, config.vocab_size)

处理后的预测分数。

Flax 扭曲 logits 的方法。

class transformers.FlaxMinLengthLogitsProcessor

< source >

( min_length: int eos_token_id: int )

参数

• min_length (int) — 当长度低于此值时，eos_token_id 的分数将被设置为 -float("Inf")。

• eos_token_id (int) — 序列结束 标记的 id。

FlaxLogitsProcessor 通过将 EOS 的概率设置为 0 来强制执行最小长度。

__call__

< source >

( input_ids: Array scores: Array cur_len: int )

class transformers.FlaxSuppressTokensAtBeginLogitsProcessor

< source >

( begin_suppress_tokens begin_index )

参数

• begin_suppress_tokens (List[int]) — 不采样的标记。

• begin_index (int) — 抑制标记的索引。

FlaxLogitsProcessor 在 generate 函数开始生成时立即抑制一组标记，使用 begin_index 标记。这应该确保由 begin_suppress_tokens 定义的标记在生成开始时不被采样。

__call__

< source >

( input_ids scores cur_len: int )

class transformers.FlaxSuppressTokensLogitsProcessor

< source >

( suppress_tokens: list )

参数

• suppress_tokens (list) — 不采样的标记。

FlaxLogitsProcessor 在每个解码步骤抑制一组标记。处理器将它们的对数概率设置为 -inf，以便它们不被采样。

__call__

< source >

( input_ids: Array scores: Array cur_len: int )

class transformers.FlaxTemperatureLogitsWarper

< source >

( temperature: float )

参数

• temperature (float) — 用于调节 logits 分布的值。

FlaxLogitsWarper 用于温度（指数缩放输出概率分布）。

__call__

< source >

( input_ids: Array scores: Array cur_len: int )

class transformers.FlaxTopKLogitsWarper

< source >

( top_k: int filter_value: float = -inf min_tokens_to_keep: int = 1 )

参数

• top_k (int) — 保留最高概率词汇标记的数量以进行 top-k 过滤。

• filter_value (float, 可选, 默认为 -inf) — 所有过滤值将被设置为此浮点值。

• min_tokens_to_keep (int, 可选, 默认为 1) — 不能被过滤的最小标记数。

FlaxLogitsWarper 执行 top-k，即限制为概率最高的 k 个元素。

__call__

< source >

( input_ids: Array scores: Array cur_len: int )

class transformers.FlaxTopPLogitsWarper

< source >

( top_p: float filter_value: float = -inf min_tokens_to_keep: int = 1 )

参数

• top_p (float) — 如果设置为 < 1，则只保留概率相加达到 top_p 或更高的最小一组最可能的标记用于生成。

• filter_value (float, 可选, 默认为 -inf) — 所有过滤值将被设置为此浮点值。

• min_tokens_to_keep (int，可选，默认为 1) — 不能被过滤的最小标记数。

FlaxLogitsWarper 执行 top-p，即限制总概率小于等于 prob_cut_off 的前 p 个标记。

__call__

< source >

( input_ids: Array scores: Array cur_len: int )

class transformers.FlaxWhisperTimeStampLogitsProcessor

< source >

( generate_config model_config decoder_input_length )

参数

• generate_config (GenerateConfig) — 用于生成输出的生成配置。需要以下参数：eos_token_id (int，可选，默认为 50257)：序列结束标记的 id。no_timestamps_token_id (int，可选，默认为 50363)："<|notimestamps|>"标记的 id。max_initial_timestamp_index (int，可选，默认为 1)：用于设置初始时间戳的最大值。这用于防止模型预测太遥远的时间戳。

Whisper 特定的处理器。此处理器可用于强制一个标记列表。处理器将将它们的对数概率设置为inf，以便在相应的索引处对它们进行采样。

__call__

< source >

( input_ids scores cur_len )

StoppingCriteria

StoppingCriteria 可用于更改生成过程何时停止（除了 EOS 标记）。请注意，这仅适用于我们的 PyTorch 实现。

class transformers.StoppingCriteria

< source >

( )

所有可以在生成过程中应用的停止标准的抽象基类。

如果您的停止标准取决于scores输入，请确保将return_dict_in_generate=True, output_scores=True传递给generate。

__call__

< source >

( input_ids: LongTensor scores: FloatTensor **kwargs )

参数

• input_ids (torch.LongTensor，形状为(batch_size, sequence_length)) — 词汇表中输入序列标记的索引。

  可以使用 AutoTokenizer 来获取索引。有关详细信息，请参阅 PreTrainedTokenizer.encode()和 PreTrainedTokenizer.call()。

  什么是输入 ID？

• scores (torch.FloatTensor，形状为(batch_size, config.vocab_size)) — 语言建模头的预测分数。这些可以是 SoftMax 之前每个词汇标记的分数，也可以是 SoftMax 之后每个词汇标记的分数。如果此停止标准取决于scores输入，请确保将return_dict_in_generate=True, output_scores=True传递给generate。

• kwargs (Dict[str, Any]，可选) — 其他特定停止标准的关键字参数。

class transformers.StoppingCriteriaList

< source >

( iterable = () )

__call__

< source >

( input_ids: LongTensor scores: FloatTensor **kwargs )

参数

• input_ids (torch.LongTensor，形状为(batch_size, sequence_length)) — 词汇表中输入序列标记的索引。

  可以使用 AutoTokenizer 获取索引。有关详细信息，请参阅 PreTrainedTokenizer.encode()和 PreTrainedTokenizer.call()。

  什么是输入 ID？

• scores (torch.FloatTensor of shape (batch_size, config.vocab_size)) — 语言建模头的预测分数。这些可以是 SoftMax 之前每个词汇标记的分数，也可以是 SoftMax 之后每个词汇标记的分数。如果此停止标准取决于scores输入，请确保您传递return_dict_in_generate=True, output_scores=True给generate。

• kwargs (Dict[str, Any], 可选) — 其他特定停止标准的 kwargs。

class transformers.MaxLengthCriteria

<来源>

( max_length: int max_position_embeddings: Optional = None )

参数

• max_length (int) — 输出序列在标记数量上可以具有的最大长度。

• max_position_embeddings (int, 可选) — 模型的最大长度，由模型的config.max_position_embeddings属性定义。

这个类可以用来在生成的标记数超过max_length时停止生成。请注意，对于仅解码器类型的 transformers，这将包括初始提示的标记。

__call__

<来源>

( input_ids: LongTensor scores: FloatTensor **kwargs )

参数

• input_ids (torch.LongTensor of shape (batch_size, sequence_length)) — 输入序列标记在词汇表中的索引。

  可以使用 AutoTokenizer 获取索引。有关详细信息，请参阅 PreTrainedTokenizer.encode()和 PreTrainedTokenizer.call()。

  什么是输入 ID？

• scores (torch.FloatTensor of shape (batch_size, config.vocab_size)) — 语言建模头的预测分数。这些可以是 SoftMax 之前每个词汇标记的分数，也可以是 SoftMax 之后每个词汇标记的分数。如果此停止标准取决于scores输入，请确保您传递return_dict_in_generate=True, output_scores=True给generate。

• kwargs (Dict[str, Any], 可选) — 其他特定停止标准的 kwargs。

class transformers.MaxTimeCriteria

<来源>

( max_time: float initial_timestamp: Optional = None )

参数

• max_time (float) — 生成的最大允许时间（以秒为单位）。

• initial_time (float, 可选, 默认为time.time()) — 允许生成的开始时间。

这个类可以用来在完整生成超过一定时间时停止生成。默认情况下，当初始化此函数时，时间将开始计算。您可以通过传递initial_time来覆盖这一点。

__call__

<来源>

( input_ids: LongTensor scores: FloatTensor **kwargs )

参数

• input_ids (torch.LongTensor of shape (batch_size, sequence_length)) — 输入序列标记在词汇表中的索引。

  可以使用 AutoTokenizer 获取索引。有关详细信息，请参阅 PreTrainedTokenizer.encode() 和 PreTrainedTokenizer.call()。

  什么是输入 ID？

• scores (torch.FloatTensor of shape (batch_size, config.vocab_size)) — 语言建模头的预测分数。这些可以是 SoftMax 之前每个词汇标记的分数，也可以是 SoftMax 之后每个词汇标记的分数。如果这个停止标准依赖于 scores 输入，确保你传递 return_dict_in_generate=True, output_scores=True 给 generate。

• kwargs (Dict[str, Any], 可选) — 其他特定的停止标准参数。

约束

Constraint 可以用来强制生成结果中包含特定的标记或序列。请注意，这仅适用于我们的 PyTorch 实现。

class transformers.Constraint

< source >

( )

所有可以在生成过程中应用的约束的抽象基类。它必须定义约束如何被满足。

所有继承 Constraint 的类必须遵循的要求

completed = False
while not completed:
    _, completed = constraint.update(constraint.advance())

将始终终止（停止）。

advance

< source >

( ) → export const metadata = 'undefined';token_ids(torch.tensor)

返回

token_ids(torch.tensor)

必须是一个可索引的标记列表的张量，而不是某个整数。

调用时，返回一个标记，这个标记会使这个约束更接近被满足一步。

copy

< source >

( stateful = False ) → export const metadata = 'undefined';constraint(Constraint)

返回

constraint(Constraint)

与被调用的相同的约束。

创建这个约束的一个新实例。

does_advance

< source >

( token_id: int )

读取一个标记并返回它是否推进了进度。

remaining

< source >

( )

返回 advance() 完成这个约束还需要多少步骤。

reset

< source >

( )

重置这个约束的状态到初始化状态。我们会在约束的实现被不想要的标记中断时调用这个方法。

test

< source >

( )

测试这个约束是否已经正确定义。

update

< source >

( token_id: int ) → export const metadata = 'undefined';stepped(bool)

返回

stepped(bool)

这个约束是否变得更接近被满足一步。completed(bool): 这个约束是否已经被这个生成的标记完全满足。reset (bool): 这个约束是否已经被这个生成的标记重置了进度。

读取一个标记并返回指示其推进程度的布尔值。这个函数会更新这个对象的状态，不像 does_advance(self, token_id: int)。

这不是为了测试某个特定的标记是否会推进进度；而是为了更新它的状态，就好像它已经被生成了。如果 token_id != desired token（参考 PhrasalConstraint 中的 else 语句），这变得很重要。

class transformers.PhrasalConstraint

<来源>

( token_ids: List )

参数

• token_ids（List[int]）— 必须由输出生成的 token 的 id。

Constraint 强制要求输出中包含一个有序的 token 序列。

class transformers.DisjunctiveConstraint

<来源>

( nested_token_ids: List )

参数

• nested_token_ids（List[List[int]]）— 一个单词列表，其中每个单词都是一个 id 列表。通过从单词列表中生成一个单词来满足此约束。

一个特殊的 Constraint，通过满足几个约束中的一个来实现。

class transformers.ConstraintListState

<来源>

( constraints: List )

参数

• constraints（List[Constraint]）— 必须由 beam 评分器满足的 Constraint 对象列表。

用于跟踪 beam 评分器通过一系列约束的进度的类。

advance

<来源>

( )

要生成的 token 列表，以便我们可以取得进展。这里的“列表”并不意味着将完全满足约束的 token 列表。

给定约束c_i = {t_ij | j == # of tokens}，如果我们不处于通过特定约束c_i进行进度的中间阶段，我们返回：

[t_k1 for k in indices of unfulfilled constraints]

如果我们处于约束的中间阶段，那么我们返回：[t_ij]，其中i是正在进行的约束的索引，j是约束的下一步。

虽然我们不关心哪个约束先被满足，但如果我们正在满足一个约束，那么这是我们唯一会返回的。

reset

<来源>

( token_ids: Optional )

token_ids：到目前为止生成的 token，以重置通过约束的进度状态。

BeamSearch

class transformers.BeamScorer

<来源>

( )

所有用于 beam_search()和 beam_sample()的 beam 评分器的抽象基类。

process

<来源>

( input_ids: LongTensor next_scores: FloatTensor next_tokens: LongTensor next_indices: LongTensor **kwargs ) → export const metadata = 'undefined';UserDict

参数

• input_ids（形状为(batch_size * num_beams, sequence_length)的torch.LongTensor）— 词汇表中输入序列 token 的索引。

  可以使用任何继承自 PreTrainedTokenizer 的类来获取索引。有关详细信息，请参阅 PreTrainedTokenizer.encode()和 PreTrainedTokenizer.call()。

  什么是输入 ID？

• next_scores（形状为(batch_size, 2 * num_beams)的torch.FloatTensor）— 前2 * num_beams个未完成的 beam 假设的当前分数。

• next_tokens（形状为(batch_size, 2 * num_beams)的torch.LongTensor）— 与前2 * num_beams个未完成的 beam 假设对应的input_ids的 tokens。

• next_indices（形状为(batch_size, 2 * num_beams)的torch.LongTensor）— 指示next_tokens对应于哪个 beam 假设的 beam 索引。

• pad_token_id（int，可选）— 填充标记的 id。

• eos_token_id（Union[int, List[int]]，可选）— 结束序列标记的 id。可选择使用列表设置多个结束序列标记。

• beam_indices（torch.LongTensor，可选）— 指示每个标记对应于哪个 beam 假设的 beam 索引。

• group_index（int，可选）— beam 组的索引。与 group_beam_search()一起使用。

返回值

UserDict

由上述字段组成的字典：

• next_beam_scores（形状为(batch_size * num_beams)的torch.FloatTensor）— 所有未完成 beam 的更新分数。

• next_beam_tokens（形状为(batch_size * num_beams)的torch.FloatTensor）— 要添加到未完成 beam_hypotheses 的下一个标记。

• next_beam_indices（形状为(batch_size * num_beams)的torch.FloatTensor）— 指示下一个标记应添加到哪个 beam 的 beam 索引。

finalize

<来源>

( input_ids: LongTensor next_scores: FloatTensor next_tokens: LongTensor next_indices: LongTensor max_length: int **kwargs ) → export const metadata = 'undefined';torch.LongTensor of shape (batch_size * num_return_sequences, sequence_length)

参数

• input_ids（形状为(batch_size * num_beams, sequence_length)的torch.LongTensor）— 词汇表中输入序列标记的索引。

  可以使用任何继承自 PreTrainedTokenizer 的类来获取索引。有关详细信息，请参阅 PreTrainedTokenizer.encode()和 PreTrainedTokenizer.call()。

  什么是输入 ID？

• final_beam_scores（形状为(batch_size * num_beams)的torch.FloatTensor）— 所有未完成 beam 的最终分数。

• final_beam_tokens（形状为(batch_size * num_beams)的torch.FloatTensor）— 要添加到未完成 beam_hypotheses 的最后一个标记。

• final_beam_indices（形状为(batch_size * num_beams)的torch.FloatTensor）— 指示final_beam_tokens应添加到哪个 beam 的 beam 索引。

• pad_token_id（int，可选）— 填充标记的 id。

• eos_token_id（Union[int, List[int]]，可选）— 结束序列标记的 id。可选择使用列表设置多个结束序列标记。

返回值

torch.LongTensor的形状为(batch_size * num_return_sequences, sequence_length)

生成的序列。第二维（sequence_length）要么等于max_length，要么如果所有批次由于eos_token_id而提前完成，则要短。

class transformers.BeamSearchScorer

<来源>

( batch_size: int num_beams: int device: device length_penalty: Optional = 1.0 do_early_stopping: Union = False num_beam_hyps_to_keep: Optional = 1 num_beam_groups: Optional = 1 max_length: Optional = None )

参数

• batch_size（int）— input_ids的批量大小，用于并行运行标准 beam 搜索解码。

• num_beams（int）— beam 搜索的 beam 数量。

• device（torch.device）— 定义此BeamSearchScorer实例将分配到的设备类型（例如，"cpu"或"cuda"）。

• length_penalty（float，可选，默认为 1.0）— 用于基于 beam 的生成的长度的指数惩罚。它作为指数应用于序列长度，然后用于分割序列的分数。由于分数是序列的对数似然（即负数），length_penalty > 0.0 促进更长的序列，而length_penalty < 0.0 鼓励更短的序列。

• do_early_stopping (bool或str，可选，默认为False) — 控制基于 beam 的方法（如 beam-search）的停止条件。接受以下值：True，生成在有num_beams个完整候选时停止；False，应用启发式方法，当很难找到更好的候选时停止生成；"never"，仅当不能有更好的候选时，beam 搜索过程才会停止（经典 beam 搜索算法）。

• num_beam_hyps_to_keep (int，可选，默认为 1) — 在调用 finalize()时应返回的 beam 假设数量。

• num_beam_groups (int，可选，默认为 1) — 将num_beams分成多个组以确保不同组的 beam 之间的多样性。有关更多详细信息，请参阅此论文。

• max_length (int，可选) — 要生成的序列的最大长度。

BeamScorer 实现标准 beam 搜索解码。

部分改编自Facebook 的 XLM beam 搜索代码。

多样性 beam 搜索算法和实现的参考Ashwin Kalyan 的 DBS 实现

process

<来源>

( input_ids: LongTensor next_scores: FloatTensor next_tokens: LongTensor next_indices: LongTensor pad_token_id: Optional = None eos_token_id: Union = None beam_indices: Optional = None group_index: Optional = 0 decoder_prompt_len: Optional = 0 )

finalize

<来源>

( input_ids: LongTensor final_beam_scores: FloatTensor final_beam_tokens: LongTensor final_beam_indices: LongTensor max_length: int pad_token_id: Optional = None eos_token_id: Union = None beam_indices: Optional = None decoder_prompt_len: Optional = 0 )

class transformers.ConstrainedBeamSearchScorer

<来源>

( batch_size: int num_beams: int constraints: List device: device length_penalty: Optional = 1.0 do_early_stopping: Union = False num_beam_hyps_to_keep: Optional = 1 num_beam_groups: Optional = 1 max_length: Optional = None )

参数

• batch_size (int) — 并行运行标准 beam 搜索解码的input_ids的批处理大小。

• num_beams (int) — beam 搜索的 beam 数量。

• constraints (List[Constraint]) — 以Constraint对象表示的正约束列表，必须在生成输出中满足。有关更多信息，请阅读 Constraint 的文档。

• device (torch.device) — 定义此BeamSearchScorer实例将分配到的设备类型（例如，"cpu"或"cuda"）。

• length_penalty (float，可选，默认为 1.0) — 用于基于 beam 的生成的长度的指数惩罚。它作为序列长度的指数应用，然后用于分割序列的分数。由于分数是序列的对数似然（即负数），length_penalty > 0.0 促进更长的序列，而length_penalty < 0.0 鼓励更短的序列。

• do_early_stopping (bool或str，可选，默认为False) — 控制基于 beam 的方法（如 beam-search）的停止条件。接受以下值：True，生成在有num_beams个完整候选时停止；False，应用启发式方法，当很难找到更好的候选时停止生成；"never"，仅当不能有更好的候选时，beam 搜索过程才会停止（经典 beam 搜索算法）。

• num_beam_hyps_to_keep (int，可选，默认为 1) — 在调用 finalize()时应返回的 beam 假设数量。

• num_beam_groups (int，可选，默认为 1）— 将num_beams分成几组以确保不同组束之间的多样性。有关更多详细信息，请参阅此论文。

• max_length (int，可选）— 要生成的序列的最大长度。

BeamScorer 实现受限束搜索解码。

process

< source >

( input_ids: LongTensor next_scores: FloatTensor next_tokens: LongTensor next_indices: LongTensor scores_for_all_vocab: FloatTensor pad_token_id: Optional = None eos_token_id: Union = None beam_indices: Optional = None decoder_prompt_len: Optional = 0 ) → export const metadata = 'undefined';UserDict

参数

• input_ids (torch.LongTensor，形状为(batch_size * num_beams, sequence_length)）— 词汇表中输入序列标记的索引。

  可以使用任何继承自 PreTrainedTokenizer 的类来获取索引。有关详细信息，请参阅 PreTrainedTokenizer.encode()和 PreTrainedTokenizer.call()。

  什么是输入 ID？

• next_scores (torch.FloatTensor，形状为(batch_size, 2 * num_beams)）— 前2 * num_beams个未完成束假设的当前分数。

• next_tokens (torch.LongTensor，形状为(batch_size, 2 * num_beams)）— 与前2 * num_beams个未完成束假设对应的标记的input_ids。

• next_indices (torch.LongTensor，形状为(batch_size, 2 * num_beams)）— 指示next_tokens对应的束假设的束索引。

• scores_for_all_vocab (torch.FloatTensor，形状为(batch_size * num_beams, sequence_length)）— 每个束假设的词汇表中所有标记的分数。

• pad_token_id (int，可选）— 填充标记的 ID。

• eos_token_id (Union[int, List[int]]，可选）— 结束序列标记的 ID。可以选择使用列表设置多个结束序列标记。

• beam_indices (torch.LongTensor，可选）— 指示每个标记对应的束假设的束索引。

• decoder_prompt_len (int，可选）— 包含在输入到解码器中的提示长度。

返回

UserDict

由上述字段组成的字典：

• next_beam_scores (torch.FloatTensor，形状为(batch_size * num_beams)）— 所有未完成束的更新分数。

• next_beam_tokens (torch.FloatTensor，形状为(batch_size * num_beams)）— 要添加到未完成束假设的下一个标记。

• next_beam_indices (torch.FloatTensor，形状为(batch_size * num_beams)）— 指示下一个标记应添加到哪个束中的束索引。

finalize

< source >

( input_ids: LongTensor final_beam_scores: FloatTensor final_beam_tokens: LongTensor final_beam_indices: LongTensor max_length: int pad_token_id: Optional = None eos_token_id: Union = None beam_indices: Optional = None decoder_prompt_len: Optional = 0 )

实用工具

transformers.top_k_top_p_filtering

< source >

( logits: FloatTensor top_k: int = 0 top_p: float = 1.0 filter_value: float = -inf min_tokens_to_keep: int = 1 )

参数

• top_k (int，可选，默认为 0）— 如果大于 0，则仅保留具有最高概率的前 k 个标记（top-k 过滤）

• top_p (float，可选，默认为 1.0）— 如果小于 1.0，则仅保留累积概率大于等于 top_p 的前几个标记（nucleus 过滤）。Nucleus 过滤在 Holtzman 等人的论文中有描述（arxiv.org/abs/1904.09751)。

• min_tokens_to_keep (int，可选，默认为 1）— 输出中每个批次示例保留的最小标记数。

使用 top-k 和/或 nucleus（top-p）过滤对数分布

来自：gist.github.com/thomwolf/1a5a29f6962089e871b94cbd09daf317

transformers.tf_top_k_top_p_filtering

<来源>

( logits top_k = 0 top_p = 1.0 filter_value = -inf min_tokens_to_keep = 1 )

参数

• top_k（int，可选，默认为 0）— 如果> 0，则仅保留具有最高概率的前 k 个标记（top-k 过滤）

• top_p（float，可选，默认为 1.0）— 如果<1.0，则仅保留累积概率>= top_p 的前几个标记（nucleus 过滤）。Nucleus 过滤在 Holtzman 等人的论文中有描述（arxiv.org/abs/1904.09751）

• min_tokens_to_keep（int，可选，默认为 1）— 输出中每个批示例要保留的最小标记数。

使用 top-k 和/或 nucleus（top-p）过滤对数分布

来自：gist.github.com/thomwolf/1a5a29f6962089e871b94cbd09daf317

流媒体器

class transformers.TextStreamer

<来源>

( tokenizer: AutoTokenizer skip_prompt: bool = False **decode_kwargs )

参数

• tokenizer（AutoTokenizer）— 用于解码标记的标记器。

• skip_prompt（bool，可选，默认为False）— 是否跳过提示以执行.generate()。例如，对于聊天机器人很有用。

• decode_kwargs（dict，可选）— 传递给标记器的decode方法的其他关键字参数。

简单的文本流媒体器，一旦形成完整单词，就会将标记打印到标准输出。

流媒体类的 API 仍在开发中，可能会在未来发生变化。

示例：

>>> from transformers import AutoModelForCausalLM, AutoTokenizer, TextStreamer

>>> tok = AutoTokenizer.from_pretrained("gpt2")
>>> model = AutoModelForCausalLM.from_pretrained("gpt2")
>>> inputs = tok(["An increasing sequence: one,"], return_tensors="pt")
>>> streamer = TextStreamer(tok)

>>> # Despite returning the usual output, the streamer will also print the generated text to stdout.
>>> _ = model.generate(**inputs, streamer=streamer, max_new_tokens=20)
An increasing sequence: one, two, three, four, five, six, seven, eight, nine, ten, eleven,

end

<来源>

( )

刷新任何剩余的缓存并将换行符打印到标准输出。

on_finalized_text

<来源>

( text: str stream_end: bool = False )

将新文本打印到标准输出。如果流结束，也会打印一个换行符。

put

<来源>

( value )

接收标记，解码它们，并在形成完整单词时立即将它们打印到标准输出。

class transformers.TextIteratorStreamer

<来源>

( tokenizer: AutoTokenizer skip_prompt: bool = False timeout: Optional = None **decode_kwargs )

参数

• tokenizer（AutoTokenizer）— 用于解码标记的标记器。

• skip_prompt（bool，可选，默认为False）— 是否跳过提示以执行.generate()。例如，对于聊天机器人很有用。

• timeout（float，可选）— 文本队列的超时时间。如果为None，队列将无限期阻塞。在单独的线程中调用.generate()时，有助于处理异常。

• decode_kwargs（dict，可选）— 传递给标记器的decode方法的其他关键字参数。

将可打印文本存储在队列中的流，供下游应用程序用作迭代器。这对于那些从以非阻塞方式访问生成的文本中受益的应用程序很有用（例如，在交互式 Gradio 演示中）。

流媒体类的 API 仍在开发中，可能会在未来发生变化。

示例：

>>> from transformers import AutoModelForCausalLM, AutoTokenizer, TextIteratorStreamer
>>> from threading import Thread

>>> tok = AutoTokenizer.from_pretrained("gpt2")
>>> model = AutoModelForCausalLM.from_pretrained("gpt2")
>>> inputs = tok(["An increasing sequence: one,"], return_tensors="pt")
>>> streamer = TextIteratorStreamer(tok)

>>> # Run the generation in a separate thread, so that we can fetch the generated text in a non-blocking way.
>>> generation_kwargs = dict(inputs, streamer=streamer, max_new_tokens=20)
>>> thread = Thread(target=model.generate, kwargs=generation_kwargs)
>>> thread.start()
>>> generated_text = ""
>>> for new_text in streamer:
...     generated_text += new_text
>>> generated_text
'An increasing sequence: one, two, three, four, five, six, seven, eight, nine, ten, eleven,'

on_finalized_text

<来源>

( text: str stream_end: bool = False )

将新文本放入队列中。如果流结束，也将停止信号放入队列中。

缓存

class transformers.Cache

<来源>

( )

所有缓存的基类。实际数据结构对于每个子类是特定的。

update

<来源>

( key_states: Tensor value_states: Tensor layer_idx: int cache_kwargs: Optional = None )

参数

• key_states（torch.Tensor）— 要缓存的新键状态。

• value_states（torch.Tensor）— 要缓存的新值状态。

• layer_idx（int）— 用于缓存状态的层的索引。

• cache_kwargs (Dict[str, Any], optional) — 缓存子类的额外参数。这些参数针对每个子类是特定的，并允许创建新类型的缓存。

使用新的key_states和value_states更新层layer_idx的缓存。

class transformers.DynamicCache

<来源>

( )

随着生成更多令牌，缓存会动态增长。这是生成模型的默认设置。

它将键和值状态存储为张量列表，每个层一个张量。每个张量的预期形状为[batch_size, num_heads, seq_len, head_dim]。

update

<来源>

( key_states: Tensor value_states: Tensor layer_idx: int cache_kwargs: Optional = None )

参数

• key_states (torch.Tensor) — 要缓存的新键状态。

• value_states (torch.Tensor) — 要缓存的新值状态。

• layer_idx (int) — 要为其缓存状态的层的索引。

• cache_kwargs (Dict[str, Any], optional) — 缓存子类的额外参数。在DynamicCache中不使用额外参数。

使用新的key_states和value_states更新层layer_idx的缓存。

get_seq_length

<来源>

( layer_idx: Optional = 0 )

返回缓存状态的序列长度。可以选择传递层索引。

reorder_cache

<来源>

( beam_idx: LongTensor )

为束搜索重新排序缓存，给定所选的束索引。

to_legacy_cache

<来源>

( )

将DynamicCache实例转换为其在传统缓存格式中的等效形式。

from_legacy_cache

<来源>

( past_key_values: Optional = None )

将传统缓存格式中的缓存转换为等效的DynamicCache。

class transformers.SinkCache

<来源>

( window_length: int num_sink_tokens: int )

参数

• window_length (int) — 上下文窗口的长度。

• num_sink_tokens (int) — 沉没令牌的数量。有关更多信息，请参阅原始论文。

如Attention Sinks 论文中描述的缓存。它允许模型在超出其上下文窗口长度的情况下生成，而不会失去对话流畅性。随着丢弃过去的令牌，模型将失去生成依赖于被丢弃上下文的令牌的能力。

它将键和值状态存储为张量列表，每个层一个张量。每个张量的预期形状为[batch_size, num_heads, seq_len, head_dim]。

update

<来源>

( key_states: Tensor value_states: Tensor layer_idx: int cache_kwargs: Optional = None )

参数

• key_states (torch.Tensor) — 要缓存的新键状态。

• value_states (torch.Tensor) — 要缓存的新值状态。

• layer_idx (int) — 要为其缓存状态的层的索引。

• cache_kwargs (Dict[str, Any], optional) — 缓存子类的额外参数。在SinkCache中可以使用以下参数：sin，cos和partial_rotation_size。这些参数用于使用 RoPE 的模型，在令牌移位时重新计算旋转。

使用新的key_states和value_states更新层layer_idx的缓存。

get_seq_length

<来源>

( layer_idx: Optional = 0 )

返回缓存状态的序列长度。可以选择传递层索引。

reorder_cache

<来源>

( beam_idx: LongTensor )

重新排列缓存以进行波束搜索，给定所选的波束索引。