# Granite Speech

## Ikhtisar

Model [Granite Speech](https://huggingface.co/papers/2505.08699) ([artikel blog](https://www.ibm.com/new/announcements/ibm-granite-3-3-speech-recognition-refined-reasoning-rag-loras)) adalah model bahasa multimodal, yang terdiri dari encoder ucapan, projector ucapan, large language model, dan adapter LoRA. Detail lebih lanjut mengenai masing-masing komponen untuk arsitektur model saat ini (Granite 3.2 Speech) dapat ditemukan di bawah ini.

1. Speech Encoder: Encoder [Conformer](https://huggingface.co/papers/2005.08100) yang dilatih dengan Connectionist Temporal Classification (CTC) pada target level karakter di korpus ASR. Encoder ini menggunakan block-attention dan self-conditioned CTC dari lapisan tengah.

2. Speech Projector: sebuah query transformer (q-former) yang beroperasi pada output dari blok encoder terakhir. Encoder dan projector melakukan downsampling temporal pada fitur audio untuk digabungkan ke dalam embedding multimodal yang akan diproses oleh llm.

3. Large Language Model: Model Granite Speech memanfaatkan Granite LLMs, yang awalnya diusulkan dalam [makalah ini](https://huggingface.co/papers/2408.13359).

4. LoRA adapter(s): Model Granite Speech berisi LoRA yang spesifik untuk modalitas, yang akan diaktifkan ketika fitur audio disediakan, dan dinonaktifkan jika tidak.

Perhatikan bahwa sebagian besar komponen yang disebutkan di atas diimplementasikan secara generik untuk memungkinkan kompatibilitas dan potensi integrasi dengan arsitektur model lain di transformers.

Model ini disumbangkan oleh [Alexander Brooks](https://huggingface.co/abrooks9944), [Avihu Dekel](https://huggingface.co/Avihu), dan [George Saon](https://huggingface.co/gsaon).

## Tips penggunaan

- Model ini menyertakan adapter LoRA-nya sendiri, yang akan dimuat secara otomatis dan diaktifkan/dinonaktifkan sesuai kebutuhan selama panggilan inferensi. Pastikan Anda menginstal [PEFT](https://github.com/huggingface/peft) untuk memastikan LoRA diterapkan dengan benar!
- Model mengharapkan audio dengan laju sampling 16kHz. Prosesor akan melakukan resampling secara otomatis jika diperlukan.
- Adaptasi LoRA secara otomatis diaktifkan ketika fitur audio hadir dan dinonaktifkan untuk input teks saja, sehingga Anda tidak perlu mengelolanya secara manual.

## Contoh penggunaan

Granite Speech adalah model speech-to-text multimodal yang dapat mentranskripsi audio dan merespons prompt teks. Berikut cara menggunakannya:

### Transkripsi Suara Dasar

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

### Transkripsi Suara ke Teks dengan Template Chat

Untuk mengikuti instruksi dengan audio, gunakan template chat dengan audio langsung dalam format percakapan:

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

### Pemrosesan Batch

Proses beberapa file audio secara efisien:

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

[Sumber](https://github.com/huggingface/transformers/blob/main/src/transformers/models/granite_speech/configuration_granite_speech.py#L84)

**Parameter:**

text_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`, *opsional*) : Objek config atau dictionary dari text backbone.

encoder_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`, *opsional*) : Objek config atau dictionary dari encoder backbone.

projector_config (`Union[AutoConfig, dict]`, *opsional*, defaultnya `Blip2QFormerConfig`) : Objek config atau dictionary dari audio projector.

audio_token_index (`int`, *opsional*, defaultnya `49155`) : Indeks token audio yang digunakan sebagai placeholder untuk audio input.

initializer_range (`float`, *opsional*, defaultnya `0.02`) : Deviasi standar dari truncated_normal_initializer untuk menginisialisasi semua matriks bobot.

has_lora_adapter (`bool`, *opsional*, defaultnya `True`) : Menunjukkan apakah model memiliki adapter lora yang hanya harus diaktifkan saat memproses input audio.

downsample_rate (`int`, *opsional*, default 5) : Tingkat downsample untuk ekstraktor fitur audio.

window_size (`int`, *opsional*, default 15) : Ukuran jendela untuk proyektor fitur audio.

tie_word_embeddings (`bool`, *opsional*, defaultnya `True`) : Apakah mengikat embedding bobot sesuai dengan pemetaan `tied_weights_keys` model.

Ini adalah kelas konfigurasi untuk menyimpan konfigurasi dari GraniteSpeechModel. Kelas ini digunakan untuk menginstansiasi model Granite Speech sesuai dengan argumen yang ditentukan, sehingga mendefinisikan arsitektur model. Menginstansiasi konfigurasi dengan nilai bawaan akan menghasilkan konfigurasi yang serupa dengan konfigurasi dari [ibm-granite/granite-speech-3.3-2b](https://huggingface.co/ibm-granite/granite-speech-3.3-2b)

Objek konfigurasi mewarisi dari [PreTrainedConfig](/docs/transformers/main/id/main_classes/configuration#transformers.PreTrainedConfig) dan dapat digunakan untuk mengontrol keluaran model. Baca dokumentasi dari [PreTrainedConfig](/docs/transformers/main/id/main_classes/configuration#transformers.PreTrainedConfig) untuk informasi lebih lanjut.

Contoh:

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

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

**Parameter:**

input_dim (`int`, *opsional*, defaultnya `160`) : Dimensi dari fitur akustik input (misalnya, jumlah kanal mel-filterbank).

num_layers (`int`, *opsional*, defaultnya `10`) : Jumlah lapisan tersembunyi dalam decoder Transformer.

hidden_dim (`int`, *opsional*, defaultnya `1024`) : Dimensi dari representasi tersembunyi.

feedforward_mult (`int`, *opsional*, default 4) : Pengali untuk proyeksi up/down pada lapisan feedforward encoder; Proyeksi akan memiliki dimensi antara sebesar `hidden_dim * feedforward_mult`.

num_heads (`int`, *opsional*, defaultnya `8`) : Jumlah kepala perhatian untuk setiap lapisan perhatian dalam decoder Transformer.

dim_head (`int`, *opsional*) : Dimensi kepala perhatian. Jika None, nilainya akan secara default menjadi hidden_size // num_attention_heads

output_dim (`int`, *opsional*, default 42) : Dimensi menengah dari proyeksi feedforward dalam conformer yang akan ditambahkan ke output setiap blok encoder lainnya.

context_size (`int`, *opsional*, default 200) : Ukuran konteks yang akan digunakan dalam perhatian conformer.

max_pos_emb (`int`, *opsional*, default 512) : Jumlah maksimum pos embeds yang digunakan dalam attention (shaw's relative positional encoding).

dropout (`Union[float, int]`, *opsional*, defaultnya `0.1`) : Rasio untuk semua lapisan dropout.

conv_kernel_size (`int`, *opsional*, defaultnya `15`) : Ukuran kernel konvolusional.

conv_expansion_factor (`int`, *opsional*, defaultnya 2) : Dimensi antara yang akan digunakan dalam konvolusi conformer.

Ini adalah kelas konfigurasi untuk menyimpan konfigurasi dari GraniteSpeechModel. Kelas ini digunakan untuk menginstansiasi model Granite Speech sesuai dengan argumen yang ditentukan, sehingga mendefinisikan arsitektur model. Menginstansiasi konfigurasi dengan nilai bawaan akan menghasilkan konfigurasi yang serupa dengan konfigurasi dari [ibm-granite/granite-speech-3.3-2b](https://huggingface.co/ibm-granite/granite-speech-3.3-2b)

Objek konfigurasi mewarisi dari [PreTrainedConfig](/docs/transformers/main/id/main_classes/configuration#transformers.PreTrainedConfig) dan dapat digunakan untuk mengontrol keluaran model. Baca dokumentasi dari [PreTrainedConfig](/docs/transformers/main/id/main_classes/configuration#transformers.PreTrainedConfig) untuk informasi lebih lanjut.

Contoh:

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

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

**Parameter:**

audio_processor (`{audio_processor_class}`) : Pemroses audio adalah input yang wajib.

tokenizer (`tokenizer_class`) : Tokenizer adalah input yang wajib.

audio_token (`str`, *opsional*, defaultnya `"<|audio|>"`) : Token khusus yang digunakan untuk merepresentasikan audio dalam urutan teks. Token ini berfungsi sebagai placeholder yang akan diganti dengan beberapa token audio berdasarkan panjang audio sebenarnya. Jumlah token audio yang disisipkan bergantung pada dimensi fitur audio yang diekstrak oleh pemroses audio.

chat_template (`str`) : Template Jinja untuk mengonversi daftar pesan dalam chat menjadi string yang dapat ditokenisasi.

Membangun GraniteSpeechProcessor yang membungkus audio processor dan tokenizer menjadi satu processor.

[GraniteSpeechProcessor](/docs/transformers/main/id/model_doc/granite_speech#transformers.GraniteSpeechProcessor) menyediakan semua fungsionalitas dari `{audio_processor_class}` dan `tokenizer_class`. Lihat `~{audio_processor_class}` dan `~tokenizer_class` untuk informasi lebih lanjut.

#### __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'>)
```

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

**Parameter:**

text (`Union[str, list[str], list[list[str]]]`) : Urutan atau batch dari urutan yang akan dienkod. Setiap urutan dapat berupa string atau daftar string (string pretokenized). Jika Anda memasukkan input pretokenized, setel `is_split_into_words=True` untuk menghindari ambiguitas dengan input batched.

audio (`Union[numpy.ndarray, torch.Tensor, collections.abc.Sequence[numpy.ndarray], collections.abc.Sequence[torch.Tensor]]`, *opsional*) : Audio atau batch audio yang akan disiapkan. Setiap audio dapat berupa array NumPy atau tensor PyTorch. Jika berupa array NumPy/tensor PyTorch, setiap audio harus memiliki bentuk (C, T), di mana C adalah jumlah channel, dan T adalah panjang sampel audio.

device (`str`, *opsional*, defaultnya `cpu`) : Perangkat untuk memproses video. Jika tidak disetel, perangkat akan disimpulkan dari video input.

return_tensors (`str` atau [TensorType](/docs/transformers/main/id/internal/file_utils#transformers.TensorType), *opsional*) : Jika diatur, akan mengembalikan tensor dari framework tertentu. Nilai yang dapat diterima adalah:  - `'pt'`: Mengembalikan objek `torch.Tensor` PyTorch. - `'np'`: Mengembalikan objek `np.ndarray` NumPy.

- ****kwargs** ([ProcessingKwargs](/docs/transformers/main/id/main_classes/processors#transformers.ProcessingKwargs), *opsional*) : Opsi pemrosesan tambahan untuk setiap modalitas (teks, gambar, video, audio). Parameter spesifik model tercantum di atas; lihat kelas TypedDict untuk daftar lengkap argumen yang didukung.

**Mengembalikan:** `~feature_extraction_utils.BatchFeature`

- **data** (`dict`, *opsional*) -- Kamus berisi daftar/array/tensor yang dikembalikan oleh metode __call__/pad ('input_values', 'attention_mask', dll.).
- **tensor_type** (`Union[None, str, TensorType]`, *opsional*) -- Anda dapat memberikan tensor_type di sini untuk mengonversi daftar bilangan bulat menjadi Tensor PyTorch/Numpy saat inisialisasi.
- **skip_tensor_conversion** (`list[str]` atau `set[str]`, *opsional*) -- Daftar atau himpunan kunci yang TIDAK boleh dikonversi menjadi tensor, bahkan ketika `tensor_type` ditentukan.

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

[Sumber](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)
```

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

**Parameter:**

config ([GraniteSpeechConfig](/docs/transformers/main/id/model_doc/granite_speech#transformers.GraniteSpeechConfig)) : Kelas konfigurasi model dengan semua parameter model. Inisialisasi dengan file konfigurasi tidak memuat bobot yang terkait dengan model, hanya konfigurasinya. Lihat metode [from_pretrained()](/docs/transformers/main/id/main_classes/model#transformers.PreTrainedModel.from_pretrained) untuk memuat bobot model.

Model Granite Speech, yang terdiri dari encoder audio, projector, dan model bahasa, tanpa kepala pemodelan bahasa.

Model ini mewarisi dari [PreTrainedModel](/docs/transformers/main/id/main_classes/model#transformers.PreTrainedModel). Periksa dokumentasi kelas induk untuk metode generik yang diimplementasikan oleh pustaka ini untuk semua model (seperti mengunduh atau menyimpan, mengubah ukuran input embeddings, memangkas heads, dll.)

Model ini juga merupakan subclass dari [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) PyTorch. Gunakan sebagai PyTorch Module biasa dan merujuk ke dokumentasi PyTorch untuk semua hal yang berkaitan dengan penggunaan dan perilaku umum.

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

[Sumber](https://github.com/huggingface/transformers/blob/main/src/transformers/models/granite_speech/modeling_granite_speech.py#L424)

**Parameter:**

input_ids (`torch.LongTensor` dengan bentuk `(batch_size, sequence_length)`, *opsional*) : Indeks token dari urutan input dalam kosakata. Padding akan diabaikan secara default. Indeks dapat diperoleh menggunakan [AutoTokenizer](/docs/transformers/main/id/model_doc/auto#transformers.AutoTokenizer). Lihat [PreTrainedTokenizer.encode()](/docs/transformers/main/id/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) dan [PreTrainedTokenizer.__call__()](/docs/transformers/main/id/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) untuk detailnya. [Apa itu input IDs?](../glossary#input-ids)

input_features (`torch.Tensor` dengan bentuk `(batch_size, sequence_length, feature_dim)`, *opsional*) : Tensor yang sesuai dengan fitur audio input. Fitur audio dapat diperoleh menggunakan [GraniteSpeechFeatureExtractor](/docs/transformers/main/id/model_doc/granite_speech#transformers.GraniteSpeechFeatureExtractor). Lihat `GraniteSpeechFeatureExtractor.__call__()` untuk detailnya ([GraniteSpeechProcessor](/docs/transformers/main/id/model_doc/granite_speech#transformers.GraniteSpeechProcessor) menggunakan [GraniteSpeechFeatureExtractor](/docs/transformers/main/id/model_doc/granite_speech#transformers.GraniteSpeechFeatureExtractor) untuk memproses audio).

input_features_mask (`torch.Tensor`, *opsional*) : Mask yang akan diterapkan pada fitur audio sebelum disebarkan ke dalam embedding bahasa.

attention_mask (`torch.Tensor` dengan bentuk `(batch_size, sequence_length)`, *opsional*) : Mask untuk menghindari pelaksanaan attention pada indeks token padding. Nilai mask dipilih dalam `[0, 1]`:  - 1 untuk token yang **tidak di-mask**, - 0 untuk token yang **di-mask**.  [Apa itu attention masks?](../glossary#attention-mask)

position_ids (`torch.LongTensor` dengan bentuk `(batch_size, sequence_length)`, *opsional*) : Indeks posisi token dari setiap urutan input dalam embedding posisi. Dipilih dalam rentang `[0, config.n_positions - 1]`.  [Apa itu position ID?](../glossary#position-ids)

past_key_values (`~cache_utils.Cache`, *opsional*) : Hidden-states yang telah dihitung sebelumnya (key dan values di blok self-attention dan di blok cross-attention) yang dapat digunakan untuk mempercepat decoding berurutan. Ini biasanya terdiri dari `past_key_values` yang dikembalikan oleh model pada tahap decoding sebelumnya, ketika `use_cache=True` atau `config.use_cache=True`. Hanya instance [Cache](/docs/transformers/main/id/internal/generation_utils#transformers.Cache) yang diizinkan sebagai input, lihat [panduan kv cache](https://huggingface.co/docs/transformers/en/kv_cache) kami. Jika tidak ada `past_key_values` yang diteruskan, [DynamicCache](/docs/transformers/main/id/internal/generation_utils#transformers.DynamicCache) akan diinisialisasi secara default. Model akan mengoutput format cache yang sama dengan yang diberikan sebagai input. Jika `past_key_values` digunakan, pengguna diharapkan untuk hanya menginput `input_ids` yang belum diproses (yang tidak memiliki state past key value mereka diberikan ke model ini) dengan bentuk `(batch_size, unprocessed_length)` alih-alih semua `input_ids` dengan bentuk `(batch_size, sequence_length)`.

inputs_embeds (`torch.Tensor` dengan bentuk `(batch_size, sequence_length, hidden_size)`, *opsional*) : Secara opsional, alih-alih meneruskan `input_ids`, Anda dapat memilih untuk langsung meneruskan representasi tertanam. Ini berguna jika Anda ingin lebih banyak kendali atas cara mengonversi indeks `input_ids` menjadi vektor terkait daripada matriks pencarian penanaman internal model.

use_cache (`bool`, *opsional*) : Jika diatur ke `True`, state kunci-nilai `past_key_values` akan dikembalikan dan dapat digunakan untuk mempercepat decoding (lihat `past_key_values`).

**Mengembalikan:** `GraniteSpeechModelOutputWithPast` atau `tuple(torch.Tensor)`

Sebuah `GraniteSpeechModelOutputWithPast` atau tuple dari `torch.Tensor` (jika `return_dict=False` diteruskan atau ketika `config.return_dict=False`) yang terdiri dari berbagai elemen tergantung pada konfigurasi ([GraniteSpeechConfig](/docs/transformers/main/id/model_doc/granite_speech#transformers.GraniteSpeechConfig)) dan input.

Metode forward dari [GraniteSpeechModel](/docs/transformers/main/id/model_doc/granite_speech#transformers.GraniteSpeechModel) menimpa metode khusus `__call__`.

Meskipun resep untuk forward pass perlu didefinisikan di dalam fungsi ini, sebaiknya panggil instance `Module` setelahnya alih-alih fungsi ini, karena yang pertama menangani langkah-langkah pra-pemrosesan dan pasca-pemrosesan, sedangkan yang kedua mengabaikannya secara diam-diam.

- **last_hidden_state** (`torch.Tensor` dengan bentuk `(batch_size, sequence_length, hidden_size)`) -- Urutan hidden-states pada keluaran lapisan terakhir model.

  Jika `past_key_values` digunakan, hanya hidden-state terakhir dari sekuens dengan bentuk `(batch_size, 1, hidden_size)` yang dioutput.
- **past_key_values** (`Cache`, *opsional*, dikembalikan saat `use_cache=True` dilewatkan atau saat `config.use_cache=True`) -- Ini adalah instance [Cache](/docs/transformers/main/id/internal/generation_utils#transformers.Cache). Untuk detail lebih lanjut, lihat [panduan kv cache](https://huggingface.co/docs/transformers/en/kv_cache) kami.

  Berisi hidden-states yang telah dihitung sebelumnya (key dan values di blok self-attention, dan secara opsional jika `config.is_encoder_decoder=True` di blok cross-attention) yang dapat digunakan (lihat input `past_key_values`) untuk mempercepat decoding berurutan.
- **hidden_states** (`tuple(torch.Tensor)`, *opsional*, dikembalikan saat `output_hidden_states=True` dilewatkan atau saat `config.output_hidden_states=True`) -- Tuple dari `torch.Tensor` (satu untuk output dari embeddings, jika model memiliki lapisan embedding, + satu untuk output dari setiap lapisan) dengan bentuk `(batch_size, sequence_length, hidden_size)`.

  Hidden-states model pada output setiap layer ditambah output embedding awal yang opsional.
- **attentions** (`tuple(torch.Tensor)`, *opsional*, dikembalikan ketika `output_attentions=True` dilewatkan atau ketika `config.output_attentions=True`) -- Tuple dari `torch.Tensor` (satu untuk setiap layer) dengan bentuk `(batch_size, num_heads, sequence_length, sequence_length)`.

  Bobot perhatian setelah softmax perhatian, digunakan untuk menghitung rata-rata berbobot di kepala self-attention.
- **audio_hidden_states** (`torch.Tensor`, *opsional*) -- Hidden states audio yang diproyeksikan.

## GraniteSpeechForConditionalGeneration[[transformers.GraniteSpeechForConditionalGeneration]]

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

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

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

**Parameter:**

config ([GraniteSpeechConfig](/docs/transformers/main/id/model_doc/granite_speech#transformers.GraniteSpeechConfig)) : Kelas konfigurasi model dengan semua parameter model. Inisialisasi dengan file konfigurasi tidak memuat bobot yang terkait dengan model, hanya konfigurasinya. Lihat metode [from_pretrained()](/docs/transformers/main/id/main_classes/model#transformers.PreTrainedModel.from_pretrained) untuk memuat bobot model.

Model Granite Speech, yang terdiri dari encoder audio, projector, dan model bahasa.

Model ini mewarisi dari [PreTrainedModel](/docs/transformers/main/id/main_classes/model#transformers.PreTrainedModel). Periksa dokumentasi kelas induk untuk metode generik yang diimplementasikan oleh pustaka ini untuk semua model (seperti mengunduh atau menyimpan, mengubah ukuran input embeddings, memangkas heads, dll.)

Model ini juga merupakan subclass dari [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) PyTorch. Gunakan sebagai PyTorch Module biasa dan merujuk ke dokumentasi PyTorch untuk semua hal yang berkaitan dengan penggunaan dan perilaku umum.

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

[Sumber](https://github.com/huggingface/transformers/blob/main/src/transformers/models/granite_speech/modeling_granite_speech.py#L518)

**Parameter:**

input_ids (`torch.LongTensor` dengan bentuk `(batch_size, sequence_length)`, *opsional*) : Indeks token dari urutan input dalam kosakata. Padding akan diabaikan secara default. Indeks dapat diperoleh menggunakan [AutoTokenizer](/docs/transformers/main/id/model_doc/auto#transformers.AutoTokenizer). Lihat [PreTrainedTokenizer.encode()](/docs/transformers/main/id/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) dan [PreTrainedTokenizer.__call__()](/docs/transformers/main/id/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) untuk detailnya. [Apa itu input IDs?](../glossary#input-ids)

input_features (`torch.Tensor` dengan bentuk `(batch_size, sequence_length, feature_dim)`, *opsional*) : Tensor yang sesuai dengan fitur audio input. Fitur audio dapat diperoleh menggunakan [GraniteSpeechFeatureExtractor](/docs/transformers/main/id/model_doc/granite_speech#transformers.GraniteSpeechFeatureExtractor). Lihat `GraniteSpeechFeatureExtractor.__call__()` untuk detailnya ([GraniteSpeechProcessor](/docs/transformers/main/id/model_doc/granite_speech#transformers.GraniteSpeechProcessor) menggunakan [GraniteSpeechFeatureExtractor](/docs/transformers/main/id/model_doc/granite_speech#transformers.GraniteSpeechFeatureExtractor) untuk memproses audio).

input_features_mask (`torch.Tensor`, *opsional*) : Mask yang akan diterapkan pada fitur audio sebelum disebarkan ke dalam embedding bahasa.

attention_mask (`torch.Tensor` dengan bentuk `(batch_size, sequence_length)`, *opsional*) : Mask untuk menghindari pelaksanaan attention pada indeks token padding. Nilai mask dipilih dalam `[0, 1]`:  - 1 untuk token yang **tidak di-mask**, - 0 untuk token yang **di-mask**.  [Apa itu attention masks?](../glossary#attention-mask)

position_ids (`torch.LongTensor` dengan bentuk `(batch_size, sequence_length)`, *opsional*) : Indeks posisi token dari setiap urutan input dalam embedding posisi. Dipilih dalam rentang `[0, config.n_positions - 1]`.  [Apa itu position ID?](../glossary#position-ids)

past_key_values (`~cache_utils.Cache`, *opsional*) : Hidden-states yang telah dihitung sebelumnya (key dan values di blok self-attention dan di blok cross-attention) yang dapat digunakan untuk mempercepat decoding berurutan. Ini biasanya terdiri dari `past_key_values` yang dikembalikan oleh model pada tahap decoding sebelumnya, ketika `use_cache=True` atau `config.use_cache=True`. Hanya instance [Cache](/docs/transformers/main/id/internal/generation_utils#transformers.Cache) yang diizinkan sebagai input, lihat [panduan kv cache](https://huggingface.co/docs/transformers/en/kv_cache) kami. Jika tidak ada `past_key_values` yang diteruskan, [DynamicCache](/docs/transformers/main/id/internal/generation_utils#transformers.DynamicCache) akan diinisialisasi secara default. Model akan mengoutput format cache yang sama dengan yang diberikan sebagai input. Jika `past_key_values` digunakan, pengguna diharapkan untuk hanya menginput `input_ids` yang belum diproses (yang tidak memiliki state past key value mereka diberikan ke model ini) dengan bentuk `(batch_size, unprocessed_length)` alih-alih semua `input_ids` dengan bentuk `(batch_size, sequence_length)`.

inputs_embeds (`torch.Tensor` dengan bentuk `(batch_size, sequence_length, hidden_size)`, *opsional*) : Secara opsional, alih-alih meneruskan `input_ids`, Anda dapat memilih untuk langsung meneruskan representasi tertanam. Ini berguna jika Anda ingin lebih banyak kendali atas cara mengonversi indeks `input_ids` menjadi vektor terkait daripada matriks pencarian penanaman internal model.

labels (`torch.LongTensor` dengan bentuk `(batch_size, sequence_length)`, *opsional*) : Label untuk menghitung kerugian pemodelan bahasa yang disamarkan. Indeks harus berada di `[0, ..., config.vocab_size]` atau -100 (lihat docstring `input_ids`). Token dengan indeks yang disetel ke `-100` diabaikan (disamarkan), kerugian hanya dihitung untuk token dengan label di `[0, ..., config.vocab_size]`.

use_cache (`bool`, *opsional*) : Jika diatur ke `True`, state kunci-nilai `past_key_values` akan dikembalikan dan dapat digunakan untuk mempercepat decoding (lihat `past_key_values`).

logits_to_keep (`Union[int, torch.Tensor]`, *opsional*, defaultnya `0`) : Jika berupa `int`, hitung logits untuk `logits_to_keep` token terakhir. Jika `0`, hitung logits untuk semua `input_ids` (kasus khusus). Hanya logits token terakhir yang diperlukan untuk generasi, dan menghitungnya hanya untuk token tersebut dapat menghemat memori, yang menjadi cukup signifikan untuk urutan panjang atau ukuran kosakata besar. Jika berupa `torch.Tensor`, harus 1D yang sesuai dengan indeks yang akan dipertahankan pada dimensi panjang urutan. Ini berguna saat menggunakan format tensor terpadu (satu dimensi untuk batch dan panjang urutan).

**Mengembalikan:** `GraniteSpeechCausalLMOutputWithPast` atau `tuple(torch.Tensor)`

A `GraniteSpeechCausalLMOutputWithPast` atau tuple dari `torch.Tensor` (jika `return_dict=False` dilewatkan atau ketika `config.return_dict=False`) yang terdiri dari berbagai elemen tergantung pada konfigurasi ([GraniteSpeechConfig](/docs/transformers/main/id/model_doc/granite_speech#transformers.GraniteSpeechConfig)) dan input.

Metode forward dari [GraniteSpeechForConditionalGeneration](/docs/transformers/main/id/model_doc/granite_speech#transformers.GraniteSpeechForConditionalGeneration) menimpa metode khusus `__call__`.

Meskipun resep untuk forward pass perlu didefinisikan di dalam fungsi ini, sebaiknya panggil instance `Module` setelahnya alih-alih fungsi ini, karena yang pertama menangani langkah-langkah pra-pemrosesan dan pasca-pemrosesan, sedangkan yang kedua mengabaikannya secara diam-diam.

- **loss** (`torch.Tensor` dengan bentuk `(1,)`, *opsional*, dikembalikan saat `labels` disediakan) -- Loss pemodelan bahasa (untuk prediksi token berikutnya).
- **logits** (`torch.Tensor` dengan bentuk `(batch_size, sequence_length, config.vocab_size)`) -- Skor prediksi dari kepala pemodelan bahasa (skor untuk setiap token kosakata sebelum SoftMax).
- **past_key_values** (`Cache`, *opsional*, dikembalikan saat `use_cache=True` dilewatkan atau saat `config.use_cache=True`) -- Ini adalah instance [Cache](/docs/transformers/main/id/internal/generation_utils#transformers.Cache). Untuk detail lebih lanjut, lihat [panduan kv cache](https://huggingface.co/docs/transformers/en/kv_cache) kami.

  Berisi hidden-states yang telah dihitung sebelumnya (key dan values di blok self-attention) yang dapat digunakan (lihat input `past_key_values`) untuk mempercepat decoding berurutan.
- **hidden_states** (`tuple[torch.Tensor]`, *opsional*, dikembalikan ketika `output_hidden_states=True` dilewatkan atau ketika `config.output_hidden_states=True`) -- Tuple dari `torch.Tensor` (satu untuk output dari embeddings, jika model memiliki lapisan embedding, + satu untuk output dari setiap lapisan) dengan bentuk `(batch_size, sequence_length, hidden_size)`.

  Hidden-states model pada output setiap layer ditambah output embedding awal yang opsional.
- **attentions** (`tuple[torch.Tensor]`, *opsional*, dikembalikan ketika `output_attentions=True` dilewatkan atau ketika `config.output_attentions=True`) -- Tuple dari `torch.Tensor` (satu untuk setiap layer) dengan bentuk `(batch_size, num_heads, sequence_length, sequence_length)`.

  Bobot perhatian setelah softmax perhatian, digunakan untuk menghitung rata-rata berbobot di kepala self-attention.
- **audio_hidden_states** (`torch.Tensor`, *opsional*) -- Hidden states audio yang diproyeksikan.

Contoh:

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

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