# Granite Speech Plus

## 개요

Granite Speech Plus는 [Granite Speech](./granite_speech)의 변형으로, projector가 인코더의 최종 hidden states와 중간 hidden states의 임의의 부분집합을 feature 차원 방향으로 연결(concatenate)한 값을 입력으로 사용합니다. 선택된 중간 레이어는 [GraniteSpeechPlusEncoderConfig](/docs/transformers/main/ko/model_doc/granite_speech_plus#transformers.GraniteSpeechPlusEncoderConfig)의 `cat_hidden_layers` config 필드로 제어됩니다. 이 값이 `None`인 경우 모델은 Granite Speech와 동일하게 동작합니다. 값이 설정된 경우, projector의 `encoder_hidden_size`는 `encoder_config.hidden_dim * (len(cat_hidden_layers) + 1)`과 같아야 합니다.

나머지 아키텍처 — 음성 인코더, 쿼리 트랜스포머 프로젝터, 언어 모델, 선택적 LoRA 어댑터 — 은 Granite Speech에서 변경 없이 상속됩니다. 사용 예제는 [Granite Speech 문서](./granite_speech)를 참고하세요. 여기서는 동일한 [GraniteSpeechProcessor](/docs/transformers/main/ko/model_doc/granite_speech#transformers.GraniteSpeechProcessor)와 [GraniteSpeechFeatureExtractor](/docs/transformers/main/ko/model_doc/granite_speech#transformers.GraniteSpeechFeatureExtractor)가 사용됩니다.

## 사용

Granite Speech Plus는 텍스트 프롬프트에 응답하여 오디오를 전사하고 화자 주석 및 단어 수준 타임스탬프를 제공하는 멀티모달 음성-텍스트 변환 모델입니다. 각 기능을 사용하는 방법은 다음과 같습니다:

**설정** — 모델과 테스트 오디오 클립을 로드합니다:

```python
import re
import torch
from datasets import Audio, load_dataset
from transformers import AutoModelForSpeechSeq2Seq, AutoProcessor

SAMPLE_RATE = 16000
MODEL_NAME = "ibm-granite/granite-speech-4.1-2b-plus"
```

각 다른 작업에 사용되는 프롬프트를 정의합니다:

```python
SYSTEM_PROMPT = "Knowledge Cutoff Date: April 2024.\nToday's Date: December 19, 2024.\nYou are Granite, developed by IBM. You are a helpful AI assistant"
ASR_PROMPT = "<|audio|> can you transcribe the speech into a written format?"
SAA_PROMPT = "<|audio|> Speaker attribution: Transcribe and denote who is speaking by adding [Speaker 1]: and [Speaker 2]: tags before speaker turns."
TS_PROMPT = "<|audio|> Timestamps: Transcribe the speech. After each word, add a timestamp tag showing the end time in centiseconds, e.g. hello [T:45] world [T:82]"
```

모델을 로드하고 오디오를 디코딩하는 일반 함수를 정의합니다:

```python
processor = AutoProcessor.from_pretrained(MODEL_NAME)
model = AutoModelForSpeechSeq2Seq.from_pretrained(MODEL_NAME, device_map="auto")

@torch.inference_mode()
def transcribe(audio, prompt, max_new_tokens=2000, prefix_text=None):
    chat = [{"role": "system", "content": SYSTEM_PROMPT}, {"role": "user", "content": prompt}]
    extra = {"prefix_text": prefix_text} if prefix_text is not None else {}
    prompt_text = processor.apply_chat_template(chat, tokenize=False, add_generation_prompt=True, **extra)
    inputs = processor(prompt_text, audio, device=device, return_tensors="pt").to(device)
    outputs = model.generate(**inputs, max_new_tokens=max_new_tokens, do_sample=False, num_beams=1)
    new_tokens = outputs[0, inputs["input_ids"].shape[-1]:]
    output_text = processor.decode(new_tokens, add_special_tokens=False, skip_special_tokens=True)
    return output_text
```

AMI 데이터셋에서 예시 오디오 데이터를 로드합니다

```python
ds = load_dataset("diarizers-community/ami", "ihm", split="test")
ds = ds.cast_column("audio", Audio(sampling_rate=SAMPLE_RATE, num_channels=1))

TEST_SAMPLE = 0
START_TIME, END_TIME = 5 * 60, 6 * 60
audio = ds["audio"][TEST_SAMPLE].get_samples_played_in_range(START_TIME, END_TIME)
```

**작업 1: ASR** — 단순 음성-텍스트 변환:

```python
asr_text = transcribe(audio.data, ASR_PROMPT)
print(asr_text)
```

**작업 2: 화자 귀속 ASR** — 화자 라벨이 포함된 전사:

```python
saa_text = transcribe(audio.data, SAA_PROMPT)
for segment in re.split(r"(\[Speaker \d+\]:)", saa_text):
    print(segment.strip())
```

**작업 3: 단어별 타임스탬프** — 단어별 타이밍을 포함한 전사:

timestamps는 센티초 단위로 제공되며 1000(=10초)을 기준으로 모듈로 연산이 적용되므로, 10초의 배수를 추가하여 풀어줘야 합니다.

```python
ts_text = transcribe(audio.data, TS_PROMPT, max_new_tokens=10000)
ts_words = re.split(r"\[T:(\d+)\]", ts_text)
last_word_end_time = 0
offset_time = 0
for word, ts in zip(ts_words[::2], ts_words[1::2]):
    word_end_time = float(ts) / 100
    while word_end_time + offset_time < last_word_end_time:
        offset_time += 10
    last_word_end_time = word_end_time + offset_time
    print(f"{word}\t{last_word_end_time:.2f}s")
```

**작업 4: 증분 디코딩** — 오디오 컨텍스트를 누적하면서 세그먼트를 전사합니다:

```python
NUM_SEGMENTS = 3
previous_transcript = ""
all_audio = None

for k in range(NUM_SEGMENTS):
    t1 = START_TIME + (END_TIME - START_TIME) * k / NUM_SEGMENTS
    t2 = START_TIME + (END_TIME - START_TIME) * (k + 1) / NUM_SEGMENTS
    new_audio = ds["audio"][TEST_SAMPLE].get_samples_played_in_range(t1, t2)
    all_audio = new_audio.data if all_audio is None else torch.cat([all_audio, new_audio.data], dim=-1)
    saa_text = transcribe(all_audio, SAA_PROMPT, prefix_text=previous_transcript)
    print(f"{t1:06.2f}-{t2:06.2f}:\t{saa_text}")
    previous_transcript = (previous_transcript + " " + saa_text).strip()
```

## GraniteSpeechPlusConfig[[transformers.GraniteSpeechPlusConfig]]

#### transformers.GraniteSpeechPlusConfig[[transformers.GraniteSpeechPlusConfig]]

```python
transformers.GraniteSpeechPlusConfig(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_plus/configuration_granite_speech_plus.py#L95)

**매개변수:**

text_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`, *선택*) : 텍스트 백본의 config 객체 또는 사전입니다.

encoder_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`, *선택*) : 인코더 백본의 config 객체 또는 사전.

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`, *선택 사항*, 기본값 5) : 오디오 피처 추출기의 다운샘플링 비율입니다.

