Hugging Face's logo

Transformers documentation

GraniteSpeech5

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

该模型于 2026-08-25 贡献至 Hugging Face Transformers。

GraniteSpeech5

概述

Granite Speech 5.0 Turbo CTC 是一款轻量级（约 4.7 亿参数）的 conformer 编码器，用于自动语音识别，并基于 BPE 目标采用连接主义时序分类（CTC）进行训练。它是 Granite Speech 系列中一个快速、仅包含编码器的成员：转录过程只需一次前向传播，随后进行贪心 CTC 解码，无需自回归解码器。

在架构上，它扩展了 Granite Speech conformer CTC 编码器，具体包括：

  1. 帧堆叠 + 分块时间下采样：特征提取器将 log-mel（+delta）帧成对堆叠（2 倍），前两个 conformer 块各自通过步长为 2 的深度可分离卷积（带均值池化残差）将时间维度下采样 2 倍，在 10 ms mel 跳步下实现总计 8 倍的时间缩减。

  2. 使用 Shaw 相对位置嵌入的块注意力：注意力在固定大小的块上计算（序列向右填充至块的整数倍，填充的帧会被掩码），并使用独立的无偏置查询/键/值投影。

  3. 自条件 CTC：将中间层的 CTC 后验概率投影后反馈至隐藏状态，并且 CTC 头在此中间层自条件机制与最终预测之间共享。

该模型由 Eustache Le Bihan 贡献。

用法

GraniteSpeech5ForCTC 的用法

Pipeline
AutoModel
from transformers import pipeline


pipe = pipeline("automatic-speech-recognition", model="ibm-granite/granite-speech-5.0-470m-turboctc")
out = pipe("https://huggingface.co/datasets/hf-internal-testing/dummy-audio-samples/resolve/main/bcn_weather.mp3")
print(out)
# {'text': 'yesterday it was 35 degrees in barcelona but today the temperature will go down to -20 degrees'}

GraniteSpeech5CTCConfig

class transformers.GraniteSpeech5CTCConfig

< >

( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonevocab_size: int = 16384ctc_loss_reduction: str = 'mean'ctc_zero_infinity: bool = Trueencoder_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Nonepad_token_id: int | None = 0tie_word_embeddings: bool = True )

参数

  • vocab_size (int，可选，默认为 16384) — 模型的词汇表大小。定义了 input_ids 可以表示的不同 token 数量。
  • ctc_loss_reduction (str，可选，默认为 "mean") — 指定应用于 torch.nn.CTCLoss 输出的归约方式。仅在训练 GraniteSpeech5ForCTC 实例时相关。
  • ctc_zero_infinity（bool，可选，默认为 True）— 是否将 torch.nn.CTCLoss 的无穷大损失及其相关梯度置零。当输入过短、无法与目标对齐时，通常会出现无穷大损失。仅在训练 GraniteSpeech5ForCTC 实例时相关。
  • encoder_config (Union[dict, GraniteSpeech5EncoderConfig]，可选) — 编码器的配置对象或字典。
  • pad_token_id (int, 可选，默认为 0) — 词表中用于填充的 token id。
  • tie_word_embeddings (bool，可选，默认为 True) — 是否根据模型的 tied_weights_keys 映射来绑定权重嵌入。

这是用于存储 Granite Speech5Model 配置的类。它根据指定的参数实例化 Granite Speech5 模型，并定义模型架构。使用默认值实例化配置，将得到与 ibm-granite/granite-speech-5.0-470m-turboctc 类似的配置。

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

示例：

>>> from transformers import GraniteSpeech5ForCTC, GraniteSpeech5CTCConfig
>>> # Initializing a GraniteSpeech5 configuration
>>> configuration = GraniteSpeech5CTCConfig()
>>> # Initializing a model from the configuration
>>> model = GraniteSpeech5ForCTC(configuration)
>>> # Accessing the model configuration
>>> configuration = model.config

GraniteSpeech5EncoderConfig

类 transformers.GraniteSpeech5EncoderConfig

< >

( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonevocab_size: int = 16384hidden_size: int = 1024intermediate_size: int = 4096num_hidden_layers: int = 16num_attention_heads: int = 8num_key_value_heads: int | None = Nonenum_mel_bins: int = 80head_dim: int | None = Nonehidden_act: str = 'silu'max_position_embeddings: int = 512context_size: int = 128conv_kernel_size: int = 7conv_expansion_factor: int = 2subsample_layers: list[int] | None = Noneattention_bias: bool = Trueattention_dropout: float | int = 0.0activation_dropout: float | int = 0.0initializer_range: float = 0.02 )

参数

  • vocab_size (int，可选，默认为 16384) — 模型的词汇表大小。定义了 input_ids 可以表示的不同 token 数量。
  • hidden_size (int，可选，默认为 1024) — 隐藏表示的维度。
  • intermediate_size (int，可选，默认为 4096) — MLP 表示的维度。
  • num_hidden_layers (int，可选，默认为 16) — Transformer 解码器中的隐藏层数量。
  • num_attention_heads (int，可选，默认为 8) — Transformer 解码器中每个注意力层的注意力头数量。
  • num_key_value_heads (int, 可选) — 这是用于实现 Grouped Query Attention 的 key_value 头数。如果 num_key_value_heads=num_attention_heads，模型将使用 Multi Head Attention (MHA)；如果 num_key_value_heads=1，模型将使用 Multi Query Attention (MQA)；否则使用 GQA。在将多头检查点转换为 GQA 检查点时，每个组的 key 和 value 头应通过对该组内所有原始头进行平均池化来构建。更多详情请参阅 这篇论文。如果未指定，则默认为 num_attention_heads。
  • num_mel_bins (int，可选，默认为 80) — 每个输入帧使用的 mel 特征数量。应与 AutoFeatureExtractor 类中使用的值相对应。
  • head_dim (int，可选) — 注意力头维度。如果为 None，则默认为 hidden_size // num_attention_heads
  • hidden_act (str，可选，默认为 silu) — 解码器中的非线性激活函数（函数或字符串）。例如，"gelu"、 "relu"、"silu" 等。
  • max_position_embeddings (int，可选，默认值为 512) — Shaw 相对位置编码的最大相对位置索引；嵌入表包含 2 * max_position_embeddings + 1 个条目。
  • context_size (int，可选，默认为 128) — 用于分块 Conformer 注意力的上下文大小。
  • conv_kernel_size (int，可选，默认为 7) — Conformer 卷积模块中深度可分离卷积的卷积核大小。
  • conv_expansion_factor (int，可选，默认为 2) — Conformer 卷积模块的扩展因子。
  • subsample_layers (list[int]，可选，默认为 [0, 1]) — 对时间维度进行 2 倍下采样的 conformer 块的索引（使用步长为 2 的深度卷积和均值池化残差）。
  • attention_bias (bool，可选，默认为 True) — 在自注意力机制中，是否在查询、键、值以及输出投影层中使用偏置。
  • attention_dropout (Union[float, int]，可选，默认为 0.0) — 注意力概率的 dropout 比率。
  • activation_dropout (Union[float, int]，可选，默认为 0.0) — 全连接层中激活值的 dropout 比率。
  • initializer_range (float，可选，默认为 0.02) — 用于初始化所有权重矩阵的 truncated_normal_initializer 的标准差。

这是用于存储 Granite Speech5Model 配置的类。它根据指定的参数实例化 Granite Speech5 模型，并定义模型架构。使用默认值实例化配置，将得到与 ibm-granite/granite-speech-5.0-470m-turboctc 类似的配置。

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

示例：

>>> from transformers import GraniteSpeech5EncoderConfig, GraniteSpeech5Encoder

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

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

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

GraniteSpeech5FeatureExtractor

class transformers.GraniteSpeech5FeatureExtractor

< >

( num_mel_bins: int = 80sampling_rate: int = 16000n_fft: int = 512win_length: int = 400hop_length: int = 160delta_win_length: int = 3logmel_floor_db: float = 8.0padding_value: float = 0.0**kwargs )

