# UniSpeech

## 概述

UniSpeech 模型由 Chengyi Wang、Yu Wu、Yao Qian、Kenichi Kumatani、Shujie Liu、Furu Wei、Michael Zeng 和 Xuedong Huang 在 [UniSpeech: Unified Speech Representation Learning with Labeled and Unlabeled Data](https://huggingface.co/papers/2101.07597) 中提出。

该论文的摘要如下：

*在本文中，我们提出了一种名为 UniSpeech 的统一预训练方法，旨在利用无标签数据和有标签数据来学习语音表示。该方法以多任务学习的方式，同时执行有监督的音素 CTC 学习和音素感知的对比自监督学习。所得到的表示能够捕获与音素结构相关性更高的信息，并提升跨语言和跨领域的泛化能力。我们在公开的 CommonVoice 语料库上评估了 UniSpeech 在跨语言表示学习中的有效性。结果表明，与自监督预训练和有监督迁移学习相比，UniSpeech 在语音识别任务上分别实现了最高 13.4% 和 17.8% 的相对音素错误率降低（在所有测试语言上的平均值）。此外，UniSpeech 在领域偏移的语音识别任务上也展示了其可迁移性，相较于之前的方法，相对词错误率降低了 6%。*

该模型由 [patrickvonplaten](https://huggingface.co/patrickvonplaten) 贡献。作者的代码可在[此处](https://github.com/microsoft/UniSpeech/tree/main/UniSpeech)找到。

## 使用技巧

- UniSpeech 是一种语音模型，它接受与语音信号原始波形对应的浮点数数组。请使用 [Wav2Vec2Processor](/docs/transformers/main/zh/model_doc/wav2vec2#transformers.Wav2Vec2Processor) 进行特征提取。
- UniSpeech 模型可以使用连接主义时间分类（CTC）进行微调，因此模型输出必须使用 [Wav2Vec2CTCTokenizer](/docs/transformers/main/zh/model_doc/wav2vec2#transformers.Wav2Vec2CTCTokenizer) 进行解码。

## 资源

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

## UniSpeechConfig[[transformers.UniSpeechConfig]]

#### transformers.UniSpeechConfig[[transformers.UniSpeechConfig]]

```python
transformers.UniSpeechConfig(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 = 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 = 'mean', ctc_zero_infinity: bool = False, use_weighted_layer_sum: bool = False, classifier_proj_size: int = 256, num_ctc_classes: int = 80, pad_token_id: int | None = 0, bos_token_id: int | None = 1, eos_token_id: int | list[int] | None = 2, replace_prob: float | int = 0.5)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/unispeech/configuration_unispeech.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)：[UniSpeechForCTC](/docs/transformers/main/zh/model_doc/unispeech#transformers.UniSpeechForCTC) 最终投影层的 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, 2, 2)`) : 一个整数元组，用于定义特征编码器中每个一维卷积层的卷积核大小。*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_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_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`，*可选*，默认为 `mean`)：指定应用于 `torch.nn.CTCLoss` 输出的归约方式。仅在训练时相关。

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

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

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

num_ctc_classes (`int`，*可选*，默认为 80)：指定音素级 CTC 损失的类别数（音素标记和空白标记）。仅在使用 [UniSpeechForPreTraining](/docs/transformers/main/zh/model_doc/unispeech#transformers.UniSpeechForPreTraining) 实例时相关。

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。

replace_prob (`float`, *可选*，默认为 0.5)：在预训练过程中，transformer 特征被量化特征替换的概率。

这是用于存储 UniSpeechModel 配置的类。它根据指定的参数实例化 Unispeech 模型，并定义模型架构。使用默认值实例化配置将生成与 [microsoft/unispeech-large-1500h-cv](https://huggingface.co/microsoft/unispeech-large-1500h-cv) 类似的配置。

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

示例：

```python
>>> from transformers import UniSpeechConfig, UniSpeechModel

>>> # Initializing a UniSpeech facebook/unispeech-base-960h style configuration
>>> configuration = UniSpeechConfig()

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

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

## UniSpeech 特定输出[[transformers.models.unispeech.modeling_unispeech.UniSpeechForPreTrainingOutput]]

#### transformers.models.unispeech.modeling_unispeech.UniSpeechForPreTrainingOutput[[transformers.models.unispeech.modeling_unispeech.UniSpeechForPreTrainingOutput]]

```python
transformers.models.unispeech.modeling_unispeech.UniSpeechForPreTrainingOutput(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)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/unispeech/modeling_unispeech.py#L62)

**参数：**

loss (`*optional*`，当模型处于训练模式时返回，形状为 `(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 之后的注意力权重，用于在自注意力头中计算加权平均值。

`UniSpeechForPreTrainingOutput` 的输出类型，可能包含隐藏状态和注意力。

## UniSpeechModel[[transformers.UniSpeechModel]]

#### transformers.UniSpeechModel[[transformers.UniSpeechModel]]

```python
transformers.UniSpeechModel(config: UniSpeechConfig)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/unispeech/modeling_unispeech.py#L868)

**参数：**

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

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

该模型继承自 [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.UniSpeechModel.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/unispeech/modeling_unispeech.py#L932)

**参数：**

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`），其包含的元素取决于配置（[UniSpeechConfig](/docs/transformers/main/zh/model_doc/unispeech#transformers.UniSpeechConfig)）和输入。

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

## UniSpeechForCTC[[transformers.UniSpeechForCTC]]

#### transformers.UniSpeechForCTC[[transformers.UniSpeechForCTC]]

```python
transformers.UniSpeechForCTC(config: UniSpeechConfig, target_lang: str | None = None)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/unispeech/modeling_unispeech.py#L1096)

**参数：**

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

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

带有 `language modeling` 头部的 UniSpeech 模型，用于连接主义时间分类（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.UniSpeechForCTC.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/unispeech/modeling_unispeech.py#L1165)

**参数：**

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`），其包含的元素取决于配置（[UniSpeechConfig](/docs/transformers/main/zh/model_doc/unispeech#transformers.UniSpeechConfig)）和输入。

[UniSpeechForCTC](/docs/transformers/main/zh/model_doc/unispeech#transformers.UniSpeechForCTC) 的 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, UniSpeechForCTC
>>> 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("microsoft/unispeech-large-1500h-cv")
>>> model = UniSpeechForCTC.from_pretrained("microsoft/unispeech-large-1500h-cv")

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

## UniSpeechForSequenceClassification[[transformers.UniSpeechForSequenceClassification]]

#### transformers.UniSpeechForSequenceClassification[[transformers.UniSpeechForSequenceClassification]]

```python
transformers.UniSpeechForSequenceClassification(config: UniSpeechConfig)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/unispeech/modeling_unispeech.py#L1223)

**参数：**

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

在顶部添加序列分类头（对池化输出应用线性层）的 UniSpeech 模型，用于 SUPERB 关键词检测等任务。

该模型继承自 [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.UniSpeechForSequenceClassification.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/unispeech/modeling_unispeech.py#L1256)

**参数：**

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` 类型的张量。有关详细信息，请参阅 `UniSpeechProcessor.__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`），其包含的元素取决于配置（[UniSpeechConfig](/docs/transformers/main/zh/model_doc/unispeech#transformers.UniSpeechConfig)）和输入。

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

>>> tokenizer = AutoTokenizer.from_pretrained("microsoft/unispeech-large-1500h-cv")
>>> model = UniSpeechForSequenceClassification.from_pretrained("microsoft/unispeech-large-1500h-cv")

>>> 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 = UniSpeechForSequenceClassification.from_pretrained("microsoft/unispeech-large-1500h-cv", 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, UniSpeechForSequenceClassification

>>> tokenizer = AutoTokenizer.from_pretrained("microsoft/unispeech-large-1500h-cv")
>>> model = UniSpeechForSequenceClassification.from_pretrained("microsoft/unispeech-large-1500h-cv", 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 = UniSpeechForSequenceClassification.from_pretrained(
...     "microsoft/unispeech-large-1500h-cv", 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
```

## UniSpeechForPreTraining[[transformers.UniSpeechForPreTraining]]

#### transformers.UniSpeechForPreTraining[[transformers.UniSpeechForPreTraining]]

```python
transformers.UniSpeechForPreTraining(config: UniSpeechConfig)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/unispeech/modeling_unispeech.py#L978)

**参数：**

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

带有向量量化模块和 ctc 损失函数的 UniSpeech 模型，用于预训练。

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

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

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/unispeech/modeling_unispeech.py#L1027)

**参数：**

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)

**返回：** [UniSpeechForPreTrainingOutput](/docs/transformers/main/zh/model_doc/unispeech#transformers.models.unispeech.modeling_unispeech.UniSpeechForPreTrainingOutput) 或 `tuple(torch.Tensor)`

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

[UniSpeechForPreTraining](/docs/transformers/main/zh/model_doc/unispeech#transformers.UniSpeechForPreTraining) 的 forward 方法重写了 `__call__` 特殊方法。

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

- **loss** (`*optional*`，当模型处于训练模式时返回，形状为 `(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 后的注意力权重，用于在自注意力头中计算加权平均值。

示例：

```python
>>> import torch
>>> from transformers import AutoFeatureExtractor, UniSpeechForPreTraining

>>> feature_extractor = AutoFeatureExtractor.from_pretrained("microsoft/unispeech-large-1500h-cv")
>>> model = UniSpeechForPreTraining.from_pretrained("microsoft/unispeech-large-1500h-cv")
>>> # TODO: Add full pretraining example
```