# Speech2Text

## 概述

Speech2Text 模型由 Changhan Wang、Yun Tang、Xutai Ma、Anne Wu、Dmytro Okhonko 和 Juan Pino 在 [fairseq S2T: Fast Speech-to-Text Modeling with fairseq](https://huggingface.co/papers/2010.05171) 中提出。它是一种基于 Transformer 的 seq2seq（编码器-解码器）模型，专为端到端的自动语音识别（ASR）和语音翻译（ST）而设计。该模型使用卷积下采样器，在语音输入送入编码器之前将其长度缩短 3/4。模型使用标准的自回归交叉熵损失进行训练，并以自回归方式生成转录文本或翻译结果。Speech2Text 已在多个 ASR 和 ST 数据集上进行了微调：[LibriSpeech](http://www.openslr.org/12)、[CoVoST 2](https://github.com/facebookresearch/covost)、[MuST-C](https://ict.fbk.eu/must-c/)。

该模型由 [valhalla](https://huggingface.co/valhalla) 贡献。原始代码可在[此处](https://github.com/pytorch/fairseq/tree/master/examples/speech_to_text)找到。

## 推理

Speech2Text 是一种语音模型，它接受从语音信号中提取的 log-mel 滤波器组特征的浮点张量。它是一个基于 Transformer 的 seq2seq 模型，因此转录/翻译结果是自回归生成的。可以使用 `generate()` 方法进行推理。

[Speech2TextFeatureExtractor](/docs/transformers/v5.23.0/zh/model_doc/speech_to_text#transformers.Speech2TextFeatureExtractor) 类负责提取对数梅尔滤波器组特征。[Speech2TextProcessor](/docs/transformers/v5.23.0/zh/model_doc/speech_to_text#transformers.Speech2TextProcessor) 将 [Speech2TextFeatureExtractor](/docs/transformers/v5.23.0/zh/model_doc/speech_to_text#transformers.Speech2TextFeatureExtractor) 和 [Speech2TextTokenizer](/docs/transformers/v5.23.0/zh/model_doc/speech_to_text#transformers.Speech2TextTokenizer) 封装为单一实例，以同时提取输入特征并解码预测的 token id。

特征提取器依赖于 `torchaudio`，分词器依赖于 `sentencepiece`，因此在运行示例之前，请务必安装这些包。你可以通过 `pip install transformers"[speech, sentencepiece]"` 将它们作为额外的语音依赖项安装，或者使用 `pip install torchaudio sentencepiece` 单独安装这些包。此外，`torchaudio` 需要 [libsndfile](http://www.mega-nerd.com/libsndfile/) 包的开发者版本，该版本可通过系统包管理器安装。在 Ubuntu 上，可以按以下方式安装：`apt install libsndfile1-dev`

- ASR 与语音翻译

```python
from datasets import load_dataset

from transformers import Speech2TextForConditionalGeneration, Speech2TextProcessor

model = Speech2TextForConditionalGeneration.from_pretrained("facebook/s2t-small-librispeech-asr", device_map="auto")
processor = Speech2TextProcessor.from_pretrained("facebook/s2t-small-librispeech-asr")

ds = load_dataset("hf-internal-testing/librispeech_asr_demo", "clean", split="validation")

inputs = processor(ds[0]["audio"]["array"], sampling_rate=ds[0]["audio"]["sampling_rate"], return_tensors="pt").to(model.device)
generated_ids = model.generate(inputs["input_features"], attention_mask=inputs["attention_mask"])

transcription = processor.batch_decode(generated_ids, skip_special_tokens=True)
transcription
['mister quilter is the apostle of the middle classes and we are glad to welcome his gospel']
```

- 多语言语音翻译

  对于多语言语音翻译模型，`eos_token_id` 用作 `decoder_start_token_id`，并且目标语言 id 被强制作为第一个生成的 token。要将目标语言 id 强制作为第一个生成的 token，请将 `forced_bos_token_id` 参数传递给 `generate()` 方法。以下示例展示了如何使用 *facebook/s2t-medium-mustc-multilingual-st* 检查点将英语语音翻译为法语文本。

```python
from datasets import load_dataset

from transformers import Speech2TextForConditionalGeneration, Speech2TextProcessor

model = Speech2TextForConditionalGeneration.from_pretrained("facebook/s2t-medium-mustc-multilingual-st", device_map="auto")
processor = Speech2TextProcessor.from_pretrained("facebook/s2t-medium-mustc-multilingual-st")

ds = load_dataset("hf-internal-testing/librispeech_asr_demo", "clean", split="validation")

inputs = processor(ds[0]["audio"]["array"], sampling_rate=ds[0]["audio"]["sampling_rate"], return_tensors="pt").to(model.device)
generated_ids = model.generate(
    inputs["input_features"],
    attention_mask=inputs["attention_mask"],
    forced_bos_token_id=processor.tokenizer.lang_code_to_id["fr"],
)

translation = processor.batch_decode(generated_ids, skip_special_tokens=True)
translation
["(Vidéo) Si M. Kilder est l'apossible des classes moyennes, et nous sommes heureux d'être accueillis dans son évangile."]
```

请查看 [model hub](https://huggingface.co/models?filter=speech_to_text) 以查找 Speech2Text 检查点。

## Speech2TextConfig[[transformers.Speech2TextConfig]]

#### transformers.Speech2TextConfig[[transformers.Speech2TextConfig]]

```python
transformers.Speech2TextConfig(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, is_encoder_decoder: bool = True, vocab_size: int = 10000, encoder_layers: int = 12, encoder_ffn_dim: int = 2048, encoder_attention_heads: int = 4, decoder_layers: int = 6, decoder_ffn_dim: int = 2048, decoder_attention_heads: int = 4, encoder_layerdrop: float | int = 0.0, decoder_layerdrop: float | int = 0.0, use_cache: bool = True, activation_function: str = 'relu', d_model: int = 256, dropout: float | int = 0.1, attention_dropout: float | int = 0.0, activation_dropout: float | int = 0.0, init_std: float = 0.02, decoder_start_token_id: int = 2, scale_embedding: bool = True, pad_token_id: int | None = 1, bos_token_id: int | None = 0, eos_token_id: int | list[int] | None = 2, max_source_positions: int = 6000, max_target_positions: int = 1024, num_conv_layers: int = 2, conv_kernel_sizes: list[int] | tuple[int, ...] = (5, 5), conv_channels: int = 1024, input_feat_per_channel: int = 80, input_channels: int = 1, tie_word_embeddings: bool = True)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/speech_to_text/configuration_speech_to_text.py#L24)

**参数：**

is_encoder_decoder (`bool`，*可选*，默认为 `True`)：模型是否用作编码器/解码器。

vocab_size (`int`，*可选*，默认为 `10000`)：模型的词汇表大小。定义了 `input_ids` 可以表示的不同 token 数量。

encoder_layers (`int`，*可选*，默认为 `12`)：Transformer 编码器中的隐藏层数。如果未设置，将使用与 `num_layers` 相同的值。

encoder_ffn_dim (`int`，*可选*，默认为 `2048`)：编码器中“中间”（通常称为前馈）层的维度。

encoder_attention_heads (`int`，*可选*，默认为 `4`)：Transformer 编码器中每个注意力层的注意力头数量。

decoder_layers (`int`，*可选*，默认为 `6`)：Transformer 解码器中的隐藏层数。如果未设置，将使用与 `num_layers` 相同的值。

decoder_ffn_dim (`int`，*可选*，默认为 `2048`)：解码器中“中间”（通常称为前馈）层的维度。

decoder_attention_heads (`int`，*可选*，默认为 `4`)：Transformer 解码器中每个注意力层的注意力头数量。

encoder_layerdrop (`Union[float, int]`，*可选*，默认为 `0.0`)：编码器的 LayerDrop 概率。有关更多详细信息，请参阅 [LayerDrop 论文](see https://huggingface.co/papers/1909.11556)。

decoder_layerdrop (`Union[float, int]`，*可选*，默认值为 `0.0`)：解码器的 LayerDrop 概率。有关更多详细信息，请参阅 [LayerDrop 论文](see https://huggingface.co/papers/1909.11556)。

use_cache (`bool`，*可选*，默认为 `True`)：模型是否应返回最后的键/值注意力（并非所有模型都使用）。仅当 `config.is_decoder=True` 或模型为仅解码器生成模型时相关。

activation_function (`str`，*可选*，默认为 `relu`)：解码器中的非线性激活函数（函数或字符串）。例如，`"gelu"`、`"relu"`、`"silu"` 等。

d_model (`int`，*可选*，默认为 `256`)：编码器层和池化层的大小。

dropout (`Union[float, int]`，*可选*，默认为 `0.1`)：所有 dropout 层的比率。

attention_dropout (`Union[float, int]`，*可选*，默认值为 `0.0`)：注意力概率的 dropout 比率。

activation_dropout (`Union[float, int]`，*可选*，默认值为 `0.0`)：全连接层内部激活值的 dropout 比率。

init_std (`float`，*可选*，默认值为 `0.02`)：用于初始化所有权重矩阵的 truncated_normal_initializer 的标准差。

decoder_start_token_id (`int`，*可选*，默认为 `2`)：如果编码器-解码器模型以不同于 `bos` 的 token 开始解码，则该 token 的 id。

scale_embedding (`bool`, *可选*, 默认为 `True`) : 是否通过将嵌入除以 sqrt(d_model) 来对其进行缩放。

pad_token_id (`int`，*可选*，默认为 `1`)：词表中用于填充的 token id。

bos_token_id (`int`，*可选*，默认为 `0`)：词汇表中用于表示流开始的 token id。

eos_token_id (`Union[int, list[int]]`，*可选*，默认为 `2`)：词汇表中用于表示流结束（end-of-stream）的 token id。

max_source_positions (`int`, *可选*，默认为 6000)：该模型可能使用的对数梅尔滤波器组特征的最大序列长度。

max_target_positions (`int`, *可选*，默认为 1024)：该模型可能使用的最大序列长度。通常，建议将其设置为一个较大的值以防万一（例如 512、1024 或 2048）。

num_conv_layers (`int`, *可选*，默认为 2)：卷积模块中一维卷积层的数量。

conv_kernel_sizes (`tuple[int]`, *可选*, 默认为 `(5, 5)`) : 一个整数元组，用于定义卷积模块中每个一维卷积层的核大小。`conv_kernel_sizes` 的长度必须与 `num_conv_layers` 相匹配。

conv_channels (`int`，*可选*，默认为 1024)：一个整数，用于定义卷积模块中除最后一层外每个卷积层的输出通道数。

input_feat_per_channel (`int`，*可选*，默认为 80)：一个整数，指定特征向量的大小。这也是对数梅尔滤波器组特征的维度。

input_channels (`int`，*可选*，默认为 `1`)：输入通道数。

tie_word_embeddings (`bool`，*可选*，默认为 `True`)：是否根据模型的 `tied_weights_keys` 映射来绑定权重嵌入。

这是用于存储 Speech2TextModel 配置的类。它根据指定的参数实例化语音转文本模型，并定义模型架构。使用默认值实例化配置将得到与 [facebook/s2t-small-librispeech-asr](https://huggingface.co/facebook/s2t-small-librispeech-asr) 类似的配置。

配置对象继承自 [PreTrainedConfig](/docs/transformers/v5.23.0/zh/main_classes/configuration#transformers.PreTrainedConfig)，可用于控制模型输出。有关更多信息，请参阅 [PreTrainedConfig](/docs/transformers/v5.23.0/zh/main_classes/configuration#transformers.PreTrainedConfig) 的文档。

示例：

```python
>>> from transformers import Speech2TextConfig, Speech2TextModel

>>> # Initializing a Speech2Text s2t_transformer_s style configuration
>>> configuration = Speech2TextConfig()

>>> # Initializing a model (with random weights) from the s2t_transformer_s style configuration
>>> model = Speech2TextModel(configuration)

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

## Speech2TextTokenizer[[transformers.Speech2TextTokenizer]]

#### transformers.Speech2TextTokenizer[[transformers.Speech2TextTokenizer]]

```python
transformers.Speech2TextTokenizer(vocab_file, spm_file, bos_token = '<s>', eos_token = '</s>', pad_token = '<pad>', unk_token = '<unk>', do_upper_case = False, do_lower_case = False, tgt_lang = None, lang_codes = None, additional_special_tokens = None, sp_model_kwargs: dict[str, typing.Any] | None = None, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/speech_to_text/tokenization_speech_to_text.py#L49)

**参数：**

vocab_file (`str`) : 包含词汇表的文件。

spm_file (`str`) : [SentencePiece](https://github.com/google/sentencepiece) 模型文件的路径

bos_token (`str`，*可选*，默认为 `"<s>"`)：句子起始标记。

eos_token (`str`，*可选*，默认为 `"</s>"`)：句子结束标记。

unk_token (`str`，*可选*，默认为 `"<unk>"`)：未知标记。不在词汇表中的标记无法转换为 ID，因此会被设置为该标记。

pad_token (`str`，*可选*，默认为 `"<pad>"`)：用于填充的标记，例如在对长度不同的序列进行批处理时。

do_upper_case (`bool`，*可选*，默认为 `False`)：解码时是否将输出转换为大写。

do_lower_case (`bool`，*可选*，默认为 `False`)：分词时是否将输入转换为小写。

tgt_lang (`str`, *可选*) : 表示目标语言的字符串。

sp_model_kwargs (`dict`, *可选*) : 将传递给 `SentencePieceProcessor.__init__()` 方法。[SentencePiece 的 Python 封装](https://github.com/google/sentencepiece/tree/master/python) 可用于设置以下参数： - `enable_sampling`：启用子词正则化。 - `nbest_size`：unigram 的采样参数。对 BPE-Dropout 无效。  - `nbest_size = {0,1}`：不执行采样。 - `nbest_size > 1`：从 nbest_size 个结果中进行采样。 - `nbest_size < 0`：假设 nbest_size 为无穷大，并使用前向过滤与后向采样算法从所有假设（格）中进行采样。  - `alpha`：unigram 采样的平滑参数，以及 BPE-dropout 中合并操作的 dropout 概率。

- ****kwargs** : 传递给 [PreTrainedTokenizer](/docs/transformers/v5.23.0/zh/main_classes/tokenizer#transformers.PythonBackend) 的额外关键字参数

构建一个 Speech2Text 分词器。

该分词器继承自 [PreTrainedTokenizer](/docs/transformers/v5.23.0/zh/main_classes/tokenizer#transformers.PythonBackend)，其中包含一些主要方法。有关这些方法的更多信息，请参阅其父类。

#### build_inputs_with_special_tokens[[transformers.Speech2TextTokenizer.build_inputs_with_special_tokens]]

```python
build_inputs_with_special_tokens(token_ids_0, token_ids_1 = None)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/speech_to_text/tokenization_speech_to_text.py#L206)

通过追加 eos_token_id 从序列构建模型输入。

#### get_special_tokens_mask[[transformers.Speech2TextTokenizer.get_special_tokens_mask]]

```python
get_special_tokens_mask(token_ids_0: list[int], token_ids_1: list[int] | None = None, already_has_special_tokens: bool = False)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/speech_to_text/tokenization_speech_to_text.py#L213)

**参数：**

token_ids_0 (`list[int]`) : ID 列表。

token_ids_1 (`list[int]`, *可选*) : 用于序列对的可选第二个 ID 列表。

already_has_special_tokens (`bool`，*可选*，默认为 `False`)：标记列表是否已使用模型的特殊标记进行格式化。

**返回：** `list[int]`

一个整数列表，取值范围为 [0, 1]：1 表示特殊标记，0 表示序列标记。

从未添加特殊标记的标记列表中获取序列 ID。当使用分词器的 `prepare_for_model` 方法添加特殊标记时，会调用此方法。

#### create_token_type_ids_from_sequences[[transformers.Speech2TextTokenizer.create_token_type_ids_from_sequences]]

```python
create_token_type_ids_from_sequences(token_ids_0: list[int], token_ids_1: list[int] | None = None)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/tokenization_python.py#L1301)

**参数：**

token_ids_0 (`list[int]`) : ID 列表。

token_ids_1 (`list[int]`, *可选*) : 用于序列对的可选第二个 ID 列表。

**返回：** `list[int]`

根据配置的模式生成的 Token 类型 ID。

创建一个掩码，该掩码由传入的两个序列生成，用于序列对分类任务。

此方法根据分词器的配置属性动态构建 token 类型 ID：
- `token_type_ids_pattern`：要使用的模式（"all_zeros" 或 "bert_style"）
- `token_type_ids_include_special_tokens`：在长度计算中是否考虑特殊标记

示例：
```python
# All zeros pattern (default, used by RoBERTa, BART, etc.)
tokenizer.token_type_ids_pattern = "all_zeros"
# Returns: [0, 0, 0, ...] for both sequences

# BERT-style pattern (first sequence gets 0s, second gets 1s)
tokenizer.token_type_ids_pattern = "bert_style"
# Returns: [0, 0, 0, ..., 1, 1, 1, ...] for sequence pairs
```

#### save_vocabulary[[transformers.Speech2TextTokenizer.save_vocabulary]]

```python
save_vocabulary(save_directory: str, filename_prefix: str | None = None)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/speech_to_text/tokenization_speech_to_text.py#L257)

## Speech2TextFeatureExtractor[[transformers.Speech2TextFeatureExtractor]]

#### transformers.Speech2TextFeatureExtractor[[transformers.Speech2TextFeatureExtractor]]

```python
transformers.Speech2TextFeatureExtractor(feature_size = 80, sampling_rate = 16000, num_mel_bins = 80, padding_value = 0.0, dither = 0.0, do_ceptral_normalize = True, normalize_means = True, normalize_vars = True, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/speech_to_text/feature_extraction_speech_to_text.py#L33)

**参数：**

feature_size (`int`，*可选*，默认为 80)：提取特征的维度。

sampling_rate (`int`，*可选*，默认值为 16000)：音频文件应被数字化采样的采样率，单位为赫兹（Hz）。

num_mel_bins (`int`，*可选*，默认为 80)：梅尔频率（Mel-frequency）分箱的数量。

padding_value (`float`，*可选*，默认值为 0.0)：用于填充 padding 向量的值。

dither (`float`, *可选*，默认为 0.0)：添加抖动。换句话说，为每一帧添加少量高斯噪声。例如，使用 4.0 可添加以 0.0 为中心、标准差为 4.0 的正态分布抖动（假设 kaldi 波形的范围为 [-32k,+32k]）。值 0.0 表示不添加抖动。抖动的作用与 `mel_floor` 类似。当信号中存在 VAD 截断时，它会降低具有硬零部分的信号的高 log_mel_fbank 值。

do_ceptral_normalize (`bool`，*可选*，默认为 `True`)：是否对提取的特征应用语句级倒谱均值和方差归一化。

normalize_means (`bool`，*可选*，默认为 `True`)：是否对提取的特征进行零均值归一化。

normalize_vars (`bool`，*可选*，默认为 `True`)：是否对提取的特征进行单位方差归一化。

构建一个 Speech2Text 特征提取器。

此特征提取器继承自 [Speech2TextFeatureExtractor](/docs/transformers/v5.23.0/zh/model_doc/speech_to_text#transformers.Speech2TextFeatureExtractor)，后者包含了大部分主要方法。用户应参考该父类以获取有关这些方法的更多信息。

如果已安装 TorchAudio，此类将使用 TorchAudio 从原始语音中提取梅尔滤波器组特征，否则使用 numpy，并对提取的特征应用话语级的倒谱均值和方差归一化。

#### __调用__[[transformers.Speech2TextFeatureExtractor.__call__]]

```python
__call__(raw_speech: numpy.ndarray | list[float] | list[numpy.ndarray] | list[list[float]], padding: bool | str | transformers.utils.generic.PaddingStrategy = False, max_length: int | None = None, truncation: bool = False, pad_to_multiple_of: int | None = None, return_tensors: str | transformers.utils.generic.TensorType | None = None, sampling_rate: int | None = None, return_attention_mask: bool | None = None, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/speech_to_text/feature_extraction_speech_to_text.py#L174)

**参数：**

raw_speech (`np.ndarray`、`list[float]`、`list[np.ndarray]`、`list[list[float]]`)：需要填充的序列或序列批次。每个序列可以是 numpy 数组、浮点值列表、numpy 数组列表或浮点值列表的列表。必须是单声道音频，而非立体声，即每个时间步仅包含一个浮点值。

padding (`bool`、`str` 或 [PaddingStrategy](/docs/transformers/v5.23.0/zh/internal/file_utils#transformers.utils.PaddingStrategy)，*可选*，默认为 `True`)：选择一种策略来填充返回的序列（根据模型的填充方向和填充索引），可选策略如下： - `True` 或 `'longest'`：填充到批次中最长的序列（如果只提供了单个序列，则不进行填充）。 - `'max_length'`：填充到由参数 `max_length` 指定的最大长度，或者如果未提供该参数，则填充到模型可接受的最大输入长度。 - `False` 或 `'do_not_pad'`（默认）：不进行填充（即可以输出包含不同长度序列的批次）。

max_length (`int`, *可选*) : 返回列表的最大长度，以及可选的填充长度（见上文）。

truncation (`bool`) : 启用截断，将长度超过 *max_length* 的输入序列截断为 *max_length*。

pad_to_multiple_of (`int`, *optional*) : 如果设置，则将序列填充为所提供值的倍数。 这对于在计算能力 `>= 7.5`（Volta）的 NVIDIA 硬件上启用 Tensor Cores 的使用特别有用，或者对于受益于序列长度为 128 的倍数的 TPU 也很有用。

return_attention_mask (`bool`, *可选*) : 是否返回注意力掩码。如果保持默认值，则根据特定 feature_extractor 的默认设置返回注意力掩码。  [什么是注意力掩码？](../glossary#attention-mask)    对于 Speech2TextTransformer 模型，在进行批量推理时，始终应传入 `attention_mask`，以避免细微的 bug。

return_tensors (`str` 或 [TensorType](/docs/transformers/v5.23.0/zh/internal/file_utils#transformers.TensorType)，*可选*)：如果设置，将返回张量而不是 Python 整数列表。可接受的值为： - `'pt'`：返回 PyTorch `torch.Tensor` 对象。 - `'np'`：返回 Numpy `np.ndarray` 对象。

sampling_rate (`int`，*可选*)：`raw_speech` 输入的采样率。强烈建议在 forward 调用时传入 `sampling_rate`，以避免静默错误。

padding_value (`float`，*可选*，默认值为 0.0)：用于填充填充值/向量的数值。

用于对一条或多条序列进行特征化并准备输入模型的主要方法。

## Speech2TextProcessor[[transformers.Speech2TextProcessor]]

#### transformers.Speech2TextProcessor[[transformers.Speech2TextProcessor]]

```python
transformers.Speech2TextProcessor(feature_extractor, tokenizer)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/speech_to_text/processing_speech_to_text.py#L23)

**参数：**

feature_extractor (`Speech2TextFeatureExtractor`)：特征提取器是必需的输入。

tokenizer (`Speech2TextTokenizer`)：分词器是必需的输入。

构建一个 Speech2TextProcessor，它将特征提取器和分词器封装为单个处理器。

[Speech2TextProcessor](/docs/transformers/v5.23.0/zh/model_doc/speech_to_text#transformers.Speech2TextProcessor) 提供了 [Speech2TextFeatureExtractor](/docs/transformers/v5.23.0/zh/model_doc/speech_to_text#transformers.Speech2TextFeatureExtractor) 和 [Speech2TextTokenizer](/docs/transformers/v5.23.0/zh/model_doc/speech_to_text#transformers.Speech2TextTokenizer) 的所有功能。有关更多信息，请参阅 [~Speech2TextFeatureExtractor](/docs/transformers/v5.23.0/zh/model_doc/speech_to_text#transformers.Speech2TextFeatureExtractor) 和 [~Speech2TextTokenizer](/docs/transformers/v5.23.0/zh/model_doc/speech_to_text#transformers.Speech2TextTokenizer)。

#### __调用__[[transformers.Speech2TextProcessor.__call__]]

```python
__call__(*args, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/speech_to_text/processing_speech_to_text.py#L27)

**参数：**

return_tensors (`str` 或 [TensorType](/docs/transformers/v5.23.0/zh/internal/file_utils#transformers.TensorType)，*可选*)：如果设置，将返回特定框架的张量。可接受的值为： - `'pt'`：返回 PyTorch `torch.Tensor` 对象。 - `'np'`：返回 NumPy `np.ndarray` 对象。

#### from_pretrained[[transformers.Speech2TextProcessor.from_pretrained]]

```python
from_pretrained(pretrained_model_name_or_path: str | os.PathLike, cache_dir: str | os.PathLike | None = None, force_download: bool = False, local_files_only: bool = False, token: str | bool | None = None, revision: str = 'main', **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/processing_utils.py#L1799)

**参数：**

pretrained_model_name_or_path (`str` 或 `os.PathLike`) : 可以是以下之一： - 一个字符串，即托管在 huggingface.co 模型仓库中的预训练 feature_extractor 的 *model id*。 - 指向一个 *目录* 的路径，该目录包含使用 [save_pretrained()](/docs/transformers/v5.23.0/zh/main_classes/feature_extractor#transformers.FeatureExtractionMixin.save_pretrained) 方法保存的 feature extractor 文件，例如 `./my_model_directory/`。 - 指向已保存的 feature extractor JSON *file* 的路径，例如 `./my_model_directory/preprocessor_config.json`。

- ****kwargs** : 同时传递给 [from_pretrained()](/docs/transformers/v5.23.0/zh/main_classes/feature_extractor#transformers.FeatureExtractionMixin.from_pretrained) 和 `~tokenization_utils_base.PreTrainedTokenizer.from_pretrained` 的额外关键字参数。

实例化与预训练模型关联的处理器。

此类的该方法只是调用了特征提取器的 [from_pretrained()](/docs/transformers/v5.23.0/zh/main_classes/feature_extractor#transformers.FeatureExtractionMixin.from_pretrained)、图像处理器 [ImageProcessingMixin](/docs/transformers/v5.23.0/zh/internal/image_processing_utils#transformers.ImageProcessingMixin) 以及分词器的 `~tokenization_utils_base.PreTrainedTokenizer.from_pretrained` 方法。有关更多信息，请参阅上述方法的文档字符串。

#### save_pretrained[[transformers.Speech2TextProcessor.save_pretrained]]

```python
save_pretrained(save_directory, push_to_hub: bool = False, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/processing_utils.py#L1182)

**参数：**

save_directory (`str` 或 `os.PathLike`) : 用于保存特征提取器 JSON 文件和分词器文件的目录（如果该目录不存在，则会自动创建）。

push_to_hub (`bool`，*可选*，默认为 `False`)：是否在保存模型后将其推送到 Hugging Face 模型库。您可以通过 `repo_id` 指定要推送到的仓库（默认使用您命名空间中 `save_directory` 的名称）。

kwargs (`dict[str, Any]`，*可选*)：传递给 [push_to_hub()](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.utils.PushToHubMixin.push_to_hub) 方法的额外关键字参数。

将此处理器的属性（特征提取器、分词器……）保存到指定目录中，以便使用 [from_pretrained()](/docs/transformers/v5.23.0/zh/model_doc/wav2vec2#transformers.Wav2Vec2Processor.from_pretrained) 方法重新加载。

此类的该方法只是调用了 [save_pretrained()](/docs/transformers/v5.23.0/zh/main_classes/feature_extractor#transformers.FeatureExtractionMixin.save_pretrained) 和 [save_pretrained()](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.save_pretrained)。有关更多信息，请参阅上述方法的文档字符串。

#### batch_decode[[transformers.Speech2TextProcessor.batch_decode]]

```python
batch_decode(*args, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/processing_utils.py#L2054)

此方法将其所有参数转发给 PreTrainedTokenizer 的 [batch_decode()](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.batch_decode)。有关更多信息，请参阅该方法的文档字符串。

#### decode[[transformers.Speech2TextProcessor.decode]]

```python
decode(*args, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/processing_utils.py#L2063)

此方法将其所有参数转发给 PreTrainedTokenizer 的 [decode()](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.decode)。有关更多信息，请参阅该方法的文档字符串。

## Speech2TextModel[[transformers.Speech2TextModel]]

#### transformers.Speech2TextModel[[transformers.Speech2TextModel]]

```python
transformers.Speech2TextModel(config: Speech2TextConfig)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/speech_to_text/modeling_speech_to_text.py#L720)

**参数：**

config ([Speech2TextConfig](/docs/transformers/v5.23.0/zh/model_doc/speech_to_text#transformers.Speech2TextConfig))：模型配置类，包含模型的所有参数。通过配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 [from_pretrained()](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.PreTrainedModel.from_pretrained) 方法以加载模型权重。

未附加任何特定头部的裸 Speech To Text Text Model，直接输出原始隐藏状态。

该模型继承自 [PreTrainedModel](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.PreTrainedModel)。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。

该模型也是 PyTorch [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) 的子类。请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。

#### forward[[transformers.Speech2TextModel.forward]]

```python
forward(input_features: typing.Optional[torch.LongTensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, decoder_input_ids: typing.Optional[torch.LongTensor] = None, decoder_attention_mask: typing.Optional[torch.LongTensor] = None, encoder_outputs: tuple[tuple[torch.Tensor]] | None = None, past_key_values: transformers.cache_utils.Cache | None = None, decoder_inputs_embeds: typing.Optional[torch.Tensor] = None, use_cache: bool | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/speech_to_text/modeling_speech_to_text.py#L736)

**参数：**

input_features (`torch.LongTensor`，形状为 `(batch_size, sequence_length, feature_dim)`，*可选*) : 与输入音频特征对应的张量。可以使用 [Speech2TextFeatureExtractor](/docs/transformers/v5.23.0/zh/model_doc/speech_to_text#transformers.Speech2TextFeatureExtractor) 获取音频特征。有关详细信息，请参阅 [Speech2TextFeatureExtractor.__call__()](/docs/transformers/v5.23.0/zh/model_doc/speech_to_text#transformers.Speech2TextFeatureExtractor.__call__)（[Speech2TextProcessor](/docs/transformers/v5.23.0/zh/model_doc/speech_to_text#transformers.Speech2TextProcessor) 使用 [Speech2TextFeatureExtractor](/docs/transformers/v5.23.0/zh/model_doc/speech_to_text#transformers.Speech2TextFeatureExtractor) 来处理音频）。

attention_mask (`torch.Tensor`，形状为 `(batch_size, sequence_length)`，*可选*)：用于避免对填充（padding）标记索引执行注意力机制的掩码。掩码值取自 `[0, 1]`： - 1 表示**未掩码**的标记， - 0 表示**已掩码**的标记。 [什么是注意力掩码？](../glossary#attention-mask)

decoder_input_ids (`torch.LongTensor`，形状为 `(batch_size, target_sequence_length)`，*可选*)：解码器输入序列中各个 token 在词汇表中的索引。 可以使用 `SpeechToTextTokenizer` 获取这些索引。 有关详细信息，请参阅 [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 和 [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)。  [什么是解码器输入 ID？](../glossary#decoder-input-ids)  SpeechToText 使用 `eos_token_id` 作为 `decoder_input_ids` 生成的起始 token。 如果使用 `past_key_values`，则只需输入最后几个 `decoder_input_ids`（参见 `past_key_values`）。

decoder_attention_mask (`torch.LongTensor`，形状为 `(batch_size, target_sequence_length)`，*可选*) : 默认行为：生成一个忽略 `decoder_input_ids` 中填充标记的张量。默认情况下也会使用因果掩码。 如果您想更改填充行为，请阅读 `modeling_speech_to_text._prepare_decoder_attention_mask` 并根据需要修改。有关默认策略的更多信息，请参阅[论文](https://huggingface.co/papers/1910.13461)中的图 1。

encoder_outputs (`tuple[tuple[torch.Tensor]]`, *可选*) : 元组由 (`last_hidden_state`, *可选*: `hidden_states`, *可选*: `attentions`) 组成。`last_hidden_state` 的形状为 `(batch_size, sequence_length, hidden_size)`，*可选*) 是编码器最后一层输出的隐藏状态序列。用于解码器的交叉注意力中。

past_key_values (`~cache_utils.Cache`，*可选*)：预计算的隐藏状态（自注意力块和交叉注意力块中的键和值），可用于加速顺序解码。这通常由模型在解码的先前阶段返回的 `past_key_values` 组成，前提是 `use_cache=True` 或 `config.use_cache=True`。 仅允许 [Cache](/docs/transformers/v5.23.0/zh/internal/generation_utils#transformers.Cache) 实例作为输入，请参阅我们的 [kv cache guide](https://huggingface.co/docs/transformers/en/kv_cache)。如果未传入 `past_key_values`，则默认初始化 [DynamicCache](/docs/transformers/v5.23.0/zh/internal/generation_utils#transformers.DynamicCache)。 模型将输出与输入相同的缓存格式。 如果使用 `past_key_values`，则用户预期仅输入未处理的 `input_ids`（即未向此模型提供其过去键值状态的那些），其形状为 `(batch_size, unprocessed_length)`，而不是形状为 `(batch_size, sequence_length)` 的所有 `input_ids`。

decoder_inputs_embeds (`torch.Tensor`，形状为 `(batch_size, target_sequence_length, hidden_size)`，*可选*)：可选地，您可以选择直接传入嵌入表示，而不是传入 `decoder_input_ids`。如果使用了 `past_key_values`，则只需输入最后一段 `decoder_inputs_embeds`（参见 `past_key_values`）。如果您希望比模型内部的嵌入查找矩阵更精细地控制将 `decoder_input_ids` 索引转换为对应向量的方式，这将非常有用。如果 `decoder_input_ids` 和 `decoder_inputs_embeds` 均未设置，则 `decoder_inputs_embeds` 将取 `inputs_embeds` 的值。

use_cache (`bool`，*可选*)：如果设置为 `True`，则会返回 `past_key_values` 键值状态，可用于加速解码（参见 `past_key_values`）。

**返回：** [Seq2SeqLMOutput](/docs/transformers/v5.23.0/zh/main_classes/output#transformers.modeling_outputs.Seq2SeqLMOutput) 或 `tuple(torch.Tensor)`

一个 [Seq2SeqLMOutput](/docs/transformers/v5.23.0/zh/main_classes/output#transformers.modeling_outputs.Seq2SeqLMOutput) 或 `torch.Tensor` 元组（如果传入了 `return_dict=False` 或 `config.return_dict=False`），其包含的元素取决于配置（[Speech2TextConfig](/docs/transformers/v5.23.0/zh/model_doc/speech_to_text#transformers.Speech2TextConfig)）和输入。

[Speech2TextModel](/docs/transformers/v5.23.0/zh/model_doc/speech_to_text#transformers.Speech2TextModel) 的 forward 方法重写了 `__call__` 特殊方法。

尽管前向传播的实现需要在此函数中定义，但之后应调用 `Module` 实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者会静默地忽略这些步骤。

- **loss** (`torch.Tensor`，形状为 `(1,)`，*可选*，在提供 `labels` 时返回) -- 语言建模损失。
- **logits**（形状为 `(batch_size, sequence_length, config.vocab_size)` 的 `torch.Tensor`）-- 语言建模头的预测分数（SoftMax 之前每个词汇表 token 的分数）。
- **past_key_values**（`EncoderDecoderCache`，*可选*，在传入 `use_cache=True` 或 `config.use_cache=True` 时返回）-- 它是一个 [EncoderDecoderCache](/docs/transformers/v5.23.0/zh/internal/generation_utils#transformers.EncoderDecoderCache) 实例。更多详情，请参阅我们的 [kv cache 指南](https://huggingface.co/docs/transformers/en/kv_cache)。

  包含预计算的隐藏状态（自注意力块和交叉注意力块中的键和值），可用于（参见 `past_key_values` 输入）加速顺序解码。
- **decoder_hidden_states** (`tuple(torch.Tensor)`，*可选*，在传入 `output_hidden_states=True` 或 `config.output_hidden_states=True` 时返回) -- 一个 `torch.Tensor` 元组（如果模型具有嵌入层，则包含嵌入层输出的一个张量，以及每个层输出的一个张量），形状为 `(batch_size, sequence_length, hidden_size)`。

  解码器在每一层输出处的隐藏状态，以及初始嵌入输出。
- **decoder_attentions** (`tuple(torch.Tensor)`，*可选*，当传入 `output_attentions=True` 或 `config.output_attentions=True` 时返回) -- 一个 `torch.Tensor` 元组（每层一个），形状为 `(batch_size, num_heads, sequence_length, sequence_length)`。

  解码器在注意力 softmax 之后的注意力权重，用于在自注意力头中计算加权平均值。
- **cross_attentions** (`tuple(torch.Tensor)`，*可选*，在传入 `output_attentions=True` 或 `config.output_attentions=True` 时返回) -- 一个 `torch.Tensor` 元组（每层一个），形状为 `(batch_size, num_heads, sequence_length, sequence_length)`。

  解码器交叉注意力层在注意力 softmax 之后的注意力权重，用于在交叉注意力头中计算加权平均值。
- **encoder_last_hidden_state**（形状为 `(batch_size, sequence_length, hidden_size)` 的 `torch.Tensor`，*可选*）-- 模型编码器最后一层输出的隐藏状态序列。
- **encoder_hidden_states** (`tuple(torch.Tensor)`，*可选*，在传入 `output_hidden_states=True` 或 `config.output_hidden_states=True` 时返回) -- 一个 `torch.Tensor` 元组（如果模型具有嵌入层，则包含嵌入层的输出，以及每一层的输出），形状为 `(batch_size, sequence_length, hidden_size)`。

  编码器在每一层输出处的隐藏状态，以及初始嵌入输出。
- **encoder_attentions** (`tuple(torch.Tensor)`，*可选*，在传入 `output_attentions=True` 或 `config.output_attentions=True` 时返回) -- 一个 `torch.Tensor` 元组（每层一个），形状为 `(batch_size, num_heads, sequence_length, sequence_length)`。

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

示例：

```python
>>> import torch
>>> from transformers import Speech2TextModel, AutoFeatureExtractor
>>> from datasets import load_dataset

>>> model = Speech2TextModel.from_pretrained("facebook/s2t-small-librispeech-asr")
>>> feature_extractor = AutoFeatureExtractor.from_pretrained("facebook/s2t-small-librispeech-asr")
>>> ds = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")
>>> inputs = feature_extractor(
...     ds[0]["audio"]["array"], sampling_rate=ds[0]["audio"]["sampling_rate"], return_tensors="pt"
... )
>>> input_features = inputs.input_features
>>> decoder_input_ids = torch.tensor([[1, 1]]) * model.config.decoder_start_token_id
>>> last_hidden_state = model(input_features, decoder_input_ids=decoder_input_ids).last_hidden_state
>>> list(last_hidden_state.shape)
[1, 2, 256]
```

## Speech2TextForConditionalGeneration[[transformers.Speech2TextForConditionalGeneration]]

#### transformers.Speech2TextForConditionalGeneration[[transformers.Speech2TextForConditionalGeneration]]

```python
transformers.Speech2TextForConditionalGeneration(config: Speech2TextConfig)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/speech_to_text/modeling_speech_to_text.py#L842)

**参数：**

config ([Speech2TextConfig](/docs/transformers/v5.23.0/zh/model_doc/speech_to_text#transformers.Speech2TextConfig))：模型配置类，包含模型的所有参数。通过配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 [from_pretrained()](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.PreTrainedModel.from_pretrained) 方法以加载模型权重。

带有语言建模头的 Speech2Text 模型。可用于摘要生成。

该模型继承自 [PreTrainedModel](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.PreTrainedModel)。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。

该模型也是 PyTorch [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) 的子类。请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。

#### forward[[transformers.Speech2TextForConditionalGeneration.forward]]

```python
forward(input_features: typing.Optional[torch.LongTensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, decoder_input_ids: typing.Optional[torch.LongTensor] = None, decoder_attention_mask: typing.Optional[torch.LongTensor] = None, encoder_outputs: tuple[tuple[torch.Tensor]] | None = None, past_key_values: transformers.cache_utils.Cache | None = None, decoder_inputs_embeds: typing.Optional[torch.Tensor] = None, labels: typing.Optional[torch.LongTensor] = None, use_cache: bool | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/speech_to_text/modeling_speech_to_text.py#L855)

**参数：**

input_features (`torch.LongTensor`，形状为 `(batch_size, sequence_length, feature_dim)`，*可选*) : 与输入音频特征对应的张量。可以使用 [Speech2TextFeatureExtractor](/docs/transformers/v5.23.0/zh/model_doc/speech_to_text#transformers.Speech2TextFeatureExtractor) 获取音频特征。有关详细信息，请参阅 [Speech2TextFeatureExtractor.__call__()](/docs/transformers/v5.23.0/zh/model_doc/speech_to_text#transformers.Speech2TextFeatureExtractor.__call__)（[Speech2TextProcessor](/docs/transformers/v5.23.0/zh/model_doc/speech_to_text#transformers.Speech2TextProcessor) 使用 [Speech2TextFeatureExtractor](/docs/transformers/v5.23.0/zh/model_doc/speech_to_text#transformers.Speech2TextFeatureExtractor) 来处理音频）。

attention_mask (`torch.Tensor`，形状为 `(batch_size, sequence_length)`，*可选*)：用于避免对填充（padding）标记索引执行注意力机制的掩码。掩码值取自 `[0, 1]`： - 1 表示**未掩码**的标记， - 0 表示**已掩码**的标记。 [什么是注意力掩码？](../glossary#attention-mask)

decoder_input_ids (`torch.LongTensor`，形状为 `(batch_size, target_sequence_length)`，*可选*)：解码器输入序列中各个 token 在词汇表中的索引。 可以使用 `SpeechToTextTokenizer` 获取这些索引。 有关详细信息，请参阅 [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 和 [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)。  [什么是解码器输入 ID？](../glossary#decoder-input-ids)  SpeechToText 使用 `eos_token_id` 作为 `decoder_input_ids` 生成的起始 token。 如果使用 `past_key_values`，则只需输入最后几个 `decoder_input_ids`（参见 `past_key_values`）。

decoder_attention_mask (`torch.LongTensor`，形状为 `(batch_size, target_sequence_length)`，*可选*) : 默认行为：生成一个忽略 `decoder_input_ids` 中填充标记的张量。默认情况下也会使用因果掩码。 如果您想更改填充行为，请阅读 `modeling_speech_to_text._prepare_decoder_attention_mask` 并根据需要修改。有关默认策略的更多信息，请参阅[论文](https://huggingface.co/papers/1910.13461)中的图 1。

encoder_outputs (`tuple[tuple[torch.Tensor]]`, *可选*) : 元组由 (`last_hidden_state`, *可选*: `hidden_states`, *可选*: `attentions`) 组成。`last_hidden_state` 的形状为 `(batch_size, sequence_length, hidden_size)`，*可选*) 是编码器最后一层输出的隐藏状态序列。用于解码器的交叉注意力中。

past_key_values (`~cache_utils.Cache`，*可选*)：预计算的隐藏状态（自注意力块和交叉注意力块中的键和值），可用于加速顺序解码。这通常由模型在解码的先前阶段返回的 `past_key_values` 组成，前提是 `use_cache=True` 或 `config.use_cache=True`。 仅允许 [Cache](/docs/transformers/v5.23.0/zh/internal/generation_utils#transformers.Cache) 实例作为输入，请参阅我们的 [kv cache guide](https://huggingface.co/docs/transformers/en/kv_cache)。如果未传入 `past_key_values`，则默认初始化 [DynamicCache](/docs/transformers/v5.23.0/zh/internal/generation_utils#transformers.DynamicCache)。 模型将输出与输入相同的缓存格式。 如果使用 `past_key_values`，则用户预期仅输入未处理的 `input_ids`（即未向此模型提供其过去键值状态的那些），其形状为 `(batch_size, unprocessed_length)`，而不是形状为 `(batch_size, sequence_length)` 的所有 `input_ids`。

decoder_inputs_embeds (`torch.Tensor`，形状为 `(batch_size, target_sequence_length, hidden_size)`，*可选*)：可选地，您可以选择直接传入嵌入表示，而不是传入 `decoder_input_ids`。如果使用了 `past_key_values`，则只需输入最后一段 `decoder_inputs_embeds`（参见 `past_key_values`）。如果您希望比模型内部的嵌入查找矩阵更精细地控制将 `decoder_input_ids` 索引转换为对应向量的方式，这将非常有用。如果 `decoder_input_ids` 和 `decoder_inputs_embeds` 均未设置，则 `decoder_inputs_embeds` 将取 `inputs_embeds` 的值。

labels (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*)：用于计算语言建模损失的标签。索引应在 `[0, ..., config.vocab_size]` 范围内，或为 -100（参见 `input_ids` 的文档字符串）。索引设置为 `-100` 的标记将被忽略（被掩码），损失仅针对标签在 `[0, ..., config.vocab_size]` 范围内的标记进行计算。

use_cache (`bool`，*可选*)：如果设置为 `True`，则会返回 `past_key_values` 键值状态，可用于加速解码（参见 `past_key_values`）。

**返回：** [Seq2SeqLMOutput](/docs/transformers/v5.23.0/zh/main_classes/output#transformers.modeling_outputs.Seq2SeqLMOutput) 或 `tuple(torch.Tensor)`

一个 [Seq2SeqLMOutput](/docs/transformers/v5.23.0/zh/main_classes/output#transformers.modeling_outputs.Seq2SeqLMOutput) 或 `torch.Tensor` 元组（如果传入了 `return_dict=False` 或 `config.return_dict=False`），其包含的元素取决于配置（[Speech2TextConfig](/docs/transformers/v5.23.0/zh/model_doc/speech_to_text#transformers.Speech2TextConfig)）和输入。

[Speech2TextForConditionalGeneration](/docs/transformers/v5.23.0/zh/model_doc/speech_to_text#transformers.Speech2TextForConditionalGeneration) 的 forward 方法重写了 `__call__` 特殊方法。

尽管前向传播的实现需要在此函数中定义，但之后应调用 `Module` 实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者会静默地忽略这些步骤。

- **loss** (`torch.Tensor`，形状为 `(1,)`，*可选*，在提供 `labels` 时返回) -- 语言建模损失。
- **logits**（形状为 `(batch_size, sequence_length, config.vocab_size)` 的 `torch.Tensor`）-- 语言建模头的预测分数（SoftMax 之前每个词汇表 token 的分数）。
- **past_key_values**（`EncoderDecoderCache`，*可选*，在传入 `use_cache=True` 或 `config.use_cache=True` 时返回）-- 它是一个 [EncoderDecoderCache](/docs/transformers/v5.23.0/zh/internal/generation_utils#transformers.EncoderDecoderCache) 实例。更多详情，请参阅我们的 [kv cache 指南](https://huggingface.co/docs/transformers/en/kv_cache)。

  包含预计算的隐藏状态（自注意力块和交叉注意力块中的键和值），可用于（参见 `past_key_values` 输入）加速顺序解码。
- **decoder_hidden_states** (`tuple(torch.Tensor)`，*可选*，在传入 `output_hidden_states=True` 或 `config.output_hidden_states=True` 时返回) -- 一个 `torch.Tensor` 元组（如果模型具有嵌入层，则包含嵌入层输出的一个张量，以及每个层输出的一个张量），形状为 `(batch_size, sequence_length, hidden_size)`。

  解码器在每一层输出处的隐藏状态，以及初始嵌入输出。
- **decoder_attentions** (`tuple(torch.Tensor)`，*可选*，当传入 `output_attentions=True` 或 `config.output_attentions=True` 时返回) -- 一个 `torch.Tensor` 元组（每层一个），形状为 `(batch_size, num_heads, sequence_length, sequence_length)`。

  解码器在注意力 softmax 之后的注意力权重，用于在自注意力头中计算加权平均值。
- **cross_attentions** (`tuple(torch.Tensor)`，*可选*，在传入 `output_attentions=True` 或 `config.output_attentions=True` 时返回) -- 一个 `torch.Tensor` 元组（每层一个），形状为 `(batch_size, num_heads, sequence_length, sequence_length)`。

  解码器交叉注意力层在注意力 softmax 之后的注意力权重，用于在交叉注意力头中计算加权平均值。
- **encoder_last_hidden_state**（形状为 `(batch_size, sequence_length, hidden_size)` 的 `torch.Tensor`，*可选*）-- 模型编码器最后一层输出的隐藏状态序列。
- **encoder_hidden_states** (`tuple(torch.Tensor)`，*可选*，在传入 `output_hidden_states=True` 或 `config.output_hidden_states=True` 时返回) -- 一个 `torch.Tensor` 元组（如果模型具有嵌入层，则包含嵌入层的输出，以及每一层的输出），形状为 `(batch_size, sequence_length, hidden_size)`。

  编码器在每一层输出处的隐藏状态，以及初始嵌入输出。
- **encoder_attentions** (`tuple(torch.Tensor)`，*可选*，在传入 `output_attentions=True` 或 `config.output_attentions=True` 时返回) -- 一个 `torch.Tensor` 元组（每层一个），形状为 `(batch_size, num_heads, sequence_length, sequence_length)`。

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

示例：

```python
>>> import torch
>>> from transformers import Speech2TextProcessor, Speech2TextForConditionalGeneration
>>> from datasets import load_dataset

>>> model = Speech2TextForConditionalGeneration.from_pretrained("facebook/s2t-small-librispeech-asr")
>>> processor = Speech2TextProcessor.from_pretrained("facebook/s2t-small-librispeech-asr")

>>> ds = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")

>>> inputs = processor(
...     ds[0]["audio"]["array"], sampling_rate=ds[0]["audio"]["sampling_rate"], 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
'mister quilter is the apostle of the middle classes and we are glad to welcome his gospel'
```