window_size (`int`, *선택 사항*, 기본값 15) : 오디오 특징 프로젝터의 윈도우 크기입니다.

tie_word_embeddings (`bool`, *선택 사항*, 기본값 `True`) : 모델의 `tied_weights_keys` 매핑에 따라 가중치 임베딩을 묶을지 여부.

이것은 GraniteSpeechPlusModel의 구성을 저장하기 위한 구성 클래스입니다. 지정된 인자에 따라 Granite Speech Plus 모델을 초기화하여 모델 아키텍처를 정의하는 데 사용됩니다. 기본값으로 구성을 초기화하면 [ibm-granite/granite-speech-4.1-2b-plus](https://huggingface.co/ibm-granite/granite-speech-4.1-2b-plus)와 유사한 구성이 생성됩니다.

Configuration 객체는 [PreTrainedConfig](/docs/transformers/main/ko/main_classes/configuration#transformers.PreTrainedConfig)를 상속하며, 모델 출력을 제어하는 데 사용할 수 있습니다. 자세한 내용은 [PreTrainedConfig](/docs/transformers/main/ko/main_classes/configuration#transformers.PreTrainedConfig)의 문서를 참고하세요.

예:

```python
>>> from transformers import GraniteSpeechPlusConfig, GraniteSpeechPlusForConditionalGeneration

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

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

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

## GraniteSpeechPlusEncoderConfig[[transformers.GraniteSpeechPlusEncoderConfig]]

#### transformers.GraniteSpeechPlusEncoderConfig[[transformers.GraniteSpeechPlusEncoderConfig]]

```python
transformers.GraniteSpeechPlusEncoderConfig(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, cat_hidden_layers: list[int] | None = None)
```

[소스](https://github.com/huggingface/transformers/blob/main/src/transformers/models/granite_speech_plus/configuration_granite_speech_plus.py#L29)

**매개변수:**

input_dim (*int*, *optional*, 기본값 *160*) : 입력 음향 특징의 차원(예: 멜 필터뱅크 채널 수).

num_layers (*int*, *optional*, 기본값 *10*) : Transformer 디코더의 숨겨진 레이어 수.

hidden_dim (*int*, *optional*, 기본값 *1024*) : 숨겨진 표현의 차원.

feedforward_mult (*int*, *optional*, 기본값 4) : 인코더의 피드포워드 레이어에서 업/다운 투영에 사용되는 배율; 투영의 중간 차원 크기는 *hidden_dim * feedforward_mult*입니다.

num_heads (*int*, *optional*, 기본값 *8*) : Transformer 디코더의 각 어텐션 레이어에 사용할 어텐션 헤드 수입니다.

dim_head (*int*, *optional*) : 어텐션 헤드 차원입니다. None인 경우 hidden_size // num_attention_heads 값이 기본값으로 사용됩니다.

output_dim (*int*, *optional*, 기본값 42) : conformer의 피드포워드 투영에서, 모든 짝수 인코더 블록의 출력에 추가될 중간 차원입니다.

context_size (*int*, *optional*, 기본값 200) : conformer attention에서 사용할 컨텍스트 크기입니다.

max_pos_emb (*int*, *optional*, 기본값 512) : attention에서 사용할 최대 위치 임베딩(shaw's relative positional encoding)

dropout (*Union[float, int]*, *선택 사항*, 기본값 *0.1*) : 모든 dropout 레이어의 비율입니다.

conv_kernel_size (*int*, *optional*, 기본값 *15*) : 컨볼루션 커널의 크기입니다.

conv_expansion_factor (*int*, *optional*, 기본값 2) : conformer 컨볼루션에서 사용할 중간 차원.

cat_hidden_layers (*list[int]*, *optional*) : 최종 인코더 출력으로 전달되기 전에, 해당 출력과 특징 차원(feature dimension)을 따라 연결(concatenate)되는 인코더 conformer 레이어의 인덱스입니다. 설정된 경우, projector의 `encoder_hidden_size`는 `encoder_config.hidden_dim * (len(cat_hidden_layers) + 1)`과 같아야 합니다.

이것은 GraniteSpeechPlusModel의 구성을 저장하기 위한 구성 클래스입니다. 지정된 인자에 따라 Granite Speech Plus 모델을 초기화하여 모델 아키텍처를 정의하는 데 사용됩니다. 기본값으로 구성을 초기화하면 [ibm-granite/granite-speech-4.1-2b-plus](https://huggingface.co/ibm-granite/granite-speech-4.1-2b-plus)와 유사한 구성이 생성됩니다.

Configuration 객체는 [*PreTrainedConfig*]에서 상속되며 모델 출력을 제어하는 데 사용할 수 있습니다. 자세한 내용은 [*PreTrainedConfig*]의 문서를 참고하세요.

예:

```python
>>> from transformers import GraniteSpeechPlusEncoderConfig, GraniteSpeechPlusCTCEncoder

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

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

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

## GraniteSpeechPlusModel[[transformers.GraniteSpeechPlusModel]]

#### transformers.GraniteSpeechPlusModel[[transformers.GraniteSpeechPlusModel]]

```python
transformers.GraniteSpeechPlusModel(config: GraniteSpeechPlusConfig)
```

[소스](https://github.com/huggingface/transformers/blob/main/src/transformers/models/granite_speech_plus/modeling_granite_speech_plus.py#L131)

**매개변수:**

config ([GraniteSpeechPlusConfig](/docs/transformers/main/ko/model_doc/granite_speech_plus#transformers.GraniteSpeechPlusConfig)) : 모델의 모든 매개변수를 포함하는 모델 구성 클래스입니다. 구성 파일로 초기화하는 것은 모델과 관련된 가중치를 로드하지 않으며, 구성 정보만 로드합니다. 모델 가중치를 로드하려면 [from_pretrained()](/docs/transformers/main/ko/main_classes/model#transformers.PreTrainedModel.from_pretrained) 메서드를 확인하세요.

언어 모델링 헤드가 없는 오디오 인코더, 프로젝터, 언어 모델로 구성된 Granite Speech 모델

이 모델은 [PreTrainedModel](/docs/transformers/main/ko/main_classes/model#transformers.PreTrainedModel)에서 상속됩니다. 라이브러리가 모든 모델에 대해 구현하는 일반적 메서드(다운로드 또는 저장, 입력 임베딩 크기 조정, 헤드 프루닝 등)에 대해서는 상위 클래스 문서를 확인하세요.

이 모델은 또한 PyTorch [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module)의 하위 클래스입니다. 일반적인 PyTorch Module처럼 사용하며, 일반적인 사용법과 동작에 관한 모든 사항은 PyTorch 문서를 참조하세요.

#### forward[[transformers.GraniteSpeechPlusModel.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_plus/modeling_granite_speech_plus.py#L204)

**매개변수:**

input_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : 어휘(input sequence tokens)의 인덱스입니다. 기본적으로 패딩은 무시됩니다. [AutoTokenizer](/docs/transformers/main/ko/model_doc/auto#transformers.AutoTokenizer)를 사용하여 인덱스를 얻을 수 있습니다. 자세한 내용은 [PreTrainedTokenizer.encode()](/docs/transformers/main/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 및 [PreTrainedTokenizer.__call__()](/docs/transformers/main/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)를 참조하세요. [입력 ID란 무엇인가요?](../glossary#input-ids)

input_features (`torch.Tensor`, shape `(batch_size, sequence_length, feature_dim)`, *선택 사항*) : 입력 오디오 특징에 해당하는 텐서입니다. 오디오 특징은 [GraniteSpeechFeatureExtractor](/docs/transformers/main/ko/model_doc/granite_speech#transformers.GraniteSpeechFeatureExtractor)를 사용하여 얻을 수 있습니다. 자세한 내용은 `GraniteSpeechFeatureExtractor.__call__()`를 참조하세요 ([GraniteSpeechProcessor](/docs/transformers/main/ko/model_doc/granite_speech#transformers.GraniteSpeechProcessor)는 오디오 처리에 [GraniteSpeechFeatureExtractor](/docs/transformers/main/ko/model_doc/granite_speech#transformers.GraniteSpeechFeatureExtractor)를 사용합니다).

input_features_mask (`torch.Tensor`, *선택 사항*) : 언어 임베딩으로 산란(scattering)하기 전에 오디오 특징에 적용할 마스크입니다.

attention_mask (`torch.Tensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : 패딩 토큰 인덱스에 대한 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(셀프 어텐션 블록과 크로스 어텐션 블록의 key 및 value)입니다. 일반적으로 `use_cache=True` 또는 `config.use_cache=True`일 때 모델이 디코딩의 이전 단계에서 반환한 `past_key_values`로 구성됩니다. 입력으로 [Cache](/docs/transformers/main/ko/internal/generation_utils#transformers.Cache) 인스턴스만 허용되며, [kv cache 가이드](https://huggingface.co/docs/transformers/en/kv_cache)를 참조하세요. `past_key_values`가 전달되지 않으면 기본적으로 [DynamicCache](/docs/transformers/main/ko/internal/generation_utils#transformers.DynamicCache)가 초기화됩니다. 모델은 입력으로 제공된 것과 동일한 캐시 형식을 출력합니다. `past_key_values`를 사용하는 경우, 이 모델에 과거 key value 상태가 제공되지 않은 `input_ids`(처리되지 않은 항목)만 `(batch_size, unprocessed_length)` 형식으로 입력해야 하며, `(batch_size, sequence_length)` 형식의 모든 `input_ids`를 입력하지 않습니다.

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` 참조).

**반환값:** `GraniteSpeechPlusModelOutputWithPast` 또는 `tuple(torch.Tensor)`

`GraniteSpeechPlusModelOutputWithPast` 또는 `return_dict=False`가 전달되거나 `config.return_dict=False`인 경우 `torch.Tensor`의 튜플로, [GraniteSpeechPlusConfig](/docs/transformers/main/ko/model_doc/granite_speech_plus#transformers.GraniteSpeechPlusConfig) 및 입력에 따라 다양한 요소를 포함합니다.

[GraniteSpeechPlusModel](/docs/transformers/main/ko/model_doc/granite_speech_plus#transformers.GraniteSpeechPlusModel)의 forward 메서드는 `__call__` 특수 메서드를 오버라이드합니다.

`Module` 인스턴스는 전처리 및 후처리 단계를 실행하는 것을 처리하지만, 이 함수는 해당 단계를 조용히 무시하므로, 순전파(forward pass) 레시피를 이 함수 내에서 정의해야 하더라도 이후에는 이 함수 대신 `Module` 인스턴스를 호출해야 합니다.

- **last_hidden_state** (`torch.Tensor`, shape `(batch_size, sequence_length, hidden_size)`) -- 모델의 마지막 레이어 출력에서 생성된 hidden-state 시퀀스입니다.

  `past_key_values`가 사용되면, `(batch_size, 1, hidden_size)` 형태의 시퀀스의 마지막 hidden-state만 출력됩니다.
- **past_key_values** (`Cache`, *선택 사항*, `use_cache=True`가 전달되었거나 `config.use_cache=True`인 경우 반환됨) -- [Cache](/docs/transformers/main/ko/internal/generation_utils#transformers.Cache) 인스턴스입니다. 자세한 내용은 [kv cache 가이드](https://huggingface.co/docs/transformers/en/kv_cache)를 참조하세요.

  순차적 디코딩을 가속화하는 데 사용할 수 있는 사전 계산된 hidden-states(셀프 어텐션 블록의 key와 value, 그리고 `config.is_encoder_decoder=True`인 경우 크로스 어텐션 블록의 key와 value)를 포함합니다(입력 `past_key_values` 참조).
- **hidden_states** (`tuple(torch.Tensor)`, *선택 사항*, `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)`, *선택 사항*, `output_attentions=True`가 전달되었거나 `config.output_attentions=True`인 경우 반환됨) -- 각 레이어마다 하나씩 포함된 `torch.Tensor`의 튜플로, 모양은 `(batch_size, num_heads, sequence_length, sequence_length)`입니다.

  self-attention 헤드에서 가중 평균을 계산하는 데 사용되는 attention softmax 이후의 attention 가중치입니다.
- **audio_hidden_states** (`torch.Tensor`, *선택 사항*) -- 투영된 오디오 히든 상태입니다.

## GraniteSpeechPlusForConditionalGeneration[[transformers.GraniteSpeechPlusForConditionalGeneration]]

#### transformers.GraniteSpeechPlusForConditionalGeneration[[transformers.GraniteSpeechPlusForConditionalGeneration]]

```python
transformers.GraniteSpeechPlusForConditionalGeneration(config: GraniteSpeechPlusConfig)
```

[소스](https://github.com/huggingface/transformers/blob/main/src/transformers/models/granite_speech_plus/modeling_granite_speech_plus.py#L517)

**매개변수:**

config ([GraniteSpeechPlusConfig](/docs/transformers/main/ko/model_doc/granite_speech_plus#transformers.GraniteSpeechPlusConfig)) : 모델의 모든 매개변수를 포함하는 모델 구성 클래스입니다. 구성 파일로 초기화하는 것은 모델과 관련된 가중치를 로드하지 않으며, 구성 정보만 로드합니다. 모델 가중치를 로드하려면 [from_pretrained()](/docs/transformers/main/ko/main_classes/model#transformers.PreTrainedModel.from_pretrained) 메서드를 확인하세요.

Granite Speech Plus 모델은 Granite Speech의 변형으로, projector가 인코더의 최종 hidden states와 그 중간 hidden states의 임의의 부분집합을 연결(concatenation)한 값을 입력으로 사용합니다.

이 모델은 [PreTrainedModel](/docs/transformers/main/ko/main_classes/model#transformers.PreTrainedModel)에서 상속됩니다. 라이브러리가 모든 모델에 대해 구현하는 일반적 메서드(다운로드 또는 저장, 입력 임베딩 크기 조정, 헤드 프루닝 등)에 대해서는 상위 클래스 문서를 확인하세요.

이 모델은 또한 PyTorch [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module)의 하위 클래스입니다. 일반적인 PyTorch Module처럼 사용하며, 일반적인 사용법과 동작에 관한 모든 사항은 PyTorch 문서를 참조하세요.

#### forward[[transformers.GraniteSpeechPlusForConditionalGeneration.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_plus/modeling_granite_speech_plus.py#L539)

**매개변수:**

input_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : 어휘(input sequence tokens)의 인덱스입니다. 기본적으로 패딩은 무시됩니다. [AutoTokenizer](/docs/transformers/main/ko/model_doc/auto#transformers.AutoTokenizer)를 사용하여 인덱스를 얻을 수 있습니다. 자세한 내용은 [PreTrainedTokenizer.encode()](/docs/transformers/main/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 및 [PreTrainedTokenizer.__call__()](/docs/transformers/main/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)를 참조하세요. [입력 ID란 무엇인가요?](../glossary#input-ids)

input_features (`torch.Tensor`, shape `(batch_size, sequence_length, feature_dim)`, *선택 사항*) : 입력 오디오 특징에 해당하는 텐서입니다. 오디오 특징은 [GraniteSpeechFeatureExtractor](/docs/transformers/main/ko/model_doc/granite_speech#transformers.GraniteSpeechFeatureExtractor)를 사용하여 얻을 수 있습니다. 자세한 내용은 `GraniteSpeechFeatureExtractor.__call__()`를 참조하세요 ([GraniteSpeechProcessor](/docs/transformers/main/ko/model_doc/granite_speech#transformers.GraniteSpeechProcessor)는 오디오 처리에 [GraniteSpeechFeatureExtractor](/docs/transformers/main/ko/model_doc/granite_speech#transformers.GraniteSpeechFeatureExtractor)를 사용합니다).

input_features_mask (`torch.Tensor`, *선택 사항*) : 언어 임베딩으로 산란(scattering)하기 전에 오디오 특징에 적용할 마스크입니다.

attention_mask (`torch.Tensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : 패딩 토큰 인덱스에 대한 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(셀프 어텐션 블록과 크로스 어텐션 블록의 key 및 value)입니다. 일반적으로 `use_cache=True` 또는 `config.use_cache=True`일 때 모델이 디코딩의 이전 단계에서 반환한 `past_key_values`로 구성됩니다. 입력으로 [Cache](/docs/transformers/main/ko/internal/generation_utils#transformers.Cache) 인스턴스만 허용되며, [kv cache 가이드](https://huggingface.co/docs/transformers/en/kv_cache)를 참조하세요. `past_key_values`가 전달되지 않으면 기본적으로 [DynamicCache](/docs/transformers/main/ko/internal/generation_utils#transformers.DynamicCache)가 초기화됩니다. 모델은 입력으로 제공된 것과 동일한 캐시 형식을 출력합니다. `past_key_values`를 사용하는 경우, 이 모델에 과거 key value 상태가 제공되지 않은 `input_ids`(처리되지 않은 항목)만 `(batch_size, unprocessed_length)` 형식으로 입력해야 하며, `(batch_size, sequence_length)` 형식의 모든 `input_ids`를 입력하지 않습니다.

inputs_embeds (`torch.Tensor`, shape `(batch_size, sequence_length, hidden_size)`, *선택 사항*) : `input_ids`를 전달하는 대신 임베디드 표현을 직접 전달할 수 있습니다. 이는 모델의 내부 임베딩 조회 행렬보다 `input_ids` 인덱스를 관련 벡터로 변환하는 방식에 대해 더 많은 제어가 필요한 경우 유용합니다.

labels (`torch.LongTensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : masked language modeling loss를 계산하기 위한 라벨. 인덱스는 `[0, ..., config.vocab_size]` 범위 내이거나 -100이어야 합니다(`input_ids` docstring 참조). 인덱스가 `-100`으로 설정된 토큰은 무시(마스크)되며, loss는 `[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차원 텐서여야 합니다. 이는 packed tensor 형식(배치와 시퀀스 길이를 단일 차원으로 사용하는 경우)을 사용할 때 유용합니다.

**반환값:** `GraniteSpeechPlusCausalLMOutputWithPast` 또는 `tuple(torch.Tensor)`

`GraniteSpeechPlusCausalLMOutputWithPast` 또는 `torch.Tensor`의 튜플(`return_dict=False`가 전달되거나 `config.return_dict=False`인 경우)로, 구성([GraniteSpeechPlusConfig](/docs/transformers/main/ko/model_doc/granite_speech_plus#transformers.GraniteSpeechPlusConfig))과 입력에 따라 다양한 요소를 포함합니다.

[GraniteSpeechPlusForConditionalGeneration](/docs/transformers/main/ko/model_doc/granite_speech_plus#transformers.GraniteSpeechPlusForConditionalGeneration)의 forward 메서드는 `__call__` 특수 메서드를 오버라이드합니다.

`Module` 인스턴스는 전처리 및 후처리 단계를 실행하는 것을 처리하지만, 이 함수는 해당 단계를 조용히 무시하므로, 순전파(forward pass) 레시피를 이 함수 내에서 정의해야 하더라도 이후에는 이 함수 대신 `Module` 인스턴스를 호출해야 합니다.

- **loss** (`torch.Tensor`, shape `(1,)`, *선택 사항*, `labels`가 제공될 때 반환됨) -- 언어 모델링 손실(다음 토큰 예측용).
- **logits** (`torch.Tensor`, shape `(batch_size, sequence_length, config.vocab_size)`) -- 언어 모델링 헤드에서 생성된 예측 점수(SoftMax 적용 전 각 어휘 토큰에 대한 점수).
- **past_key_values** (`Cache`, *선택 사항*, `use_cache=True`가 전달되었거나 `config.use_cache=True`인 경우 반환됨) -- [Cache](/docs/transformers/main/ko/internal/generation_utils#transformers.Cache) 인스턴스입니다. 자세한 내용은 [kv cache 가이드](https://huggingface.co/docs/transformers/en/kv_cache)를 참조하세요.

  순차적 디코딩을 가속화하는 데 사용할 수 있는 사전 계산된 hidden-states(셀프 어텐션 블록의 key와 value)를 포함합니다(입력 `past_key_values` 참조).
- **hidden_states** (`tuple[torch.Tensor]`, *선택*, `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]`, *선택*, `output_attentions=True`가 전달되었거나 `config.output_attentions=True`인 경우 반환됨) -- 각 레이어마다 하나씩 포함된 `torch.Tensor`의 튜플로, 모양은 `(batch_size, num_heads, sequence_length, sequence_length)`입니다.

  self-attention 헤드에서 가중 평균을 계산하는 데 사용되는 attention softmax 이후의 attention 가중치입니다.
- **audio_hidden_states** (`torch.Tensor`, *선택 사항*) -- 투영된 오디오 히든 상태입니다.

예:

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

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

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

[소스](https://github.com/huggingface/transformers/blob/main/src/transformers/models/granite_speech_plus/modeling_granite_speech_plus.py#L536)