Transformers 4.37 中文文档（八十一）（3）

Transformers 4.37 中文文档（八十一）（2）https://developer.aliyun.com/article/1563270

WhisperForConditionalGeneration

class transformers.WhisperForConditionalGeneration

<来源>

( config: WhisperConfig )

参数

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

带有语言建模头的 Whisper 模型。可用于自动语音识别。此模型继承自 PreTrainedModel。查看超类文档以获取库为所有模型实现的通用方法（如下载或保存、调整输入嵌入、修剪头等）。

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

forward

<来源>

( input_features: Optional = None attention_mask: Optional = None decoder_input_ids: 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 decoder_inputs_embeds: Optional = None decoder_position_ids: Optional = None labels: Optional = None use_cache: Optional = None output_attentions: Optional = None output_hidden_states: Optional = None return_dict: Optional = None ) → export const metadata = 'undefined';transformers.modeling_outputs.Seq2SeqLMOutput or tuple(torch.FloatTensor)

参数

• input_features（形状为(batch_size, feature_size, sequence_length)的torch.FloatTensor）- 从原始语音波形中提取的浮点值 mel 特征。原始语音波形可以通过将.flac或.wav音频文件加载到类型为List[float]或numpy.ndarray的数组中获得，例如通过 soundfile 库（pip install soundfile）。要将数组准备成input_features，应使用 AutoFeatureExtractor 来提取 mel 特征，填充并转换为torch.FloatTensor类型的张量。参见call()
  
• attention_mask（形状为(batch_size, sequence_length)的torch.LongTensor，可选）- 用于避免在填充标记索引上执行SpecAugment数据增强的掩码。掩码值选定在[0, 1]范围内：

• 1 表示头部未被掩盖,
  
• 0 表示被掩盖的标记。
  

• 什么是注意力掩码？
  
• decoder_input_ids（形状为(batch_size, target_sequence_length)的torch.LongTensor，可选）- 词汇表中解码器输入序列标记的索引。
  可以使用 WhisperTokenizer 获取索引。有关详细信息，请参见 PreTrainedTokenizer.encode()和 PreTrainedTokenizer.call()。
  什么是解码器输入 ID？
  Whisper 使用decoder_start_token_id作为decoder_input_ids生成的起始标记。如果使用past_key_values，则可能只需输入最后的decoder_input_ids（请参见past_key_values）。
  
• decoder_attention_mask（形状为(batch_size, target_sequence_length)的torch.LongTensor，可选）- 默认行为：生成一个忽略decoder_input_ids中填充标记的张量。因果掩码也将默认使用。
  如果要更改填充行为，应阅读modeling_whisper._prepare_decoder_attention_mask并根据需要进行修改。有关默认策略的更多信息，请参见BART 论文中的图表 1。
  
