# Wav2Vec2-Conformer

## 概述

Wav2Vec2-Conformer 已被添加到 Changhan Wang、Yun Tang、Xutai Ma、Anne Wu、Sravya Popuri、Dmytro Okhonko 和 Juan Pino 更新的 [fairseq S2T: Fast Speech-to-Text Modeling with fairseq](https://huggingface.co/papers/2010.05171) 版本中。

该模型的官方结果可在论文的表 3 和表 4 中找到。

Wav2Vec2-Conformer 的权重由 Meta AI 团队在 [Fairseq 库](https://github.com/pytorch/fairseq/blob/main/examples/wav2vec/README.md#pre-trained-models) 中发布。

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

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

## 使用技巧

- Wav2Vec2-Conformer 遵循与 Wav2Vec2 相同的架构，但将 *Attention* 模块替换为 [Conformer: Convolution-augmented Transformer for Speech Recognition](https://huggingface.co/papers/2005.08100) 中介绍的 *Conformer* 模块。
- 在层数相同的情况下，Wav2Vec2-Conformer 比 Wav2Vec2 需要更多的参数，但同时也
更低的词错误率。
- Wav2Vec2-Conformer 使用与 Wav2Vec2 相同的分词器和特征提取器。
- Wav2Vec2-Conformer 可以通过设置正确的 `config.position_embeddings_type` 来使用无相对位置嵌入、类似 Transformer-XL 的位置嵌入或旋转位置嵌入。

## 资源

- [音频分类任务指南](../tasks/audio_classification)
- [自动语音识别任务指南](../tasks/asr)

## Wav2Vec2ConformerConfig[[transformers.Wav2Vec2ConformerConfig]]

#### transformers.Wav2Vec2ConformerConfig[[transformers.Wav2Vec2ConformerConfig]]

```python
transformers.Wav2Vec2ConformerConfig(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 = None, 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, 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, position_embeddings_type: str | None = 'relative', rotary_embedding_base: int = 10000, max_source_positions: int = 5000, conv_depthwise_kernel_size: int = 31, conformer_conv_dropout: float | int = 0.1)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/wav2vec2_conformer/configuration_wav2vec2_conformer.py#L27)

**参数：**

vocab_size (`int`, *可选*) : 模型的词汇表大小。定义了 `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)：[Wav2Vec2ConformerForCTC](/docs/transformers/main/zh/model_doc/wav2vec2-conformer#transformers.Wav2Vec2ConformerForCTC) 最终投影层的 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)：一维卷积位置嵌入层的组数。

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` 输出的归约方式。仅在训练时相关。

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

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

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`)：是否应在 Wav2Vec2Conformer Encoder 之上堆叠一个卷积网络。对于为 SpeechEncoderDecoder 模型预热启动 Wav2Vec2Conformer 非常有用。

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` 时相关。

position_embeddings_type (`str`，*可选*，默认为 `"relative"`)：可以指定为 `relative` 或 `rotary`，分别表示相对位置嵌入或旋转位置嵌入。如果留空为 `None`，则不应用相对位置嵌入。

rotary_embedding_base (`int`，*可选*，默认为 10000)：如果使用 `"rotary"` 位置嵌入，则定义嵌入基数的大小。

max_source_positions (`int`，*可选*，默认为 5000)：如果使用 `"relative"` 位置嵌入，则定义源输入的最大位置。

conv_depthwise_kernel_size (`int`，*可选*，默认为 31)：Conformer 块中卷积深度可分离一维层的核大小。

conformer_conv_dropout (`float`, *可选*，默认为 0.1)：Conformer 块中所有卷积层的 dropout 概率。

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

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

示例：

```python
>>> from transformers import Wav2Vec2ConformerConfig, Wav2Vec2ConformerModel

>>> # Initializing a Wav2Vec2Conformer facebook/wav2vec2-conformer-rel-pos-large style configuration
>>> configuration = Wav2Vec2ConformerConfig()

>>> # Initializing a model (with random weights) from the facebook/wav2vec2-conformer-rel-pos-large style configuration
>>> model = Wav2Vec2ConformerModel(configuration)

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

## Wav2Vec2Conformer 特定输出[[transformers.models.wav2vec2_conformer.modeling_wav2vec2_conformer.Wav2Vec2ConformerForPreTrainingOutput]]

#### transformers.models.wav2vec2_conformer.modeling_wav2vec2_conformer.Wav2Vec2ConformerForPreTrainingOutput[[transformers.models.wav2vec2_conformer.modeling_wav2vec2_conformer.Wav2Vec2ConformerForPreTrainingOutput]]

```python
transformers.models.wav2vec2_conformer.modeling_wav2vec2_conformer.Wav2Vec2ConformerForPreTrainingOutput(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/main/src/transformers/models/wav2vec2_conformer/modeling_wav2vec2_conformer.py#L46)

**参数：**

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

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

## Wav2Vec2ConformerModel[[transformers.Wav2Vec2ConformerModel]]

#### transformers.Wav2Vec2ConformerModel[[transformers.Wav2Vec2ConformerModel]]

```python
transformers.Wav2Vec2ConformerModel(config: Wav2Vec2ConformerConfig)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/wav2vec2_conformer/modeling_wav2vec2_conformer.py#L1079)

**参数：**

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

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

该模型继承自 [PreTrainedModel](/docs/transformers/main/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.Wav2Vec2ConformerModel.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/main/src/transformers/models/wav2vec2_conformer/modeling_wav2vec2_conformer.py#L1150)

**参数：**

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/main/zh/model_doc/auto#transformers.AutoProcessor) 进行填充并转换为 `torch.Tensor` 类型的张量。有关详细信息，请参阅 [Wav2Vec2Processor.__call__()](/docs/transformers/main/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/main/zh/model_doc/wav2vec2#transformers.modeling_outputs.Wav2Vec2BaseModelOutput) 或 `tuple(torch.Tensor)`

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

[Wav2Vec2ConformerModel](/docs/transformers/main/zh/model_doc/wav2vec2-conformer#transformers.Wav2Vec2ConformerModel) 的 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 后的注意力权重，用于在自注意力头中计算加权平均值。

## Wav2Vec2ConformerForCTC[[transformers.Wav2Vec2ConformerForCTC]]

#### transformers.Wav2Vec2ConformerForCTC[[transformers.Wav2Vec2ConformerForCTC]]

```python
transformers.Wav2Vec2ConformerForCTC(config: Wav2Vec2ConformerConfig, target_lang: str | None = None)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/wav2vec2_conformer/modeling_wav2vec2_conformer.py#L1404)

**参数：**

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

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

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

该模型继承自 [PreTrainedModel](/docs/transformers/main/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.Wav2Vec2ConformerForCTC.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/main/src/transformers/models/wav2vec2_conformer/modeling_wav2vec2_conformer.py#L1441)

**参数：**

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/main/zh/model_doc/auto#transformers.AutoProcessor) 进行填充并转换为 `torch.Tensor` 类型的张量。有关详细信息，请参阅 [Wav2Vec2Processor.__call__()](/docs/transformers/main/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/main/zh/main_classes/output#transformers.modeling_outputs.CausalLMOutput) 或 `tuple(torch.Tensor)`

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

[Wav2Vec2ConformerForCTC](/docs/transformers/main/zh/model_doc/wav2vec2-conformer#transformers.Wav2Vec2ConformerForCTC) 的 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, Wav2Vec2ConformerForCTC
>>> 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-conformer-rel-pos-large")
>>> model = Wav2Vec2ConformerForCTC.from_pretrained("facebook/wav2vec2-conformer-rel-pos-large")

>>> # 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)
...
```

## Wav2Vec2ConformerForSequenceClassification[[transformers.Wav2Vec2ConformerForSequenceClassification]]

#### transformers.Wav2Vec2ConformerForSequenceClassification[[transformers.Wav2Vec2ConformerForSequenceClassification]]

```python
transformers.Wav2Vec2ConformerForSequenceClassification(config: Wav2Vec2ConformerConfig)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/wav2vec2_conformer/modeling_wav2vec2_conformer.py#L1499)

**参数：**

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

Wav2Vec2Conformer 模型，顶部带有用于 SUPERB Keyword Spotting 等任务的序列分类头（在池化输出上的线性层）。

该模型继承自 [PreTrainedModel](/docs/transformers/main/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.Wav2Vec2ConformerForSequenceClassification.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/main/src/transformers/models/wav2vec2_conformer/modeling_wav2vec2_conformer.py#L1532)

**参数：**

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/main/zh/model_doc/auto#transformers.AutoProcessor) 进行填充并转换为 `torch.Tensor` 类型的张量。有关详细信息，请参阅 `Wav2Vec2ConformerProcessor.__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/main/zh/main_classes/output#transformers.modeling_outputs.SequenceClassifierOutput) 或 `tuple(torch.Tensor)`

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

[Wav2Vec2ConformerForSequenceClassification](/docs/transformers/main/zh/model_doc/wav2vec2-conformer#transformers.Wav2Vec2ConformerForSequenceClassification) 的 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, Wav2Vec2ConformerForSequenceClassification

>>> tokenizer = AutoTokenizer.from_pretrained("facebook/wav2vec2-conformer-rel-pos-large")
>>> model = Wav2Vec2ConformerForSequenceClassification.from_pretrained("facebook/wav2vec2-conformer-rel-pos-large")

>>> 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 = Wav2Vec2ConformerForSequenceClassification.from_pretrained("facebook/wav2vec2-conformer-rel-pos-large", 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, Wav2Vec2ConformerForSequenceClassification

>>> tokenizer = AutoTokenizer.from_pretrained("facebook/wav2vec2-conformer-rel-pos-large")
>>> model = Wav2Vec2ConformerForSequenceClassification.from_pretrained("facebook/wav2vec2-conformer-rel-pos-large", 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 = Wav2Vec2ConformerForSequenceClassification.from_pretrained(
...     "facebook/wav2vec2-conformer-rel-pos-large", 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
```

## Wav2Vec2ConformerForAudioFrameClassification[[transformers.Wav2Vec2ConformerForAudioFrameClassification]]

#### transformers.Wav2Vec2ConformerForAudioFrameClassification[[transformers.Wav2Vec2ConformerForAudioFrameClassification]]

```python
transformers.Wav2Vec2ConformerForAudioFrameClassification(config: Wav2Vec2ConformerConfig)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/wav2vec2_conformer/modeling_wav2vec2_conformer.py#L1592)

**参数：**

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

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

该模型继承自 [PreTrainedModel](/docs/transformers/main/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.Wav2Vec2ConformerForAudioFrameClassification.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/main/src/transformers/models/wav2vec2_conformer/modeling_wav2vec2_conformer.py#L1624)

**参数：**

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/main/zh/model_doc/auto#transformers.AutoProcessor) 进行填充并转换为 `torch.Tensor` 类型的张量。有关详细信息，请参阅 `Wav2Vec2ConformerProcessor.__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/main/zh/main_classes/output#transformers.modeling_outputs.TokenClassifierOutput) 或 `tuple(torch.Tensor)`

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

[Wav2Vec2ConformerForAudioFrameClassification](/docs/transformers/main/zh/model_doc/wav2vec2-conformer#transformers.Wav2Vec2ConformerForAudioFrameClassification) 的 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, Wav2Vec2ConformerForAudioFrameClassification
>>> 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-conformer-rel-pos-large")
>>> model = Wav2Vec2ConformerForAudioFrameClassification.from_pretrained("facebook/wav2vec2-conformer-rel-pos-large")

>>> # 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()
...
```

## Wav2Vec2ConformerForXVector[[transformers.Wav2Vec2ConformerForXVector]]

#### transformers.Wav2Vec2ConformerForXVector[[transformers.Wav2Vec2ConformerForXVector]]

```python
transformers.Wav2Vec2ConformerForXVector(config: Wav2Vec2ConformerConfig)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/wav2vec2_conformer/modeling_wav2vec2_conformer.py#L1738)

**参数：**

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

Wav2Vec2Conformer 模型，顶部带有 XVector 特征提取头，用于说话人验证等任务。

该模型继承自 [PreTrainedModel](/docs/transformers/main/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.Wav2Vec2ConformerForXVector.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/main/src/transformers/models/wav2vec2_conformer/modeling_wav2vec2_conformer.py#L1788)

**参数：**

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/main/zh/model_doc/auto#transformers.AutoProcessor) 进行填充并转换为 `torch.Tensor` 类型的张量。有关详细信息，请参阅 `Wav2Vec2ConformerProcessor.__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/main/zh/main_classes/output#transformers.modeling_outputs.XVectorOutput) 或 `tuple(torch.Tensor)`

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

[Wav2Vec2ConformerForXVector](/docs/transformers/main/zh/model_doc/wav2vec2-conformer#transformers.Wav2Vec2ConformerForXVector) 的 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, Wav2Vec2ConformerForXVector
>>> 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-conformer-rel-pos-large")
>>> model = Wav2Vec2ConformerForXVector.from_pretrained("facebook/wav2vec2-conformer-rel-pos-large")

>>> # 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)
...
```

## Wav2Vec2ConformerForPreTraining[[transformers.Wav2Vec2ConformerForPreTraining]]

#### transformers.Wav2Vec2ConformerForPreTraining[[transformers.Wav2Vec2ConformerForPreTraining]]

```python
transformers.Wav2Vec2ConformerForPreTraining(config: Wav2Vec2ConformerConfig)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/wav2vec2_conformer/modeling_wav2vec2_conformer.py#L1201)

**参数：**

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

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

该模型继承自 [PreTrainedModel](/docs/transformers/main/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.Wav2Vec2ConformerForPreTraining.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/main/src/transformers/models/wav2vec2_conformer/modeling_wav2vec2_conformer.py#L1249)

**参数：**

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/main/zh/model_doc/auto#transformers.AutoProcessor) 进行填充并转换为 `torch.Tensor` 类型的张量。有关详细信息，请参阅 [Wav2Vec2Processor.__call__()](/docs/transformers/main/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)`，*可选*)：指示哪些量化目标向量被用作对比损失中的负采样向量的索引。预训练所需的输入。

**返回：** [Wav2Vec2ConformerForPreTrainingOutput](/docs/transformers/main/zh/model_doc/wav2vec2-conformer#transformers.models.wav2vec2_conformer.modeling_wav2vec2_conformer.Wav2Vec2ConformerForPreTrainingOutput) 或 `tuple(torch.Tensor)`

一个 [Wav2Vec2ConformerForPreTrainingOutput](/docs/transformers/main/zh/model_doc/wav2vec2-conformer#transformers.models.wav2vec2_conformer.modeling_wav2vec2_conformer.Wav2Vec2ConformerForPreTrainingOutput)，或者一个由 `torch.Tensor` 组成的元组（如果传入了 `return_dict=False` 或 `config.return_dict=False`），其包含的元素取决于配置（[Wav2Vec2ConformerConfig](/docs/transformers/main/zh/model_doc/wav2vec2-conformer#transformers.Wav2Vec2ConformerConfig)）和输入。

[Wav2Vec2ConformerForPreTraining](/docs/transformers/main/zh/model_doc/wav2vec2-conformer#transformers.Wav2Vec2ConformerForPreTraining) 的 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, Wav2Vec2ConformerForPreTraining
>>> from transformers.models.wav2vec2_conformer.modeling_wav2vec2_conformer import _compute_mask_indices, _sample_negative_indices
>>> from datasets import load_dataset

>>> feature_extractor = AutoFeatureExtractor.from_pretrained("facebook/wav2vec2_conformer-base")
>>> model = Wav2Vec2ConformerForPreTraining.from_pretrained("facebook/wav2vec2_conformer-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
```