# Granite Speech

## 概要

[Granite Speech](https://huggingface.co/papers/2505.08699)モデル（[ブログ記事](https://www.ibm.com/new/announcements/ibm-granite-3-3-speech-recognition-refined-reasoning-rag-loras)）は、音声エンコーダー、音声プロジェクター、大規模言語モデル、およびLoRAアダプターで構成されるマルチモーダル言語モデルです。現在の（Granite 3.2 Speech）モデルアーキテクチャの各コンポーネントの詳細については、以下を参照してください。

1. Speech Encoder: ASRコーパス上で、文字レベルのターゲットに対してConnectionist Temporal Classification (CTC)を用いて学習された[Conformer](https://huggingface.co/papers/2005.08100)エンコーダーです。このエンコーダーは、ブロックアテンションと中間層からの自己条件付きCTCを使用しています。

2. Speech Projector: 最後のエンコーダーブロックの出力に対して動作するクエリトランスフォーマー（q-former）。エンコーダーとプロジェクターは、llmによって処理されるマルチモーダル埋め込みに統合される音声特徴を時間的にダウンサンプリングします。

3. 大規模言語モデル: Granite Speech モデルは、[この論文](https://huggingface.co/papers/2408.13359)で初めて提案された Granite LLM を活用しています。

4. LoRA アダプター: Granite Speech モデルには、モダリティ固有の LoRA が含まれており、音声特徴が提供された場合に有効化され、それ以外の場合は無効化されます。

前述のコンポーネントの多くは、transformers における他のモデルアーキテクチャとの互換性および潜在的な統合を可能にするために、汎用的に実装されている点にご注意ください。

このモデルは、[Alexander Brooks](https://huggingface.co/abrooks9944)、[Avihu Dekel](https://huggingface.co/Avihu)、および [George Saon](https://huggingface.co/gsaon) によって提供されました。

## 使用のコツ

- このモデルには独自の LoRA アダプターがバンドルされており、推論呼び出しのたびに必要に応じて自動的に読み込まれて、有効化または無効化されます。LoRA が正しく適用されるよう、[PEFT](https://github.com/huggingface/peft) のインストールを忘れないでください。
- モデルは16kHzのサンプリングレートのオーディオを前提としています。必要に応じて、プロセッサが自動的にリサンプリングを行います。
- LoRA アダプターは、音声特徴が存在する場合に自動的に有効化され、テキストのみの入力では無効化されるため、手動での管理は不要です。

## 使用例

Granite Speech は、音声の文字起こしとテキストプロンプトへの応答が可能なマルチモーダルな音声認識モデルです。使用方法は以下の通りです。

### 基本的な音声文字起こし

```python
from datasets import Audio, load_dataset

from transformers import GraniteSpeechForConditionalGeneration, GraniteSpeechProcessor

# Load model and processor
model = GraniteSpeechForConditionalGeneration.from_pretrained(
    "ibm-granite/granite-3.2-8b-speech",
    device_map="auto"
)
processor = GraniteSpeechProcessor.from_pretrained("ibm-granite/granite-3.2-8b-speech")

# Load audio from dataset (16kHz sampling rate required)
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))
audio = ds['audio'][0]['array']

# Process audio
inputs = processor(audio=audio, return_tensors="pt").to(model.device)

# Generate transcription
generated_ids = model.generate(**inputs, max_new_tokens=256)
transcription = processor.batch_decode(generated_ids, skip_special_tokens=True)[0]
print(transcription)
```

### Chat テンプレートによる Speech-to-Text

音声を用いた指示追従には、会話形式に音声を直接含めたチャットテンプレートを使用します。

```python
from datasets import Audio, load_dataset

from transformers import GraniteSpeechForConditionalGeneration, GraniteSpeechProcessor

model = GraniteSpeechForConditionalGeneration.from_pretrained(
    "ibm-granite/granite-3.2-8b-speech",
    device_map="auto"
)
processor = GraniteSpeechProcessor.from_pretrained("ibm-granite/granite-3.2-8b-speech")

# Load audio from dataset
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))
audio = ds['audio'][0]

# Prepare conversation with audio and text
conversation = [
    {
        "role": "user",
        "content": [
            {"type": "audio", "audio": audio},
            {"type": "text", "text": "Transcribe the following audio:"},
        ],
    }
]

# Apply chat template with audio - processor handles both tokenization and audio processing
inputs = processor.apply_chat_template(conversation, tokenize=True, return_tensors="pt").to(model.device)

# Generate transcription
generated_ids = model.generate(**inputs, max_new_tokens=512)
output_text = processor.batch_decode(generated_ids, skip_special_tokens=True)[0]
print(output_text)
```

### バッチ処理

複数のオーディオファイルを効率的に処理します:

```python
from datasets import Audio, load_dataset

from transformers import GraniteSpeechForConditionalGeneration, GraniteSpeechProcessor

model = GraniteSpeechForConditionalGeneration.from_pretrained(
    "ibm-granite/granite-3.2-8b-speech",
    device_map="auto"
)
processor = GraniteSpeechProcessor.from_pretrained("ibm-granite/granite-3.2-8b-speech")

# Load multiple audio samples from dataset
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))
audio_samples = [ds['audio'][i]['array'] for i in range(3)]

# Process batch
inputs = processor(audio=audio_samples, return_tensors="pt", padding=True).to(model.device)

# Generate for all inputs
generated_ids = model.generate(**inputs, max_new_tokens=256)
transcriptions = processor.batch_decode(generated_ids, skip_special_tokens=True)

for i, transcription in enumerate(transcriptions):
    print(f"Audio {i+1}: {transcription}")
```

## GraniteSpeechConfig[[transformers.GraniteSpeechConfig]]

#### transformers.GraniteSpeechConfig[[transformers.GraniteSpeechConfig]]

```python
transformers.GraniteSpeechConfig(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/configuration_granite_speech.py#L84)

**パラメータ:**

text_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`, *任意*) : テキストバックボーンの config オブジェクトまたは辞書。

encoder_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`、*optional*) : エンコーダーのバックボーンの設定オブジェクトまたは辞書。

projector_config (`Union[AutoConfig, dict]`、*任意*、デフォルトは`Blip2QFormerConfig`) : 音声プロジェクターの config オブジェクトまたは辞書。

audio_token_index (`int`、*任意*、デフォルトは`49155`) : 入力音声のプレースホルダーとして使用される音声トークンインデックス。

initializer_range (`float`、*任意*、デフォルトは`0.02`) : すべての重み行列を初期化するためのtruncated_normal_initializerの標準偏差です。

has_lora_adapter (`bool`、*任意*、デフォルトは`True`) : モデルに、音声入力の処理時のみ有効化すべき LoRA アダプターが存在するかどうかを示します。

downsample_rate (`int`、*optional*、デフォルト値は 5) : 音声特徴抽出器のダウンサンプル率。

window_size (`int`、*optional*、デフォルトは 15) : 音声特徴量プロジェクターのウィンドウサイズ。

tie_word_embeddings (`bool`、*任意*、デフォルトは`True`) : モデルの`tied_weights_keys`マッピングに従って重み埋め込みを共有するかどうか。

これは GraniteSpeechModel の設定を保存するための設定クラスです。指定された引数に基づいて Granite Speech モデルをインスタンス化し、モデルのアーキテクチャを定義するために使用されます。デフォルト値で設定をインスタンス化すると、[ibm-granite/granite-speech-3.3-2b](https://huggingface.co/ibm-granite/granite-speech-3.3-2b) と同様の設定が得られます。

設定オブジェクトは [PreTrainedConfig](/docs/transformers/main/ja/main_classes/configuration#transformers.PreTrainedConfig) を継承し、モデルの出力を制御するために使用できます。詳細については、[PreTrainedConfig](/docs/transformers/main/ja/main_classes/configuration#transformers.PreTrainedConfig) のドキュメントを参照してください。

例:

```python
>>> from transformers import GraniteSpeechConfig, GraniteSpeechForConditionalGeneration

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

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

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

## GraniteSpeechEncoderConfig[[transformers.GraniteSpeechEncoderConfig]]

#### transformers.GraniteSpeechEncoderConfig[[transformers.GraniteSpeechEncoderConfig]]

```python
transformers.GraniteSpeechEncoderConfig(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)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/granite_speech/configuration_granite_speech.py#L25)

**パラメータ:**

input_dim (`int`、*optional*、デフォルトは`160`) : 入力音声特徴量の次元数（例：メルフィルタバンクのチャネル数）。

num_layers (`int`, *任意*, デフォルトは `10`) : Transformer デコーダーの隠れ層の数。

hidden_dim (`int`、*任意*、デフォルトは`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`、*任意*、デフォルトは 200) : conformer attention で使用されるコンテキストサイズ。

max_pos_emb (`int`、*optional*、デフォルト値は 512) : attention で使用する最大位置埋め込み数（shaw の相対位置エンコーディング）。

dropout (`Union[float, int]`、*任意*、デフォルトは`0.1`) : すべての dropout 層の比率。

conv_kernel_size (`int`、*任意*、デフォルトは`15`) : 畳み込みカーネルのサイズ。

conv_expansion_factor (`int`、*optional*、デフォルトは 2) : conformer の畳み込みで使用する中間次元。

これは GraniteSpeechModel の設定を保存するための設定クラスです。指定された引数に基づいて Granite Speech モデルをインスタンス化し、モデルのアーキテクチャを定義するために使用されます。デフォルト値で設定をインスタンス化すると、[ibm-granite/granite-speech-3.3-2b](https://huggingface.co/ibm-granite/granite-speech-3.3-2b) と同様の設定が得られます。

設定オブジェクトは [PreTrainedConfig](/docs/transformers/main/ja/main_classes/configuration#transformers.PreTrainedConfig) を継承し、モデルの出力を制御するために使用できます。詳細については、[PreTrainedConfig](/docs/transformers/main/ja/main_classes/configuration#transformers.PreTrainedConfig) のドキュメントを参照してください。

例:

```python
>>> from transformers import GraniteSpeechEncoderConfig, GraniteSpeechCTCEncoder

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

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

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

## GraniteSpeechProcessor[[transformers.GraniteSpeechProcessor]]

#### transformers.GraniteSpeechProcessor[[transformers.GraniteSpeechProcessor]]

```python
transformers.GraniteSpeechProcessor(audio_processor, tokenizer, audio_token = '<|audio|>', chat_template = None)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/granite_speech/processing_granite_speech.py#L35)

**パラメータ:**

audio_processor (`{audio_processor_class}`) : 音声プロセッサは必須の入力です。

tokenizer (`tokenizer_class`) : トークナイザーは必須の入力です。

audio_token (`str`、*任意*、デフォルトは`"<|audio|>"`) : テキストシーケンス内でオーディオを表すために使用される特殊トークンです。このトークンはプレースホルダーとして機能し、実際のオーディオの長さに基づいて複数のオーディオトークンに置き換えられます。挿入されるオーディオトークンの数は、オーディオプロセッサによって抽出されるオーディオ特徴量の次元数に依存します。

chat_template (`str`) : チャット内のメッセージのリストをトークン化可能な文字列に変換するための Jinja テンプレート。

オーディオプロセッサとトークナイザーを単一のプロセッサにラップするGraniteSpeechProcessorを構築します。

[GraniteSpeechProcessor](/docs/transformers/main/ja/model_doc/granite_speech#transformers.GraniteSpeechProcessor) は、`{audio_processor_class}` と `tokenizer_class` のすべての機能を提供します。詳細については、`~{audio_processor_class}` および `~tokenizer_class` を参照してください。

#### __call__[[transformers.GraniteSpeechProcessor.__call__]]

```python
__call__(text: str | list[str] | list[list[str]], audio: typing.Union[numpy.ndarray, ForwardRef('torch.Tensor'), collections.abc.Sequence[numpy.ndarray], collections.abc.Sequence['torch.Tensor'], NoneType] = None, device: str = 'cpu', **kwargs: *<class 'transformers.models.granite_speech.processing_granite_speech.GraniteSpeechProcessorKwargs'>)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/granite_speech/processing_granite_speech.py#L54)

**パラメータ:**

text (`Union[str, list[str], list[list[str]]]`) : エンコード対象のシーケンスまたはシーケンスのバッチです。各シーケンスは、文字列または文字列のリスト（プレトークナイズ済み文字列）であることができます。プレトークナイズ済み入力を渡す場合は、バッチ入力との曖昧さを避けるために`is_split_into_words=True`を設定してください。

audio (`Union[numpy.ndarray, torch.Tensor, collections.abc.Sequence[numpy.ndarray], collections.abc.Sequence[torch.Tensor]]`, *任意*) : 準備対象のオーディオまたはオーディオのバッチです。各オーディオは NumPy 配列または PyTorch テンソルであることができます。NumPy 配列/PyTorch テンソルの場合、各オーディオの形状は (C, T) である必要があります。ここで C はチャネル数、T はオーディオのサンプル長を表します。

device (`str`、*任意*、デフォルトは `cpu`) : 動画を処理するデバイスです。設定されていない場合、入力された動画からデバイスが推論されます。

return_tensors (`str` または [TensorType](/docs/transformers/main/ja/internal/file_utils#transformers.TensorType)、*optional*) : 設定されている場合、特定のフレームワークのテンソルを返します。受け入れ可能な値は以下の通りです:  - `'pt'`: PyTorch の `torch.Tensor` オブジェクトを返します。 - `'np'`: NumPy の `np.ndarray` オブジェクトを返します。

- ****kwargs** ([ProcessingKwargs](/docs/transformers/main/ja/main_classes/processors#transformers.ProcessingKwargs), *optional*) : 各モダリティ（テキスト、画像、動画、音声）の追加処理オプション。モデル固有のパラメータは上記にリストされています。サポートされている引数の完全なリストについては、TypedDict クラスを参照してください。

**戻り値:** `~feature_extraction_utils.BatchFeature`

- **data** (`dict`, *任意*) -- __call__/pad メソッドによって返されるリスト/配列/テンソルの辞書（'input_values'、'attention_mask' など）。
- **tensor_type** (`Union[None, str, TensorType]`、*省略可*) -- 初期化時に PyTorch/Numpy の Tensor 内の整数リストを変換するために、ここで tensor_type を指定できます。
- **skip_tensor_conversion** (`list[str]` または `set[str]`、*任意*) -- `tensor_type` が指定されている場合でも、テンソルに変換すべきでないキーのリストまたはセット。

## GraniteSpeechFeatureExtractor[[transformers.GraniteSpeechFeatureExtractor]]

#### transformers.GraniteSpeechFeatureExtractor[[transformers.GraniteSpeechFeatureExtractor]]

```python
transformers.GraniteSpeechFeatureExtractor(sampling_rate: int = 16000, n_fft: int = 512, win_length: int = 400, hop_length: int = 160, n_mels: int = 80, projector_window_size: int = 15, projector_downsample_rate: int = 5, padding_value: float = 0.0, **kwargs)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/granite_speech/feature_extraction_granite_speech.py#L37)

## GraniteSpeechModel[[transformers.GraniteSpeechModel]]

#### transformers.GraniteSpeechModel[[transformers.GraniteSpeechModel]]

```python
transformers.GraniteSpeechModel(config: GraniteSpeechConfig)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/granite_speech/modeling_granite_speech.py#L351)

**パラメータ:**

config ([GraniteSpeechConfig](/docs/transformers/main/ja/model_doc/granite_speech#transformers.GraniteSpeechConfig)) : モデルのパラメータをすべて含むモデル設定クラスです。設定ファイルで初期化しても、モデルに関連する重みは読み込まれず、設定のみが読み込まれます。モデルの重みをロードするには、[from_pretrained()](/docs/transformers/main/ja/main_classes/model#transformers.PreTrainedModel.from_pretrained) メソッドを確認してください。

言語モデリングヘッドを含まない、オーディオエンコーダー、プロジェクター、言語モデルで構成される Granite Speech モデル。

このモデルは [PreTrainedModel](/docs/transformers/main/ja/main_classes/model#transformers.PreTrainedModel) を継承しています。ライブラリがすべてのモデルに対して実装している汎用的なメソッド（ダウンロードや保存、入力埋め込みのリサイズ、ヘッドのプルーニングなど）については、スーパークラスのドキュメントを参照してください。

このモデルは、PyTorchの[torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module)のサブクラスでもあります。通常のPyTorch Moduleとして使用し、一般的な使用方法や動作に関する詳細については、PyTorchのドキュメントを参照してください。

#### forward[[transformers.GraniteSpeechModel.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/modeling_granite_speech.py#L424)

**パラメータ:**

input_ids (`torch.LongTensor`、shape `(batch_size, sequence_length)`、*任意*) : 語彙における入力シーケンスのトークンインデックスです。デフォルトでは、パディングは無視されます。インデックスは [AutoTokenizer](/docs/transformers/main/ja/model_doc/auto#transformers.AutoTokenizer) を使用して取得できます。詳細については、[PreTrainedTokenizer.encode()](/docs/transformers/main/ja/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) および [PreTrainedTokenizer.__call__()](/docs/transformers/main/ja/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) を参照してください。 [入力IDとは何ですか？](../glossary#input-ids)

input_features (`torch.Tensor`、形状 `(batch_size, sequence_length, feature_dim)`、*任意*) : 入力音声特徴に対応するテンソルです。音声特徴は [GraniteSpeechFeatureExtractor](/docs/transformers/main/ja/model_doc/granite_speech#transformers.GraniteSpeechFeatureExtractor) を使用して取得できます。詳細は `GraniteSpeechFeatureExtractor.__call__()` を参照してください（[GraniteSpeechProcessor](/docs/transformers/main/ja/model_doc/granite_speech#transformers.GraniteSpeechProcessor) は音声の処理に [GraniteSpeechFeatureExtractor](/docs/transformers/main/ja/model_doc/granite_speech#transformers.GraniteSpeechFeatureExtractor) を使用します）。

input_features_mask (`torch.Tensor`, *任意*) : 言語埋め込みに散りばめる前に、音声特徴量に適用されるマスク。

attention_mask (`torch.Tensor`、shape `(batch_size, sequence_length)`、*任意*) : padding トークンのインデックスに対する attention を回避するためのマスクです。マスクの値は `[0, 1]` から選択されます:  - **マスクされない**トークンは 1、- **マスクされる**トークンは 0。  [attention マスクとは?](../glossary#attention-mask)

position_ids (`torch.LongTensor`、shape `(batch_size, sequence_length)`、*任意*) : 各入力シーケンスのトークンが位置埋め込み内で占める位置のインデックスです。`[0, config.n_positions - 1]` の範囲から選択されます。 [位置 ID とは何か？](../glossary#position-ids)

past_key_values (`~cache_utils.Cache`, *任意*) : 逐次デコードを高速化するために使用できる、事前計算された hidden-states（self-attention ブロックおよび cross-attention ブロック内の key と value）です。通常、`use_cache=True` または `config.use_cache=True` の場合、モデルがデコードの以前の段階で返した `past_key_values` で構成されます。入力として許可されるのは [Cache](/docs/transformers/main/ja/internal/generation_utils#transformers.Cache) インスタンスのみです。[kv cache ガイド](https://huggingface.co/docs/transformers/en/kv_cache)を参照してください。`past_key_values` が渡されない場合、デフォルトで [DynamicCache](/docs/transformers/main/ja/internal/generation_utils#transformers.DynamicCache) が初期化されます。モデルは、入力として与えられたのと同じキャッシュ形式を出力します。`past_key_values` を使用する場合は、すべての `input_ids`（形状 `(batch_size, sequence_length)`）の代わりに、このモデルに過去の key value 状態が与えられていない未処理の `input_ids`（形状 `(batch_size, unprocessed_length)`）のみを入力する必要があります。

inputs_embeds (`torch.Tensor`、shape `(batch_size, sequence_length, hidden_size)`、*任意*) : `input_ids` を渡す代わりに、埋め込み表現を直接渡すこともできます。これは、モデル内部の埋め込み参照行列よりも、`input_ids` のインデックスを対応するベクトルに変換する方法をより細かく制御したい場合に有用です。

use_cache (`bool`, *任意*) : `True`に設定すると、`past_key_values`のキーバリュー状態が返され、デコーディングの高速化に利用できます（`past_key_values`を参照）。

**戻り値:** `GraniteSpeechModelOutputWithPast` または `tuple(torch.Tensor)`

`GraniteSpeechModelOutputWithPast`、または`torch.Tensor`のタプル（`return_dict=False`が渡された場合、または`config.return_dict=False`の場合）。構成要素は、設定（[GraniteSpeechConfig](/docs/transformers/main/ja/model_doc/granite_speech#transformers.GraniteSpeechConfig)）と入力に応じて異なります。

[GraniteSpeechModel](/docs/transformers/main/ja/model_doc/granite_speech#transformers.GraniteSpeechModel)のforwardメソッドは、`__call__`特殊メソッドをオーバーライドします。

この関数内でフォワードパスの手順を定義する必要がありますが、その後、この関数ではなく`Module`インスタンスを呼び出すべきです。前者は前処理と後処理の実行を適切に処理するのに対し、後者はそれらを無視してしまいます。

- **last_hidden_state** (`torch.Tensor`、形状 `(batch_size, sequence_length, hidden_size)`) -- モデルの最終層の出力における隠れ状態のシーケンス。

  `past_key_values`が使用されている場合、出力されるのは、形状`(batch_size, 1, hidden_size)`のシーケンスの最後の隠れ状態のみです。
- **past_key_values** (`Cache`、*任意*、`use_cache=True` が渡された場合または `config.use_cache=True` の場合に返されます) -- [Cache](/docs/transformers/main/ja/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)`、*optional*、`output_hidden_states=True` が渡された場合または `config.output_hidden_states=True` の場合に返されます) -- `torch.Tensor` のタプル（モデルに埋め込み層がある場合はその出力用 1 つ、各層の出力用 1 つずつ）で、形状は `(batch_size, sequence_length, hidden_size)` です。

  各層の出力におけるモデルのHidden-states、および任意の初期埋め込み出力。
- **attentions** (`tuple(torch.Tensor)`、*optional*、`output_attentions=True` が渡された場合または `config.output_attentions=True` の場合に返されます) -- `torch.Tensor` のタプル（各レイヤーごとに1つ）、形状は `(batch_size, num_heads, sequence_length, sequence_length)`。

  アテンションのsoftmax後のアテンション重み。自己アテンションヘッド内で加重平均を計算するために使用されます。
- **audio_hidden_states** (`torch.Tensor`、*任意*) -- 投影されたオーディオの隠れ状態。

## GraniteSpeechForConditionalGeneration[[transformers.GraniteSpeechForConditionalGeneration]]

#### transformers.GraniteSpeechForConditionalGeneration[[transformers.GraniteSpeechForConditionalGeneration]]

```python
transformers.GraniteSpeechForConditionalGeneration(config: GraniteSpeechConfig)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/granite_speech/modeling_granite_speech.py#L496)

**パラメータ:**

config ([GraniteSpeechConfig](/docs/transformers/main/ja/model_doc/granite_speech#transformers.GraniteSpeechConfig)) : モデルのパラメータをすべて含むモデル設定クラスです。設定ファイルで初期化しても、モデルに関連する重みは読み込まれず、設定のみが読み込まれます。モデルの重みをロードするには、[from_pretrained()](/docs/transformers/main/ja/main_classes/model#transformers.PreTrainedModel.from_pretrained) メソッドを確認してください。

オーディオエンコーダー、プロジェクター、言語モデルで構成されるGranite Speechモデル。

このモデルは [PreTrainedModel](/docs/transformers/main/ja/main_classes/model#transformers.PreTrainedModel) を継承しています。ライブラリがすべてのモデルに対して実装している汎用的なメソッド（ダウンロードや保存、入力埋め込みのリサイズ、ヘッドのプルーニングなど）については、スーパークラスのドキュメントを参照してください。

このモデルは、PyTorchの[torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module)のサブクラスでもあります。通常のPyTorch Moduleとして使用し、一般的な使用方法や動作に関する詳細については、PyTorchのドキュメントを参照してください。

#### forward[[transformers.GraniteSpeechForConditionalGeneration.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/modeling_granite_speech.py#L518)

**パラメータ:**

input_ids (`torch.LongTensor`、shape `(batch_size, sequence_length)`、*任意*) : 語彙における入力シーケンスのトークンインデックスです。デフォルトでは、パディングは無視されます。インデックスは [AutoTokenizer](/docs/transformers/main/ja/model_doc/auto#transformers.AutoTokenizer) を使用して取得できます。詳細については、[PreTrainedTokenizer.encode()](/docs/transformers/main/ja/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) および [PreTrainedTokenizer.__call__()](/docs/transformers/main/ja/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) を参照してください。 [入力IDとは何ですか？](../glossary#input-ids)

input_features (`torch.Tensor`、形状 `(batch_size, sequence_length, feature_dim)`、*任意*) : 入力音声特徴に対応するテンソルです。音声特徴は [GraniteSpeechFeatureExtractor](/docs/transformers/main/ja/model_doc/granite_speech#transformers.GraniteSpeechFeatureExtractor) を使用して取得できます。詳細は `GraniteSpeechFeatureExtractor.__call__()` を参照してください（[GraniteSpeechProcessor](/docs/transformers/main/ja/model_doc/granite_speech#transformers.GraniteSpeechProcessor) は音声の処理に [GraniteSpeechFeatureExtractor](/docs/transformers/main/ja/model_doc/granite_speech#transformers.GraniteSpeechFeatureExtractor) を使用します）。

input_features_mask (`torch.Tensor`, *任意*) : 言語埋め込みに散りばめる前に、音声特徴量に適用されるマスク。

attention_mask (`torch.Tensor`、shape `(batch_size, sequence_length)`、*任意*) : padding トークンのインデックスに対する attention を回避するためのマスクです。マスクの値は `[0, 1]` から選択されます:  - **マスクされない**トークンは 1、- **マスクされる**トークンは 0。  [attention マスクとは?](../glossary#attention-mask)

position_ids (`torch.LongTensor`、shape `(batch_size, sequence_length)`、*任意*) : 各入力シーケンスのトークンが位置埋め込み内で占める位置のインデックスです。`[0, config.n_positions - 1]` の範囲から選択されます。 [位置 ID とは何か？](../glossary#position-ids)

past_key_values (`~cache_utils.Cache`, *任意*) : 逐次デコードを高速化するために使用できる、事前計算された hidden-states（self-attention ブロックおよび cross-attention ブロック内の key と value）です。通常、`use_cache=True` または `config.use_cache=True` の場合、モデルがデコードの以前の段階で返した `past_key_values` で構成されます。入力として許可されるのは [Cache](/docs/transformers/main/ja/internal/generation_utils#transformers.Cache) インスタンスのみです。[kv cache ガイド](https://huggingface.co/docs/transformers/en/kv_cache)を参照してください。`past_key_values` が渡されない場合、デフォルトで [DynamicCache](/docs/transformers/main/ja/internal/generation_utils#transformers.DynamicCache) が初期化されます。モデルは、入力として与えられたのと同じキャッシュ形式を出力します。`past_key_values` を使用する場合は、すべての `input_ids`（形状 `(batch_size, sequence_length)`）の代わりに、このモデルに過去の key value 状態が与えられていない未処理の `input_ids`（形状 `(batch_size, unprocessed_length)`）のみを入力する必要があります。

inputs_embeds (`torch.Tensor`、shape `(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` に設定されたトークンは無視（マスク）され、損失は `[0, ..., config.vocab_size]` の範囲内のラベルを持つトークンに対してのみ計算されます。

use_cache (`bool`, *任意*) : `True`に設定すると、`past_key_values`のキーバリュー状態が返され、デコーディングの高速化に利用できます（`past_key_values`を参照）。

logits_to_keep (`Union[int, torch.Tensor]`、*任意*、デフォルトは `0`) : `int` の場合、最後の `logits_to_keep` トークンについて logits を計算します。`0` の場合、すべての `input_ids` について logits を計算します（特殊ケース）。生成には最後のトークンの logits だけで十分であり、そのトークンのみについて計算することでメモリを節約できます。これは、長いシーケンスや大規模な語彙サイズの場合に特に顕著な効果があります。`torch.Tensor` の場合、シーケンス長次元で保持するインデックスに対応する 1 次元である必要があります。これは、パックされたテンソル形式（バッチとシーケンス長を単一の次元にまとめる形式）を使用する場合に有用です。

**戻り値:** `GraniteSpeechCausalLMOutputWithPast` または `tuple(torch.Tensor)`

`GraniteSpeechCausalLMOutputWithPast`、または`torch.Tensor`のタプル（`return_dict=False`が渡された場合、または`config.return_dict=False`の場合）。設定（[GraniteSpeechConfig](/docs/transformers/main/ja/model_doc/granite_speech#transformers.GraniteSpeechConfig)）や入力に応じて、さまざまな要素で構成されます。

[GraniteSpeechForConditionalGeneration](/docs/transformers/main/ja/model_doc/granite_speech#transformers.GraniteSpeechForConditionalGeneration)のforwardメソッドは、`__call__`特殊メソッドをオーバーライドします。

この関数内でフォワードパスの手順を定義する必要がありますが、その後、この関数ではなく`Module`インスタンスを呼び出すべきです。前者は前処理と後処理の実行を適切に処理するのに対し、後者はそれらを無視してしまいます。

- **loss** (`torch.Tensor`、形状 `(1,)`、*任意*、`labels` が指定された場合に返されます) -- 言語モデリングの損失(次のトークンの予測用)。
- **logits** (`torch.Tensor`、形状 `(batch_size, sequence_length, config.vocab_size)`) -- 言語モデリングヘッドの予測スコア（SoftMax 適用前の各語彙トークンのスコア）。
- **past_key_values** (`Cache`、*任意*、`use_cache=True` が渡された場合または `config.use_cache=True` の場合に返されます) -- [Cache](/docs/transformers/main/ja/internal/generation_utils#transformers.Cache) のインスタンスです。詳細については、[kv cache ガイド](https://huggingface.co/docs/transformers/en/kv_cache)を参照してください。

  逐次デコーディングを高速化するために使用できる（`past_key_values` 入力参照）、事前計算済みの隠れ状態（自己注意ブロックのキーとバリュー）が含まれます。
- **hidden_states** (`tuple[torch.Tensor]`、*optional*、`output_hidden_states=True` が渡された場合、または `config.output_hidden_states=True` の場合に返されます) -- `torch.Tensor` のタプル（モデルに埋め込み層がある場合はその出力用 1 つ、各層の出力用 1 つずつ）で、形状は `(batch_size, sequence_length, hidden_size)` です。

  各層の出力におけるモデルのHidden-states、および任意の初期埋め込み出力。
- **attentions** (`tuple[torch.Tensor]`、*optional*、`output_attentions=True` が渡された場合または `config.output_attentions=True` の場合に返されます) -- `torch.Tensor` のタプル（各レイヤーごとに1つ）、形状は `(batch_size, num_heads, sequence_length, sequence_length)`。

  アテンションのsoftmax後のアテンション重み。自己アテンションヘッド内で加重平均を計算するために使用されます。
- **audio_hidden_states** (`torch.Tensor`、*任意*) -- 投影されたオーディオの隠れ状態。

例:

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

>>> # 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.GraniteSpeechForConditionalGeneration.get_audio_features]]

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

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/granite_speech/modeling_granite_speech.py#L515)