Transformers documentation
GraniteSpeech5
このモデルは2026年8月25日にHugging Face Transformersに貢献されました。
GraniteSpeech5
概要
Granite Speech 5.0 Turbo CTC は、自動音声認識用の軽量（約470Mパラメータ）conformerエンコーダーです。BPEターゲットに対してConnectionist Temporal Classification (CTC)で学習されています。Granite Speechファミリーの高速なエンコーダー専用モデルであり、文字起こしには単一のフォワードパスとグリーディCTCデコーディングのみで完了し、自己回帰デコーダーは不要です。
アーキテクチャ的には、Granite Speechのconformer CTCエンコーダを以下のように拡張しています:
フレームスタッキング + ブロック単位の時間方向サブサンプリング: 特徴抽出器は、log-mel(+delta)フレームのペアをスタッキング（2倍）し、最初の2つのconformerブロックがそれぞれ、stride-2のdepthwise convolution（平均プーリングされた残差付き）によって時間方向を2倍サブサンプリングします。これにより、10 msのmel hopに対して合計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で表現できるトークンの種類数を定義します。 - 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) — 語彙内でパディングに使用されるトークン 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で表現できるトークンの種類数を定義します。 - 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 attention のコンテキストサイズ。 - conv_kernel_size (
int, 任意、デフォルトは 7) — Conformer の convolution モジュールにおける depthwise convolution のカーネルサイズ。 - conv_expansion_factor (
int、任意、デフォルトは 2) — Conformer 畳み込みモジュールの拡張係数。 - subsample_layers (
list[int]、任意、デフォルトは[0, 1]) — 時間方向を 2 倍にサブサンプリングする conformer ブロックのインデックス（平均プーリング付き残差接続を持つ stride-2 の depthwise 畳み込みを使用）。 - attention_bias (
bool、任意、デフォルトはTrue) — 自己注意機構において、クエリ、キー、バリュー、および出力の投影層にバイアスを使用するかどうかを指定します。 - attention_dropout (
Union[float, int]、任意、デフォルトは0.0) — アテンション確率のドロップアウト率です。 - 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) — mel スペクトラムを取得するために使用される STFT の、重複するウィンドウの長さ（サンプル数）。 - delta_win_length (
int, 任意、デフォルトは 3) — デルタ特徴量を計算するために使用するウィンドウ長。 - logmel_floor_db (
float、任意、デフォルト値は 8.0) — log-mel 特徴量は、サンプルごとの最大値からこの dB 数だけ低い値で下限が設定されます。 - padding_value (
float、任意、デフォルト値は 0.0)— オーディオをパディングするために使用される値です。
Granite Speech 5.0 の特徴抽出器を構築します。
このフィーチャーエクストラクターは、主要なメソッドの大部分を含む SequenceFeatureExtractor を継承しています。これらのメソッドに関する詳細については、このスーパークラスを参照してください。
GraniteSpeech5Processor
クラス 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 CTC エンコーダーから派生した、ブロック単位の時間方向サブサンプリングと中間層からの自己条件付きCTCを備えたGranite Speech 5.0 conformerエンコーダーです。
このモデルは 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.FloatTensor)
パラメータ
- 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), 、任意) — パディングトークンのインデックスに対するアテンションを回避するためのマスク。[0, 1]:- マスクされていないトークンに対して1
- マスクされたトークンに対しては 0 です。
- output_attention_mask (
bool、任意、デフォルトはTrue) — 出力アテンションマスクを返すかどうか。attention_maskが指定されている場合のみ有効です。
戻り値
GraniteSpeech5EncoderModelOutput または tuple(torch.FloatTensor)
GraniteSpeech5EncoderModelOutput、またはtorch.FloatTensorのタプル（return_dict=Falseが渡された場合、またはconfig.return_dict=Falseの場合）。設定（None）と入力に応じて、さまざまな要素で構成されます。
GraniteSpeech5Encoderのforwardメソッドは、__call__特殊メソッドをオーバーライドします。
この関数内でフォワードパスの手順を定義する必要がありますが、その後、この関数ではなく
Moduleインスタンスを呼び出すべきです。前者は前処理と後処理の実行を適切に処理するのに対し、後者はそれらを黙って無視するためです。
last_hidden_state (
torch.FloatTensor、shape(batch_size, sequence_length, hidden_size)) — モデルの最終層の出力における隠れ状態のシーケンス。pooler_output (
torch.FloatTensor、shape(batch_size, hidden_size)) — 補助事前学習タスクに使用される層をさらに通して処理された後、シーケンスの最初のトークン（分類トークン）の最終層の隠れ状態。例えば、BERT 系のモデルでは、線形層と tanh 活性化関数を経て処理された後の分類トークンを返します。この線形層の重みは、事前学習中の次文予測（分類）目的から学習されます。hidden_states (
tuple(torch.FloatTensor)、optional、output_hidden_states=Trueが渡された場合またはconfig.output_hidden_states=Trueの場合に返されます)—torch.FloatTensorのタプル（埋め込み層を持つモデルの場合、埋め込みの出力が 1 つ、各層の出力がそれぞれ 1 つずつ）で、形状は(batch_size, sequence_length, hidden_size)です。各層の出力におけるモデルのHidden-states、および任意の初期埋め込み出力。
attentions (
tuple(torch.FloatTensor)、optional、output_attentions=Trueが渡された場合またはconfig.output_attentions=Trueの場合に返されます)—torch.FloatTensorのタプル（各レイヤーごとに1つ）、形状は(batch_size, num_heads, sequence_length, sequence_length)。アテンションのsoftmax後のアテンション重み。自己アテンションヘッド内で加重平均を計算するために使用されます。
attention_mask (
torch.Tensor、形状(batch_size, sequence_length)、任意) — シーケンス圧縮後のパディングトークンインデックスに対するアテンションを回避するためのマスク。入力シーケンスの長さと異なる可能性があるため、返されます。マスクの値は[0, 1]から選択されます:- マスクされていないトークンに対して1
- マスクされたトークンに対しては 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() メソッドを参照してください。
Connectionist Temporal Classification (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.FloatTensor)
パラメータ
- 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), 、任意) — パディングトークンのインデックスに対するアテンションを回避するためのマスク。[0, 1]:- マスクされていないトークンに対して1
- マスクされたトークンに対しては 0 です。
- labels (
torch.Tensor、shape(batch_size, sequence_length)、任意) — マスク言語モデリング損失を計算するためのラベルです。インデックスは[0, ..., config.vocab_size]の範囲内であるか、-100 である必要があります（input_idsのドキュメント文字列を参照）。インデックスが-100に設定されたトークンは無視（マスク）され、損失は[0, ..., config.vocab_size]の範囲内のラベルを持つトークンに対してのみ計算されます。
戻り値
CausalLMOutput または tuple(torch.FloatTensor)
None や入力に応じて、さまざまな要素で構成される CausalLMOutput または torch.FloatTensor のタプル（return_dict=False が渡された場合、または config.return_dict=False の場合）。
GraniteSpeech5ForCTCのforwardメソッドは、__call__特殊メソッドをオーバーライドします。
この関数内でフォワードパスの手順を定義する必要がありますが、その後、この関数ではなく
Moduleインスタンスを呼び出すべきです。前者は前処理と後処理の実行を適切に処理するのに対し、後者はそれらを黙って無視するためです。
loss (
torch.FloatTensor、shape(1,)、optional、labelsが指定された場合に返されます) — 言語モデリングの損失（次のトークン予測用）。logits (
torch.FloatTensor、shape(batch_size, sequence_length, config.vocab_size)) — 言語モデリングヘッドの予測スコア（SoftMax 適用前の各語彙トークンのスコア）。hidden_states (
tuple(torch.FloatTensor)、optional、output_hidden_states=Trueが渡された場合またはconfig.output_hidden_states=Trueの場合に返されます)—torch.FloatTensorのタプル（埋め込み層を持つモデルの場合、埋め込みの出力が 1 つ、各層の出力がそれぞれ 1 つずつ）で、形状は(batch_size, sequence_length, hidden_size)です。各層の出力におけるモデルのHidden-states、および任意の初期埋め込み出力。
attentions (
tuple(torch.FloatTensor)、optional、output_attentions=Trueが渡された場合またはconfig.output_attentions=Trueの場合に返されます)—torch.FloatTensorのタプル（各レイヤーごとに1つ）、形状は(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, 任意):
指定された場合、デコーディングループ内の forward 呼び出しに 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)