• 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)，可选）— 元组包含（last_hidden_state，可选：hidden_states，可选：attentions）last_hidden_state的形状为(batch_size, sequence_length, 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输入）。
  如果使用past_key_values，用户可以选择只输入最后一个形状为(batch_size, 1)的decoder_input_ids（那些没有将它们的过去键值状态提供给此模型的输入），而不是形状为(batch_size, sequence_length)的所有decoder_input_ids。
  
• decoder_inputs_embeds（形状为(batch_size, target_sequence_length, hidden_size)的torch.FloatTensor，可选）— 可选地，可以直接传递嵌入表示，而不是传递decoder_input_ids。如果使用past_key_values，可以选择仅输入最后一个decoder_inputs_embeds（参见past_key_values）。如果您想要更多控制如何将decoder_input_ids索引转换为相关向量，而不是模型内部的嵌入查找矩阵，则这很有用。
  
• use_cache（bool，可选）— 如果设置为True，将返回past_key_values键值状态，并可用于加速解码（参见past_key_values）。
  
• output_attentions（bool，可选）— 是否返回所有注意力层的注意力张量。有关更多详细信息，请参见返回张量下的attentions。
  
• output_hidden_states（bool，可选）— 是否返回所有层的隐藏状态。有关更多详细信息，请参见返回张量下的hidden_states。
  
• return_dict（bool，可选）— 是否返回一个 ModelOutput 而不是一个普通元组。
  
• labels（形状为(batch_size, sequence_length)的torch.LongTensor，可选）— 用于计算语言建模损失的标签。索引应该在[0, ..., config.vocab_size]范围内，或者为-100（参见input_ids文档字符串）。索引设置为-100的标记将被忽略（掩盖），损失仅计算具有[0, ..., config.vocab_size]标签的标记。
  

返回

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

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

• loss（形状为(1,)的torch.FloatTensor，可选，在提供labels时返回）— 语言建模损失。
  
• logits（形状为(batch_size, sequence_length, config.vocab_size)的torch.FloatTensor）— 语言建模头的预测分数（SoftMax 之前每个词汇标记的分数）。
  
• 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 (torch.FloatTensor，形状为(batch_size, sequence_length, hidden_size)，可选) — 模型编码器最后一层的隐藏状态序列。
  
• 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 之后，用于计算自注意力头中的加权平均值。
  

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

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

示例：

>>> import torch
>>> 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")
>>> input_features = inputs.input_features
>>> generated_ids = model.generate(inputs=input_features)
>>> transcription = processor.batch_decode(generated_ids, skip_special_tokens=True)[0]
>>> transcription
' Mr. Quilter is the apostle of the middle classes, and we are glad to welcome his gospel.'

generate

<来源>

( input_features: Optional = None generation_config: Optional = None logits_processor: Optional = None stopping_criteria: Optional = None prefix_allowed_tokens_fn: Optional = None synced_gpus: bool = False return_timestamps: Optional = None task: Optional = None language: Optional = None is_multilingual: Optional = None prompt_ids: Optional = None condition_on_prev_tokens: Optional = None temperature: Union = None compression_ratio_threshold: Optional = None logprob_threshold: Optional = None no_speech_threshold: Optional = None num_segment_frames: Optional = None attention_mask: Optional = None time_precision: float = 0.02 return_token_timestamps: Optional = None return_segments: bool = False return_dict_in_generate: Optional = None **kwargs ) → export const metadata = 'undefined';ModelOutput or torch.LongTensor or Dict[str, Any]

参数

• input_features（torch.Tensor，形状为(batch_size, feature_size, sequence_length)，可选）— 浮点值的对数梅尔特征，从原始语音波形中提取。原始语音波形可以通过将.flac或.wav音频文件加载到List[float]类型的数组或numpy.ndarray中获得，例如通过 soundfile 库（pip install soundfile）。要将数组准备成input_features，应使用 AutoFeatureExtractor 来提取梅尔特征，填充并转换为torch.FloatTensor类型的张量。详细信息请参见call()。
  
• generation_config（~generation.GenerationConfig，可选）— 用作生成调用的基本参数化的生成配置。传递给生成的**kwargs与generation_config的属性匹配将覆盖它们。如果未提供generation_config，将使用默认值，其加载优先级如下：1）从generation_config.json模型文件中，如果存在；2）从模型配置中。请注意，未指定的参数将继承 GenerationConfig 的默认值，应检查其文档以参数化生成。
  
• logits_processor（LogitsProcessorList，可选）— 自定义对数处理器，补充由参数和生成配置构建的默认对数处理器。如果传递的对数处理器已经使用参数或生成配置创建，则会引发错误。此功能适用于高级用户。
  
• stopping_criteria（StoppingCriteriaList，可选）— 自定义停止标准，补充由参数和生成配置构建的默认停止标准。如果传递的停止标准已经使用参数或生成配置创建，则会引发错误。此功能适用于高级用户。
  
• prefix_allowed_tokens_fn（Callable[[int, torch.Tensor], List[int]]，可选）— 如果提供，此函数将在每个步骤将束搜索限制为仅允许的标记。如果未提供，则不应用约束。此函数接受 2 个参数：批次 IDbatch_id和input_ids。它必须返回一个列表，其中包含下一代步骤的允许标记，条件是批次 IDbatch_id和先前生成的标记inputs_ids。此参数对于受前缀约束的生成很有用，如自回归实体检索中所述。
  
• synced_gpus（bool，可选，默认为False）— 是否继续运行 while 循环直到 max_length（对于 ZeRO 阶段 3 是必需的）
  
• return_timestamps（bool，可选）— 是否返回文本的时间戳。这将启用WhisperTimestampsLogitsProcessor。
  
• task（str，可选）— 用于生成的任务，可以是“translate”或“transcribe”。model.config.forced_decoder_ids将相应更新。
  
• language（str，optional）–用于生成的语言标记，可以是<|en|>、en或english形式。您可以在model.generation_config.lang_to_id字典中找到所有可能的语言标记。
  
• is_multilingual（bool，可选）— 模型是否是多语言的。
  
• prompt_ids（torch.Tensor，可选）— 通过将文本传递给get_prompt_ids()创建的令牌 ID 的秩-1 张量，作为每个块的提示提供。这可用于为转录提供或“提示工程”上下文，例如自定义词汇或专有名词，以使其更有可能正确预测这些单词。它不能与decoder_start_token_id结合使用，因为它会覆盖此值。
  
• condition_on_prev_tokens（bool，可选）— 仅适用于长篇转录。是否将每个片段的生成条件设置为前一个片段。如Whisper 论文所示，这可以帮助提高性能。
  
• temperature (float 或 float 列表，可选) — 用于生成的温度。传递单个 float 值并且 do_sample=True 会激活使用采样进行生成。对于长篇转录，可以通过传递一组浮点值（例如 (0.0, 0.2, 0.4, 0.6, 0.8, 1.0)）来激活温度回退。正如Whisper 论文所示，这可以帮助提高性能。
  
• compression_ratio_threshold (float, 可选) — 仅适用于长篇转录。如果定义了，将计算每个片段的 zlib 压缩率。如果一个片段的压缩率高于 compression_ratio_threshold，则激活温度回退：生成的片段被丢弃，使用更高的温度重复生成。这个特性背后的直觉是，具有非常高压缩率的片段存在大量重复。通过增加温度注入更多随机性可以减少不需要的重复。如果定义了 compression_ratio_threshold，请确保 temperature 是一个值列表。compression_ratio_threshold 的常见值为 1.35。正如Whisper 论文所示，这可以帮助提高性能。
  
• logprob_threshold (float, 可选) — 仅适用于长篇转录。如果定义了，将计算每个片段的平均对数概率。如果给定片段的对数概率低于 logprob_threshold，则激活温度回退：生成的片段被丢弃，使用更高的温度重复生成。这个特性背后的直觉是，低对数概率的片段可以通过增加温度注入更多随机性来改善。如果定义了 logprob_threshold，请确保 temperature 是一个值列表。logprob_threshold 的常见值为 -1.0。正如Whisper 论文所示，这可以帮助提高性能。
  
• no_speech_threshold (float, 可选) — 仅适用于长篇转录。如果定义了，“无语音”标记与 logprob_threshold 结合使用来确定一个片段是否只包含静音。在这种情况下，将跳过该片段的转录。正如Whisper 论文所示，这可以帮助提高性能。
  
• num_segment_frames (int, 可选) — 单个片段包含的帧数。如果未定义，num_segment_frames 默认为模型的步幅乘以最大输入长度。
  
• attention_mask (torch.Tensor, 可选) — 在使用批量大小 > 1 进行长篇转录时需要传递 attention_mask。
  
• time_precision (int, 可选, 默认为 0.02) — 输出标记的持续时间（秒）。例如，0.02 表示生成的标记平均占据 20 毫秒。
  
• return_token_timestamps (bool, 可选) — 是否返回文本的标记级时间戳。可以与 return_timestamps 选项一起使用。要获得单词级时间戳，请使用分词器将标记分组成单词。
  
• return_segments (bool, 可选, 默认为 False) — 是否额外返回所有片段的列表。请注意，只有在进行长篇转录时才能启用此选项。
  
• return_dict_in_generate (bool, 可选, 默认为 False) — 是否返回 ModelOutput 而不仅仅返回生成的标记。请注意，在进行长篇转录时，只有在设置 return_segments 为 True 时才能启用 return_dict_in_generate。在这种情况下，每个片段的生成输出将添加到每个片段中。
  
• kwargs（Dict[str, Any]，可选）-generate_config的特定于特定模型的参数化和/或其他模型特定 kwargs，将转发到模型的forward函数。如果模型是编码器-解码器模型，则不应以前缀形式指定编码器特定 kwargs，而应以*decoder_*为前缀指定解码器特定 kwargs。
  

返回

ModelOutput 或torch.LongTensor或Dict[str, Any]

一个 ModelOutput（如果return_dict_in_generate=True或当config.return_dict_in_generate=True时）或一个torch.FloatTensor或一个段的字典，当return_segments=True时。

如果传入的输入> 30 秒/ > 3000 mel 输入特征，并且return_segments=True，则返回一个生成的序列 id 字典，称为sequences，以及每个生成段的列表。

否则，如果传入的输入<= 30 秒/ >= 3000 mel 输入特征，则可能的 ModelOutput 类型为：

• GenerateEncoderDecoderOutput，
  
• GenerateBeamEncoderDecoderOutput
  

否则，仅返回生成的输出序列 id。

将对数 mel 输入特征转录或翻译为自回归生成的令牌 id 序列。

大多数生成控制参数都在generation_config中设置，如果未传递，则将设置为模型的默认生成配置。您可以通过将相应的参数传递给 generate()来覆盖任何generation_config，例如.generate(inputs, num_beams=4, do_sample=True)。

有关生成策略和代码示例的概述，请查看以下指南。

示例：

• 详细转录：要转录或翻译超过 30 秒的音频，请处理音频文件而不截断，并一次传递所有 mel 特征以生成。

>>> import torch
>>> from transformers import AutoProcessor, WhisperForConditionalGeneration
>>> from datasets import load_dataset, Audio
>>> processor = AutoProcessor.from_pretrained("openai/whisper-tiny.en")
>>> model = WhisperForConditionalGeneration.from_pretrained("openai/whisper-tiny.en")
>>> model.cuda()
>>> # load audios > 30 seconds
>>> ds = load_dataset("distil-whisper/meanwhile", "default")["test"]
>>> # resample to 16kHz
>>> ds = ds.cast_column("audio", Audio(sampling_rate=16000))
>>> # take first 8 audios and retrieve array
>>> audio = ds[:8]["audio"]
>>> audio = [x["array"] for x in audio]
>>> # make sure to NOT truncate the input audio, to return the `attention_mask` and to pad to the longest audio
>>> inputs = processor(audio, return_tensors="pt", truncation=False, padding="longest", return_attention_mask=True, sampling_rate=16_000)
>>> inputs = inputs.to("cuda", torch.float32)
>>> # transcribe audio to ids
>>> generated_ids = model.generate(**inputs)
>>> transcription = processor.batch_decode(generated_ids, skip_special_tokens=True)
>>> transcription[0]
' Folks, if you watch the show, you know, I spent a lot of time right over there. Patiently and astutely scrutinizing the boxwood and mahogany chest set of the day's biggest stories developing the central headline pawns, definitely maneuvering an oso topical night to F6, fainting a classic Sicilian, nade door variation on the news, all the while seeing eight moves deep and patiently marshalling the latest press releases into a fisher's shows in Lip Nitsky attack that culminates in the elegant lethal slow-played, all-passant checkmate that is my nightly monologue. But sometimes, sometimes, folks, I. CHEERING AND APPLAUSE Sometimes I startle away, cubside down in the monkey bars of a condemned playground on a super fun site. Get all hept up on goofballs. Rummage that were discarded tag bag of defective toys. Yank out a fist bowl of disembodied doll limbs, toss them on a stained kid's place mat from a defunct dennies. set up a table inside a rusty cargo container down by the Wharf and challenged toothless drifters to the godless bughouse blitz of tournament that is my segment. Meanwhile!'

• 简化转录：如果传入的 mel 输入特征< 30 秒，则整个音频将通过一次调用生成进行转录。

>>> import torch
>>> 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")
>>> input_features = inputs.input_features
>>> generated_ids = model.generate(inputs=input_features)
>>> transcription = processor.batch_decode(generated_ids, skip_special_tokens=True)[0]
>>> transcription
' Mr. Quilter is the apostle of the middle classes, and we are glad to welcome his gospel.'

Transformers 4.37 中文文档（八十一）（4）https://developer.aliyun.com/article/1563272