# Granite Speech Plus

## 概述

Granite Speech Plus 是 [Granite Speech](./granite_speech) 的一个变体，其投影器（projector）接收编码器最终隐藏状态与其任意一组中间隐藏状态的拼接（沿特征维度）。所选的中间层由 [GraniteSpeechPlusEncoderConfig](/docs/transformers/main/zh/model_doc/granite_speech_plus#transformers.GraniteSpeechPlusEncoderConfig) 上的 `cat_hidden_layers` 配置字段控制；当该字段为 `None` 时，模型的行为与 Granite Speech 完全一致。当该字段被设置时，投影器的 `encoder_hidden_size` 必须等于 `encoder_config.hidden_dim * (len(cat_hidden_layers) + 1)`。

架构的其余部分——语音编码器、查询 Transformer 投影器、语言模型以及可选的 LoRA 适配器——均原样继承自 Granite Speech。有关使用示例，请参阅 [Granite Speech 文档](./granite_speech)；此处同样使用 [GraniteSpeechProcessor](/docs/transformers/main/zh/model_doc/granite_speech#transformers.GraniteSpeechProcessor) 和 [GraniteSpeechFeatureExtractor](/docs/transformers/main/zh/model_doc/granite_speech#transformers.GraniteSpeechFeatureExtractor)。

## 用法

Granite Speech Plus 是一个多模态语音转文本模型，能够通过响应文本提示来转录音频、提供说话人标注以及词级时间戳。以下是如何使用其不同功能：

**设置** — 加载模型和测试音频片段：

```python
import re
import torch
from datasets import Audio, load_dataset
from transformers import AutoModelForSpeechSeq2Seq, AutoProcessor

SAMPLE_RATE = 16000
MODEL_NAME = "ibm-granite/granite-speech-4.1-2b-plus"
```

定义用于不同任务的提示词：

```python
SYSTEM_PROMPT = "Knowledge Cutoff Date: April 2024.\nToday's Date: December 19, 2024.\nYou are Granite, developed by IBM. You are a helpful AI assistant"
ASR_PROMPT = "<|audio|> can you transcribe the speech into a written format?"
SAA_PROMPT = "<|audio|> Speaker attribution: Transcribe and denote who is speaking by adding [Speaker 1]: and [Speaker 2]: tags before speaker turns."
TS_PROMPT = "<|audio|> Timestamps: Transcribe the speech. After each word, add a timestamp tag showing the end time in centiseconds, e.g. hello [T:45] world [T:82]"
```

加载模型并定义一个用于解码音频的通用函数：

```python
processor = AutoProcessor.from_pretrained(MODEL_NAME)
model = AutoModelForSpeechSeq2Seq.from_pretrained(MODEL_NAME, device_map="auto")

@torch.inference_mode()
def transcribe(audio, prompt, max_new_tokens=2000, prefix_text=None):
    chat = [{"role": "system", "content": SYSTEM_PROMPT}, {"role": "user", "content": prompt}]
    extra = {"prefix_text": prefix_text} if prefix_text is not None else {}
    prompt_text = processor.apply_chat_template(chat, tokenize=False, add_generation_prompt=True, **extra)
    inputs = processor(prompt_text, audio, device=device, return_tensors="pt").to(device)
    outputs = model.generate(**inputs, max_new_tokens=max_new_tokens, do_sample=False, num_beams=1)
    new_tokens = outputs[0, inputs["input_ids"].shape[-1]:]
    output_text = processor.decode(new_tokens, add_special_tokens=False, skip_special_tokens=True)
    return output_text
```

从 AMI 数据集加载一些示例音频数据

```python
ds = load_dataset("diarizers-community/ami", "ihm", split="test")
ds = ds.cast_column("audio", Audio(sampling_rate=SAMPLE_RATE, num_channels=1))

TEST_SAMPLE = 0
START_TIME, END_TIME = 5 * 60, 6 * 60
audio = ds["audio"][TEST_SAMPLE].get_samples_played_in_range(START_TIME, END_TIME)
```

**任务 1：ASR** — 纯语音转文本转录：

```python
asr_text = transcribe(audio.data, ASR_PROMPT)
print(asr_text)
```

**任务 2：说话人归属 ASR** — 带说话人标签的转录：

```python
saa_text = transcribe(audio.data, SAA_PROMPT)
for segment in re.split(r"(\[Speaker \d+\]:)", saa_text):
    print(segment.strip())
```

**任务 3：词级时间戳** — 带逐词计时的转录：

时间戳以厘秒为单位，并且是模 1000（即 10 秒）的，因此我们需要通过加上 10 秒的整数倍来解卷绕它们。

```python
ts_text = transcribe(audio.data, TS_PROMPT, max_new_tokens=10000)
ts_words = re.split(r"\[T:(\d+)\]", ts_text)
last_word_end_time = 0
offset_time = 0
for word, ts in zip(ts_words[::2], ts_words[1::2]):
    word_end_time = float(ts) / 100
    while word_end_time + offset_time < last_word_end_time:
        offset_time += 10
    last_word_end_time = word_end_time + offset_time
    print(f"{word}\t{last_word_end_time:.2f}s")
```

**任务 4：增量解码** — 在累积音频上下文的同时转录片段：

```python
NUM_SEGMENTS = 3
previous_transcript = ""
all_audio = None

for k in range(NUM_SEGMENTS):
    t1 = START_TIME + (END_TIME - START_TIME) * k / NUM_SEGMENTS
    t2 = START_TIME + (END_TIME - START_TIME) * (k + 1) / NUM_SEGMENTS
    new_audio = ds["audio"][TEST_SAMPLE].get_samples_played_in_range(t1, t2)
    all_audio = new_audio.data if all_audio is None else torch.cat([all_audio, new_audio.data], dim=-1)
    saa_text = transcribe(all_audio, SAA_PROMPT, prefix_text=previous_transcript)
    print(f"{t1:06.2f}-{t2:06.2f}:\t{saa_text}")
    previous_transcript = (previous_transcript + " " + saa_text).strip()
```

## GraniteSpeechPlusConfig[[transformers.GraniteSpeechPlusConfig]]

#### transformers.GraniteSpeechPlusConfig[[transformers.GraniteSpeechPlusConfig]]

```python
transformers.GraniteSpeechPlusConfig(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, text_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, encoder_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, projector_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, audio_token_index: int = 49155, initializer_range: float = 0.02, has_lora_adapter: bool = True, downsample_rate: int = 5, window_size: int = 15, tie_word_embeddings: bool = True)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/granite_speech_plus/configuration_granite_speech_plus.py#L95)

**参数：**

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

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

projector_config (`Union[AutoConfig, dict]`，*可选*，默认为 `Blip2QFormerConfig`)：音频投影器的配置对象或字典。

audio_token_index (`int`，*可选*，默认为 `49155`)：用作输入音频占位符的音频 token 索引。

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

has_lora_adapter (`bool`, *可选*, 默认为 `True`) : 指示模型是否具有一个 lora 适配器，该适配器仅应在处理音频输入时激活。

downsample_rate (`int`，*可选*，默认为 5)：音频特征提取器的下采样率。

window_size (`int`，*可选*，默认为 15)：音频特征投影器的窗口大小。

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

这是用于存储 GraniteSpeechPlusModel 配置的类。它根据指定的参数实例化 Granite Speech Plus 模型，并定义模型架构。使用默认值实例化配置将生成与 [ibm-granite/granite-speech-4.1-2b-plus](https://huggingface.co/ibm-granite/granite-speech-4.1-2b-plus) 类似的配置。

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

示例：

```python
>>> from transformers import GraniteSpeechPlusConfig, GraniteSpeechPlusForConditionalGeneration

>>> # Initializing a GraniteSpeechPlusConfig
>>> configuration = GraniteSpeechPlusConfig()

>>> # Initializing a GraniteSpeechPlusForConditionalGeneration (with random weights)
>>> model = GraniteSpeechPlusForConditionalGeneration(configuration)

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

## GraniteSpeechPlusEncoderConfig[[transformers.GraniteSpeechPlusEncoderConfig]]

#### transformers.GraniteSpeechPlusEncoderConfig[[transformers.GraniteSpeechPlusEncoderConfig]]

```python
transformers.GraniteSpeechPlusEncoderConfig(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, input_dim: int = 160, num_layers: int = 10, hidden_dim: int = 1024, feedforward_mult: int = 4, num_heads: int = 8, dim_head: int | None = None, output_dim: int = 42, context_size: int = 200, max_pos_emb: int = 512, dropout: float | int = 0.1, conv_kernel_size: int = 15, conv_expansion_factor: int = 2, cat_hidden_layers: list[int] | None = None)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/granite_speech_plus/configuration_granite_speech_plus.py#L29)

**参数：**

input_dim (*int*，*optional*，默认为 *160*)：输入声学特征的维度（例如，梅尔滤波器组通道的数量）。

num_layers (*int*，*optional*，默认为 *10*)：Transformer 解码器中的隐藏层数。

hidden_dim (*int*，*optional*，默认为 *1024*)：隐藏表示的维度。

feedforward_mult (*int*，*optional*，默认为 4)：编码器前馈层中上/下投影的乘数；投影的中间维度大小为 *hidden_dim * feedforward_mult*。

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

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

output_dim (*int*，*optional*，默认为 42)：Conformer 中前馈投影的中间维度，该维度将添加到每隔一个编码器块的输出中。

context_size (*int*，*optional*，默认为 200)：在 conformer 注意力中使用的上下文大小。

max_pos_emb (*int*，*optional*，默认为 512)：在注意力机制中使用的最大位置嵌入数（Shaw 相对位置编码）。

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

conv_kernel_size (*int*，*optional*，默认为 *15*)：卷积核的大小。

conv_expansion_factor (*int*，*optional*，默认为 2)：用于 conformer 卷积的中间维度。

cat_hidden_layers (*list[int]*, *optional*) : 编码器 conformer 层的索引，这些层的输出将与最终编码器输出（沿特征维度）拼接后传递给投影器。设置此参数时，投影器的 `encoder_hidden_size` 必须等于 `encoder_config.hidden_dim * (len(cat_hidden_layers) + 1)`。

这是用于存储 GraniteSpeechPlusModel 配置的类。它根据指定的参数实例化 Granite Speech Plus 模型，并定义模型架构。使用默认值实例化配置将生成与 [ibm-granite/granite-speech-4.1-2b-plus](https://huggingface.co/ibm-granite/granite-speech-4.1-2b-plus) 类似的配置。

配置对象继承自 [*PreTrainedConfig*]，可用于控制模型输出。有关更多信息，请参阅 [*PreTrainedConfig*] 的文档。

示例：

```python
>>> from transformers import GraniteSpeechPlusEncoderConfig, GraniteSpeechPlusCTCEncoder

>>> # Initializing a GraniteSpeechPlusEncoderConfig
>>> configuration = GraniteSpeechPlusEncoderConfig()

>>> # Initializing a GraniteSpeechPlusCTCEncoder (with random weights)
>>> model = GraniteSpeechPlusCTCEncoder(configuration)

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

## GraniteSpeechPlusModel[[transformers.GraniteSpeechPlusModel]]

#### transformers.GraniteSpeechPlusModel[[transformers.GraniteSpeechPlusModel]]

```python
transformers.GraniteSpeechPlusModel(config: GraniteSpeechPlusConfig)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/granite_speech_plus/modeling_granite_speech_plus.py#L131)

**参数：**

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

Granite Speech 模型由音频编码器、投影器和语言模型组成，不包含语言建模头。

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

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, input_features: typing.Optional[torch.Tensor] = None, input_features_mask: typing.Optional[torch.Tensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, position_ids: typing.Optional[torch.LongTensor] = None, past_key_values: transformers.cache_utils.Cache | None = None, inputs_embeds: typing.Optional[torch.Tensor] = None, use_cache: bool | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/granite_speech_plus/modeling_granite_speech_plus.py#L204)

**参数：**

input_ids (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*)：输入序列中 token 在词汇表中的索引。默认情况下，填充（padding）将被忽略。可以使用 [AutoTokenizer](/docs/transformers/main/zh/model_doc/auto#transformers.AutoTokenizer) 获取索引。有关详细信息，请参阅 [PreTrainedTokenizer.encode()](/docs/transformers/main/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 和 [PreTrainedTokenizer.__call__()](/docs/transformers/main/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)。[什么是输入 ID？](../glossary#input-ids)

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

input_features_mask (`torch.Tensor`, *可选*) : 在将音频特征散射到语言嵌入之前，应用于音频特征的掩码。

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

position_ids (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*)：输入序列中每个 token 在位置嵌入中的位置索引。取值范围为 `[0, config.n_positions - 1]`。[什么是位置 ID？](../glossary#position-ids)

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

inputs_embeds (`torch.Tensor`，形状为 `(batch_size, sequence_length, hidden_size)`，*可选*)：可选地，你可以选择直接传入嵌入表示，而不是传入 `input_ids`。如果你希望比模型内部的嵌入查找矩阵更精细地控制如何将 `input_ids` 索引转换为对应的向量，这将非常有用。

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

**返回：** `GraniteSpeechPlusModelOutputWithPast` 或 `tuple(torch.Tensor)`

`GraniteSpeechPlusModelOutputWithPast` 或 `torch.Tensor` 元组（如果传入 `return_dict=False` 或 `config.return_dict=False`），其包含的元素取决于配置（[GraniteSpeechPlusConfig](/docs/transformers/main/zh/model_doc/granite_speech_plus#transformers.GraniteSpeechPlusConfig)）和输入。

[GraniteSpeechPlusModel](/docs/transformers/main/zh/model_doc/granite_speech_plus#transformers.GraniteSpeechPlusModel) 的 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**（`Cache`，*可选*，在传入 `use_cache=True` 或 `config.use_cache=True` 时返回）—— 它是一个 [Cache](/docs/transformers/main/zh/internal/generation_utils#transformers.Cache) 实例。更多详情，请参阅我们的 [kv cache 指南](https://huggingface.co/docs/transformers/en/kv_cache)。

  包含预计算的隐藏状态（自注意力块中的键和值，以及如果 `config.is_encoder_decoder=True` 则还包括交叉注意力块中的键和值），可用于（参见 `past_key_values` 输入）加速顺序解码。
- **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 后的注意力权重，用于在自注意力头中计算加权平均值。
- **audio_hidden_states** (`torch.Tensor`，*可选*) -- 投影后的音频隐藏状态。

## GraniteSpeechPlusForConditionalGeneration[[transformers.GraniteSpeechPlusForConditionalGeneration]]

#### transformers.GraniteSpeechPlusForConditionalGeneration[[transformers.GraniteSpeechPlusForConditionalGeneration]]

```python
transformers.GraniteSpeechPlusForConditionalGeneration(config: GraniteSpeechPlusConfig)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/granite_speech_plus/modeling_granite_speech_plus.py#L517)

**参数：**

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

Granite Speech Plus 模型，一种 Granite Speech 变体，其投影器（projector）会消耗编码器最终隐藏状态与其任意中间隐藏状态子集的拼接结果。

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

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, input_features: typing.Optional[torch.Tensor] = None, input_features_mask: typing.Optional[torch.Tensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, position_ids: typing.Optional[torch.LongTensor] = None, past_key_values: transformers.cache_utils.Cache | None = None, inputs_embeds: typing.Optional[torch.Tensor] = None, labels: typing.Optional[torch.LongTensor] = None, use_cache: bool | None = None, logits_to_keep: typing.Union[int, torch.Tensor] = 0, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/granite_speech_plus/modeling_granite_speech_plus.py#L539)

**参数：**

input_ids (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*)：输入序列中 token 在词汇表中的索引。默认情况下，填充（padding）将被忽略。可以使用 [AutoTokenizer](/docs/transformers/main/zh/model_doc/auto#transformers.AutoTokenizer) 获取索引。有关详细信息，请参阅 [PreTrainedTokenizer.encode()](/docs/transformers/main/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 和 [PreTrainedTokenizer.__call__()](/docs/transformers/main/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)。[什么是输入 ID？](../glossary#input-ids)

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

input_features_mask (`torch.Tensor`, *可选*) : 在将音频特征散射到语言嵌入之前，应用于音频特征的掩码。

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

position_ids (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*)：输入序列中每个 token 在位置嵌入中的位置索引。取值范围为 `[0, config.n_positions - 1]`。[什么是位置 ID？](../glossary#position-ids)

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

inputs_embeds (`torch.Tensor`，形状为 `(batch_size, sequence_length, hidden_size)`，*可选*)：可选地，你可以选择直接传入嵌入表示，而不是传入 `input_ids`。如果你希望比模型内部的嵌入查找矩阵更精细地控制如何将 `input_ids` 索引转换为对应的向量，这将非常有用。

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

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

logits_to_keep (`Union[int, torch.Tensor]`，*可选*，默认为 `0`)：如果为 `int`，则计算最后 `logits_to_keep` 个 token 的 logits。如果为 `0`，则计算所有 `input_ids` 的 logits（特殊情况）。生成过程只需要最后一个 token 的 logits，仅针对该 token 进行计算可以节省内存，对于长序列或大词汇量而言，这种节省相当可观。如果为 `torch.Tensor`，则必须是一维张量，对应于序列长度维度中需要保留的索引。这在使用打包张量格式（将批次和序列长度合并为单一维度）时非常有用。

**返回：** `GraniteSpeechPlusCausalLMOutputWithPast` 或 `tuple(torch.Tensor)`

`GraniteSpeechPlusCausalLMOutputWithPast` 或 `torch.Tensor` 元组（如果传入 `return_dict=False` 或 `config.return_dict=False`），其包含的元素取决于配置（[GraniteSpeechPlusConfig](/docs/transformers/main/zh/model_doc/granite_speech_plus#transformers.GraniteSpeechPlusConfig)）和输入。

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

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

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

  包含预计算的隐藏状态（自注意力块中的键和值），可用于（参见 `past_key_values` 输入）加速顺序解码。
- **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 后的注意力权重，用于在自注意力头中计算加权平均值。
- **audio_hidden_states** (`torch.Tensor`，*可选*) -- 投影后的音频隐藏状态。

示例：

```python
>>> from transformers import AutoProcessor, GraniteSpeechPlusForConditionalGeneration
>>> 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("ibm-granite/granite-speech-4.1-2b-plus")
>>> model = GraniteSpeechPlusForConditionalGeneration.from_pretrained("ibm-granite/granite-speech-4.1-2b-plus")

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

#### get_audio_features[[transformers.GraniteSpeechPlusForConditionalGeneration.get_audio_features]]

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

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/granite_speech_plus/modeling_granite_speech_plus.py#L536)