Transformers documentation
GraniteSpeech5
该模型于 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 编码器，具体包括：
帧堆叠 + 分块时间下采样：特征提取器将 log-mel（+delta）帧成对堆叠（2 倍），前两个 conformer 块各自通过步长为 2 的深度可分离卷积（带均值池化残差）将时间维度下采样 2 倍，在 10 ms mel 跳步下实现总计 8 倍的时间缩减。
使用 Shaw 相对位置嵌入的块注意力：注意力在固定大小的块上计算（序列向右填充至块的整数倍，填充的帧会被掩码），并使用独立的无偏置查询/键/值投影。
自条件 CTC：将中间层的 CTC 后验概率投影后反馈至隐藏状态，并且 CTC 头在此中间层自条件机制与最终预测之间共享。
该模型由 Eustache Le Bihan 贡献。
用法
GraniteSpeech5ForCTC 的用法
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'}from datasets import Audio, load_dataset
from transformers import AutoModelForCTC, AutoProcessor
model_id = "ibm-granite/granite-speech-5.0-470m-turboctc"
processor = AutoProcessor.from_pretrained(model_id)
model = AutoModelForCTC.from_pretrained(model_id, device_map="auto")
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))
speech_samples = [el['array'] for el in ds["audio"][:5]]
# `device` computes the log-mel front-end on the model's accelerator, saving a host-to-device copy
inputs = processor(
speech_samples, sampling_rate=processor.feature_extractor.sampling_rate, device=model.device
)
inputs.to(model.device, dtype=model.dtype)
outputs = model.generate(**inputs)
print(processor.batch_decode(outputs, skip_special_tokens=True))
# ['mister quilter is the apostle of the middle classes and we are glad to welcome his gospel', ...]GraniteSpeech5CTCConfig
class transformers.GraniteSpeech5CTCConfig
< source >( 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.configGraniteSpeech5EncoderConfig
类 transformers.GraniteSpeech5EncoderConfig
< source >( 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.configGraniteSpeech5FeatureExtractor
class transformers.GraniteSpeech5FeatureExtractor
< source >( 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
< source >( feature_extractortokenizer )
构造一个 GraniteSpeech5Processor，它将特征提取器和分词器封装为单个处理器。
GraniteSpeech5Processor 提供了 feature_extractor_class 和 tokenizer_class 的所有功能。有关更多信息，请参阅 ~feature_extractor_class 和 ~tokenizer_class。
GraniteSpeech5Encoder
class transformers.GraniteSpeech5Encoder
< source >( config: GraniteSpeech5EncoderConfig )
参数
- config (GraniteSpeech5EncoderConfig) — 模型配置类，包含模型的所有参数。使用配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 from_pretrained() 方法以加载模型权重。
Granite Speech 5.0 conformer 编码器，改编自 Granite Speech CTC 编码器，并采用了分块时间下采样以及来自中间层的自条件 CTC。
该模型继承自 PreTrainedModel。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。
该模型也是 PyTorch torch.nn.Module 的子类。 请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。
forward
< source >( 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
< source >( config: GraniteSpeech5CTCConfig )
参数
- config (GraniteSpeech5CTCConfig) — 模型配置类，包含模型的所有参数。使用配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 from_pretrained() 方法以加载模型权重。
带有连接主义时间分类（CTC）头的 Granite Speech 5.0 编码器。
该模型继承自 PreTrainedModel。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。
该模型也是 PyTorch torch.nn.Module 的子类。 请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。
forward
< source >( 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
< source >( 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)