# Wav2Vec2

## 概述

Wav2Vec2 模型由 Alexei Baevski、Henry Zhou、Abdelrahman Mohamed 和 Michael Auli 在 [wav2vec 2.0: A Framework for Self-Supervised Learning of Speech Representations](https://huggingface.co/papers/2006.11477) 中提出。

该论文的摘要如下：

*我们首次证明，仅从语音音频中学习强大的表示，随后在转录语音上进行微调，可以在概念上更简单的同时，超越最佳的半监督方法。wav2vec 2.0 在潜在空间中掩蔽语音输入，并解决一个在潜在表示的量化上定义的对比任务，这些潜在表示是联合学习的。使用 Librispeech 的所有标注数据进行的实验，在 clean/other 测试集上分别实现了 1.8/3.3 的 WER。当将标注数据量降低到一小时时，wav2vec 2.0 在 100 小时子集上超越了之前的最先进水平，同时使用的标注数据减少了 100 倍。仅使用十分钟的标注数据，并在 53k 小时的无标注数据上进行预训练，仍然可以实现 4.8/8.2 的 WER。这证明了在有限标注数据量下进行语音识别的可行性。*

该模型由 [patrickvonplaten](https://huggingface.co/patrickvonplaten) 贡献。

注意：Meta（FAIR）发布了 [Wav2Vec2-BERT 2.0](./wav2vec2-bert) 的新版本——它在 450 万小时的音频上进行了预训练。我们特别推荐将其用于微调任务，例如按照[此指南](https://huggingface.co/blog/fine-tune-w2v2-bert)进行操作。

> [!TIP]
> 在 [from_pretrained()](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.PreTrainedModel.from_pretrained) 中设置 `use_kernels=True`，即可用 Hub 上的优化内核替换受支持的层。有关详细信息，请参阅 [加载内核](../kernel_doc/loading_kernels)。

## 使用技巧

- Wav2Vec2 是一种语音模型，它接受一个浮点数数组，该数组对应于语音信号的原始波形。
- Wav2Vec2 模型使用连接时序分类（CTC）进行训练，因此模型输出必须使用 [Wav2Vec2CTCTokenizer](/docs/transformers/v5.23.0/zh/model_doc/wav2vec2#transformers.Wav2Vec2CTCTokenizer) 进行解码。

## 使用 Flash Attention 2

Flash Attention 2 是该模型的更快、经过优化的版本。

### 安装

首先，检查您的硬件是否与 Flash Attention 2 兼容。最新的兼容硬件列表可在[官方文档](https://github.com/Dao-AILab/flash-attention#installation-and-features)中查阅。

接下来，[安装](https://github.com/Dao-AILab/flash-attention#installation-and-features) Flash Attention 2 的最新版本：

```bash
pip install -U flash-attn --no-build-isolation
```

### 用法

要使用 Flash Attention 2 加载模型，我们可以将参数 `attn_implementation="flash_attention_2"` 传递给 [from_pretrained()](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.PreTrainedModel.from_pretrained)。我们还会以半精度（例如 `torch.float16`）加载模型，因为这几乎不会降低音频质量，但能显著降低内存占用并加快推理速度：

```python
from transformers import Wav2Vec2Model

model = Wav2Vec2Model.from_pretrained("facebook/wav2vec2-large-960h-lv60-self", attn_implementation="flash_attention_2", device_map="auto")
...
```

### 预期加速

下图展示了 `facebook/wav2vec2-large-960h-lv60-self` 模型在 `librispeech_asr` `clean` 验证集上，transformers 原生实现与 flash-attention-2 及 sdpa（scale-dot-product-attention）版本之间纯推理时间的预期加速比。我们展示的是在该验证集上获得的平均加速比：

## 资源

一份来自 Hugging Face 官方和社区（以 🌎 标识）的资源列表，旨在帮助您入门 Wav2Vec2。如果您有兴趣提交资源以收录于此，请随时发起 Pull Request，我们将进行审核！理想情况下，该资源应展示一些新内容，而非重复现有资源。

- 一个关于如何[利用预训练的 Wav2Vec2 模型进行情感分类](https://colab.research.google.com/github/m3hrdadfi/soxan/blob/main/notebooks/Emotion_recognition_in_Greek_speech_using_Wav2Vec2.ipynb)的笔记本。🌎
- [Wav2Vec2ForCTC](/docs/transformers/v5.23.0/zh/model_doc/wav2vec2#transformers.Wav2Vec2ForCTC) 受此 [notebook](https://colab.research.google.com/github/huggingface/notebooks/blob/main/examples/audio_classification.ipynb) 支持。
- [音频分类任务指南](../tasks/audio_classification)

- 一篇关于在 🤗 Transformers 中使用 n-gram 提升 Wav2Vec2 性能的[博客文章](https://huggingface.co/blog/wav2vec2-with-ngram)。
- 一篇关于如何使用 🤗 Transformers [微调 Wav2Vec2 以进行英语 ASR](https://huggingface.co/blog/fine-tune-wav2vec2-english) 的博文。
- 一篇关于使用 [🤗 Transformers 对 XLS-R 进行多语言 ASR 微调](https://huggingface.co/blog/fine-tune-xlsr-wav2vec2) 的博文。
- 一个关于如何[使用 Wav2Vec2 转录音频，从而为任意视频创建 YouTube 字幕](https://colab.research.google.com/github/Muennighoff/ytclipcc/blob/main/wav2vec_youtube_captions.ipynb)的笔记本。🌎
- [Wav2Vec2ForCTC](/docs/transformers/v5.23.0/zh/model_doc/wav2vec2#transformers.Wav2Vec2ForCTC) 由以下两个笔记本提供支持：[如何微调英语语音识别模型](https://colab.research.google.com/github/huggingface/notebooks/blob/main/examples/speech_recognition.ipynb)，以及 [如何微调任意语言的语音识别模型](https://colab.research.google.com/github/huggingface/notebooks/blob/main/examples/multi_lingual_speech_recognition.ipynb)。
- [自动语音识别任务指南](../tasks/asr)

🚀 部署

- 一篇博客文章，介绍如何使用 Hugging Face 的 Transformers 和 Amazon SageMaker 部署 Wav2Vec2 进行[自动语音识别](https://www.philschmid.de/automatic-speech-recognition-sagemaker)。

## Wav2Vec2Config[[transformers.Wav2Vec2Config]]

#### transformers.Wav2Vec2Config[[transformers.Wav2Vec2Config]]

```python
transformers.Wav2Vec2Config(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, is_encoder_decoder: bool = False, 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, vocab_size: int | None = 32, hidden_size: int = 768, num_hidden_layers: int = 12, num_attention_heads: int = 12, intermediate_size: int = 3072, hidden_act: str = 'gelu', hidden_dropout: float | int = 0.1, activation_dropout: float | int = 0.1, attention_dropout: float | int = 0.1, feat_proj_dropout: float | int = 0.0, feat_quantizer_dropout: float | int = 0.0, final_dropout: float | int = 0.1, layerdrop: float | int = 0.1, initializer_range: float = 0.02, layer_norm_eps: float = 1e-05, feat_extract_norm: str = 'group', feat_extract_activation: str = 'gelu', conv_dim: list[int] | tuple[int, ...] = (512, 512, 512, 512, 512, 512, 512), conv_stride: list[int] | tuple[int, ...] = (5, 2, 2, 2, 2, 2, 2), conv_kernel: list[int] | tuple[int, ...] = (10, 3, 3, 3, 3, 2, 2), conv_bias: bool = False, num_conv_pos_embeddings: int = 128, num_conv_pos_embedding_groups: int = 16, do_stable_layer_norm: bool = False, apply_spec_augment: bool = True, mask_time_prob: float | int = 0.05, mask_time_length: int = 10, mask_time_min_masks: int = 2, mask_feature_prob: float | int = 0.0, mask_feature_length: int = 10, mask_feature_min_masks: int = 0, num_codevectors_per_group: int = 320, num_codevector_groups: int = 2, contrastive_logits_temperature: float = 0.1, num_negatives: int = 100, codevector_dim: int = 256, proj_codevector_dim: int = 256, diversity_loss_weight: float = 0.1, ctc_loss_reduction: str = 'sum', ctc_zero_infinity: bool = False, use_weighted_layer_sum: bool = False, classifier_proj_size: int = 256, tdnn_dim: list[int] | tuple[int, ...] = (512, 512, 512, 512, 1500), tdnn_kernel: list[int] | tuple[int, ...] = (5, 3, 3, 1, 1), tdnn_dilation: list[int] | tuple[int, ...] = (1, 2, 3, 1, 1), xvector_output_dim: int = 512, pad_token_id: int | None = 0, bos_token_id: int | None = 1, eos_token_id: int | list[int] | None = 2, add_adapter: bool = False, adapter_kernel_size: int = 3, adapter_stride: int = 2, num_adapter_layers: int = 3, output_hidden_size: int | None = None, adapter_attn_dim: int | None = None)
```

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

**参数：**

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

hidden_size (`int`，*可选*，默认为 `768`)：隐藏表示的维度。

num_hidden_layers (`int`，*可选*，默认为 `12`)：Transformer 解码器中的隐藏层数。

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

intermediate_size (`int`，*可选*，默认值为 `3072`)：MLP 表示的维度。

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

hidden_dropout (`Union[float, int]`，*可选*，默认值为 `0.1`)：嵌入层、编码器和池化器中所有全连接层的 dropout 概率。

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

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

feat_proj_dropout (`float`, *可选*，默认为 0.0)：特征编码器输出的 dropout 概率。

feat_quantizer_dropout (`float`, *可选*，默认为 0.0)：量化器所使用的特征编码器输出的 dropout 概率。

final_dropout (`float`, *可选*，默认为 0.1)：[Wav2Vec2ForCTC](/docs/transformers/v5.23.0/zh/model_doc/wav2vec2#transformers.Wav2Vec2ForCTC) 最终投影层的 dropout 概率。

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

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

layer_norm_eps (`float`，*可选*，默认为 `1e-05`)：层归一化层所使用的 epsilon。

feat_extract_norm (`str`, *可选*, 默认为 `"group"`) : 应用于特征编码器中一维卷积层的归一化方式。取值为 `"group"`，表示仅对第一个一维卷积层进行组归一化；或取值为 `"layer"`，表示对所有一维卷积层进行层归一化。

feat_extract_activation (`str, `optional`, defaults to `"gelu"`) : The non-linear activation function (function or string) in the 1D convolutional layers of the feature extractor. If string, `"gelu"`, `"relu"`, `"selu"` and `"gelu_new"` are supported.

conv_dim (`tuple[int]` 或 `list[int]`，*可选*，默认为 `(512, 512, 512, 512, 512, 512, 512)`) : 一个整数元组，用于定义特征编码器中每个一维卷积层的输入和输出通道数。*conv_dim* 的长度决定了一维卷积层的数量。

conv_stride (`tuple[int]` 或 `list[int]`，*可选*，默认为 `(5, 2, 2, 2, 2, 2, 2)`) : 一个整数元组，用于定义特征编码器中每个一维卷积层的步长。*conv_stride* 的长度定义了卷积层的数量，并且必须与 *conv_dim* 的长度相匹配。

conv_kernel (`tuple[int]` 或 `list[int]`，*可选*，默认为 `(10, 3, 3, 3, 3, 3, 3)`) : 一个整数元组，用于定义特征编码器中每个一维卷积层的卷积核大小。*conv_kernel* 的长度定义了卷积层的数量，并且必须与 *conv_dim* 的长度相匹配。

conv_bias (`bool`，*可选*，默认为 `False`)：一维卷积层是否包含偏置。

num_conv_pos_embeddings (`int`，*可选*，默认为 128)：卷积位置嵌入的数量。定义一维卷积位置嵌入层的核大小。

num_conv_pos_embedding_groups (`int`, *可选*，默认为 16)：一维卷积位置嵌入层的组数。

do_stable_layer_norm (`bool`, *可选*, 默认为 `False`) : 是否应用 Transformer 编码器的*稳定*层归一化架构。`do_stable_layer_norm is True` 表示在注意力层之前应用层归一化，而 `do_stable_layer_norm is False` 表示在注意力层之后应用层归一化。

apply_spec_augment (`bool`, *可选*, 默认为 `True`) : 是否对特征编码器的输出应用 *SpecAugment* 数据增强。参考 [SpecAugment: A Simple Data Augmentation Method for Automatic Speech Recognition](https://huggingface.co/papers/1904.08779)。

mask_time_prob (`float`, *可选*，默认为 0.05) : 沿时间轴被掩码的所有特征向量的百分比（介于 0 和 1 之间）。掩码过程会在该轴上生成 ''mask_time_prob*len(time_axis)/mask_time_length'' 个独立的掩码。如果从每个特征向量被选为待掩码向量跨度起点的概率来推理，*mask_time_prob* 应为 `prob_vector_start*mask_time_length`。请注意，重叠可能会降低实际被掩码的向量百分比。仅当 `apply_spec_augment is True` 时，此参数才相关。

mask_time_length (`int`，*可选*，默认为 10)：沿时间轴的向量跨度长度。

mask_time_min_masks (`int`, *可选*，默认为 2)：沿时间轴生成的、长度为 `mask_feature_length` 的最小掩码数量，针对每个时间步，与 `mask_feature_prob` 无关。仅当 ''mask_time_prob*len(time_axis)/mask_time_length < mask_time_min_masks'' 时相关

mask_feature_prob (`float`, *可选*，默认为 0.0)：沿特征轴被掩码的所有特征向量的百分比（介于 0 和 1 之间）。掩码过程会在该轴上生成 ''mask_feature_prob*len(feature_axis)/mask_time_length'' 个独立的掩码。如果从每个特征向量被选为待掩码向量跨度起点的概率来推理，*mask_feature_prob* 应为 `prob_vector_start*mask_feature_length`。请注意，重叠可能会降低实际被掩码的向量百分比。仅当 `apply_spec_augment is True` 时，此参数才相关。

mask_feature_prob (`Union[float, int]`，*可选*，默认为 `0.0`)：沿特征轴被掩码的所有特征向量的百分比（介于 0 和 1 之间）。掩码过程会在该轴上生成 `mask_feature_prob*len(feature_axis)/mask_time_length` 个独立的掩码。如果从每个特征向量被选为待掩码向量跨度起点的概率来推理，*mask_feature_prob* 应为 `prob_vector_start*mask_feature_length`。请注意，重叠可能会降低实际被掩码的向量百分比。仅当 `apply_spec_augment` 为 `True` 时，此参数才相关。

mask_feature_length (`int`，*可选*，默认为 10)：沿特征轴方向的向量跨度长度。

mask_feature_min_masks (`int`，*可选*，默认为 0)：每个时间步沿特征轴生成的长度为 `mask_feature_length` 的最小掩码数量，无论 `mask_feature_prob` 为何值。仅当 ''mask_feature_prob*len(feature_axis)/mask_feature_length < mask_feature_min_masks'' 时相关

num_codevectors_per_group (`int`，*可选*，默认为 320)：每个量化码本（组）中的条目数量。

num_codevectors_per_group (`int`，*可选*，默认为 320)：每个量化码本（组）中的条目数量。

num_codevector_groups (`int`，*可选*，默认为 2)：乘积码向量量化中的码向量组数。

contrastive_logits_temperature (`float`, *可选*，默认为 0.1)：对比损失中的温度 *kappa*。

num_negatives (`int`，*可选*，默认为 100)：对比损失中负样本的数量。

codevector_dim (`int`，*可选*，默认为 256)：量化特征向量的维度。

proj_codevector_dim (`int`，*可选*，默认为 256)：量化特征和 Transformer 特征最终投影的维度。

diversity_loss_weight (`int`，*可选*，默认为 0.1)：码本多样性损失分量的权重。

ctc_loss_reduction (`str`，*可选*，默认为 `"sum"`)：指定应用于 `torch.nn.CTCLoss` 输出的归约方式。仅在训练 [Wav2Vec2ForCTC](/docs/transformers/v5.23.0/zh/model_doc/wav2vec2#transformers.Wav2Vec2ForCTC) 实例时相关。

ctc_zero_infinity (`bool`，*可选*，默认为 `False`)：是否将 `torch.nn.CTCLoss` 的无穷大损失及其相关梯度置零。当输入过短而无法与目标对齐时，主要会产生无穷大损失。仅在训练 [Wav2Vec2ForCTC](/docs/transformers/v5.23.0/zh/model_doc/wav2vec2#transformers.Wav2Vec2ForCTC) 实例时相关。

use_weighted_layer_sum (`bool`，*可选*，默认为 `False`)：是否使用带有学习权重的层输出加权平均。仅在使用 [Wav2Vec2ForSequenceClassification](/docs/transformers/v5.23.0/zh/model_doc/wav2vec2#transformers.Wav2Vec2ForSequenceClassification) 实例时相关。

classifier_proj_size (`int`，*可选*，默认为 256)：用于分类的 token 平均池化之前投影的维度。

tdnn_dim (`tuple[int]` 或 `list[int]`，*可选*，默认为 `(512, 512, 512, 512, 1500)`) : 一个整数元组，用于定义 *XVector* 模型中 *TDNN* 模块内每个一维卷积层的输出通道数。*tdnn_dim* 的长度决定了 *TDNN* 层的数量。

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

tdnn_dilation (`tuple[int]` 或 `list[int]`，*可选*，默认为 `(1, 2, 3, 1, 1)`) : 一个整数元组，用于定义 *XVector* 模型中 *TDNN* 模块内每个一维卷积层的膨胀因子。*tdnn_dilation* 的长度必须与 *tdnn_dim* 的长度相匹配。

xvector_output_dim (`int`，*可选*，默认值为 512)：*XVector* 嵌入向量的维度。

pad_token_id (`int`，*可选*，默认为 `0`)：词表中用于填充的 Token ID。

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

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

add_adapter (`bool`, *可选*，默认为 `False`)：是否应在 Wav2Vec2 Encoder 之上堆叠一个卷积网络。对于为 SpeechEncoderDecoder 模型预热启动 Wav2Vec2，这可能非常有用。

adapter_kernel_size (`int`，*可选*，默认为 3)：适配器网络中卷积层的核大小。仅当 `add_adapter is True` 时相关。

adapter_stride (`int`，*可选*，默认为 2)：适配器网络中卷积层的步幅。仅当 `add_adapter is True` 时相关。

num_adapter_layers (`int`, *可选*，默认为 3)：适配器网络中应使用的卷积层数量。仅当 `add_adapter is True` 时有效。

output_hidden_size (`int`, *可选*) : 编码器输出层的维度。如果未定义，则默认为 *hidden-size*。仅在 `add_adapter is True` 时相关。

adapter_attn_dim (`int`, *可选*) : 在每个注意力块中使用的注意力适配器权重的维度。使用注意力适配器的模型示例为 [facebook/mms-1b-all](https://huggingface.co/facebook/mms-1b-all)。

这是用于存储 Wav2Vec2Model 配置的类。它根据指定的参数实例化 Wav2Vec2 模型，并定义模型架构。使用默认值实例化配置将得到与 [facebook/wav2vec2-base-960h](https://huggingface.co/facebook/wav2vec2-base-960h) 类似的配置

配置对象继承自 [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 Wav2Vec2Config, Wav2Vec2Model

>>> # Initializing a Wav2Vec2 facebook/wav2vec2-base-960h style configuration
>>> configuration = Wav2Vec2Config()

>>> # Initializing a model (with random weights) from the facebook/wav2vec2-base-960h style configuration
>>> model = Wav2Vec2Model(configuration)

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

## Wav2Vec2CTCTokenizer[[transformers.Wav2Vec2CTCTokenizer]]

#### transformers.Wav2Vec2CTCTokenizer[[transformers.Wav2Vec2CTCTokenizer]]

```python
transformers.Wav2Vec2CTCTokenizer(vocab_file, bos_token = '<s>', eos_token = '</s>', unk_token = '<unk>', pad_token = '<pad>', word_delimiter_token = '|', replace_word_delimiter_char = ' ', do_lower_case = False, target_lang = None, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/wav2vec2/tokenization_wav2vec2.py#L101)

**参数：**

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

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

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

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

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

word_delimiter_token (`str`，*可选*，默认为 `"|"`)：用于定义单词结束符的标记。

do_lower_case (`bool`, *可选*，默认为 `False`)：是否接受小写输入，并在解码时将输出转换为小写。

target_lang (`str`, *可选*) : 分词器应默认设置的目标语言。对于 [facebook/mms-1b-all](https://huggingface.co/facebook/mms-1b-all) 等多语言嵌套词汇表，必须定义 `target_lang`。

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

构建一个 Wav2Vec2CTC 分词器。

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

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

```python
__call__(text: TextInput | PreTokenizedInput | list[TextInput] | list[PreTokenizedInput] | None = None, text_pair: TextInput | PreTokenizedInput | list[TextInput] | list[PreTokenizedInput] | None = None, text_target: TextInput | PreTokenizedInput | list[TextInput] | list[PreTokenizedInput] | None = None, text_pair_target: TextInput | PreTokenizedInput | list[TextInput] | list[PreTokenizedInput] | None = None, add_special_tokens: bool = True, padding: bool | str | PaddingStrategy = False, truncation: bool | str | TruncationStrategy | None = None, max_length: int | None = None, stride: int = 0, is_split_into_words: bool = False, pad_to_multiple_of: int | None = None, padding_side: str | None = None, return_tensors: str | TensorType | None = None, return_token_type_ids: bool | None = None, return_attention_mask: bool | None = None, return_overflowing_tokens: bool = False, return_special_tokens_mask: bool = False, return_offsets_mapping: bool = False, return_length: bool = False, verbose: bool = True, tokenizer_kwargs: dict[str, Any] | None = None, **kwargs)
```

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

**参数：**

text (`str`、`list[str]`、`list[list[str]]`、*可选*)：要编码的序列或序列批次。每个序列可以是字符串或字符串列表（预分词字符串）。如果以字符串列表（预分词）形式提供序列，则必须设置 `is_split_into_words=True`（以消除与序列批次的歧义）。

text_pair (`str`、`list[str]`、`list[list[str]]`、*可选*)：要编码的序列或序列批次。每个序列可以是字符串或字符串列表（预分词字符串）。如果以字符串列表（预分词）形式提供序列，则必须设置 `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`（以消除与序列批次的歧义）。

tokenizer_kwargs (`dict[str, Any]`, *可选*) : 传递给 tokenizer 的额外 kwargs。这些 kwargs 将与显式参数及其他 kwargs 合并，其中显式参数具有更高的优先级。

add_special_tokens (`bool`，*可选*，默认为 `True`)：在编码序列时是否添加特殊标记。此操作将使用底层的 `PretrainedTokenizerBase.build_inputs_with_special_tokens` 函数，该函数定义了哪些标记会自动添加到输入 ID 中。如果您希望自动添加 `bos` 或 `eos` 标记，此功能非常有用。

padding (`bool`、`str` 或 [PaddingStrategy](/docs/transformers/v5.23.0/zh/internal/file_utils#transformers.utils.PaddingStrategy)，*可选*，默认为 `False`)：启用并控制填充。接受以下值： - `True` 或 `'longest'`：填充至批次中最长的序列（如果仅提供单个序列，则不进行填充）。 - `'max_length'`：填充至由参数 `max_length` 指定的最大长度，或者如果未提供该参数，则填充至模型可接受的最大输入长度。 - `False` 或 `'do_not_pad'`（默认值）：不进行填充（即，可以输出包含不同长度序列的批次）。

truncation (`bool`、`str` 或 [TruncationStrategy](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.tokenization_utils_base.TruncationStrategy)，*optional*，默认为 `False`)：启用并控制截断。接受以下值： - `True` 或 `'longest_first'`：截断至参数 `max_length` 指定的最大长度，若未提供该参数，则截断至模型可接受的最大输入长度。如果提供了一对序列（或一批序列对），这将逐个 token 进行截断，从该对中最长的序列中移除一个 token。 - `'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` 时，返回的溢出 token 将包含来自截断序列末尾的若干 token，以在截断序列和溢出序列之间提供一定的重叠。该参数的值定义了重叠 token 的数量。

is_split_into_words (`bool`，*可选*，默认为 `False`)：输入是否已经预先分词（例如，已拆分为单词）。如果设置为 `True`，分词器将假设输入已经拆分为单词（例如，通过按空白字符拆分），然后对其进行分词。这对于 NER 或 token 分类很有用。

pad_to_multiple_of (`int`，*可选*)：如果设置，则将序列填充为所提供值的倍数。需要启用 `padding`。这对于在计算能力 `>= 7.5`（Volta）的 NVIDIA 硬件上启用 Tensor Cores 的使用特别有用。

padding_side (`str`, *可选*) : 模型应应用填充的一侧。应在 ['right', 'left'] 中进行选择。默认值取自同名的类属性。

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

return_token_type_ids (`bool`，*可选*)：是否返回 token type ID。如果保持默认值，则根据特定 tokenizer 的默认设置返回 token type ID，该设置由 `return_outputs` 属性定义。[什么是 token type ID？](../glossary#token-type-ids)

return_attention_mask (`bool`，*可选*)：是否返回注意力掩码。如果保持默认值，将根据特定分词器的默认设置返回注意力掩码，该设置由 `return_outputs` 属性定义。[什么是注意力掩码？](../glossary#attention-mask)

return_overflowing_tokens (`bool`，*可选*，默认为 `False`)：是否返回溢出的 token 序列。如果提供了输入 id 的序列对（或序列对的批次），并且 `truncation_strategy = longest_first` 或 `True`，则会引发错误，而不是返回溢出的 token。

return_special_tokens_mask (`bool`，*可选*，默认为 `False`)：是否返回特殊标记掩码信息。

return_offsets_mapping (`bool`，*可选*，默认为 `False`)：是否返回每个 token 的 `(char_start, char_end)`。此功能仅适用于继承自 [PreTrainedTokenizerFast](/docs/transformers/v5.23.0/zh/main_classes/tokenizer#transformers.TokenizersBackend) 的快速分词器；如果使用 Python 分词器，此方法将抛出 `NotImplementedError`。

return_length (`bool`，*可选*，默认为 `False`)：是否返回编码后输入的长度。

verbose (`bool`，*可选*，默认为 `True`)：是否打印更多信息和警告。

- ****kwargs** : 传递给 `self.tokenize()` 方法

**返回：** [BatchEncoding](/docs/transformers/v5.23.0/zh/main_classes/tokenizer#transformers.BatchEncoding)

一个包含以下字段的 [BatchEncoding](/docs/transformers/v5.23.0/zh/main_classes/tokenizer#transformers.BatchEncoding)：

- **input_ids** -- 输入模型的 token id 列表。

  [什么是输入 ID？](../glossary#input-ids)

- **token_type_ids** -- 要输入模型的 token 类型 ID 列表（当 `return_token_type_ids=True` 或 `self.model_input_names` 中包含 *"token_type_ids"* 时）。

  [什么是 token type ID？](../glossary#token-type-ids)

- **attention_mask** -- 指定模型应关注哪些 token 的索引列表（当 `return_attention_mask=True` 或 *"attention_mask"* 位于 `self.model_input_names` 中时）。

  [什么是注意力掩码？](../glossary#attention-mask)

- **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 表示添加的特殊标记，0 表示常规序列标记（当 `add_special_tokens=True` 且 `return_special_tokens_mask=True` 时）。
- **length** -- 输入的长度（当 `return_length=True` 时）

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

#### save_vocabulary[[transformers.Wav2Vec2CTCTokenizer.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/wav2vec2/tokenization_wav2vec2.py#L643)

#### decode[[transformers.Wav2Vec2CTCTokenizer.decode]]

```python
decode(token_ids: typing.Union[int, list[int], numpy.ndarray, ForwardRef('torch.Tensor')], skip_special_tokens: bool = False, clean_up_tokenization_spaces: bool | None = None, output_char_offsets: bool = False, output_word_offsets: bool = False, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/wav2vec2/tokenization_wav2vec2.py#L538)

**参数：**

token_ids (`Union[int, list[int], np.ndarray, torch.Tensor]`) : 标记化输入 ID 的列表。可通过 `__call__` 方法获取。

skip_special_tokens (`bool`，*可选*，默认为 `False`)：是否在解码过程中移除特殊标记。

clean_up_tokenization_spaces (`bool`, *可选*) : 是否清理分词空格。

output_char_offsets (`bool`，*可选*，默认为 `False`)：是否输出字符偏移量。字符偏移量可与采样率和模型降采样率结合使用，以计算转录字符的时间戳。请查看下方的示例，以更好地了解如何使用 `output_char_offsets`。

output_word_offsets (`bool`，*可选*，默认为 `False`)：是否输出单词偏移量。单词偏移量可与采样率和模型降采样率结合使用，以计算转录单词的时间戳。请查看下方的示例，以更好地了解如何使用 `output_word_offsets`。

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

**返回：** `str` 或 `Wav2Vec2CTCTokenizerOutput`

解码后的句子列表。当 `output_char_offsets == True` 或 `output_word_offsets == True` 时，将是一个 `Wav2Vec2CTCTokenizerOutput`。

使用分词器和词汇表将字符串中的 id 序列进行转换，并可选择移除特殊标记以及清理分词空格。

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

示例：

```python
>>> # Let's see how to retrieve time steps for a model
>>> from transformers import AutoTokenizer, AutoFeatureExtractor, AutoModelForCTC
>>> from datasets import load_dataset
>>> import datasets
>>> import torch

>>> # import model, feature extractor, tokenizer
>>> model = AutoModelForCTC.from_pretrained("facebook/wav2vec2-base-960h")
>>> tokenizer = AutoTokenizer.from_pretrained("facebook/wav2vec2-base-960h")
>>> feature_extractor = AutoFeatureExtractor.from_pretrained("facebook/wav2vec2-base-960h")

>>> # load first sample of English common_voice
>>> dataset = load_dataset("mozilla-foundation/common_voice_11_0", "en", split="train", streaming=True)
>>> dataset = dataset.cast_column("audio", datasets.Audio(sampling_rate=16_000))
>>> dataset_iter = iter(dataset)
>>> sample = next(dataset_iter)

>>> # forward sample through model to get greedily predicted transcription ids
>>> input_values = feature_extractor(sample["audio"]["array"], return_tensors="pt").input_values
>>> logits = model(input_values).logits[0]
>>> pred_ids = torch.argmax(logits, axis=-1)

>>> # retrieve word stamps (analogous commands for `output_char_offsets`)
>>> outputs = tokenizer.decode(pred_ids, output_word_offsets=True)
>>> # compute `time_offset` in seconds as product of downsampling ratio and sampling_rate
>>> time_offset = model.config.inputs_to_logits_ratio / feature_extractor.sampling_rate

>>> word_offsets = [
...     {
...         "word": d["word"],
...         "start_time": round(d["start_offset"] * time_offset, 2),
...         "end_time": round(d["end_offset"] * time_offset, 2),
...     }
...     for d in outputs.word_offsets
... ]
>>> # compare word offsets with audio `en_train_0/common_voice_en_19121553.mp3` online on the dataset viewer:
>>> # https://huggingface.co/datasets/mozilla-foundation/common_voice_11_0/viewer/en
>>> word_offsets[:3]
[{'word': 'THE', 'start_time': 0.7, 'end_time': 0.78}, {'word': 'TRICK', 'start_time': 0.88, 'end_time': 1.08}, {'word': 'APPEARS', 'start_time': 1.2, 'end_time': 1.64}]
```

#### batch_decode[[transformers.Wav2Vec2CTCTokenizer.batch_decode]]

```python
batch_decode(sequences: typing.Union[list[int], list[list[int]], numpy.ndarray, ForwardRef('torch.Tensor')], skip_special_tokens: bool = False, clean_up_tokenization_spaces: bool | None = None, output_char_offsets: bool = False, output_word_offsets: bool = False, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/wav2vec2/tokenization_wav2vec2.py#L468)

**参数：**

sequences (`Union[list[int], list[list[int]], np.ndarray, torch.Tensor]`) : 标记化输入 ID 的列表。可通过 `__call__` 方法获取。

skip_special_tokens (`bool`，*可选*，默认为 `False`)：是否在解码过程中移除特殊标记。

clean_up_tokenization_spaces (`bool`, *可选*) : 是否清理分词空格。

output_char_offsets (`bool`，*可选*，默认为 `False`)：是否输出字符偏移量。字符偏移量可与采样率和模型降采样率结合使用，以计算转录字符的时间戳。请查看 [decode()](/docs/transformers/v5.23.0/zh/model_doc/wav2vec2#transformers.Wav2Vec2CTCTokenizer.decode) 的示例，以更好地理解如何使用 `output_char_offsets`。[batch_decode()](/docs/transformers/v5.23.0/zh/model_doc/wav2vec2#transformers.Wav2Vec2CTCTokenizer.batch_decode) 在处理批量输出时的工作方式相同。

output_word_offsets (`bool`，*可选*，默认为 `False`)：是否输出单词偏移量。单词偏移量可与采样率和模型降采样率结合使用，以计算转录单词的时间戳。请查看 [decode()](/docs/transformers/v5.23.0/zh/model_doc/wav2vec2#transformers.Wav2Vec2CTCTokenizer.decode) 的示例，以更好地理解如何使用 `output_word_offsets`。[batch_decode()](/docs/transformers/v5.23.0/zh/model_doc/wav2vec2#transformers.Wav2Vec2CTCTokenizer.batch_decode) 在处理批量输出时的工作方式相同。

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

**返回：** `list[str]` 或 `Wav2Vec2CTCTokenizerOutput`

解码后的句子列表。当 `output_char_offsets == True` 或 `output_word_offsets == True` 时，将是一个 `Wav2Vec2CTCTokenizerOutput`。

通过调用 decode，将 token id 的列表的列表转换为字符串列表。

#### set_target_lang[[transformers.Wav2Vec2CTCTokenizer.set_target_lang]]

```python
set_target_lang(target_lang: str)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/wav2vec2/tokenization_wav2vec2.py#L184)

设置嵌套多语言字典的目标语言

## Wav2Vec2FeatureExtractor[[transformers.Wav2Vec2FeatureExtractor]]

#### transformers.Wav2Vec2FeatureExtractor[[transformers.Wav2Vec2FeatureExtractor]]

```python
transformers.Wav2Vec2FeatureExtractor(feature_size = 1, sampling_rate = 16000, padding_value = 0.0, return_attention_mask = False, do_normalize = True, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/wav2vec2/feature_extraction_wav2vec2.py#L28)

**参数：**

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

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

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

do_normalize (`bool`, *可选*, 默认为 `True`) : 是否对输入进行零均值单位方差归一化。归一化可以显著提升某些模型的性能，*例如*，[wav2vec2-lv60](https://huggingface.co/models?search=lv60)。

return_attention_mask (`bool`，*可选*，默认为 `False`)：是否让 [__call__()](/docs/transformers/v5.23.0/zh/model_doc/wav2vec2#transformers.Wav2Vec2FeatureExtractor.__call__) 返回 `attention_mask`。已设置 `config.feat_extract_norm == "group"` 的 Wav2Vec2 模型（例如 [wav2vec2-base](https://huggingface.co/facebook/wav2vec2-base-960h)）在训练时**未**使用 `attention_mask`。对于此类模型，`input_values` 应直接用 0 填充，且不应传入 `attention_mask`。对于已设置 `config.feat_extract_norm == "layer"` 的 Wav2Vec2 模型（例如 [wav2vec2-lv60](https://huggingface.co/facebook/wav2vec2-large-960h-lv60-self)），在进行批量推理时应传入 `attention_mask`。

构建 Wav2Vec2 特征提取器。

此特征提取器继承自 [SequenceFeatureExtractor](/docs/transformers/v5.23.0/zh/main_classes/feature_extractor#transformers.SequenceFeatureExtractor)，后者包含了大部分主要方法。有关这些方法的更多信息，请参阅该父类。

#### __调用__[[transformers.Wav2Vec2FeatureExtractor.__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_attention_mask: bool | None = None, return_tensors: str | transformers.utils.generic.TensorType | None = None, sampling_rate: int | None = None, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/wav2vec2/feature_extraction_wav2vec2.py#L99)

**参数：**

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)，*可选*，默认为 `False`)：选择一种策略来填充返回的序列（根据模型的填充方向和填充索引），可选策略如下： - `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)    设置了 `config.feat_extract_norm == "group"` 的 Wav2Vec2 模型，例如 [wav2vec2-base](https://huggingface.co/facebook/wav2vec2-base-960h)，在训练时**未**使用 `attention_mask`。对于此类模型，`input_values` 应直接用 0 填充，且不应传入 `attention_mask`。  对于设置了 `config.feat_extract_norm == "layer"` 的 Wav2Vec2 模型，例如 [wav2vec2-lv60](https://huggingface.co/facebook/wav2vec2-large-960h-lv60-self)，在进行批量推理时应传入 `attention_mask`。

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) --

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

## Wav2Vec2Processor[[transformers.Wav2Vec2Processor]]

#### transformers.Wav2Vec2Processor[[transformers.Wav2Vec2Processor]]

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

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/wav2vec2/processing_wav2vec2.py#L25)

**参数：**

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

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

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

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

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

```python
__call__(audio: typing.Union[numpy.ndarray, ForwardRef('torch.Tensor'), list[numpy.ndarray], list['torch.Tensor'], NoneType] = None, text: str | list[str] | None = None, **kwargs: *<class 'transformers.processing_utils.ProcessingKwargs'>)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/wav2vec2/processing_wav2vec2.py#L29)

**参数：**

audio (`Union[numpy.ndarray, torch.Tensor, list[numpy.ndarray], list[torch.Tensor]]`, *可选*) : 要准备的音频或音频批次。每个音频可以是 NumPy 数组或 PyTorch 张量。对于 NumPy 数组/PyTorch 张量，每个音频的形状应为 (C, T)，其中 C 是通道数，T 是音频的采样长度。

text (`Union[str, list[str]]`，*可选*)：要编码的序列或序列批次。每个序列可以是字符串或字符串列表（预分词字符串）。如果传入预分词输入，请设置 `is_split_into_words=True` 以避免与批量输入产生歧义。

return_mm_token_type_ids (`bool`, *kwargs*) : 是否返回多模态 token 类型 ID，以指示多模态占位符 token 的位置。

return_text_replacement_offsets (`bool`, *kwargs*) : 是否返回每个多模态占位符及其替换项的字符偏移量。

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

- ****kwargs** ([ProcessingKwargs](/docs/transformers/v5.23.0/zh/main_classes/processors#transformers.ProcessingKwargs), *可选*) : 针对每种模态（文本、图像、视频、音频）的额外处理选项。模型特定参数已在上方列出；有关支持参数的完整列表，请参阅 TypedDict 类。

**返回值：**

此方法返回每个 `call` 方法的结果。如果两者都使用，输出将是一个包含两者结果的字典。

#### pad[[transformers.Wav2Vec2Processor.pad]]

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

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/wav2vec2/processing_wav2vec2.py#L61)

**参数：**

input_features : 当第一个参数是包含一批张量的字典，或者存在 `input_features` 参数时，它会传递给 [Wav2Vec2FeatureExtractor.pad()](/docs/transformers/v5.23.0/zh/main_classes/feature_extractor#transformers.SequenceFeatureExtractor.pad)。

labels : 当存在 `label` 参数时，它会传递给 [PreTrainedTokenizer.pad()](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.pad)。

**返回值：**

此方法返回每个 `pad` 方法的结果。如果两者都使用，输出将是一个包含两者结果的字典。

此方法处理提取的特征批次和/或分词后的文本。它根据输入模态将所有参数转发给 [Wav2Vec2FeatureExtractor.pad()](/docs/transformers/v5.23.0/zh/main_classes/feature_extractor#transformers.SequenceFeatureExtractor.pad) 和/或 [PreTrainedTokenizer.pad()](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.pad)，并返回它们的输出。如果同时传入两种模态，则会调用 [Wav2Vec2FeatureExtractor.pad()](/docs/transformers/v5.23.0/zh/main_classes/feature_extractor#transformers.SequenceFeatureExtractor.pad) 和 [PreTrainedTokenizer.pad()](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.pad)。

#### from_pretrained[[transformers.Wav2Vec2Processor.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.Wav2Vec2Processor.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.Wav2Vec2Processor.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.Wav2Vec2Processor.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)。有关更多信息，请参阅该方法的文档字符串。

## Wav2Vec2ProcessorWithLM[[transformers.Wav2Vec2ProcessorWithLM]]

> [!WARNING]
> [Wav2Vec2ProcessorWithLM](/docs/transformers/v5.23.0/zh/model_doc/wav2vec2#transformers.Wav2Vec2ProcessorWithLM) 以及基于 pyctcdecode + kenlm 的 n-gram 语言模型解码已被弃用，并将在 Transformers v6 中移除。它们依赖 pyctcdecode 和 kenlm，而这两个库不再随 `transformers[audio]` 一起安装。如需保留语言模型解码功能，请直接调用 pyctcdecode，参见 [迁移到 pyctcdecode](#migrating-to-pyctcdecode)。

#### transformers.Wav2Vec2ProcessorWithLM[[transformers.Wav2Vec2ProcessorWithLM]]

```python
transformers.Wav2Vec2ProcessorWithLM(feature_extractor: FeatureExtractionMixin, tokenizer: PreTrainedTokenizerBase, decoder: BeamSearchDecoderCTC)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/wav2vec2_with_lm/processing_wav2vec2_with_lm.py#L70)

**参数：**

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

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

decoder (`BeamSearchDecoderCTC`)：`pyctcdecode.BeamSearchDecoderCTC` 的实例。解码器是必需的输入。

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

[Wav2Vec2ProcessorWithLM](/docs/transformers/v5.23.0/zh/model_doc/wav2vec2#transformers.Wav2Vec2ProcessorWithLM) 提供了 `feature_extractor_class` 和 `tokenizer_class` 的所有功能。有关更多信息，请参阅 `~feature_extractor_class` 和 `~tokenizer_class`。

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

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

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/wav2vec2_with_lm/processing_wav2vec2_with_lm.py#L219)

**参数：**

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

#### pad[[transformers.Wav2Vec2ProcessorWithLM.pad]]

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

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/wav2vec2_with_lm/processing_wav2vec2_with_lm.py#L244)

在常规模式下使用时，此方法会将其所有参数转发给特征提取器的 `~FeatureExtractionMixin.pad` 并返回其输出。如果在 `~Wav2Vec2ProcessorWithLM.as_target_processor` 上下文中使用，此方法会将其所有参数转发给 Wav2Vec2CTCTokenizer 的 [pad()](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.pad)。有关更多信息，请参阅上述两个方法的文档字符串。

#### from_pretrained[[transformers.Wav2Vec2ProcessorWithLM.from_pretrained]]

```python
from_pretrained(pretrained_model_name_or_path, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/wav2vec2_with_lm/processing_wav2vec2_with_lm.py#L112)

**参数：**

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** : 同时传递给 [SequenceFeatureExtractor](/docs/transformers/v5.23.0/zh/main_classes/feature_extractor#transformers.SequenceFeatureExtractor) 和 [PreTrainedTokenizer](/docs/transformers/v5.23.0/zh/main_classes/tokenizer#transformers.PythonBackend) 的额外关键字参数

从预训练的 Wav2Vec2 处理器实例化一个 [Wav2Vec2ProcessorWithLM](/docs/transformers/v5.23.0/zh/model_doc/wav2vec2#transformers.Wav2Vec2ProcessorWithLM)。

This class method is simply calling the feature extractor's [from_pretrained()](/docs/transformers/v5.23.0/zh/main_classes/feature_extractor#transformers.FeatureExtractionMixin.from_pretrained), Wav2Vec2CTCTokenizer's [from_pretrained()](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.from_pretrained), and `pyctcdecode.BeamSearchDecoderCTC.load_from_hf_hub`.

有关更多信息，请参阅上述方法的文档字符串。

#### save_pretrained[[transformers.Wav2Vec2ProcessorWithLM.save_pretrained]]

```python
save_pretrained(save_directory)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/wav2vec2_with_lm/processing_wav2vec2_with_lm.py#L108)

#### batch_decode[[transformers.Wav2Vec2ProcessorWithLM.batch_decode]]

```python
batch_decode(logits: ndarray, pool: multiprocessing.pool.Pool | None = None, num_processes: int | None = None, beam_width: int | None = None, beam_prune_logp: float | None = None, token_min_logp: float | None = None, hotwords: collections.abc.Iterable[str] | None = None, hotword_weight: float | None = None, alpha: float | None = None, beta: float | None = None, unk_score_offset: float | None = None, lm_score_boundary: bool | None = None, output_word_offsets: bool = False, n_best: int = 1)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/wav2vec2_with_lm/processing_wav2vec2_with_lm.py#L271)

**参数：**

logits (`np.ndarray`) : 模型的 logits 输出向量，表示每个 token 的对数概率。

pool (`multiprocessing.Pool`，*可选*)：一个可选的由用户管理的进程池。如果未设置，将自动创建并关闭一个进程池。该进程池应在 `Wav2Vec2ProcessorWithLM` *之后* 实例化。否则，语言模型将无法在进程池的子进程中可用。目前，仅支持使用 'fork' 上下文创建的进程池。如果传入 'spawn' 进程池，它将被忽略，并改用顺序解码。

num_processes (`int`, *optional*) : 如果未设置 `pool`，则指定该函数应并行化的进程数。默认为可用 CPU 的数量。

beam_width (`int`, *可选*) : 解码过程中每一步的最大束数。默认为 pyctcdecode 的 DEFAULT_BEAM_WIDTH。

beam_prune_logp (`int`, *可选*) : 远差于最佳束的束将被剪枝。默认值为 pyctcdecode 的 DEFAULT_PRUNE_LOGP。

token_min_logp (`int`, *可选*) : 低于此 logp 的 token 将被跳过，除非它们是帧的 argmax。默认值为 pyctcdecode 的 DEFAULT_MIN_TOKEN_LOGP。

hotwords (`list[str]`，*可选*)：具有额外重要性的单词列表，对于语言模型（LM）而言可以是未登录词（OOV）

hotword_weight (`int`, *可选*) : 热词重要性的权重因子。默认值为 pyctcdecode 的 DEFAULT_HOTWORD_WEIGHT。

alpha (`float`, *可选*) : 浅层融合期间语言模型的权重

beta (`float`, *可选*) : 在评分过程中用于长度分数调整的权重

unk_score_offset (`float`, *可选*) : 未知标记的对数分数偏移量

lm_score_boundary (`bool`, *可选*) : 是否让 kenlm 在评分时遵循边界

output_word_offsets (`bool`，*可选*，默认为 `False`)：是否输出单词偏移量。单词偏移量可与采样率和模型降采样率结合使用，以计算转录单词的时间戳。

n_best (`int`, *可选*，默认为 `1`) : 要返回的最佳假设数量。如果 `n_best` 大于 1，则返回的 `text` 将是字符串列表的列表，`logit_score` 将是浮点数列表的列表，`lm_score` 也将是浮点数列表的列表，其中外层列表的长度对应于批处理大小，内层列表的长度对应于返回的假设数量。该值应 >= 1。 请查看 [decode()](/docs/transformers/v5.23.0/zh/model_doc/wav2vec2#transformers.Wav2Vec2ProcessorWithLM.decode) 的示例，以更好地了解如何使用 `output_word_offsets`。[batch_decode()](/docs/transformers/v5.23.0/zh/model_doc/wav2vec2#transformers.Wav2Vec2ProcessorWithLM.batch_decode) 以相同的方式处理批处理输出。

**返回值：**

`~models.wav2vec2.Wav2Vec2DecoderWithLMOutput`.

使用语言模型支持，将批量解码的输出 logits 转换为音频转录文本。

此函数使用了 Python 的 multiprocessing。目前，multiprocessing 仅在 Unix 系统上可用（参见此 [issue](https://github.com/kensho-technologies/pyctcdecode/issues/65)）。

如果您正在解码多个批次，建议创建一个 `Pool` 并将其传递给 `batch_decode`。否则，`batch_decode` 会非常慢，因为它会为每次调用创建一个新的 `Pool`。用法示例见下文。

示例：参见[解码多个音频](#decoding-multiple-audios)。

#### decode[[transformers.Wav2Vec2ProcessorWithLM.decode]]

```python
decode(logits: ndarray, beam_width: int | None = None, beam_prune_logp: float | None = None, token_min_logp: float | None = None, hotwords: collections.abc.Iterable[str] | None = None, hotword_weight: float | None = None, alpha: float | None = None, beta: float | None = None, unk_score_offset: float | None = None, lm_score_boundary: bool | None = None, output_word_offsets: bool = False, n_best: int = 1)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/wav2vec2_with_lm/processing_wav2vec2_with_lm.py#L456)

**参数：**

logits (`np.ndarray`) : 模型的 logits 输出向量，表示每个 token 的对数概率。

beam_width (`int`, *可选*) : 解码过程中每一步的最大束数。默认为 pyctcdecode 的 DEFAULT_BEAM_WIDTH。

beam_prune_logp (`int`, *可选*) : 用于剪枝 log-probs 小于 best_beam_logp + beam_prune_logp 的 beam 的阈值。该值应 <= 0。默认为 pyctcdecode 的 DEFAULT_PRUNE_LOGP。

token_min_logp (`int`, *可选*) : 除非某个 token 具有该话语的最大 log-prob，否则 log-prob 低于 token_min_logp 的 token 将被跳过。默认值为 pyctcdecode 的 DEFAULT_MIN_TOKEN_LOGP。

hotwords (`list[str]`, *可选*) : 包含额外重要词语的列表，这些词语可能不在语言模型的词汇表中，例如 ["huggingface"]

hotword_weight (`int`, *可选*) : 用于提升热词得分的权重乘数。默认值为 pyctcdecode 的 DEFAULT_HOTWORD_WEIGHT。

alpha (`float`, *可选*) : 浅层融合期间语言模型的权重

beta (`float`, *可选*) : 在评分过程中用于长度分数调整的权重

unk_score_offset (`float`, *可选*) : 未知标记的对数分数偏移量

lm_score_boundary (`bool`, *可选*) : 是否让 kenlm 在评分时遵循边界

output_word_offsets (`bool`，*可选*，默认为 `False`)：是否输出单词偏移量。单词偏移量可与采样率和模型降采样率结合使用，以计算转录单词的时间戳。

n_best (`int`, *可选*，默认为 `1`) : 要返回的最佳假设数量。如果 `n_best` 大于 1，则返回的 `text` 将是字符串列表，`logit_score` 将是浮点数列表，`lm_score` 也将是浮点数列表，这些列表的长度将与返回的假设数量相对应。该值应 >= 1。 请查看下面的示例，以更好地了解如何使用 `output_word_offsets`。

**返回值：**

`~models.wav2vec2.Wav2Vec2DecoderWithLMOutput`.

使用语言模型支持将解码输出的 logits 转换为音频转录文本。

示例：

```python
>>> # Let's see how to retrieve time steps for a model
>>> from transformers import AutoTokenizer, AutoProcessor, AutoModelForCTC
>>> from datasets import load_dataset
>>> import datasets
>>> import torch

>>> # import model, feature extractor, tokenizer
>>> model = AutoModelForCTC.from_pretrained("patrickvonplaten/wav2vec2-base-100h-with-lm")
>>> processor = AutoProcessor.from_pretrained("patrickvonplaten/wav2vec2-base-100h-with-lm")

>>> # load first sample of English common_voice
>>> dataset = load_dataset("mozilla-foundation/common_voice_11_0", "en", split="train", streaming=True)
>>> dataset = dataset.cast_column("audio", datasets.Audio(sampling_rate=16_000))
>>> dataset_iter = iter(dataset)
>>> sample = next(dataset_iter)

>>> # forward sample through model to get greedily predicted transcription ids
>>> input_values = processor(sample["audio"]["array"], return_tensors="pt").input_values
>>> with torch.no_grad():
...     logits = model(input_values).logits[0].cpu().numpy()

>>> # retrieve word stamps (analogous commands for `output_char_offsets`)
>>> outputs = processor.decode(logits, output_word_offsets=True)
>>> # compute `time_offset` in seconds as product of downsampling ratio and sampling_rate
>>> time_offset = model.config.inputs_to_logits_ratio / processor.feature_extractor.sampling_rate

>>> word_offsets = [
...     {
...         "word": d["word"],
...         "start_time": round(d["start_offset"] * time_offset, 2),
...         "end_time": round(d["end_offset"] * time_offset, 2),
...     }
...     for d in outputs.word_offsets
... ]
>>> # compare word offsets with audio `en_train_0/common_voice_en_19121553.mp3` online on the dataset viewer:
>>> # https://huggingface.co/datasets/mozilla-foundation/common_voice_11_0/viewer/en
>>> word_offsets[:4]
[{'word': 'THE', 'start_time': 0.68, 'end_time': 0.78}, {'word': 'TRACK', 'start_time': 0.88, 'end_time': 1.1}, {'word': 'APPEARS', 'start_time': 1.18, 'end_time': 1.66}, {'word': 'ON', 'start_time': 1.86, 'end_time': 1.92}]
```

### 解码多个音频

> [!WARNING]
> 此示例使用了已弃用的 [Wav2Vec2ProcessorWithLM](/docs/transformers/v5.23.0/zh/model_doc/wav2vec2#transformers.Wav2Vec2ProcessorWithLM)。对于新代码，请改为将 `multiprocessing.Pool` 传递给 pyctcdecode 的 `decode_beams_batch`，参见 [迁移到 pyctcdecode](#migrating-to-pyctcdecode)。

如果您计划解码多个音频批次，应考虑使用 [batch_decode()](/docs/transformers/v5.23.0/zh/model_doc/wav2vec2#transformers.Wav2Vec2ProcessorWithLM.batch_decode) 并传入一个已实例化的 `multiprocessing.Pool`。否则，[batch_decode()](/docs/transformers/v5.23.0/zh/model_doc/wav2vec2#transformers.Wav2Vec2ProcessorWithLM.batch_decode) 的性能将慢于对每个音频单独调用 [decode()](/docs/transformers/v5.23.0/zh/model_doc/wav2vec2#transformers.Wav2Vec2ProcessorWithLM.decode)，因为它在每次调用时都会在内部实例化一个新的 `Pool`。请参阅以下示例：

```python
# Let's see how to use a user-managed pool for batch decoding multiple audios
from multiprocessing import get_context

import datasets
import torch
from datasets import load_dataset

from transformers import AutoModelForCTC, AutoProcessor

# import model, feature extractor, tokenizer
model = AutoModelForCTC.from_pretrained("patrickvonplaten/wav2vec2-base-100h-with-lm", device_map="auto")
processor = AutoProcessor.from_pretrained("patrickvonplaten/wav2vec2-base-100h-with-lm")

# load example dataset
dataset = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")
dataset = dataset.cast_column("audio", datasets.Audio(sampling_rate=16_000))

def map_to_array(example):
    example["speech"] = example["audio"]["array"]
    return example

# prepare speech data for batch inference
dataset = dataset.map(map_to_array, remove_columns=["audio"])

def map_to_pred(batch, pool):
    inputs = processor(batch["speech"], sampling_rate=16_000, padding=True, return_tensors="pt").to(model.device)
    inputs = {k: v.to(model.device) for k, v in inputs.items()}

    with torch.no_grad():
        logits = model(**inputs).logits

    transcription = processor.batch_decode(logits.cpu().numpy(), pool).text
    batch["transcription"] = transcription
    return batch

# note: pool should be instantiated *after* `Wav2Vec2ProcessorWithLM`.
#       otherwise, the LM won't be available to the pool's sub-processes
# select number of processes and batch_size based on number of CPU cores available and on dataset size
with get_context("fork").Pool(processes=2) as pool:
    result = dataset.map(
        map_to_pred, batched=True, batch_size=2, fn_kwargs={"pool": pool}, remove_columns=["speech"]
    )

result["transcription"][:2]
['MISTER QUILTER IS THE APOSTLE OF THE MIDDLE CLASSES AND WE ARE GLAD TO WELCOME HIS GOSPEL', "NOR IS MISTER COULTER'S MANNER LESS INTERESTING THAN HIS MATTER"]
```

### 迁移到 pyctcdecode

[Wav2Vec2ProcessorWithLM](/docs/transformers/v5.23.0/zh/model_doc/wav2vec2#transformers.Wav2Vec2ProcessorWithLM) 是 [pyctcdecode](https://github.com/kensho-technologies/pyctcdecode) 的轻量级封装。使用 [Wav2Vec2Processor](/docs/transformers/v5.23.0/zh/model_doc/wav2vec2#transformers.Wav2Vec2Processor) 加载特征提取器和分词器，使用 pyctcdecode 加载语言模型，并对 logits 调用 pyctcdecode。这将得到与 [batch_decode()](/docs/transformers/v5.23.0/zh/model_doc/wav2vec2#transformers.Wav2Vec2ProcessorWithLM.batch_decode) 相同的转录结果。它需要 [pyctcdecode](https://github.com/kensho-technologies/pyctcdecode) 和 [kenlm](https://github.com/kpu/kenlm)，而这两者不再随 `transformers[audio]` 一起安装。

```python
import torch
from pyctcdecode import BeamSearchDecoderCTC

from transformers import AutoModelForCTC, Wav2Vec2Processor

repo = "patrickvonplaten/wav2vec2-base-100h-with-lm"
model = AutoModelForCTC.from_pretrained(repo)
processor = Wav2Vec2Processor.from_pretrained(repo)  # feature extractor + tokenizer
# only download the language model and the alphabet, not the model weights
decoder = BeamSearchDecoderCTC.load_from_hf_hub(repo, allow_patterns=["language_model/*", "alphabet.json"])

inputs = processor(audio, sampling_rate=16_000, padding=True, return_tensors="pt")
with torch.no_grad():
    logits = model(**inputs).logits.cpu().numpy()

# was: processor_with_lm.batch_decode(logits, alpha=0.5, beta=1.0, beam_width=50).text

# `alpha`, `beta`, `unk_score_offset` and `lm_score_boundary` are set on the decoder (values that are not passed are kept)
decoder.reset_params(alpha=0.5, beta=1.0)

# drop the frames padded with -100, as `batch_decode` does
logits_list = [sample[(sample != -100.0).all(axis=-1)] for sample in logits]

# `beam_width`, `beam_prune_logp`, `token_min_logp`, `hotwords` and `hotword_weight` are decoding arguments
beams = decoder.decode_beams_batch(None, logits_list, beam_width=50)
transcription = [sample_beams[0][0] for sample_beams in beams]
```

- **单个样本**：`processor_with_lm.decode(logits[0]).text` 变为 `decoder.decode_beams(logits[0])[0][0]`。
- 使用 **`decode_beams` / `decode_beams_batch`**，而不是 `decode` / `decode_batch`：后者会修剪 beam 历史，可能导致不同的转录结果。
- **并行解码**：将使用 `fork` 上下文创建的 `multiprocessing.Pool` 作为 `decode_beams_batch` 的第一个参数传入。
- **Beams** 按最优优先排序，并携带分数和单词偏移量：
  - `decode_beams_batch`: `(text, word_offsets, logit_score, lm_score)`;
  - `decode_beams`: `(text, last_lm_state, word_offsets, logit_score, lm_score)`.

要在没有语言模型的情况下进行解码，请在每一帧选择最可能的 token：

```python
transcription = processor.batch_decode(logits.argmax(-1))
```

## Wav2Vec2 特定输出[[transformers.models.wav2vec2_with_lm.processing_wav2vec2_with_lm.Wav2Vec2DecoderWithLMOutput]]

#### transformers.models.wav2vec2_with_lm.processing_wav2vec2_with_lm.Wav2Vec2DecoderWithLMOutput[[transformers.models.wav2vec2_with_lm.processing_wav2vec2_with_lm.Wav2Vec2DecoderWithLMOutput]]

```python
transformers.models.wav2vec2_with_lm.processing_wav2vec2_with_lm.Wav2Vec2DecoderWithLMOutput(text: list[list[str]] | list[str] | str, logit_score: list[list[float]] | list[float] | float = None, lm_score: list[list[float]] | list[float] | float = None, word_offsets: list[list[list[dict[str, int | str]]]] | list[list[dict[str, int | str]]] | list[dict[str, int | str]] = None)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/wav2vec2_with_lm/processing_wav2vec2_with_lm.py#L46)

**参数：**

text （`str` 或 `str` 的列表）：以文本形式解码的 logits。通常是语音转录结果。

logit_score （`float` 或 `float` 的列表）：与生成的文本相关联的 beam 的总 logit 分数。

lm_score （`float` 列表）：与生成的文本相关联的 beam 的融合 lm_score。

word_offsets （`list[dict[str, Union[int, str]]]` 或 `list[dict[str, Union[int, str]]]` 列表）：解码后单词的偏移量。结合采样率和模型下采样率，单词偏移量可用于计算每个单词的时间戳。

[decode()](/docs/transformers/v5.23.0/zh/model_doc/wav2vec2#transformers.Wav2Vec2ProcessorWithLM.decode) 和 [batch_decode()](/docs/transformers/v5.23.0/zh/model_doc/wav2vec2#transformers.Wav2Vec2ProcessorWithLM.batch_decode) 的输出类型。已弃用，将在 Transformers v6 中移除。

#### transformers.modeling_outputs.Wav2Vec2BaseModelOutput[[transformers.modeling_outputs.Wav2Vec2BaseModelOutput]]

```python
transformers.modeling_outputs.Wav2Vec2BaseModelOutput(last_hidden_state: typing.Optional[torch.Tensor] = None, extract_features: typing.Optional[torch.Tensor] = None, hidden_states: tuple[torch.Tensor, ...] | None = None, attentions: tuple[torch.Tensor, ...] | None = None)
```

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

**参数：**

last_hidden_state （形状为 `(batch_size, sequence_length, hidden_size)` 的 `torch.Tensor`）：模型最后一层输出的隐藏状态序列。

extract_features (`torch.Tensor`，形状为 `(batch_size, sequence_length, conv_dim[-1])`)：模型最后一个卷积层提取的特征向量序列。

hidden_states (`tuple(torch.Tensor)`，*可选*，在传入 `output_hidden_states=True` 或 `config.output_hidden_states=True` 时返回)：一个 `torch.Tensor` 元组（包含嵌入层输出以及每一层的输出），形状为 `(batch_size, sequence_length, hidden_size)`。模型在每一层输出处的隐藏状态以及初始嵌入输出。

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

使用 Wav2Vec2 损失目标进行训练的模型基类。

#### transformers.models.wav2vec2.modeling_wav2vec2.Wav2Vec2ForPreTrainingOutput[[transformers.models.wav2vec2.modeling_wav2vec2.Wav2Vec2ForPreTrainingOutput]]

```python
transformers.models.wav2vec2.modeling_wav2vec2.Wav2Vec2ForPreTrainingOutput(loss: typing.Optional[torch.Tensor] = None, projected_states: typing.Optional[torch.Tensor] = None, projected_quantized_states: typing.Optional[torch.Tensor] = None, codevector_perplexity: typing.Optional[torch.Tensor] = None, hidden_states: tuple[torch.Tensor] | None = None, attentions: tuple[torch.Tensor] | None = None, contrastive_loss: typing.Optional[torch.Tensor] = None, diversity_loss: typing.Optional[torch.Tensor] = None)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/wav2vec2/modeling_wav2vec2.py#L76)

**参数：**

loss (`*optional*`，当传入 `sample_negative_indices` 时返回，形状为 `(1,)` 的 `torch.Tensor`) : 如[官方论文](https://huggingface.co/papers/2006.11477)所述，对比损失 (L_m) 与多样性损失 (L_d) 之和的总损失。

projected_states (`torch.Tensor`，形状为 `(batch_size, sequence_length, config.proj_codevector_dim)`)：模型隐藏状态投影到 *config.proj_codevector_dim* 后的结果，可用于预测被掩码的投影量化状态。

projected_quantized_states (`torch.Tensor`，形状为 `(batch_size, sequence_length, config.proj_codevector_dim)`)：量化后的提取特征向量，投影至 *config.proj_codevector_dim*，表示用于对比损失的阳性目标向量。

codevector_perplexity (`torch.Tensor`，形状为 `(1,)`)：码向量分布的困惑度，用于衡量码本多样性。

hidden_states (`tuple[torch.Tensor]`，*可选*，在传入 `output_hidden_states=True` 或 `config.output_hidden_states=True` 时返回)：一个 `torch.Tensor` 元组（如果模型具有嵌入层，则包含嵌入层输出的一个张量，以及每个层输出的一个张量），形状为 `(batch_size, sequence_length, hidden_size)`。模型在每层输出处的隐藏状态，以及可选的初始嵌入输出。

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

contrastive_loss (`*optional*`，当传入 `sample_negative_indices` 时返回，形状为 `(1,)` 的 `torch.Tensor`) : [官方论文](https://huggingface.co/papers/2006.11477)中所述的对比损失 (L_m)。

diversity_loss (`*optional*`，当传入 `sample_negative_indices` 时返回，形状为 `(1,)` 的 `torch.Tensor`) : [官方论文](https://huggingface.co/papers/2006.11477)中所述的多样性损失 (L_d)。

[Wav2Vec2ForPreTraining](/docs/transformers/v5.23.0/zh/model_doc/wav2vec2#transformers.Wav2Vec2ForPreTraining) 的输出类型，可能包含隐藏状态和注意力。

## Wav2Vec2Model[[transformers.Wav2Vec2Model]]

#### transformers.Wav2Vec2Model[[transformers.Wav2Vec2Model]]

```python
transformers.Wav2Vec2Model(config: Wav2Vec2Config)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/wav2vec2/modeling_wav2vec2.py#L1197)

**参数：**

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

输出原始隐藏状态、顶部未附加任何特定头部的裸 Wav2Vec2 模型。

该模型继承自 [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.Wav2Vec2Model.forward]]

```python
forward(input_values: typing.Optional[torch.Tensor], attention_mask: typing.Optional[torch.Tensor] = None, mask_time_indices: typing.Optional[torch.Tensor] = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/wav2vec2/modeling_wav2vec2.py#L1271)

**参数：**

input_values (`torch.Tensor`，形状为 `(batch_size, sequence_length)`，*可选*) : 输入原始语音波形的浮点值。可以通过将 `.flac` 或 `.wav` 音频文件加载为 `list[float]`、`numpy.ndarray` 或 `torch.Tensor` 类型的数组来获取这些值，*例如* 使用 torchcodec 库（`pip install torchcodec`）或 soundfile 库（`pip install soundfile`）。要将该数组准备为 `input_values`，应使用 [AutoProcessor](/docs/transformers/v5.23.0/zh/model_doc/auto#transformers.AutoProcessor) 进行填充并转换为 `torch.Tensor` 类型的张量。有关详细信息，请参阅 [Wav2Vec2Processor.__call__()](/docs/transformers/v5.23.0/zh/model_doc/wav2vec2#transformers.Wav2Vec2Processor.__call__)。

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

mask_time_indices (`torch.BoolTensor`，形状为 `(batch_size, sequence_length)`，*可选*)：用于掩码提取特征以计算对比损失的索引。在训练模式下，模型学习在 *config.proj_codevector_dim* 空间中预测被掩码的提取特征。

**返回：** [Wav2Vec2BaseModelOutput](/docs/transformers/v5.23.0/zh/model_doc/wav2vec2#transformers.modeling_outputs.Wav2Vec2BaseModelOutput) 或 `tuple(torch.Tensor)`

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

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

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

- **last_hidden_state**（形状为 `(batch_size, sequence_length, hidden_size)` 的 `torch.Tensor`）-- 模型最后一层输出的隐藏状态序列。
- **extract_features**（形状为 `(batch_size, sequence_length, conv_dim[-1])` 的 `torch.Tensor`）-- 模型最后一个卷积层提取的特征向量序列。
- **hidden_states** (`tuple(torch.Tensor)`，*可选*，在传入 `output_hidden_states=True` 或 `config.output_hidden_states=True` 时返回) -- 一个 `torch.Tensor` 元组（包含嵌入层的输出以及每一层的输出），形状为 `(batch_size, sequence_length, hidden_size)`。

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

  经过注意力 softmax 后的注意力权重，用于在自注意力头中计算加权平均值。

## Wav2Vec2ForCTC[[transformers.Wav2Vec2ForCTC]]

#### transformers.Wav2Vec2ForCTC[[transformers.Wav2Vec2ForCTC]]

```python
transformers.Wav2Vec2ForCTC(config: Wav2Vec2Config, target_lang: str | None = None)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/wav2vec2/modeling_wav2vec2.py#L1525)

**参数：**

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

target_lang (`str`, *可选*) : 适配器权重的语言 ID。适配器权重以 adapter..safetensors 或 adapter..bin 格式存储。仅在使用带有适配器的 [Wav2Vec2ForCTC](/docs/transformers/v5.23.0/zh/model_doc/wav2vec2#transformers.Wav2Vec2ForCTC) 实例时相关。默认使用 'eng'。

带有 `language modeling` 头部的 Wav2Vec2 模型，用于连接主义时间分类（CTC）。

该模型继承自 [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.Wav2Vec2ForCTC.forward]]

```python
forward(input_values: typing.Optional[torch.Tensor], attention_mask: typing.Optional[torch.Tensor] = None, labels: typing.Optional[torch.Tensor] = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/wav2vec2/modeling_wav2vec2.py#L1594)

**参数：**

input_values (`torch.Tensor`，形状为 `(batch_size, sequence_length)`，*可选*) : 输入原始语音波形的浮点值。可以通过将 `.flac` 或 `.wav` 音频文件加载为 `list[float]`、`numpy.ndarray` 或 `torch.Tensor` 类型的数组来获取这些值，*例如* 使用 torchcodec 库（`pip install torchcodec`）或 soundfile 库（`pip install soundfile`）。要将该数组准备为 `input_values`，应使用 [AutoProcessor](/docs/transformers/v5.23.0/zh/model_doc/auto#transformers.AutoProcessor) 进行填充并转换为 `torch.Tensor` 类型的张量。有关详细信息，请参阅 [Wav2Vec2Processor.__call__()](/docs/transformers/v5.23.0/zh/model_doc/wav2vec2#transformers.Wav2Vec2Processor.__call__)。

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

labels (`torch.LongTensor`，形状为 `(batch_size, target_length)`，*可选*)：用于连接时序分类的标签。请注意，`target_length` 必须小于或等于输出 logits 的序列长度。索引的取值范围为 `[-100, 0, ..., config.vocab_size - 1]`。所有设置为 `-100` 的标签都会被忽略（即被掩码），损失仅针对 `[0, ..., config.vocab_size - 1]` 范围内的标签进行计算。

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

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

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

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

- **loss** (`torch.Tensor`，形状为 `(1,)`，*可选*，当提供 `labels` 时返回) -- 语言建模损失（用于下一个 token 预测）。
- **logits**（形状为 `(batch_size, sequence_length, config.vocab_size)` 的 `torch.Tensor`）-- 语言建模头的预测分数（SoftMax 之前每个词汇表 token 的分数）。
- **hidden_states** (`tuple(torch.Tensor)`，*可选*，在传入 `output_hidden_states=True` 或 `config.output_hidden_states=True` 时返回) -- 一个 `torch.Tensor` 元组（如果模型具有嵌入层，则包含嵌入层的输出，以及每一层的输出），形状为 `(batch_size, sequence_length, hidden_size)`。

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

  经过注意力 softmax 后的注意力权重，用于在自注意力头中计算加权平均值。

示例：

```python
>>> from transformers import AutoProcessor, Wav2Vec2ForCTC
>>> from datasets import load_dataset
>>> import torch

>>> dataset = load_dataset("hf-internal-testing/librispeech_asr_demo", "clean", split="validation")
>>> dataset = dataset.sort("id")
>>> sampling_rate = dataset.features["audio"].sampling_rate

>>> processor = AutoProcessor.from_pretrained("facebook/wav2vec2-base-960h")
>>> model = Wav2Vec2ForCTC.from_pretrained("facebook/wav2vec2-base-960h")

>>> # audio file is decoded on the fly
>>> inputs = processor(dataset[0]["audio"]["array"], sampling_rate=sampling_rate, return_tensors="pt")
>>> with torch.no_grad():
...     logits = model(**inputs).logits
>>> predicted_ids = torch.argmax(logits, dim=-1)

>>> # transcribe speech
>>> transcription = processor.batch_decode(predicted_ids)
>>> transcription[0]
...

>>> inputs["labels"] = processor(text=dataset[0]["text"], return_tensors="pt").input_ids

>>> # compute loss
>>> loss = model(**inputs).loss
>>> round(loss.item(), 2)
...
```

#### load_adapter[[transformers.Wav2Vec2ForCTC.load_adapter]]

```python
load_adapter(target_lang: str, force_load = True, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/wav2vec2/modeling_wav2vec2.py#L1020)

**参数：**

target_lang (`str`) : 必须是现有适配器权重的语言 ID。适配器权重以 adapter..safetensors 或 adapter..bin 格式存储

force_load (`bool`，默认为 `True`) : 即使 `target_lang` 与 `self.target_lang` 匹配，是否仍应加载权重。

cache_dir (`Union[str, os.PathLike]`，*可选*)：如果不应使用标准缓存，则下载的预训练模型配置应缓存到的目录路径。

force_download (`bool`，*可选*，默认为 `False`)：是否强制（重新）下载模型权重和配置文件，如果存在缓存版本则覆盖它们。

proxies (`dict[str, str]`，*可选*)：一个字典，按协议或端点指定要使用的代理服务器，例如 `{'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}`。每次请求都会使用这些代理。

local_files_only(`bool`，*可选*，默认为 `False`)：是否仅查看本地文件（即不尝试下载模型）。

token (`str` 或 `bool`，*可选*) : 用于远程文件的 HTTP bearer 授权令牌。如果为 `True` 或未指定，将使用运行 `hf auth login` 时生成的令牌（存储在 `~/.huggingface` 中）。

revision (`str`, *可选*，默认为 `"main"`) : 要使用的特定模型版本。由于我们在 huggingface.co 上使用基于 git 的系统来存储模型和其他工件，因此它可以是分支名称、标签名称或提交 id，`revision` 可以是 git 允许的任何标识符。    若要测试您在 Hub 上创建的拉取请求，可以传入 `revision="refs/pr/<pr_number>"`。

mirror (`str`, *可选*) : 用于加速中国境内下载的镜像源。如果您在中国且遇到访问问题，可以设置此选项以解决。请注意，我们不保证镜像源的时效性或安全性。更多信息请参阅镜像站点。

从预训练的适配器模型加载语言适配器模型。

启用特殊的 ["offline-mode"](https://huggingface.co/transformers/installation.html#offline-mode)，以便在防火墙环境中使用此方法。

示例：

```python
>>> from transformers import Wav2Vec2ForCTC, AutoProcessor

>>> ckpt = "facebook/mms-1b-all"
>>> processor = AutoProcessor.from_pretrained(ckpt)
>>> model = Wav2Vec2ForCTC.from_pretrained(ckpt, target_lang="eng")
>>> # set specific language
>>> processor.tokenizer.set_target_lang("spa")
>>> model.load_adapter("spa")
```

## Wav2Vec2ForSequenceClassification[[transformers.Wav2Vec2ForSequenceClassification]]

#### transformers.Wav2Vec2ForSequenceClassification[[transformers.Wav2Vec2ForSequenceClassification]]

```python
transformers.Wav2Vec2ForSequenceClassification(config: Wav2Vec2Config)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/wav2vec2/modeling_wav2vec2.py#L1652)

**参数：**

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

Wav2Vec2 模型，顶部带有用于 SUPERB 关键词检测等任务的序列分类头（在池化输出上的线性层）。

该模型继承自 [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.Wav2Vec2ForSequenceClassification.forward]]

```python
forward(input_values: typing.Optional[torch.Tensor], attention_mask: typing.Optional[torch.Tensor] = None, labels: typing.Optional[torch.Tensor] = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/wav2vec2/modeling_wav2vec2.py#L1685)

**参数：**

input_values (`torch.Tensor`，形状为 `(batch_size, sequence_length)`) : 输入原始语音波形的浮点值。可以通过将 `.flac` 或 `.wav` 音频文件加载为 `list[float]`、`numpy.ndarray` 或 `torch.Tensor` 类型的数组来获取这些值，*例如* 使用 torchcodec 库（`pip install torchcodec`）或 soundfile 库（`pip install soundfile`）。要将数组准备为 `input_values`，应使用 [AutoProcessor](/docs/transformers/v5.23.0/zh/model_doc/auto#transformers.AutoProcessor) 进行填充并转换为 `torch.Tensor` 类型的张量。有关详细信息，请参阅 [Wav2Vec2Processor.__call__()](/docs/transformers/v5.23.0/zh/model_doc/wav2vec2#transformers.Wav2Vec2Processor.__call__)。

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

labels (`torch.LongTensor`，形状为 `(batch_size,)`，*可选*)：用于计算序列分类/回归损失的标签。索引应在 `[0, ..., config.num_labels - 1]` 范围内。如果 `config.num_labels == 1`，则计算回归损失（均方损失）；如果 `config.num_labels > 1`，则计算分类损失（交叉熵）。

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

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

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

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

- **loss** (`torch.Tensor`，形状为 `(1,)`，*可选*，当提供 `labels` 时返回) -- 分类损失（如果 config.num_labels==1，则为回归损失）。
- **logits**（形状为 `(batch_size, config.num_labels)` 的 `torch.Tensor`）-- 分类（或当 config.num_labels==1 时为回归）得分（SoftMax 之前）。
- **hidden_states** (`tuple(torch.Tensor)`，*可选*，在传入 `output_hidden_states=True` 或 `config.output_hidden_states=True` 时返回) -- 一个 `torch.Tensor` 元组（如果模型具有嵌入层，则包含嵌入层的输出，以及每一层的输出），形状为 `(batch_size, sequence_length, hidden_size)`。

  模型在每一层输出处的隐藏状态，以及可选的初始嵌入输出。
- **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 AutoTokenizer, Wav2Vec2ForSequenceClassification

>>> tokenizer = AutoTokenizer.from_pretrained("facebook/wav2vec2-base-960h")
>>> model = Wav2Vec2ForSequenceClassification.from_pretrained("facebook/wav2vec2-base-960h")

>>> inputs = tokenizer("Hello, my dog is cute", return_tensors="pt")

>>> with torch.no_grad():
...     logits = model(**inputs).logits

>>> predicted_class_id = logits.argmax().item()
>>> model.config.id2label[predicted_class_id]
...

>>> # To train a model on `num_labels` classes, you can pass `num_labels=num_labels` to `.from_pretrained(...)`
>>> num_labels = len(model.config.id2label)
>>> model = Wav2Vec2ForSequenceClassification.from_pretrained("facebook/wav2vec2-base-960h", num_labels=num_labels)

>>> labels = torch.tensor([1])
>>> loss = model(**inputs, labels=labels).loss
>>> round(loss.item(), 2)
...
```

多标签分类示例：

```python
>>> import torch
>>> from transformers import AutoTokenizer, Wav2Vec2ForSequenceClassification

>>> tokenizer = AutoTokenizer.from_pretrained("facebook/wav2vec2-base-960h")
>>> model = Wav2Vec2ForSequenceClassification.from_pretrained("facebook/wav2vec2-base-960h", problem_type="multi_label_classification")

>>> inputs = tokenizer("Hello, my dog is cute", return_tensors="pt")

>>> with torch.no_grad():
...     logits = model(**inputs).logits

>>> predicted_class_ids = torch.arange(0, logits.shape[-1])[torch.sigmoid(logits).squeeze(dim=0) > 0.5]

>>> # To train a model on `num_labels` classes, you can pass `num_labels=num_labels` to `.from_pretrained(...)`
>>> num_labels = len(model.config.id2label)
>>> model = Wav2Vec2ForSequenceClassification.from_pretrained(
...     "facebook/wav2vec2-base-960h", num_labels=num_labels, problem_type="multi_label_classification"
... )

>>> labels = torch.sum(
...     torch.nn.functional.one_hot(predicted_class_ids[None, :].clone(), num_classes=num_labels), dim=1
... ).to(torch.float)
>>> loss = model(**inputs, labels=labels).loss
```

## Wav2Vec2ForAudioFrameClassification[[transformers.Wav2Vec2ForAudioFrameClassification]]

#### transformers.Wav2Vec2ForAudioFrameClassification[[transformers.Wav2Vec2ForAudioFrameClassification]]

```python
transformers.Wav2Vec2ForAudioFrameClassification(config: Wav2Vec2Config)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/wav2vec2/modeling_wav2vec2.py#L1745)

**参数：**

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

带有帧分类头部的 Wav2Vec2 模型，用于说话人分离等任务。

该模型继承自 [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.Wav2Vec2ForAudioFrameClassification.forward]]

```python
forward(input_values: typing.Optional[torch.Tensor], attention_mask: typing.Optional[torch.Tensor] = None, labels: typing.Optional[torch.Tensor] = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/wav2vec2/modeling_wav2vec2.py#L1777)

**参数：**

input_values (`torch.Tensor`，形状为 `(batch_size, sequence_length)`) : 输入原始语音波形的浮点值。可以通过将 `.flac` 或 `.wav` 音频文件加载为 `list[float]`、`numpy.ndarray` 或 `torch.Tensor` 类型的数组来获取这些值，*例如* 使用 torchcodec 库（`pip install torchcodec`）或 soundfile 库（`pip install soundfile`）。要将数组准备为 `input_values`，应使用 [AutoProcessor](/docs/transformers/v5.23.0/zh/model_doc/auto#transformers.AutoProcessor) 进行填充并转换为 `torch.Tensor` 类型的张量。有关详细信息，请参阅 [Wav2Vec2Processor.__call__()](/docs/transformers/v5.23.0/zh/model_doc/wav2vec2#transformers.Wav2Vec2Processor.__call__)。

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

labels (`torch.LongTensor`，形状为 `(batch_size,)`，*可选*)：用于计算序列分类/回归损失的标签。索引应在 `[0, ..., config.num_labels - 1]` 范围内。如果 `config.num_labels == 1`，则计算回归损失（均方损失）；如果 `config.num_labels > 1`，则计算分类损失（交叉熵）。

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

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

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

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

- **loss** (`torch.Tensor`，形状为 `(1,)`，*可选*，在提供 `labels` 时返回) -- 分类损失。
- **logits**（形状为 `(batch_size, sequence_length, config.num_labels)` 的 `torch.Tensor`）-- 分类分数（SoftMax 之前）。
- **hidden_states** (`tuple(torch.Tensor)`，*可选*，在传入 `output_hidden_states=True` 或 `config.output_hidden_states=True` 时返回) -- 一个 `torch.Tensor` 元组（如果模型具有嵌入层，则包含嵌入层的输出，以及每一层的输出），形状为 `(batch_size, sequence_length, hidden_size)`。

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

  经过注意力 softmax 后的注意力权重，用于在自注意力头中计算加权平均值。

示例：

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

>>> dataset = load_dataset("hf-internal-testing/librispeech_asr_demo", "clean", split="validation")
>>> dataset = dataset.sort("id")
>>> sampling_rate = dataset.features["audio"].sampling_rate

>>> feature_extractor = AutoFeatureExtractor.from_pretrained("facebook/wav2vec2-base-960h")
>>> model = Wav2Vec2ForAudioFrameClassification.from_pretrained("facebook/wav2vec2-base-960h")

>>> # audio file is decoded on the fly
>>> inputs = feature_extractor(dataset[0]["audio"]["array"], return_tensors="pt", sampling_rate=sampling_rate)
>>> with torch.no_grad():
...     logits = model(**inputs).logits

>>> probabilities = torch.sigmoid(logits[0])
>>> # labels is a one-hot array of shape (num_frames, num_speakers)
>>> labels = (probabilities > 0.5).long()
>>> labels[0].tolist()
...
```

## Wav2Vec2ForXVector[[transformers.Wav2Vec2ForXVector]]

#### transformers.Wav2Vec2ForXVector[[transformers.Wav2Vec2ForXVector]]

```python
transformers.Wav2Vec2ForXVector(config: Wav2Vec2Config)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/wav2vec2/modeling_wav2vec2.py#L1893)

**参数：**

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

在 Wav2Vec2 模型顶部添加 XVector 特征提取头，用于说话人验证等任务。

该模型继承自 [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.Wav2Vec2ForXVector.forward]]

```python
forward(input_values: typing.Optional[torch.Tensor], attention_mask: typing.Optional[torch.Tensor] = None, labels: typing.Optional[torch.Tensor] = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/wav2vec2/modeling_wav2vec2.py#L1943)

**参数：**

input_values (`torch.Tensor`，形状为 `(batch_size, sequence_length)`) : 输入原始语音波形的浮点值。可以通过将 `.flac` 或 `.wav` 音频文件加载为 `list[float]`、`numpy.ndarray` 或 `torch.Tensor` 类型的数组来获取这些值，*例如* 使用 torchcodec 库（`pip install torchcodec`）或 soundfile 库（`pip install soundfile`）。要将数组准备为 `input_values`，应使用 [AutoProcessor](/docs/transformers/v5.23.0/zh/model_doc/auto#transformers.AutoProcessor) 进行填充并转换为 `torch.Tensor` 类型的张量。有关详细信息，请参阅 [Wav2Vec2Processor.__call__()](/docs/transformers/v5.23.0/zh/model_doc/wav2vec2#transformers.Wav2Vec2Processor.__call__)。

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

labels (`torch.LongTensor`，形状为 `(batch_size,)`，*可选*)：用于计算序列分类/回归损失的标签。索引应在 `[0, ..., config.num_labels - 1]` 范围内。如果 `config.num_labels == 1`，则计算回归损失（均方损失）；如果 `config.num_labels > 1`，则计算分类损失（交叉熵）。

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

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

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

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

- **loss** (`torch.Tensor`，形状为 `(1,)`，*可选*，在提供 `labels` 时返回) -- 分类损失。
- **logits**（形状为 `(batch_size, config.xvector_output_dim)` 的 `torch.Tensor`）-- AMSoftmax 之前的分类隐藏状态。
- **嵌入**（形状为 `(batch_size, config.xvector_output_dim)` 的 `torch.Tensor`）-- 用于基于向量相似度的检索的语句嵌入。
- **hidden_states** (`tuple(torch.Tensor)`，*可选*，在传入 `output_hidden_states=True` 或 `config.output_hidden_states=True` 时返回) -- 一个 `torch.Tensor` 元组（包含嵌入层的输出以及每一层的输出），形状为 `(batch_size, sequence_length, hidden_size)`。

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

  经过注意力 softmax 后的注意力权重，用于在自注意力头中计算加权平均值。

示例：

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

>>> dataset = load_dataset("hf-internal-testing/librispeech_asr_demo", "clean", split="validation")
>>> dataset = dataset.sort("id")
>>> sampling_rate = dataset.features["audio"].sampling_rate

>>> feature_extractor = AutoFeatureExtractor.from_pretrained("facebook/wav2vec2-base-960h")
>>> model = Wav2Vec2ForXVector.from_pretrained("facebook/wav2vec2-base-960h")

>>> # audio file is decoded on the fly
>>> inputs = feature_extractor(
...     [d["array"] for d in dataset[:2]["audio"]], sampling_rate=sampling_rate, return_tensors="pt", padding=True
... )
>>> with torch.no_grad():
...     embeddings = model(**inputs).embeddings

>>> embeddings = torch.nn.functional.normalize(embeddings, dim=-1).cpu()

>>> # the resulting embeddings can be used for cosine similarity-based retrieval
>>> cosine_sim = torch.nn.CosineSimilarity(dim=-1)
>>> similarity = cosine_sim(embeddings[0], embeddings[1])
>>> threshold = 0.7  # the optimal threshold is dataset-dependent
>>> if similarity < threshold:
...     print("Speakers are not the same!")
>>> round(similarity.item(), 2)
...
```

## Wav2Vec2ForPreTraining[[transformers.Wav2Vec2ForPreTraining]]

#### transformers.Wav2Vec2ForPreTraining[[transformers.Wav2Vec2ForPreTraining]]

```python
transformers.Wav2Vec2ForPreTraining(config: Wav2Vec2Config)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/wav2vec2/modeling_wav2vec2.py#L1322)

**参数：**

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

带有量化器和顶部 `VQ` 头的 Wav2Vec2 模型。

该模型继承自 [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.Wav2Vec2ForPreTraining.forward]]

```python
forward(input_values: typing.Optional[torch.Tensor], attention_mask: typing.Optional[torch.Tensor] = None, mask_time_indices: typing.Optional[torch.BoolTensor] = None, sampled_negative_indices: typing.Optional[torch.BoolTensor] = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/wav2vec2/modeling_wav2vec2.py#L1370)

**参数：**

input_values (`torch.Tensor`，形状为 `(batch_size, sequence_length)`，*可选*) : 输入原始语音波形的浮点值。可以通过将 `.flac` 或 `.wav` 音频文件加载为 `list[float]`、`numpy.ndarray` 或 `torch.Tensor` 类型的数组来获取这些值，*例如* 使用 torchcodec 库（`pip install torchcodec`）或 soundfile 库（`pip install soundfile`）。要将该数组准备为 `input_values`，应使用 [AutoProcessor](/docs/transformers/v5.23.0/zh/model_doc/auto#transformers.AutoProcessor) 进行填充并转换为 `torch.Tensor` 类型的张量。有关详细信息，请参阅 [Wav2Vec2Processor.__call__()](/docs/transformers/v5.23.0/zh/model_doc/wav2vec2#transformers.Wav2Vec2Processor.__call__)。

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

mask_time_indices (`torch.BoolTensor`，形状为 `(batch_size, sequence_length)`，*可选*)：用于掩码提取特征以计算对比损失的索引。在训练模式下，模型学习在 *config.proj_codevector_dim* 空间中预测被掩码的提取特征。

sampled_negative_indices (`torch.BoolTensor`，形状为 `(batch_size, sequence_length, num_negatives)`，*可选*)：指示哪些量化目标向量被用作对比损失中的负采样向量的索引。预训练所需的输入。

**返回：** [Wav2Vec2ForPreTrainingOutput](/docs/transformers/v5.23.0/zh/model_doc/wav2vec2#transformers.models.wav2vec2.modeling_wav2vec2.Wav2Vec2ForPreTrainingOutput) 或 `tuple(torch.Tensor)`

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

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

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

- **loss** (`*optional*`，在传入 `sample_negative_indices` 时返回，形状为 `(1,)` 的 `torch.Tensor`) -- 如[官方论文](https://huggingface.co/papers/2006.11477)所述，总损失为对比损失 (L_m) 与多样性损失 (L_d) 之和。
- **projected_states**（形状为 `(batch_size, sequence_length, config.proj_codevector_dim)` 的 `torch.Tensor`）-- 模型投影到 *config.proj_codevector_dim* 的隐藏状态，可用于预测被掩码的投影量化状态。
- **projected_quantized_states**（形状为 `(batch_size, sequence_length, config.proj_codevector_dim)` 的 `torch.Tensor`）-- 量化提取的特征向量，投影至 *config.proj_codevector_dim*，表示用于对比损失的阳性目标向量。
- **codevector_perplexity**（形状为 `(1,)` 的 `torch.Tensor`）-- 码向量分布的困惑度，用于衡量码本（codebook）的多样性。
- **hidden_states** (`tuple[torch.Tensor]`，*可选*，在传入 `output_hidden_states=True` 或 `config.output_hidden_states=True` 时返回) -- 一个 `torch.Tensor` 元组（如果模型具有嵌入层，则包含嵌入层输出的一个张量，以及每个层输出的一个张量），形状为 `(batch_size, sequence_length, hidden_size)`。

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

  经过注意力 softmax 后的注意力权重，用于在自注意力头中计算加权平均值。
- **contrastive_loss** (`*optional*`，在传入 `sample_negative_indices` 时返回，形状为 `(1,)` 的 `torch.Tensor`) -- 如[官方论文](https://huggingface.co/papers/2006.11477)中所述的对比损失 (L_m)。
- **diversity_loss** (`*optional*`，在传入 `sample_negative_indices` 时返回，形状为 `(1,)` 的 `torch.Tensor`) -- 如[官方论文](https://huggingface.co/papers/2006.11477)中所述的多样性损失 (L_d)。

示例：

```python
>>> import torch
>>> from transformers import AutoFeatureExtractor, Wav2Vec2ForPreTraining
>>> from transformers.models.wav2vec2.modeling_wav2vec2 import _compute_mask_indices, _sample_negative_indices
>>> from datasets import load_dataset

>>> feature_extractor = AutoFeatureExtractor.from_pretrained("facebook/wav2vec2-base")
>>> model = Wav2Vec2ForPreTraining.from_pretrained("facebook/wav2vec2-base")

>>> ds = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")
>>> input_values = feature_extractor(ds[0]["audio"]["array"], return_tensors="pt").input_values  # Batch size 1

>>> # compute masked indices
>>> batch_size, raw_sequence_length = input_values.shape
>>> sequence_length = model._get_feat_extract_output_lengths(raw_sequence_length).item()
>>> mask_time_indices = _compute_mask_indices(
...     shape=(batch_size, sequence_length), mask_prob=0.2, mask_length=2
... )
>>> sampled_negative_indices = _sample_negative_indices(
...     features_shape=(batch_size, sequence_length),
...     num_negatives=model.config.num_negatives,
...     mask_time_indices=mask_time_indices,
... )
>>> mask_time_indices = torch.tensor(data=mask_time_indices, device=input_values.device, dtype=torch.long)
>>> sampled_negative_indices = torch.tensor(
...     data=sampled_negative_indices, device=input_values.device, dtype=torch.long
... )

>>> with torch.no_grad():
...     outputs = model(input_values, mask_time_indices=mask_time_indices)

>>> # compute cosine similarity between predicted (=projected_states) and target (=projected_quantized_states)
>>> cosine_sim = torch.cosine_similarity(outputs.projected_states, outputs.projected_quantized_states, dim=-1)

>>> # show that cosine similarity is much higher than random
>>> cosine_sim[mask_time_indices.to(torch.bool)].mean() > 0.5
tensor(True)

>>> # for contrastive loss training model should be put into train mode
>>> model = model.train()
>>> loss = model(
...     input_values, mask_time_indices=mask_time_indices, sampled_negative_indices=sampled_negative_indices
... ).loss
```