参数

  • num_mel_bins (int，可选，默认为 80) — Mel 滤波器组的数量。
  • sampling_rate (int，可选，默认为 16000) — 音频文件应被数字化时的采样率，以赫兹 (Hz) 为单位。
  • n_fft (int，可选，默认为 512) — 傅里叶变换的大小。
  • win_length (int，可选，默认为 400) — 以采样点为单位的窗口长度。
  • hop_length (int，可选，默认为 160) — 用于获取梅尔频谱图的 STFT 中重叠窗口的长度，以采样点为单位。
  • delta_win_length (int，可选，默认为 3) — 用于计算 delta 特征的窗口长度。
  • logmel_floor_db (float，可选，默认值为 8.0) — 对数梅尔特征的下限为每个样本最大值低于该分贝数的值。
  • padding_value (float，可选，默认为 0.0) — 用于填充音频的填充值。

构建 Granite Speech 5.0 特征提取器。

该特征提取器继承自 SequenceFeatureExtractor，其中包含了大部分主要方法。用户应参考该父类以获取有关这些方法的更多信息。

GraniteSpeech5Processor

class transformers.GraniteSpeech5Processor

< >

( feature_extractortokenizer )

参数

  • feature_extractor (feature_extractor_class) — 特征提取器是必需的输入。
  • tokenizer (tokenizer_class) — 分词器是必需的输入。

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

GraniteSpeech5Processor 提供了 feature_extractor_class 和 tokenizer_class 的所有功能。有关更多信息，请参阅 ~feature_extractor_class 和 ~tokenizer_class。

GraniteSpeech5Encoder

class transformers.GraniteSpeech5Encoder

< >

( config: GraniteSpeech5EncoderConfig )

参数

  • config (GraniteSpeech5EncoderConfig) — 模型配置类，包含模型的所有参数。使用配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 from_pretrained() 方法以加载模型权重。

Granite Speech 5.0 conformer 编码器，改编自 Granite Speech CTC 编码器，并采用了分块时间下采样以及来自中间层的自条件 CTC。

该模型继承自 PreTrainedModel。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。

该模型也是 PyTorch torch.nn.Module 的子类。 请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。

forward

< >

