# Speech2Text

## 개요

Speech2Text 모델은 Changhan Wang, Yun Tang, Xutai Ma, Anne Wu, Dmytro Okhonko, Juan Pino가 [fairseq S2T: Fast Speech-to-Text Modeling with fairseq](https://huggingface.co/papers/2010.05171)에서 제안했습니다. 이는 Transformer 기반의 seq2seq(인코더-디코더) 모델로, 끝에서 끝까지(Automatic Speech Recognition, ASR) 및 음성 번역(Speech Translation, ST)을 위해 설계되었습니다. 이 모델은 음성 입력을 인코더에 전달하기 전에 길이를 3/4로 줄이는 데 컨볼루션 다운샘플러를 사용합니다. 모델은 표준 자기 회귀 크로스 엔트로피 손실로 학습되며, 자기 회귀 방식으로 전사/번역 결과를 생성합니다. Speech2Text는 ASR과 ST를 위해 여러 데이터셋에서 미세 조정되었습니다: [LibriSpeech](http://www.openslr.org/12), [CoVoST 2](https://github.com/facebookresearch/covost), [MuST-C](https://ict.fbk.eu/must-c/).

이 모델은 [valhalla](https://huggingface.co/valhalla)에 의해 기여되었습니다. 원본 코드는 [여기](https://github.com/pytorch/fairseq/tree/master/examples/speech_to_text)에서 찾을 수 있습니다.

## 추론

Speech2Text는 음성 신호에서 추출된 log-mel filter-bank 특징의 float 텐서를 입력으로 받는 음성 모델입니다. transformer 기반의 seq2seq 모델이므로 전사/번역 결과는 자기회귀적으로 생성됩니다. 추론에는 `generate()` 메서드를 사용할 수 있습니다.

[Speech2TextFeatureExtractor](/docs/transformers/v5.23.0/ko/model_doc/speech_to_text#transformers.Speech2TextFeatureExtractor) 클래스는 log-mel 필터 뱅크 특징을 추출하는 역할을 합니다. [Speech2TextProcessor](/docs/transformers/v5.23.0/ko/model_doc/speech_to_text#transformers.Speech2TextProcessor)는 [Speech2TextFeatureExtractor](/docs/transformers/v5.23.0/ko/model_doc/speech_to_text#transformers.Speech2TextFeatureExtractor)와 [Speech2TextTokenizer](/docs/transformers/v5.23.0/ko/model_doc/speech_to_text#transformers.Speech2TextTokenizer)를 단일 인스턴스로 묶어 입력 특징을 추출하고 예측된 토큰 ID를 디코딩합니다.

feature extractor는 `torchaudio`에, tokenizer는 `sentencepiece`에 의존하므로 예제를 실행하기 전에 해당 패키지를 설치해야 합니다. `pip install transformers"[speech, sentencepiece]"`를 사용하여 추가 음성 의존성으로 설치하거나, `pip install torchaudio sentencepiece`를 사용하여 패키지를 개별적으로 설치할 수 있습니다. 또한 `torchaudio`는 시스템 패키지 관리자를 통해 설치할 수 있는 [libsndfile](http://www.mega-nerd.com/libsndfile/) 패키지의 개발 버전이 필요합니다. Ubuntu에서는 다음과 같이 설치할 수 있습니다: `apt install libsndfile1-dev`

- ASR 및 음성 번역

```python
from datasets import load_dataset

from transformers import Speech2TextForConditionalGeneration, Speech2TextProcessor

model = Speech2TextForConditionalGeneration.from_pretrained("facebook/s2t-small-librispeech-asr", device_map="auto")
processor = Speech2TextProcessor.from_pretrained("facebook/s2t-small-librispeech-asr")

ds = load_dataset("hf-internal-testing/librispeech_asr_demo", "clean", split="validation")

inputs = processor(ds[0]["audio"]["array"], sampling_rate=ds[0]["audio"]["sampling_rate"], return_tensors="pt").to(model.device)
generated_ids = model.generate(inputs["input_features"], attention_mask=inputs["attention_mask"])

transcription = processor.batch_decode(generated_ids, skip_special_tokens=True)
transcription
['mister quilter is the apostle of the middle classes and we are glad to welcome his gospel']
```

- 다국어 음성 번역

  다국어 음성 번역 모델의 경우, `eos_token_id`가 `decoder_start_token_id`로 사용되며, 대상 언어 id가 첫 번째 생성 토큰으로 강제됩니다. 대상 언어 id를 첫 번째 생성 토큰으로 강제하려면 `forced_bos_token_id` 매개변수를 `generate()` 메서드에 전달하세요. 다음 예제는 *facebook/s2t-medium-mustc-multilingual-st* 체크포인트를 사용하여 영어 음성을 프랑스어 텍스트로 번역하는 방법을 보여줍니다.

```python
from datasets import load_dataset

from transformers import Speech2TextForConditionalGeneration, Speech2TextProcessor

model = Speech2TextForConditionalGeneration.from_pretrained("facebook/s2t-medium-mustc-multilingual-st", device_map="auto")
processor = Speech2TextProcessor.from_pretrained("facebook/s2t-medium-mustc-multilingual-st")

ds = load_dataset("hf-internal-testing/librispeech_asr_demo", "clean", split="validation")

inputs = processor(ds[0]["audio"]["array"], sampling_rate=ds[0]["audio"]["sampling_rate"], return_tensors="pt").to(model.device)
generated_ids = model.generate(
    inputs["input_features"],
    attention_mask=inputs["attention_mask"],
    forced_bos_token_id=processor.tokenizer.lang_code_to_id["fr"],
)

translation = processor.batch_decode(generated_ids, skip_special_tokens=True)
translation
["(Vidéo) Si M. Kilder est l'apossible des classes moyennes, et nous sommes heureux d'être accueillis dans son évangile."]
```

Speech2Text 체크포인트를 찾으려면 [모델 허브](https://huggingface.co/models?filter=speech_to_text)를 확인하세요.

## Speech2TextConfig[[transformers.Speech2TextConfig]]

#### transformers.Speech2TextConfig[[transformers.Speech2TextConfig]]

```python
transformers.Speech2TextConfig(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, 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, is_encoder_decoder: bool = True, vocab_size: int = 10000, encoder_layers: int = 12, encoder_ffn_dim: int = 2048, encoder_attention_heads: int = 4, decoder_layers: int = 6, decoder_ffn_dim: int = 2048, decoder_attention_heads: int = 4, encoder_layerdrop: float | int = 0.0, decoder_layerdrop: float | int = 0.0, use_cache: bool = True, activation_function: str = 'relu', d_model: int = 256, dropout: float | int = 0.1, attention_dropout: float | int = 0.0, activation_dropout: float | int = 0.0, init_std: float = 0.02, decoder_start_token_id: int = 2, scale_embedding: bool = True, pad_token_id: int | None = 1, bos_token_id: int | None = 0, eos_token_id: int | list[int] | None = 2, max_source_positions: int = 6000, max_target_positions: int = 1024, num_conv_layers: int = 2, conv_kernel_sizes: list[int] | tuple[int, ...] = (5, 5), conv_channels: int = 1024, input_feat_per_channel: int = 80, input_channels: int = 1, tie_word_embeddings: bool = True)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/speech_to_text/configuration_speech_to_text.py#L24)

**매개변수:**

is_encoder_decoder (`bool`, *선택 사항*, 기본값 `True`) : 모델이 인코더/디코더로 사용되는지 여부.

vocab_size (`int`, *선택 사항*, 기본값 `10000`) : 모델의 어휘 크기입니다. `input_ids`로 표현할 수 있는 서로 다른 토큰의 수를 정의합니다.

encoder_layers (`int`, *선택 사항*, 기본값 `12`) : Transformer 인코더의 숨겨진 레이어 수입니다. 설정하지 않으면 `num_layers`와 동일한 값을 사용합니다.

encoder_ffn_dim (`int`, *선택 사항*, 기본값 `2048`) : 인코더의 "중간"(일반적으로 feed-forward라고도 함) 레이어의 차원.

encoder_attention_heads (`int`, *선택 사항*, 기본값 `4`) : Transformer 인코더의 각 어텐션 레이어에 사용할 어텐션 헤드 수입니다.

decoder_layers (`int`, *선택 사항*, 기본값 `6`) : Transformer decoder의 숨겨진 레이어 수입니다. 설정하지 않으면 `num_layers`와 동일한 값을 사용합니다.

decoder_ffn_dim (`int`, *선택 사항*, 기본값 `2048`) : 디코더의 "intermediate"(일반적으로 feed-forward라고도 함) 레이어의 차원.

decoder_attention_heads (`int`, *선택 사항*, 기본값 `4`) : Transformer 디코더의 각 어텐션 레이어에 사용할 어텐션 헤드 수입니다.

encoder_layerdrop (`Union[float, int]`, *선택 사항*, 기본값 `0.0`) : 인코더의 LayerDrop 확률입니다. 자세한 내용은 [LayerDrop 논문](see https://huggingface.co/papers/1909.11556)을 참고하세요.

decoder_layerdrop (`Union[float, int]`, *선택 사항*, 기본값 `0.0`) : 디코더의 LayerDrop 확률입니다. 자세한 내용은 [LayerDrop 논문](see https://huggingface.co/papers/1909.11556)을 참고하세요.

use_cache (`bool`, *선택 사항*, 기본값 `True`) : 모델이 마지막 key/values attention을 반환할지 여부입니다(모든 모델에서 사용되지 않음). `config.is_decoder=True`인 경우 또는 모델이 decoder-only 생성 모델인 경우에만 관련이 있습니다.

activation_function (`str`, *선택 사항*, 기본값 `relu`) : 디코더의 비선형 활성화 함수(함수 또는 문자열). 예를 들어, `"gelu"`, `"relu"`, `"silu"` 등.

d_model (`int`, *선택 사항*, 기본값 `256`) : 인코더 레이어와 풀러 레이어의 크기.

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

attention_dropout (`Union[float, int]`, *선택 사항*, 기본값 `0.0`) : attention 확률에 적용할 dropout 비율입니다.

activation_dropout (`Union[float, int]`, *선택 사항*, 기본값 `0.0`) : 완전 연결 계층 내부 활성화에 적용되는 dropout 비율입니다.

init_std (`float`, *선택 사항*, 기본값 `0.02`) : 모든 가중치 행렬을 초기화하는 truncated_normal_initializer의 표준 편차입니다.

decoder_start_token_id (`int`, *선택 사항*, 기본값 `2`) : 인코더-디코더 모델이 `bos`와 다른 토큰으로 디코딩을 시작하는 경우, 해당 토큰의 id입니다.

scale_embedding (`bool`, *선택 사항*, 기본값 `True`) : 임베딩을 sqrt(d_model)로 나누어 스케일링할지 여부.

pad_token_id (`int`, *선택 사항*, 기본값 `1`) : 어휘에서 패딩에 사용되는 토큰 ID입니다.

bos_token_id (`int`, *선택 사항*, 기본값 `0`) : 어휘에서 스트림 시작에 사용되는 토큰 ID입니다.

eos_token_id (`Union[int, list[int]]`, *선택*, 기본값 `2`) : 어휘에서 스트림 종료에 사용되는 토큰 ID입니다.

max_source_positions (`int`, *선택 사항*, 기본값 6000) : 이 모델이 사용될 수 있는 log-mel filter-bank 특징의 최대 시퀀스 길이입니다.

max_target_positions (`int`, *선택 사항*, 기본값 1024) : 이 모델이 사용될 수 있는 최대 시퀀스 길이입니다. 일반적으로 안전을 위해 큰 값으로 설정합니다(예: 512 또는 1024 또는 2048).

num_conv_layers (`int`, *선택 사항*, 기본값 2) : conv 모듈의 1D 컨볼루션 레이어 수.

conv_kernel_sizes (`tuple[int]`, *선택 사항*, 기본값 `(5, 5)`) : conv 모듈의 각 1D 컨볼루션 레이어의 커널 크기를 정의하는 정수 튜플입니다. `conv_kernel_sizes`의 길이는 `num_conv_layers`와 일치해야 합니다.

conv_channels (`int`, *선택 사항*, 기본값 1024) : conv 모듈의 마지막 레이어를 제외한 각 컨볼루션 레이어의 출력 채널 수를 정의하는 정수입니다.

input_feat_per_channel (`int`, *선택 사항*, 기본값 80) : 특징 벡터의 크기를 지정하는 정수입니다. 이는 또한 log-mel 필터 뱅크 특징의 차원입니다.

input_channels (`int`, *선택 사항*, 기본값 `1`) : 입력 채널의 수입니다.

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

이것은 Speech2TextModel의 구성을 저장하기 위한 구성 클래스입니다. 지정된 인자에 따라 Speech To Text 모델을 인스턴스화하여 모델 아키텍처를 정의하는 데 사용됩니다. 기본값으로 구성을 인스턴스화하면 [facebook/s2t-small-librispeech-asr](https://huggingface.co/facebook/s2t-small-librispeech-asr)와 유사한 구성이 생성됩니다.

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

예:

```python
>>> from transformers import Speech2TextConfig, Speech2TextModel

>>> # Initializing a Speech2Text s2t_transformer_s style configuration
>>> configuration = Speech2TextConfig()

>>> # Initializing a model (with random weights) from the s2t_transformer_s style configuration
>>> model = Speech2TextModel(configuration)

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

## Speech2TextTokenizer[[transformers.Speech2TextTokenizer]]

#### transformers.Speech2TextTokenizer[[transformers.Speech2TextTokenizer]]

```python
transformers.Speech2TextTokenizer(vocab_file, spm_file, bos_token = '<s>', eos_token = '</s>', pad_token = '<pad>', unk_token = '<unk>', do_upper_case = False, do_lower_case = False, tgt_lang = None, lang_codes = None, additional_special_tokens = None, sp_model_kwargs: dict[str, typing.Any] | None = None, **kwargs)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/speech_to_text/tokenization_speech_to_text.py#L49)

**매개변수:**

vocab_file (`str`) : 어휘를 포함하는 파일.

spm_file (`str`) : [SentencePiece](https://github.com/google/sentencepiece) 모델 파일의 경로

bos_token (`str`, *선택 사항*, 기본값 `"<s>"`) : 문장 시작 토큰입니다.

eos_token (`str`, *선택 사항*, 기본값 `"</s>"`) : 문장 종료 토큰입니다.

unk_token (`str`, *선택*, 기본값 `"<unk>"`) : 알 수 없는 토큰. 어휘에 없는 토큰은 ID로 변환할 수 없으므로 이 토큰으로 설정됩니다.

pad_token (`str`, *선택 사항*, 기본값 `"<pad>"`) : 패딩에 사용되는 토큰입니다. 예를 들어 길이가 다른 시퀀스를 배치할 때 사용됩니다.

do_upper_case (`bool`, *선택 사항*, 기본값 `False`) : 디코딩 시 출력을 대문자로 변환할지 여부.

do_lower_case (`bool`, *선택 사항*, 기본값 `False`) : 토큰화할 때 입력을 소문자로 변환할지 여부.

tgt_lang (`str`, *선택 사항*) : 대상 언어를 나타내는 문자열.

sp_model_kwargs (`dict`, *선택 사항*) : `SentencePieceProcessor.__init__()` 메서드에 전달됩니다. [SentencePiece의 Python 래퍼](https://github.com/google/sentencepiece/tree/master/python)는 다음을 설정하는 데 사용할 수 있습니다. - `enable_sampling`: 서브워드 정규화를 활성화합니다. - `nbest_size`: 유니그램의 샘플링 매개변수입니다. BPE-Dropout에는 적용되지 않습니다. - `nbest_size = {0,1}`: 샘플링이 수행되지 않습니다. - `nbest_size > 1`: nbest_size 결과에서 샘플링합니다. - `nbest_size < 0`: nbest_size가 무한하다고 가정하고, forward-filtering-and-backward-sampling 알고리즘을 사용하여 모든 가설(격자)에서 샘플링합니다. - `alpha`: 유니그램 샘플링의 스무딩 매개변수이며, BPE-dropout의 병합 작업 드롭아웃 확률입니다.

- ****kwargs** : [PreTrainedTokenizer](/docs/transformers/v5.23.0/ko/main_classes/tokenizer#transformers.PythonBackend)에 전달되는 추가 키워드 인자

Speech2Text 토크나이저를 구성합니다.

이 토크나이저는 일부 주요 메서드를 포함하는 [PreTrainedTokenizer](/docs/transformers/v5.23.0/ko/main_classes/tokenizer#transformers.PythonBackend)를 상속합니다. 해당 메서드에 대한 자세한 정보는 상위 클래스를 참고하세요.

#### build_inputs_with_special_tokens[[transformers.Speech2TextTokenizer.build_inputs_with_special_tokens]]

```python
build_inputs_with_special_tokens(token_ids_0, token_ids_1 = None)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/speech_to_text/tokenization_speech_to_text.py#L206)

시퀀스에서 eos_token_id를 추가하여 모델 입력을 구성합니다.

#### get_special_tokens_mask[[transformers.Speech2TextTokenizer.get_special_tokens_mask]]

```python
get_special_tokens_mask(token_ids_0: list[int], token_ids_1: list[int] | None = None, already_has_special_tokens: bool = False)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/speech_to_text/tokenization_speech_to_text.py#L213)

**매개변수:**

token_ids_0 (`list[int]`) : ID 목록.

token_ids_1 (`list[int]`, *선택 사항*) : 시퀀스 쌍을 위한 선택적 두 번째 ID 목록.

already_has_special_tokens (`bool`, *선택 사항*, 기본값 `False`) : 토큰 목록이 이미 모델의 특수 토큰으로 포맷되어 있는지 여부.

**반환값:** `list[int]`

[0, 1] 범위의 정수 목록: 특수 토큰은 1, 시퀀스 토큰은 0.

특수 토큰이 추가되지 않은 토큰 목록에서 시퀀스 ID를 가져옵니다. 이 메서드는 토크나이저의 `prepare_for_model` 메서드를 사용하여 특수 토큰을 추가할 때 호출됩니다.

#### 시퀀스에서 토큰 타입 ID 생성[[transformers.Speech2TextTokenizer.create_token_type_ids_from_sequences]]

```python
create_token_type_ids_from_sequences(token_ids_0: list[int], token_ids_1: list[int] | None = None)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/tokenization_python.py#L1301)

**매개변수:**

token_ids_0 (`list[int]`) : ID 목록.

token_ids_1 (`list[int]`, *선택 사항*) : 시퀀스 쌍을 위한 선택적 두 번째 ID 목록.

**반환값:** `list[int]`

구성된 패턴에 따른 토큰 유형 ID입니다.

시퀀스-페어 분류 작업에 사용될 마스크를 전달된 두 시퀀스에서 생성합니다.

이 메서드는 토크나이저의 구성 속성을 기반으로 토큰 유형 ID를 동적으로 생성합니다:
- `token_type_ids_pattern`: 사용할 패턴("all_zeros" 또는 "bert_style")
- `token_type_ids_include_special_tokens`: 길이 계산에 특수 토큰을 포함할지 여부

예:
```python
# All zeros pattern (default, used by RoBERTa, BART, etc.)
tokenizer.token_type_ids_pattern = "all_zeros"
# Returns: [0, 0, 0, ...] for both sequences

# BERT-style pattern (first sequence gets 0s, second gets 1s)
tokenizer.token_type_ids_pattern = "bert_style"
# Returns: [0, 0, 0, ..., 1, 1, 1, ...] for sequence pairs
```

#### save_vocabulary[[transformers.Speech2TextTokenizer.save_vocabulary]]

```python
save_vocabulary(save_directory: str, filename_prefix: str | None = None)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/speech_to_text/tokenization_speech_to_text.py#L257)

## Speech2TextFeatureExtractor[[transformers.Speech2TextFeatureExtractor]]

#### transformers.Speech2TextFeatureExtractor[[transformers.Speech2TextFeatureExtractor]]

```python
transformers.Speech2TextFeatureExtractor(feature_size = 80, sampling_rate = 16000, num_mel_bins = 80, padding_value = 0.0, dither = 0.0, do_ceptral_normalize = True, normalize_means = True, normalize_vars = True, **kwargs)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/speech_to_text/feature_extraction_speech_to_text.py#L33)

**매개변수:**

feature_size (`int`, *선택 사항*, 기본값 80) : 추출된 특징의 차원입니다.

sampling_rate (`int`, *선택 사항*, 기본값 16000) : 오디오 파일을 디지털화할 때 사용할 샘플링 주파수입니다. 헤르츠(Hz) 단위로 표시됩니다.

num_mel_bins (`int`, *선택 사항*, 기본값 80) : Mel 주파수 빈의 수.

padding_value (`float`, *선택 사항*, 기본값 0.0) : 패딩 벡터를 채우는 데 사용되는 값입니다.

dither (`float`, *선택 사항*, 기본값 0.0) : 디더링을 추가합니다. 즉, 각 프레임에 작은 가우시안 노이즈를 추가합니다. 예를 들어, 4.0을 사용하면 0.0을 중심으로 표준편차가 4.0인 정규 분포의 디더링을 추가합니다 (kaldi 웨이브폼의 [-32k,+32k] 범위를 가정). 값 0.0은 디더링을 하지 않음을 의미합니다. 디더링은 `mel_floor`와 유사한 효과를 냅니다. 신호에 VAD 컷오프가 존재할 때, 하드 제로 구간이 있는 신호의 높은 log_mel_fbank 값을 줄입니다.

do_ceptral_normalize (`bool`, *선택 사항*, 기본값 `True`) : 추출된 특징에 발화 수준의 세프스트럴 평균 및 분산 정규화를 적용할지 여부.

normalize_means (`bool`, *선택 사항*, 기본값 `True`) : 추출된 특징을 평균 제로 정규화할지 여부.

normalize_vars (`bool`, *선택 사항*, 기본값 `True`) : 추출된 특징을 단위 분산 정규화할지 여부.

Speech2Text feature extractor를 생성합니다.

이 feature extractor는 대부분의 주요 메서드를 포함하고 있는 [Speech2TextFeatureExtractor](/docs/transformers/v5.23.0/ko/model_doc/speech_to_text#transformers.Speech2TextFeatureExtractor)를 상속합니다. 해당 메서드에 대한 자세한 정보는 이 상위 클래스를 참고하세요.

이 클래스는 설치된 경우 TorchAudio를, 그렇지 않은 경우 numpy를 사용하여 원시 음성에서 mel-filter bank 특징을 추출하고, 추출된 특징에 발화 수준의 cepstral mean 및 variance 정규화를 적용합니다.

#### __call__[[transformers.Speech2TextFeatureExtractor.__call__]]

```python
__call__(raw_speech: numpy.ndarray | list[float] | list[numpy.ndarray] | list[list[float]], padding: bool | str | transformers.utils.generic.PaddingStrategy = False, max_length: int | None = None, truncation: bool = False, pad_to_multiple_of: int | None = None, return_tensors: str | transformers.utils.generic.TensorType | None = None, sampling_rate: int | None = None, return_attention_mask: bool | None = None, **kwargs)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/speech_to_text/feature_extraction_speech_to_text.py#L174)

**매개변수:**

raw_speech (`np.ndarray`, `list[float]`, `list[np.ndarray]`, `list[list[float]]`) : 패딩할 시퀀스 또는 시퀀스 배치입니다. 각 시퀀스는 numpy 배열, float 값의 리스트, numpy 배열의 리스트, float 값의 리스트의 리스트일 수 있습니다. 스테레오가 아닌 모노 채널 오디오여야 하며, 즉 각 타임스텝당 float 값이 하나만 있어야 합니다.

padding (`bool`, `str` 또는 [PaddingStrategy](/docs/transformers/v5.23.0/ko/internal/file_utils#transformers.utils.PaddingStrategy), *optional*, 기본값 `True`) : 반환되는 시퀀스에 패딩을 적용할 전략을 선택합니다 (모델의 패딩 방향 및 패딩 인덱스에 따라). 선택지: - `True` 또는 `'longest'`: 배치 내 가장 긴 시퀀스 길이로 패딩합니다 (단일 시퀀스만 제공된 경우 패딩하지 않음). - `'max_length'`: `max_length` 인수로 지정된 최대 길이로 패딩하거나, 해당 인수가 제공되지 않은 경우 모델이 허용하는 최대 입력 길이로 패딩합니다. - `False` 또는 `'do_not_pad'` (기본값): 패딩하지 않음 (즉, 서로 다른 길이의 시퀀스로 구성된 배치 출력 가능).

max_length (`int`, *선택 사항*) : 반환되는 리스트의 최대 길이 및 선택적으로 패딩 길이(위 참조).

truncation (`bool`) : *max_length*보다 긴 입력 시퀀스를 *max_length*로 잘라내기 위해 truncation을 활성화합니다.

pad_to_multiple_of (`int`, *선택 사항*) : 설정된 경우 시퀀스를 제공된 값의 배수로 패딩합니다. 이는 컴퓨트 캐피빌리티가 `>= 7.5`(Volta)인 NVIDIA 하드웨어에서 Tensor Cores 사용을 활성화하거나, 시퀀스 길이가 128의 배수일 때 성능이 향상되는 TPU에서 특히 유용합니다.

return_attention_mask (`bool`, *선택 사항*) : attention mask를 반환할지 여부입니다. 기본값으로 두면 해당 feature_extractor의 기본 설정에 따라 attention mask를 반환합니다. [attention mask란 무엇인가요?](../glossary#attention-mask)    Speech2TextTransformer 모델의 경우, 미묘한 버그를 방지하기 위해 배치 추론 시 `attention_mask`를 항상 전달해야 합니다.

return_tensors (`str` 또는 [TensorType](/docs/transformers/v5.23.0/ko/internal/file_utils#transformers.TensorType), *optional*) : 설정된 경우, python 정수 목록 대신 텐서를 반환합니다. 허용되는 값은 다음과 같습니다:  - `'pt'`: PyTorch `torch.Tensor` 객체를 반환합니다. - `'np'`: Numpy `np.ndarray` 객체를 반환합니다.

sampling_rate (`int`, *선택 사항*) : `raw_speech` 입력이 샘플링된 샘플링 레이트입니다. 조용한 오류를 방지하기 위해 forward 호출 시 `sampling_rate`를 전달하는 것이 강력히 권장됩니다.

padding_value (`float`, *선택 사항*, 기본값 0.0) : 패딩 값/벡터를 채우는 데 사용되는 값입니다.

하나 이상의 시퀀스를 특징화(featurize)하고 모델에 맞게 준비하는 주요 메서드입니다.

## Speech2TextProcessor[[transformers.Speech2TextProcessor]]

#### transformers.Speech2TextProcessor[[transformers.Speech2TextProcessor]]

```python
transformers.Speech2TextProcessor(feature_extractor, tokenizer)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/speech_to_text/processing_speech_to_text.py#L23)

**매개변수:**

feature_extractor (`Speech2TextFeatureExtractor`) : feature extractor는 필수 입력입니다.

tokenizer (`Speech2TextTokenizer`) : 토크나이저는 필수 입력입니다.

feature extractor와 tokenizer를 단일 processor로 감싸는 Speech2TextProcessor를 생성합니다.

[Speech2TextProcessor](/docs/transformers/v5.23.0/ko/model_doc/speech_to_text#transformers.Speech2TextProcessor)는 [Speech2TextFeatureExtractor](/docs/transformers/v5.23.0/ko/model_doc/speech_to_text#transformers.Speech2TextFeatureExtractor)와 [Speech2TextTokenizer](/docs/transformers/v5.23.0/ko/model_doc/speech_to_text#transformers.Speech2TextTokenizer)의 모든 기능을 제공합니다. 자세한 내용은 [~Speech2TextFeatureExtractor](/docs/transformers/v5.23.0/ko/model_doc/speech_to_text#transformers.Speech2TextFeatureExtractor)와 [~Speech2TextTokenizer](/docs/transformers/v5.23.0/ko/model_doc/speech_to_text#transformers.Speech2TextTokenizer)를 참고하세요.

#### __call__[[transformers.Speech2TextProcessor.__call__]]

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

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/speech_to_text/processing_speech_to_text.py#L27)

**매개변수:**

return_tensors (`str` 또는 [TensorType](/docs/transformers/v5.23.0/ko/internal/file_utils#transformers.TensorType), *optional*) : 설정된 경우, 특정 프레임워크의 텐서를 반환합니다. 허용되는 값은 다음과 같습니다:  - `'pt'`: PyTorch `torch.Tensor` 객체를 반환합니다. - `'np'`: NumPy `np.ndarray` 객체를 반환합니다.

#### from_pretrained[[transformers.Speech2TextProcessor.from_pretrained]]

```python
from_pretrained(pretrained_model_name_or_path: str | os.PathLike, cache_dir: str | os.PathLike | None = None, force_download: bool = False, local_files_only: bool = False, token: str | bool | None = None, revision: str = 'main', **kwargs)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/processing_utils.py#L1799)

**매개변수:**

pretrained_model_name_or_path (`str` 또는 `os.PathLike`) : 다음 중 하나일 수 있습니다. - huggingface.co의 모델 저장소에 호스팅된 사전 학습된 feature_extractor의 *model id*인 문자열. - [save_pretrained()](/docs/transformers/v5.23.0/ko/main_classes/feature_extractor#transformers.FeatureExtractionMixin.save_pretrained) 메서드를 사용하여 저장된 feature extractor 파일이 포함된 *디렉터리*의 경로, 예: `./my_model_directory/`. - 저장된 feature extractor JSON *파일*의 경로, 예: `./my_model_directory/preprocessor_config.json`.

- ****kwargs** : [from_pretrained()](/docs/transformers/v5.23.0/ko/main_classes/feature_extractor#transformers.FeatureExtractionMixin.from_pretrained)와 `~tokenization_utils_base.PreTrainedTokenizer.from_pretrained`에 함께 전달되는 추가 키워드 인자입니다.

과(와) 연관된 를 초기화합니다.

이 클래스 메서드는 단순히 feature extractor의 [from_pretrained()](/docs/transformers/v5.23.0/ko/main_classes/feature_extractor#transformers.FeatureExtractionMixin.from_pretrained), image processor의 [ImageProcessingMixin](/docs/transformers/v5.23.0/ko/internal/image_processing_utils#transformers.ImageProcessingMixin) 및 tokenizer의 `~tokenization_utils_base.PreTrainedTokenizer.from_pretrained` 메서드를 호출합니다. 자세한 내용은 위 메서드들의 docstring을 참고하세요.

#### save_pretrained[[transformers.Speech2TextProcessor.save_pretrained]]

```python
save_pretrained(save_directory, push_to_hub: bool = False, **kwargs)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/processing_utils.py#L1182)

**매개변수:**

save_directory (`str` 또는 `os.PathLike`) : feature extractor JSON 파일과 tokenizer 파일이 저장될 디렉터리 (존재하지 않으면 생성됩니다).

push_to_hub (`bool`, *선택 사항*, 기본값 `False`) : 모델을 저장한 후 Hugging Face 모델 허브에 푸시할지 여부입니다. `repo_id`를 사용하여 푸시할 저장소를 지정할 수 있으며, 지정하지 않으면 네임스페이스 내 `save_directory`의 이름이 기본값으로 사용됩니다.

kwargs (`dict[str, Any]`, *선택*) : [push_to_hub()](/docs/transformers/v5.23.0/ko/main_classes/model#transformers.utils.PushToHubMixin.push_to_hub) 메서드에 함께 전달되는 추가 키워드 인자입니다.

이 프로세서의 속성(피처 추출기, 토크나이저...)을 지정된 디렉터리에 저장하여 [from_pretrained()](/docs/transformers/v5.23.0/ko/model_doc/wav2vec2#transformers.Wav2Vec2Processor.from_pretrained) 메서드를 사용해 다시 로드할 수 있도록 합니다.

이 클래스 메서드는 단순히 [save_pretrained()](/docs/transformers/v5.23.0/ko/main_classes/feature_extractor#transformers.FeatureExtractionMixin.save_pretrained)와 [save_pretrained()](/docs/transformers/v5.23.0/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.save_pretrained)를 호출합니다. 자세한 내용은 위 메서드의 docstring을 참고하세요.

#### batch_decode[[transformers.Speech2TextProcessor.batch_decode]]

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

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/processing_utils.py#L2054)

이 메서드는 모든 인수를 PreTrainedTokenizer의 [batch_decode()](/docs/transformers/v5.23.0/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.batch_decode)로 전달합니다. 자세한 내용은 해당 메서드의 docstring을 참조하세요.

#### decode[[transformers.Speech2TextProcessor.decode]]

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

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/processing_utils.py#L2063)

이 메서드는 모든 인수를 PreTrainedTokenizer의 [decode()](/docs/transformers/v5.23.0/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.decode)로 전달합니다. 자세한 내용은 해당 메서드의 docstring을 참조하세요.

## Speech2TextModel[[transformers.Speech2TextModel]]

#### transformers.Speech2TextModel[[transformers.Speech2TextModel]]

```python
transformers.Speech2TextModel(config: Speech2TextConfig)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/speech_to_text/modeling_speech_to_text.py#L720)

**매개변수:**

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

특정 헤드가 위에 없는 상태에서 원시 hidden-states를 출력하는 기본 Speech To Text Text Model입니다.

이 모델은 [PreTrainedModel](/docs/transformers/v5.23.0/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.Speech2TextModel.forward]]

```python
forward(input_features: typing.Optional[torch.LongTensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, decoder_input_ids: typing.Optional[torch.LongTensor] = None, decoder_attention_mask: typing.Optional[torch.LongTensor] = None, encoder_outputs: tuple[tuple[torch.Tensor]] | None = None, past_key_values: transformers.cache_utils.Cache | None = None, decoder_inputs_embeds: typing.Optional[torch.Tensor] = None, use_cache: bool | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/speech_to_text/modeling_speech_to_text.py#L736)

**매개변수:**

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

attention_mask (`torch.Tensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : 패딩 토큰 인덱스에 대한 attention을 수행하지 않도록 방지하는 마스크입니다. `[0, 1]`에서 선택된 마스크 값: - **마스크되지 않은** 토큰은 1, - **마스크된** 토큰은 0. [attention 마스크란?](../glossary#attention-mask)

decoder_input_ids (`torch.LongTensor`, shape `(batch_size, target_sequence_length)`, *선택 사항*) : 어휘에서 디코더 입력 시퀀스 토큰의 인덱스입니다. `SpeechToTextTokenizer`를 사용하여 인덱스를 얻을 수 있습니다. 자세한 내용은 [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 및 [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)를 참조하세요. [디코더 입력 ID란 무엇인가요?](../glossary#decoder-input-ids) SpeechToText는 `decoder_input_ids` 생성의 시작 토큰으로 `eos_token_id`를 사용합니다. `past_key_values`를 사용하는 경우, 선택적으로 마지막 `decoder_input_ids`만 입력하면 됩니다(`past_key_values` 참조).

decoder_attention_mask (`torch.LongTensor`, shape `(batch_size, target_sequence_length)`, *선택 사항*) : 기본 동작: `decoder_input_ids`의 pad 토큰을 무시하는 텐서를 생성합니다. 기본적으로 Causal mask도 사용됩니다. 패딩 동작을 변경하려면 `modeling_speech_to_text._prepare_decoder_attention_mask`를 읽고 필요에 맞게 수정해야 합니다. 기본 전략에 대한 자세한 내용은 [논문](https://huggingface.co/papers/1910.13461)의 다이어그램 1을 참조하세요.

encoder_outputs (`tuple[tuple[torch.Tensor]]`, *선택 사항*) : (`last_hidden_state`, *선택 사항*: `hidden_states`, *선택 사항*: `attentions`) `last_hidden_state`의 shape은 `(batch_size, sequence_length, hidden_size)`, *선택 사항*)이며, 인코더의 마지막 레이어 출력에서 생성된 hidden-states의 시퀀스입니다. 디코더의 cross-attention에 사용됩니다.

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

decoder_inputs_embeds (`torch.Tensor`, shape `(batch_size, target_sequence_length, hidden_size)`, *선택 사항*) : `decoder_input_ids`를 전달하는 대신 임베디드 표현을 직접 전달할 수 있습니다. `past_key_values`를 사용하는 경우, 선택적으로 마지막 `decoder_inputs_embeds`만 입력하면 됩니다(`past_key_values` 참조). 모델 내부 임베딩 조회 행렬보다 `decoder_input_ids` 인덱스를 관련 벡터로 변환하는 방식을 더 세밀하게 제어하려는 경우 유용합니다. `decoder_input_ids`와 `decoder_inputs_embeds`가 모두 설정되지 않은 경우, `decoder_inputs_embeds`는 `inputs_embeds`의 값을 취합니다.

use_cache (`bool`, *선택 사항*) : `True`로 설정하면 `past_key_values` 키 값 상태가 반환되며, 디코딩 속도를 높이는 데 사용할 수 있습니다(`past_key_values` 참조).

**반환값:** [Seq2SeqLMOutput](/docs/transformers/v5.23.0/ko/main_classes/output#transformers.modeling_outputs.Seq2SeqLMOutput) 또는 `tuple(torch.Tensor)`

구성([Speech2TextConfig](/docs/transformers/v5.23.0/ko/model_doc/speech_to_text#transformers.Speech2TextConfig))과 입력에 따라 다양한 요소를 포함하는 [Seq2SeqLMOutput](/docs/transformers/v5.23.0/ko/main_classes/output#transformers.modeling_outputs.Seq2SeqLMOutput) 또는 `torch.Tensor`의 튜플(`return_dict=False`가 전달되거나 `config.return_dict=False`인 경우).

[Speech2TextModel](/docs/transformers/v5.23.0/ko/model_doc/speech_to_text#transformers.Speech2TextModel)의 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** (`EncoderDecoderCache`, *선택 사항*, `use_cache=True`가 전달되거나 `config.use_cache=True`인 경우 반환됨) -- [EncoderDecoderCache](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.EncoderDecoderCache) 인스턴스입니다. 자세한 내용은 [kv 캐시 가이드](https://huggingface.co/docs/transformers/en/kv_cache)를 참조하세요.

  순차적 디코딩을 가속화하는 데 사용할 수 있는 사전 계산된 hidden-states(셀프-어텐션 블록과 크로스-어텐션 블록의 key 및 values)를 포함합니다(입력 `past_key_values` 참조).
- **decoder_hidden_states** (`tuple(torch.Tensor)`, *선택*, `output_hidden_states=True`가 전달되거나 `config.output_hidden_states=True`인 경우 반환) -- shape가 `(batch_size, sequence_length, hidden_size)`인 `torch.Tensor`의 튜플 (모델에 임베딩 레이어가 있는 경우 임베딩 출력 1개 + 각 레이어의 출력 1개).

  각 레이어의 출력에서 디코더의 Hidden-states와 초기 임베딩 출력을 더한 값.
- **decoder_attentions** (`tuple(torch.Tensor)`, *선택 사항*, `output_attentions=True`가 전달되었거나 `config.output_attentions=True`인 경우 반환) -- 각 레이어마다 하나씩 포함된 `torch.Tensor` 튜플이며, shape는 `(batch_size, num_heads, sequence_length, sequence_length)`입니다.

  self-attention 헤드에서 가중 평균을 계산하는 데 사용되는, attention softmax 이후의 decoder의 attention 가중치입니다.
- **cross_attentions** (`tuple(torch.Tensor)`, *선택*, `output_attentions=True`가 전달되거나 `config.output_attentions=True`인 경우 반환) -- 각 레이어마다 하나씩 포함된 `torch.Tensor`의 튜플로, shape는 `(batch_size, num_heads, sequence_length, sequence_length)`입니다.

  decoder의 cross-attention 레이어에서 attention softmax를 적용한 후, cross-attention 헤드에서 가중 평균을 계산하는 데 사용되는 attention 가중치입니다.
- **encoder_last_hidden_state** (`torch.Tensor`, shape `(batch_size, sequence_length, hidden_size)`, *선택 사항*) -- 모델 인코더의 마지막 레이어 출력의 hidden-state 시퀀스입니다.
- **encoder_hidden_states** (`tuple(torch.Tensor)`, *선택*, `output_hidden_states=True`가 전달되거나 `config.output_hidden_states=True`일 때 반환) -- shape가 `(batch_size, sequence_length, hidden_size)`인 `torch.Tensor`의 튜플 (모델에 임베딩 레이어가 있는 경우 임베딩 출력 1개 + 각 레이어의 출력 1개).

  각 레이어의 출력에서 인코더의 Hidden-states와 초기 임베딩 출력을 더한 값.
- **encoder_attentions** (`tuple(torch.Tensor)`, *선택 사항*, `output_attentions=True`가 전달되거나 `config.output_attentions=True`인 경우 반환) -- 각 레이어에 하나씩 포함된 `torch.Tensor` 튜플로, shape는 `(batch_size, num_heads, sequence_length, sequence_length)`입니다.

  인코더의 어텐션 가중치입니다. 어텐션 softmax 이후에 self-attention 헤드에서 가중 평균을 계산하는 데 사용됩니다.

예:

```python
>>> import torch
>>> from transformers import Speech2TextModel, AutoFeatureExtractor
>>> from datasets import load_dataset

>>> model = Speech2TextModel.from_pretrained("facebook/s2t-small-librispeech-asr")
>>> feature_extractor = AutoFeatureExtractor.from_pretrained("facebook/s2t-small-librispeech-asr")
>>> ds = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")
>>> inputs = feature_extractor(
...     ds[0]["audio"]["array"], sampling_rate=ds[0]["audio"]["sampling_rate"], return_tensors="pt"
... )
>>> input_features = inputs.input_features
>>> decoder_input_ids = torch.tensor([[1, 1]]) * model.config.decoder_start_token_id
>>> last_hidden_state = model(input_features, decoder_input_ids=decoder_input_ids).last_hidden_state
>>> list(last_hidden_state.shape)
[1, 2, 256]
```

## Speech2TextForConditionalGeneration[[transformers.Speech2TextForConditionalGeneration]]

#### transformers.Speech2TextForConditionalGeneration[[transformers.Speech2TextForConditionalGeneration]]

```python
transformers.Speech2TextForConditionalGeneration(config: Speech2TextConfig)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/speech_to_text/modeling_speech_to_text.py#L842)

**매개변수:**

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

언어 모델링 헤드를 갖춘 Speech2Text 모델. 요약에 사용할 수 있습니다.

이 모델은 [PreTrainedModel](/docs/transformers/v5.23.0/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.Speech2TextForConditionalGeneration.forward]]

```python
forward(input_features: typing.Optional[torch.LongTensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, decoder_input_ids: typing.Optional[torch.LongTensor] = None, decoder_attention_mask: typing.Optional[torch.LongTensor] = None, encoder_outputs: tuple[tuple[torch.Tensor]] | None = None, past_key_values: transformers.cache_utils.Cache | None = None, decoder_inputs_embeds: typing.Optional[torch.Tensor] = None, labels: typing.Optional[torch.LongTensor] = None, use_cache: bool | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/speech_to_text/modeling_speech_to_text.py#L855)

**매개변수:**

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

attention_mask (`torch.Tensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : 패딩 토큰 인덱스에 대한 attention을 수행하지 않도록 방지하는 마스크입니다. `[0, 1]`에서 선택된 마스크 값: - **마스크되지 않은** 토큰은 1, - **마스크된** 토큰은 0. [attention 마스크란?](../glossary#attention-mask)

decoder_input_ids (`torch.LongTensor`, shape `(batch_size, target_sequence_length)`, *선택 사항*) : 어휘에서 디코더 입력 시퀀스 토큰의 인덱스입니다. `SpeechToTextTokenizer`를 사용하여 인덱스를 얻을 수 있습니다. 자세한 내용은 [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 및 [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)를 참조하세요. [디코더 입력 ID란 무엇인가요?](../glossary#decoder-input-ids) SpeechToText는 `decoder_input_ids` 생성의 시작 토큰으로 `eos_token_id`를 사용합니다. `past_key_values`를 사용하는 경우, 선택적으로 마지막 `decoder_input_ids`만 입력하면 됩니다(`past_key_values` 참조).

decoder_attention_mask (`torch.LongTensor`, shape `(batch_size, target_sequence_length)`, *선택 사항*) : 기본 동작: `decoder_input_ids`의 pad 토큰을 무시하는 텐서를 생성합니다. 기본적으로 Causal mask도 사용됩니다. 패딩 동작을 변경하려면 `modeling_speech_to_text._prepare_decoder_attention_mask`를 읽고 필요에 맞게 수정해야 합니다. 기본 전략에 대한 자세한 내용은 [논문](https://huggingface.co/papers/1910.13461)의 다이어그램 1을 참조하세요.

encoder_outputs (`tuple[tuple[torch.Tensor]]`, *선택 사항*) : (`last_hidden_state`, *선택 사항*: `hidden_states`, *선택 사항*: `attentions`) `last_hidden_state`의 shape은 `(batch_size, sequence_length, hidden_size)`, *선택 사항*)이며, 인코더의 마지막 레이어 출력에서 생성된 hidden-states의 시퀀스입니다. 디코더의 cross-attention에 사용됩니다.

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

decoder_inputs_embeds (`torch.Tensor`, shape `(batch_size, target_sequence_length, hidden_size)`, *선택 사항*) : `decoder_input_ids`를 전달하는 대신 임베디드 표현을 직접 전달할 수 있습니다. `past_key_values`를 사용하는 경우, 선택적으로 마지막 `decoder_inputs_embeds`만 입력하면 됩니다(`past_key_values` 참조). 모델 내부 임베딩 조회 행렬보다 `decoder_input_ids` 인덱스를 관련 벡터로 변환하는 방식을 더 세밀하게 제어하려는 경우 유용합니다. `decoder_input_ids`와 `decoder_inputs_embeds`가 모두 설정되지 않은 경우, `decoder_inputs_embeds`는 `inputs_embeds`의 값을 취합니다.

labels (`torch.LongTensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : 언어 모델링 손실을 계산하기 위한 라벨. 인덱스는 `[0, ..., config.vocab_size]` 범위 내이거나 -100이어야 합니다(`input_ids` docstring 참조). 인덱스가 `-100`으로 설정된 토큰은 무시(마스크)되며, 손실은 `[0, ..., config.vocab_size]` 범위의 라벨을 가진 토큰에 대해서만 계산됩니다.

use_cache (`bool`, *선택 사항*) : `True`로 설정하면 `past_key_values` 키 값 상태가 반환되며, 디코딩 속도를 높이는 데 사용할 수 있습니다(`past_key_values` 참조).

**반환값:** [Seq2SeqLMOutput](/docs/transformers/v5.23.0/ko/main_classes/output#transformers.modeling_outputs.Seq2SeqLMOutput) 또는 `tuple(torch.Tensor)`

구성([Speech2TextConfig](/docs/transformers/v5.23.0/ko/model_doc/speech_to_text#transformers.Speech2TextConfig))과 입력에 따라 다양한 요소를 포함하는 [Seq2SeqLMOutput](/docs/transformers/v5.23.0/ko/main_classes/output#transformers.modeling_outputs.Seq2SeqLMOutput) 또는 `torch.Tensor`의 튜플(`return_dict=False`가 전달되거나 `config.return_dict=False`인 경우).

[Speech2TextForConditionalGeneration](/docs/transformers/v5.23.0/ko/model_doc/speech_to_text#transformers.Speech2TextForConditionalGeneration)의 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** (`EncoderDecoderCache`, *선택 사항*, `use_cache=True`가 전달되거나 `config.use_cache=True`인 경우 반환됨) -- [EncoderDecoderCache](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.EncoderDecoderCache) 인스턴스입니다. 자세한 내용은 [kv 캐시 가이드](https://huggingface.co/docs/transformers/en/kv_cache)를 참조하세요.

  순차적 디코딩을 가속화하는 데 사용할 수 있는 사전 계산된 hidden-states(셀프-어텐션 블록과 크로스-어텐션 블록의 key 및 values)를 포함합니다(입력 `past_key_values` 참조).
- **decoder_hidden_states** (`tuple(torch.Tensor)`, *선택*, `output_hidden_states=True`가 전달되거나 `config.output_hidden_states=True`인 경우 반환) -- shape가 `(batch_size, sequence_length, hidden_size)`인 `torch.Tensor`의 튜플 (모델에 임베딩 레이어가 있는 경우 임베딩 출력 1개 + 각 레이어의 출력 1개).

  각 레이어의 출력에서 디코더의 Hidden-states와 초기 임베딩 출력을 더한 값.
- **decoder_attentions** (`tuple(torch.Tensor)`, *선택 사항*, `output_attentions=True`가 전달되었거나 `config.output_attentions=True`인 경우 반환) -- 각 레이어마다 하나씩 포함된 `torch.Tensor` 튜플이며, shape는 `(batch_size, num_heads, sequence_length, sequence_length)`입니다.

  self-attention 헤드에서 가중 평균을 계산하는 데 사용되는, attention softmax 이후의 decoder의 attention 가중치입니다.
- **cross_attentions** (`tuple(torch.Tensor)`, *선택*, `output_attentions=True`가 전달되거나 `config.output_attentions=True`인 경우 반환) -- 각 레이어마다 하나씩 포함된 `torch.Tensor`의 튜플로, shape는 `(batch_size, num_heads, sequence_length, sequence_length)`입니다.

  decoder의 cross-attention 레이어에서 attention softmax를 적용한 후, cross-attention 헤드에서 가중 평균을 계산하는 데 사용되는 attention 가중치입니다.
- **encoder_last_hidden_state** (`torch.Tensor`, shape `(batch_size, sequence_length, hidden_size)`, *선택 사항*) -- 모델 인코더의 마지막 레이어 출력의 hidden-state 시퀀스입니다.
- **encoder_hidden_states** (`tuple(torch.Tensor)`, *선택*, `output_hidden_states=True`가 전달되거나 `config.output_hidden_states=True`일 때 반환) -- shape가 `(batch_size, sequence_length, hidden_size)`인 `torch.Tensor`의 튜플 (모델에 임베딩 레이어가 있는 경우 임베딩 출력 1개 + 각 레이어의 출력 1개).

  각 레이어의 출력에서 인코더의 Hidden-states와 초기 임베딩 출력을 더한 값.
- **encoder_attentions** (`tuple(torch.Tensor)`, *선택 사항*, `output_attentions=True`가 전달되거나 `config.output_attentions=True`인 경우 반환) -- 각 레이어에 하나씩 포함된 `torch.Tensor` 튜플로, shape는 `(batch_size, num_heads, sequence_length, sequence_length)`입니다.

  인코더의 어텐션 가중치입니다. 어텐션 softmax 이후에 self-attention 헤드에서 가중 평균을 계산하는 데 사용됩니다.

예:

```python
>>> import torch
>>> from transformers import Speech2TextProcessor, Speech2TextForConditionalGeneration
>>> from datasets import load_dataset

>>> model = Speech2TextForConditionalGeneration.from_pretrained("facebook/s2t-small-librispeech-asr")
>>> processor = Speech2TextProcessor.from_pretrained("facebook/s2t-small-librispeech-asr")

>>> ds = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")

>>> inputs = processor(
...     ds[0]["audio"]["array"], sampling_rate=ds[0]["audio"]["sampling_rate"], return_tensors="pt"
... )
>>> input_features = inputs.input_features

>>> generated_ids = model.generate(inputs=input_features)

>>> transcription = processor.batch_decode(generated_ids, skip_special_tokens=True)[0]
>>> transcription
'mister quilter is the apostle of the middle classes and we are glad to welcome his gospel'
```

