# CohereAsr

## 概述

Cohere ASR 是 Cohere 于 2026 年 3 月 26 日[发布](https://cohere.com/blog/transcribe)的基于 Conformer 的编码器-解码器语音识别模型，参数量为 20 亿。

该模型由 [Eustache Le Bihan](https://huggingface.co/eustlb) 贡献。

## 用法

### 短文本转录

```python
from transformers import AutoProcessor, CohereAsrForConditionalGeneration
from transformers.audio_utils import load_audio

revision = "refs/pr/6"
processor = AutoProcessor.from_pretrained("CohereLabs/cohere-transcribe-03-2026", revision=revision)
model = CohereAsrForConditionalGeneration.from_pretrained("CohereLabs/cohere-transcribe-03-2026", device_map="auto", revision=revision)

audio = load_audio(
    "https://huggingface.co/datasets/hf-internal-testing/dummy-audio-samples/resolve/main/bcn_weather.mp3",
    sampling_rate=16000,
)

inputs = processor(audio, sampling_rate=16000, return_tensors="pt", language="en").to(model.device)
inputs.to(model.device, dtype=model.dtype)

outputs = model.generate(**inputs, max_new_tokens=256)
text = processor.decode(outputs, skip_special_tokens=True)
print(text)
```

### 标点控制

传入 `punctuation=False` 以获取不带标点符号的小写输出。

```python
inputs_pnc = processor(audio, sampling_rate=16000, return_tensors="pt", language="en", punctuation=True).to(model.device)
inputs_nopnc = processor(audio, sampling_rate=16000, return_tensors="pt", language="en", punctuation=False).to(model.device)
```

### 长文本转录

对于时长超过特征提取器 `max_audio_clip_s` 的音频，特征提取器会自动将波形切分为多个片段。处理器会使用返回的 `audio_chunk_index` 来重新组装各片段的转录结果。

```python
audio_long = load_audio(
    "https://huggingface.co/datasets/hf-internal-testing/dummy-audio-samples/resolve/main/obama_first_45_secs.mp3",
    sampling_rate=16000,
)

inputs = processor(audio=audio_long, return_tensors="pt", language="en", sampling_rate=16000).to(model.device)
audio_chunk_index = inputs.get("audio_chunk_index")
inputs.to(model.device, dtype=model.dtype)

outputs = model.generate(**inputs, max_new_tokens=256)
text = processor.decode(outputs, skip_special_tokens=True, audio_chunk_index=audio_chunk_index, language="en")
print(text)
```

### 批量推理

可以在单次调用中处理多个音频文件。当批次中混合了短音频和长音频时，处理器会负责分块和重新组装。

```python
audio_short = load_audio(
    "https://huggingface.co/datasets/hf-internal-testing/dummy-audio-samples/resolve/main/bcn_weather.mp3",
    sampling_rate=16000,
)
audio_long = load_audio(
    "https://huggingface.co/datasets/hf-internal-testing/dummy-audio-samples/resolve/main/obama_first_45_secs.mp3",
    sampling_rate=16000,
)

inputs = processor([audio_short, audio_long], sampling_rate=16000, return_tensors="pt", language="en").to(model.device)
audio_chunk_index = inputs.get("audio_chunk_index")
inputs.to(model.device, dtype=model.dtype)

outputs = model.generate(**inputs, max_new_tokens=256)
text = processor.decode(
    outputs, skip_special_tokens=True, audio_chunk_index=audio_chunk_index, language="en"
)
print(text)
```

### 非英语转录

指定要转录的语言代码，支持 14 种语言中的任意一种。

```python
audio_es = load_audio(
    "https://huggingface.co/datasets/hf-internal-testing/dummy-audio-samples/resolve/main/fleur_es_sample.wav",
    sampling_rate=16000,
)

inputs = processor(audio_es, sampling_rate=16000, return_tensors="pt", language="es", punctuation=True).to(model.device)
inputs.to(model.device, dtype=model.dtype)

outputs = model.generate(**inputs, max_new_tokens=256)
text = processor.decode(outputs, skip_special_tokens=True)
print(text)
```

## CohereAsrConfig[[transformers.CohereAsrConfig]]

#### transformers.CohereAsrConfig[[transformers.CohereAsrConfig]]

```python
transformers.CohereAsrConfig(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, is_encoder_decoder: bool = True, encoder_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, vocab_size: int = 16384, hidden_size: int = 1024, num_hidden_layers: int = 8, num_attention_heads: int = 8, num_key_value_heads: int | None = None, intermediate_size: int = 4096, hidden_act: str = 'relu', max_position_embeddings: int = 1024, pad_token_id: int | None = 2, eos_token_id: int | None = 3, bos_token_id: int | None = 4, use_cache: bool = True, initializer_range: float = 0.02, attention_dropout: float | int = 0.0, attention_bias: bool = True, decoder_start_token_id: int | None = None, tie_word_embeddings: bool = False, head_dim: int | None = None)
```

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

**参数：**

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

encoder_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`，*可选*)：编码器骨干网络的配置对象或字典。

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

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

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

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

num_key_value_heads (`int`, *可选*) : 这是用于实现分组查询注意力（Grouped Query Attention）的键值头数量。如果 `num_key_value_heads=num_attention_heads`，模型将使用多头注意力（MHA）；如果 `num_key_value_heads=1`，模型将使用多查询注意力（MQA）；否则将使用 GQA。在将多头检查点转换为 GQA 检查点时，每个组的键和值头应通过对该组内所有原始头进行平均池化来构建。更多详情请参阅 [这篇论文](https://huggingface.co/papers/2305.13245)。如果未指定，则默认为 `num_attention_heads`。

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

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

max_position_embeddings (`int`，*可选*，默认为 `1024`)：该模型可能使用的最大序列长度。

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

eos_token_id (`int`，*可选*，默认为 `3`)：词汇表中用于表示流结束（end-of-stream）的 Token ID。

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

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

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

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

attention_bias (`bool`，*可选*，默认为 `True`)：是否在使用自注意力机制时，在查询、键、值和输出投影层中使用偏置。

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

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

head_dim (`int`, *可选*) : 注意力头维度。如果为 None，则默认为 hidden_size // num_attention_heads

这是用于存储 CohereAsrModel 配置的类。它根据指定的参数实例化 Cohere Asr 模型，并定义模型架构。使用默认值实例化配置将得到与 [CohereLabs/cohere-transcribe-03-2026](https://huggingface.co/CohereLabs/cohere-transcribe-03-2026) 类似的配置。

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

>>> configuration = CohereAsrConfig()
>>> model = CohereAsrForConditionalGeneration(configuration)
>>> configuration = model.config
```

## CohereAsrFeatureExtractor[[transformers.CohereAsrFeatureExtractor]]

#### transformers.CohereAsrFeatureExtractor[[transformers.CohereAsrFeatureExtractor]]

```python
transformers.CohereAsrFeatureExtractor(feature_size = 128, sampling_rate = 16000, hop_length = 160, n_fft = 512, win_length = 400, preemphasis = 0.97, padding_value = 0.0, dither = 1e-05, max_audio_clip_s = 35.0, overlap_chunk_second = 5.0, min_energy_window_samples = 1600, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/cohere_asr/feature_extraction_cohere_asr.py#L36)

**参数：**

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

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

hop_length (`int`, *可选*，默认为 160)：用于获取梅尔频率系数的 STFT 的重叠窗口长度。

n_fft (`int`，*可选*，默认为 512)：傅里叶变换的大小。

win_length (`int`，*可选*，默认为 400)：STFT 计算的窗口长度。

preemphasis (`float`, *可选*，默认为 0.97)：预加重滤波器系数。0.0 表示不使用预加重滤波器。

padding_value (`float`, *可选*, 默认值为 0.0) : 用于填充音频的填充值。应对应静音。

dither (`float`, *可选*，默认为 1e-05)：在特征提取前添加的确定性抖动噪声量。每个样本以其有效波形长度作为种子，从而确保抖动噪声与批次组成无关。设置为 0.0 可禁用此功能。

max_audio_clip_s (`float`, *可选*，默认值为 35.0)：单个音频块的最大时长（秒）。时长超过 `max_audio_clip_s - overlap_chunk_second` 的音频将在基于能量的边界处进行分割。

overlap_chunk_second (`float`, *可选*，默认为 5.0) : 在分割长音频时，用于边界搜索的窗口大小（以秒为单位）。这并非块之间的实际重叠部分——它定义了从块边界向前搜索静音分割点的距离。

min_energy_window_samples (`int`, *可选*，默认为 1600)：用于在拆分音频块时寻找最安静位置的滑动窗口的样本大小。

构建一个 CohereAsr 特征提取器。

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

此类使用自定义的 numpy 实现的`Short Time Fourier Transform`从原始语音中提取 mel 滤波器组特征，其结果应与 pytorch 的`torch.stft`等效。

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

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

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/cohere_asr/feature_extraction_cohere_asr.py#L198)

**参数：**

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

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

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

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

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

sampling_rate (`int`, *可选*) : `raw_speech` 输入的采样率。强烈建议在 forward 调用时传入 `sampling_rate`，以防止静默错误并支持自动语音识别流水线。

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

do_normalize (`bool`，*可选*，默认为 `False`)：是否对输入进行零均值单位方差归一化。归一化可以显著提升模型性能。

device (`str`, *可选*, 默认为 `'cpu'`) : 指定在 `_torch_extract_fbank_features` 方法中计算音频信号的 log-mel 频谱图时所使用的设备。(例如，"cpu"、"cuda")

return_token_timestamps (`bool`，*可选*，默认为 `None`)：已弃用。请改用 `return_attention_mask`，从中可以推断出帧数。是否返回输入 raw_speech 的帧数。这些 num_frames 可用于模型计算单词级别的时间戳。

用于特征化一个或多个序列并为其准备模型输入的主要方法。如果可用，实现会使用 PyTorch 进行 STFT 计算，否则使用基于 NumPy 的较慢实现。

## CohereAsrProcessor[[transformers.CohereAsrProcessor]]

#### transformers.CohereAsrProcessor[[transformers.CohereAsrProcessor]]

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

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/cohere_asr/processing_cohere_asr.py#L36)

**参数：**

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

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

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

[CohereAsrProcessor](/docs/transformers/v5.23.0/zh/model_doc/cohere_asr#transformers.CohereAsrProcessor) 提供了 [CohereAsrFeatureExtractor](/docs/transformers/v5.23.0/zh/model_doc/cohere_asr#transformers.CohereAsrFeatureExtractor) 和 [TokenizersBackend](/docs/transformers/v5.23.0/zh/main_classes/tokenizer#transformers.TokenizersBackend) 的所有功能。有关更多信息，请参阅 [~CohereAsrFeatureExtractor](/docs/transformers/v5.23.0/zh/model_doc/cohere_asr#transformers.CohereAsrFeatureExtractor) 和 [~TokenizersBackend](/docs/transformers/v5.23.0/zh/main_classes/tokenizer#transformers.TokenizersBackend)。

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

```python
__call__(audio: typing.Union[numpy.ndarray, ForwardRef('torch.Tensor'), collections.abc.Sequence[numpy.ndarray], collections.abc.Sequence['torch.Tensor']], language: str, text: str | list[str] | list[list[str]] | None = None, punctuation: bool = True, sampling_rate: int | None = None, **kwargs: *<class 'transformers.processing_utils.ProcessingKwargs'>)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/cohere_asr/processing_cohere_asr.py#L75)

**参数：**

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

language (`str`) : 用于构建解码器提示的语言代码（例如 `"en"`、`"es"`、`"fr"`）。处理器会构建完整的解码器提示，并返回 `decoder_input_ids` 以及音频特征。

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

punctuation (`bool`，默认为 `True`)：是否启用解码器提示中的标点符号。

sampling_rate (`int`, *可选*) : 输入音频的采样率，单位为 Hz。此值应与特征提取器预期的采样率一致（默认为 16000 Hz）。如果提供了该值，将与处理器的预期采样率进行验证，若不一致则引发错误。如果未提供，则会发出警告并假定使用默认采样率。

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

## CohereAsrPreTrainedModel[[transformers.CohereAsrPreTrainedModel]]

#### transformers.CohereAsrPreTrainedModel[[transformers.CohereAsrPreTrainedModel]]

```python
transformers.CohereAsrPreTrainedModel(config: PreTrainedConfig, *inputs, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/cohere_asr/modeling_cohere_asr.py#L297)

**参数：**

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

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

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

点分路径（例如 `torch.float32`）的模拟值：属性访问链和调用行为如同透传装饰器，`repr` 为点分路径，将其用作基类时会替换为普通的 `type` 基类（PEP 560 `__mro_entries__`），因此真实的子类保留正常的元类，且 `inspect.signature` 读取的是它们真实的 `__init__`，而非模拟对象的。

## CohereAsrModel[[transformers.CohereAsrModel]]

#### transformers.CohereAsrModel[[transformers.CohereAsrModel]]

```python
transformers.CohereAsrModel(config: CohereAsrConfig)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/cohere_asr/modeling_cohere_asr.py#L427)

**参数：**

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

未添加任何特定头部的裸 Cohere Asr 模型，直接输出原始隐藏状态。

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

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

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/cohere_asr/modeling_cohere_asr.py#L455)

**参数：**

input_features (`torch.Tensor`，形状为 `(batch_size, audio_length)`)：原始语音波形的浮点值。原始语音波形可通过将 `.flac` 或 `.wav` 音频文件加载为 `list[float]`、`numpy.ndarray` 或 `torch.Tensor` 类型的数组获得，*例如* 使用 torchcodec 库（`pip install torchcodec`）或 soundfile 库（`pip install soundfile`）。要将该数组处理为 `input_features`，应使用 [AutoFeatureExtractor](/docs/transformers/v5.23.0/zh/model_doc/auto#transformers.AutoFeatureExtractor) 进行填充并转换为 `torch.Tensor` 类型的张量。

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

decoder_input_ids (`torch.LongTensor`，形状为 `(batch_size, target_sequence_length)`，*可选*)：解码器输入序列中词元在词汇表中的索引。 可以使用 [AutoTokenizer](/docs/transformers/v5.23.0/zh/model_doc/auto#transformers.AutoTokenizer) 获取索引。 有关详细信息，请参阅 [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 和 [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)。 [什么是解码器输入 ID？](../glossary#decoder-input-ids)

decoder_attention_mask (`torch.LongTensor`，形状为 `(batch_size, target_sequence_length)`，*可选*)：用于避免对特定 token 索引执行注意力机制的掩码。默认情况下，会使用因果掩码，以确保模型只能查看之前的输入来预测未来。

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

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

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

decoder_position_ids (`torch.LongTensor`，形状为 `(batch_size, target_sequence_length)`)：输入序列中每个 token 在位置嵌入中的位置索引。用于计算直至 `config.decoder_config.max_position_embeddings` 的位置嵌入。

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

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

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

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

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

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

  如果使用了 `past_key_values`，则仅输出形状为 `(batch_size, 1, hidden_size)` 的序列的最后一个隐藏状态。
- **past_key_values**（`EncoderDecoderCache`，*可选*，在传入 `use_cache=True` 或 `config.use_cache=True` 时返回）-- 它是一个 [EncoderDecoderCache](/docs/transformers/v5.23.0/zh/internal/generation_utils#transformers.EncoderDecoderCache) 实例。更多详情，请参阅我们的 [kv cache 指南](https://huggingface.co/docs/transformers/en/kv_cache)。

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

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

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

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

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

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

示例：

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

>>> model = CohereAsrModel.from_pretrained("UsefulSensors/cohere_asr-tiny")
>>> feature_extractor = AutoFeatureExtractor.from_pretrained("UsefulSensors/cohere_asr-tiny")
>>> ds = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")
>>> inputs = feature_extractor(ds[0]["audio"]["array"], return_tensors="pt")
>>> input_features = inputs.input_features
>>> decoder_input_ids = torch.tensor([[1, 1]]) * model.config.decoder_start_token_id
>>> last_hidden_state = model(input_features, decoder_input_ids=decoder_input_ids).last_hidden_state
>>> list(last_hidden_state.shape)
[1, 2, 288]
```

## CohereAsrForConditionalGeneration[[transformers.CohereAsrForConditionalGeneration]]

#### transformers.CohereAsrForConditionalGeneration[[transformers.CohereAsrForConditionalGeneration]]

```python
transformers.CohereAsrForConditionalGeneration(config: CohereAsrConfig)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/cohere_asr/modeling_cohere_asr.py#L549)

**参数：**

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

带有语言建模头的 CohereAsr 模型。可用于自动语音识别。

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

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

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/cohere_asr/modeling_cohere_asr.py#L569)

**参数：**

input_features (`torch.Tensor`，形状为 `(batch_size, audio_length)`)：原始语音波形的浮点值。原始语音波形可通过将 `.flac` 或 `.wav` 音频文件加载为 `list[float]`、`numpy.ndarray` 或 `torch.Tensor` 类型的数组获得，*例如* 使用 torchcodec 库（`pip install torchcodec`）或 soundfile 库（`pip install soundfile`）。要将该数组处理为 `input_features`，应使用 [AutoFeatureExtractor](/docs/transformers/v5.23.0/zh/model_doc/auto#transformers.AutoFeatureExtractor) 进行填充并转换为 `torch.Tensor` 类型的张量。

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

decoder_input_ids (`torch.LongTensor`，形状为 `(batch_size, target_sequence_length)`，*可选*)：解码器输入序列中词元在词汇表中的索引。 可以使用 [AutoTokenizer](/docs/transformers/v5.23.0/zh/model_doc/auto#transformers.AutoTokenizer) 获取索引。 有关详细信息，请参阅 [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 和 [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)。 [什么是解码器输入 ID？](../glossary#decoder-input-ids)

decoder_attention_mask (`torch.LongTensor`，形状为 `(batch_size, target_sequence_length)`，*可选*)：用于避免对特定 token 索引执行注意力机制的掩码。默认情况下，会使用因果掩码，以确保模型只能查看之前的输入来预测未来。

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

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

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

decoder_position_ids (`torch.LongTensor`，形状为 `(batch_size, target_sequence_length)`)：输入序列中每个 token 在位置嵌入中的位置索引。用于计算直至 `config.decoder_config.max_position_embeddings` 的位置嵌入。

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

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

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

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

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

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

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

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

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

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

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

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

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

示例：

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

>>> processor = AutoProcessor.from_pretrained("UsefulSensors/cohere_asr-tiny")
>>> model = CohereAsrForConditionalGeneration.from_pretrained("UsefulSensors/cohere_asr-tiny")

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

>>> inputs = processor(ds[0]["audio"]["array"], return_tensors="pt")
>>> input_features = inputs.input_features

>>> generated_ids = model.generate(input_features, max_new_tokens=100)

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