( input_features: Tensorattention_mask: typing.Optional[torch.Tensor] = Noneoutput_attention_mask: bool = True**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → GraniteSpeech5EncoderModelOutput or tuple(torch.Tensor)

参数

  • input_features (torch.Tensor，形状为 (batch_size, sequence_length, feature_dim)) — 与输入音频特征对应的张量。可以使用 feature_extractor_class 获取音频特征。有关详细信息，请参阅 feature_extractor_class.__call__（processor_class 使用 feature_extractor_class 来处理音频）。
  • attention_mask (torch.Tensor 形状为 (batch_size, sequence_length), ，可选) — 用于避免对填充 token 索引执行注意力机制的掩码。掩码值取自 [0, 1]:
    • 1 表示未被屏蔽的 token，
    • 对于被掩码的 token，值为 0。

    什么是注意力掩码？

  • output_attention_mask (bool，可选，默认为 True) — 是否返回输出的注意力掩码。仅在提供 attention_mask 时生效。

返回值

GraniteSpeech5EncoderModelOutput 或 tuple(torch.Tensor)

GraniteSpeech5EncoderModelOutput 或 torch.Tensor 元组（如果传入 return_dict=False 或 config.return_dict=False），包含根据配置（None）和输入而定的各种元素。

GraniteSpeech5Encoder 的 forward 方法重写了 __call__ 特殊方法。

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

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

  • pooler_output (torch.Tensor，形状为 (batch_size, hidden_size)) — 序列中第一个 token（分类 token）的最后一层隐藏状态，经过用于辅助预训练任务的层进一步处理后得到。例如，对于 BERT 系列模型，这返回的是分类 token 经过线性层和 tanh 激活函数处理后的结果。线性层的权重在预训练期间通过下一句预测（分类）目标进行训练。

  • 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 之后的权重，用于在自注意力头中计算加权平均值。

  • attention_mask（形状为 (batch_size, sequence_length) 的 torch.Tensor，可选）— 用于在序列压缩后避免对填充（padding）标记索引执行注意力机制的掩码。由于序列长度可能与输入序列长度不同，因此会返回该掩码。掩码值取自 [0, 1]：

    • 1 表示未被屏蔽的 token，
    • 对于被掩码的 token，值为 0。

示例：

>>> from transformers import AutoProcessor, GraniteSpeech5Encoder
>>> from datasets import load_dataset, Audio

>>> model_id = "ibm-granite/granite-speech-5.0-470m-turboctc"
>>> processor = AutoProcessor.from_pretrained(model_id)
>>> encoder = GraniteSpeech5Encoder.from_pretrained(model_id)

>>> ds = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")
>>> ds = ds.cast_column("audio", Audio(sampling_rate=processor.feature_extractor.sampling_rate))

>>> inputs = processor(ds[0]["audio"]["array"])
>>> encoder_outputs = encoder(**inputs)

>>> print(encoder_outputs.last_hidden_state.shape)

GraniteSpeech5ForCTC

class transformers.GraniteSpeech5ForCTC

< >

( config: GraniteSpeech5CTCConfig )

参数

  • config (GraniteSpeech5CTCConfig) — 模型配置类，包含模型的所有参数。使用配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 from_pretrained() 方法以加载模型权重。

带有连接主义时间分类（CTC）头的 Granite Speech 5.0 编码器。

该模型继承自 PreTrainedModel。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。

该模型也是 PyTorch torch.nn.Module 的子类。 请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。

forward

< >

( input_features: Tensorattention_mask: typing.Optional[torch.Tensor] = Nonelabels: typing.Optional[torch.Tensor] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → CausalLMOutput or tuple(torch.Tensor)

参数

  • input_features (torch.Tensor，形状为 (batch_size, sequence_length, feature_dim)) — 与输入音频特征对应的张量。可以使用 feature_extractor_class 获取音频特征。有关详细信息，请参阅 feature_extractor_class.__call__（processor_class 使用 feature_extractor_class 来处理音频）。
  • attention_mask (torch.Tensor 形状为 (batch_size, sequence_length), ，可选) — 用于避免对填充 token 索引执行注意力机制的掩码。掩码值取自 [0, 1]:
    • 1 表示未被屏蔽的 token，
    • 对于被掩码的 token，值为 0。

    什么是注意力掩码？

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

返回值

CausalLMOutput 或 tuple(torch.Tensor)

torch.Tensor 的元组，或 CausalLMOutput（当传入 return_dict=False 或 config.return_dict=False 时），其包含的元素取决于配置（None）和输入。

GraniteSpeech5ForCTC 的 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 之后的权重，用于在自注意力头中计算加权平均值。

示例：

>>> from transformers import AutoProcessor, GraniteSpeech5ForCTC
>>> from datasets import load_dataset, Audio

>>> model_id = "nvidia/granite_speech5-ctc-1.1b"
>>> processor = AutoProcessor.from_pretrained(model_id)
>>> model = GraniteSpeech5ForCTC.from_pretrained(model_id)

>>> ds = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")
>>> ds = ds.cast_column("audio", Audio(sampling_rate=processor.feature_extractor.sampling_rate))

>>> inputs = processor(ds[0]["audio"]["array"], text=ds[0]["text"])
>>> outputs = model(**inputs)

>>> print(outputs.loss)

generate

< >

( input_features: Tensorattention_mask: typing.Optional[torch.Tensor] = Nonereturn_dict_in_generate: bool = Falsecompile_config: transformers.generation.configuration_utils.CompileConfig | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> )

compile_config (CompileConfig, 可选)： 如果提供，torch.compile 将应用于解码循环中的前向调用。

示例：

>>> from transformers import AutoProcessor, GraniteSpeech5ForCTC
>>> from datasets import load_dataset, Audio

>>> model_id = "ibm-granite/granite-speech-5.0-470m-turboctc"
>>> processor = AutoProcessor.from_pretrained(model_id)
>>> model = GraniteSpeech5ForCTC.from_pretrained(model_id)

>>> ds = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")
>>> ds = ds.cast_column("audio", Audio(sampling_rate=processor.feature_extractor.sampling_rate))

>>> inputs = processor(ds[0]["audio"]["array"])
>>> predicted_ids = model.generate(**inputs)
>>> transcription = processor.batch_decode(predicted_ids, skip_special_tokens=True)

>>> print(transcription)
Update on GitHub

←GraniteSpeech GraniteSpeechPlus→