# Wav2Vec2Phoneme

## 개요

Wav2Vec2Phoneme 모델은 Qiantong Xu, Alexei Baevski, Michael Auli가 [Simple and Effective Zero-shot Cross-lingual Phoneme Recognition (Xu et al., 2021)](https://huggingface.co/papers/2109.11680)에서 제안했습니다.

해당 논문의 초록은 다음과 같습니다:

*자기 학습, 자기 지도 사전 학습 및 비지도 학습의 최근 발전 덕분에 라벨링된 데이터 없이도 높은 성능을 발휘하는 음성 인식 시스템을 구축할 수 있게 되었습니다. 그러나 많은 경우 관련 언어에 대한 라벨링된 데이터가 존재함에도 이러한 방법론에서는 이를 활용하지 못하고 있습니다. 본 논문은 다국어 사전 학습된 wav2vec 2.0 모델을 미세 조정하여 보지 못한 언어의 전사를 수행함으로써, 제로샷 크로스 링구얼 전이 학습에 관한 이전 연구를 확장합니다. 이는 발음 기제적 특징을 활용하여 학습 언어의 음소를 대상 언어로 매핑하는 방식으로 수행됩니다. 실험 결과, 이 단순한 방법은 작업별 아키텍처를 도입하고 단국어 사전 학습 모델의 일부만 사용했던 기존 연구보다 현저히 우수한 성능을 보였습니다.*

관련 체크포인트는 https://huggingface.co/models?other=phoneme-recognition에서 찾을 수 있습니다.

이 모델은 [patrickvonplaten](https://huggingface.co/patrickvonplaten)에 의해 기여되었습니다.

원본 코드는 [여기](https://github.com/pytorch/fairseq/tree/master/fairseq/models/wav2vec)에서 찾을 수 있습니다.

## 사용 팁

- Wav2Vec2Phoneme는 Wav2Vec2와 정확히 동일한 아키텍처를 사용합니다.
- Wav2Vec2Phoneme는 음성 신호의 원시 파형에 해당하는 float 배열을 입력으로 받는 음성 모델입니다.
- Wav2Vec2Phoneme 모델은 connectionist temporal classification(CTC)을 사용하여 학습되었으므로 모델 출력은 [Wav2Vec2PhonemeCTCTokenizer](/docs/transformers/v5.23.0/ko/model_doc/wav2vec2_phoneme#transformers.Wav2Vec2PhonemeCTCTokenizer)를 사용하여 디코딩해야 합니다.
- Wav2Vec2Phoneme은 여러 언어를 동시에 fine-tune하고, 한 번의 forward pass로 보지 못한 언어를 음소(phoneme) 시퀀스로 디코딩할 수 있습니다
- 기본적으로 모델은 음소(phoneme)의 시퀀스를 출력합니다. 음소를 단어의 시퀀스로 변환하려면 사전과 언어 모델을 활용해야 합니다.

Wav2Vec2Phoneme의 아키텍처는 Wav2Vec2 모델에 기반합니다. API 참고를 위해 토크나이저를 제외하고 [`Wav2Vec2`](wav2vec2)의 문서 페이지를 확인하세요.

## Wav2Vec2PhonemeCTCTokenizer[[transformers.Wav2Vec2PhonemeCTCTokenizer]]

#### transformers.Wav2Vec2PhonemeCTCTokenizer[[transformers.Wav2Vec2PhonemeCTCTokenizer]]

```python
transformers.Wav2Vec2PhonemeCTCTokenizer(vocab_file, bos_token = '<s>', eos_token = '</s>', unk_token = '<unk>', pad_token = '<pad>', phone_delimiter_token = ' ', word_delimiter_token = None, do_phonemize = True, phonemizer_lang = 'en-us', phonemizer_backend = 'espeak', **kwargs)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/wav2vec2_phoneme/tokenization_wav2vec2_phoneme.py#L71)

**매개변수:**

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

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

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

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

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

do_phonemize (`bool`, *선택 사항*, 기본값 `True`) : 토크나이저가 입력을 음성화할지 여부를 지정합니다. 토크나이저에 음소 시퀀스가 전달되는 경우에만 `do_phonemize`를 `False`로 설정해야 합니다.

phonemizer_lang (`str`, *선택 사항*, 기본값 `"en-us"`) : 토크나이저가 입력 텍스트를 음운화할 대상 음소 집합의 언어입니다.

phonemizer_backend (`str`, *선택 사항*. 기본값은 `"espeak"`) : phonemizer 라이브러리가 사용할 백엔드 음운론화(phonetization) 라이브러리입니다. 기본값은 `espeak-ng`입니다. 자세한 내용은 [phonemizer 패키지](https://github.com/bootphon/phonemizer#readme)를 참조하세요.

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

Wav2Vec2PhonemeCTC 토크나이저를 생성합니다.

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

#### __call__[[transformers.Wav2Vec2PhonemeCTCTokenizer.__call__]]

```python
__call__(text: TextInput | PreTokenizedInput | list[TextInput] | list[PreTokenizedInput] | None = None, text_pair: TextInput | PreTokenizedInput | list[TextInput] | list[PreTokenizedInput] | None = None, text_target: TextInput | PreTokenizedInput | list[TextInput] | list[PreTokenizedInput] | None = None, text_pair_target: TextInput | PreTokenizedInput | list[TextInput] | list[PreTokenizedInput] | None = None, add_special_tokens: bool = True, padding: bool | str | PaddingStrategy = False, truncation: bool | str | TruncationStrategy | None = None, max_length: int | None = None, stride: int = 0, is_split_into_words: bool = False, pad_to_multiple_of: int | None = None, padding_side: str | None = None, return_tensors: str | TensorType | None = None, return_token_type_ids: bool | None = None, return_attention_mask: bool | None = None, return_overflowing_tokens: bool = False, return_special_tokens_mask: bool = False, return_offsets_mapping: bool = False, return_length: bool = False, verbose: bool = True, tokenizer_kwargs: dict[str, Any] | None = None, **kwargs)
```

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

**매개변수:**

text (`str`, `list[str]`, `list[list[str]]`, *선택*) : 인코딩할 시퀀스 또는 시퀀스 배치입니다. 각 시퀀스는 문자열 또는 문자열 목록(사전 토큰화된 문자열)일 수 있습니다. 시퀀스가 문자열 목록(사전 토큰화)로 제공되는 경우, `is_split_into_words=True`를 설정해야 합니다(시퀀스 배치와의 모호성을 제거하기 위함).

text_pair (`str`, `list[str]`, `list[list[str]]`, *선택*) : 인코딩할 시퀀스 또는 시퀀스 배치입니다. 각 시퀀스는 문자열 또는 문자열 목록(사전 토큰화된 문자열)일 수 있습니다. 시퀀스가 문자열 목록(사전 토큰화)로 제공되는 경우, `is_split_into_words=True`를 설정해야 합니다(시퀀스 배치와의 모호성을 제거하기 위함).

text_target (`str`, `list[str]`, `list[list[str]]`, *선택*) : 대상 텍스트로 인코딩할 시퀀스 또는 시퀀스 배치입니다. 각 시퀀스는 문자열 또는 문자열 목록(사전 토큰화된 문자열)일 수 있습니다. 시퀀스가 문자열 목록(사전 토큰화)로 제공되는 경우, `is_split_into_words=True`를 설정해야 합니다(시퀀스 배치와의 모호성을 제거하기 위함).

text_pair_target (`str`, `list[str]`, `list[list[str]]`, *선택*) : 대상 텍스트로 인코딩할 시퀀스 또는 시퀀스 배치입니다. 각 시퀀스는 문자열 또는 문자열 목록(사전 토큰화된 문자열)일 수 있습니다. 시퀀스가 문자열 목록(사전 토큰화)로 제공되는 경우, `is_split_into_words=True`를 설정해야 합니다(시퀀스 배치와의 모호성을 제거하기 위함).

tokenizer_kwargs (`dict[str, Any]`, *선택*) : 토크나이저에 전달할 추가 kwargs입니다. 명시적 매개변수 및 기타 kwargs와 병합되며, 명시적 매개변수가 우선합니다.

add_special_tokens (`bool`, *선택 사항*, 기본값 `True`) : 시퀀스를 인코딩할 때 특수 토큰을 추가할지 여부입니다. 이는 입력 id에 자동으로 추가되는 토큰을 정의하는 기반 `PretrainedTokenizerBase.build_inputs_with_special_tokens` 함수를 사용합니다. `bos` 또는 `eos` 토큰을 자동으로 추가하려는 경우 유용합니다.

padding (`bool`, `str` 또는 [PaddingStrategy](/docs/transformers/v5.23.0/ko/internal/file_utils#transformers.utils.PaddingStrategy), *optional*, 기본값 `False`) : 패딩을 활성화하고 제어합니다. 다음 값을 허용합니다: - `True` 또는 `'longest'`: 배치 내 가장 긴 시퀀스 길이로 패딩합니다(단일 시퀀스만 제공된 경우 패딩하지 않음). - `'max_length'`: `max_length` 인수로 지정된 최대 길이로 패딩하거나, 해당 인수가 제공되지 않으면 모델이 허용하는 최대 입력 길이로 패딩합니다. - `False` 또는 `'do_not_pad'` (기본값): 패딩하지 않음(즉, 서로 다른 길이의 시퀀스를 가진 배치를 출력할 수 있음).

truncation (`bool`, `str` 또는 [TruncationStrategy](/docs/transformers/v5.23.0/ko/internal/tokenization_utils#transformers.tokenization_utils_base.TruncationStrategy), *optional*, 기본값 `False`) : 잘림(truncation)을 활성화하고 제어합니다. 다음 값을 허용합니다:  - `True` 또는 `'longest_first'`: `max_length` 인수로 지정된 최대 길이로 잘거나, 해당 인수가 제공되지 않으면 모델이 허용하는 최대 입력 길이로 잘릅니다. 이 경우 토큰 단위로 잘리며, 시퀀스 쌍(또는 쌍의 배치)이 제공되면 쌍에서 가장 긴 시퀀스에서 토큰을 하나씩 제거합니다. - `'only_first'`: `max_length` 인수로 지정된 최대 길이로 잘거나, 해당 인수가 제공되지 않으면 모델이 허용하는 최대 입력 길이로 잘릅니다. 이 경우 시퀀스 쌍(또는 쌍의 배치)이 제공되면 쌍의 첫 번째 시퀀스만 잘릅니다. - `'only_second'`: `max_length` 인수로 지정된 최대 길이로 잘거나, 해당 인수가 제공되지 않으면 모델이 허용하는 최대 입력 길이로 잘릅니다. 이 경우 시퀀스 쌍(또는 쌍의 배치)이 제공되면 쌍의 두 번째 시퀀스만 잘릅니다. - `False` 또는 `'do_not_truncate'` (기본값): 잘리지 않습니다(즉, 모델이 허용하는 최대 입력 크기보다 긴 시퀀스 길이를 가진 배치를 출력할 수 있습니다).

max_length (`int`, *선택 사항*) : truncation/padding 매개변수 중 하나가 사용할 최대 길이를 제어합니다. 설정하지 않거나 `None`으로 설정한 경우, truncation/padding 매개변수 중 하나가 최대 길이를 요구하면 미리 정의된 모델 최대 길이를 사용합니다. 모델에 특정 최대 입력 길이가 없는 경우(XLNet 등) 최대 길이로 truncation/padding하는 기능이 비활성화됩니다.

stride (`int`, *선택 사항*, 기본값 0) : `max_length`와 함께 숫자로 설정하면, `return_overflowing_tokens=True`일 때 반환되는 오버플로 토큰에는 잘림된 시퀀스로 반환되는 시퀀스의 끝부분에서 가져온 일부 토큰이 포함되어 잘림된 시퀀스와 오버플로 시퀀스 사이에 일부 중복이 제공됩니다. 이 인수의 값은 중복되는 토큰의 수를 정의합니다.

is_split_into_words (`bool`, *선택 사항*, 기본값 `False`) : 입력이 이미 사전 토큰화(예: 단어 단위로 분리)되었는지 여부입니다. `True`로 설정하면, 토크나이저는 입력이 이미 단어 단위로 분리되어 있다고 가정하고(예: 공백 기준으로 분리) 이를 토큰화합니다. 이는 NER 또는 토큰 분류에 유용합니다.

pad_to_multiple_of (`int`, *선택 사항*) : 설정 시 시퀀스를 제공된 값의 배수로 패딩합니다. `padding`이 활성화되어 있어야 합니다. 이는 Volta에서 `>= 7.5`의 컴퓨트 캐퍼빌리티를 가진 NVIDIA 하드웨어에서 Tensor Cores 사용을 활성화하는 데 특히 유용합니다.

padding_side (`str`, *선택 사항*) : 모델에 패딩을 적용할 쪽입니다. ['right', 'left'] 중에서 선택해야 합니다. 기본값은 동일한 이름의 클래스 속성에서 가져옵니다.

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` 객체를 반환합니다.

return_token_type_ids (`bool`, *선택 사항*) : 토큰 타입 ID를 반환할지 여부입니다. 기본값으로 두면, `return_outputs` 속성으로 정의된 해당 토크나이저의 기본값에 따라 토큰 타입 ID를 반환합니다. [토큰 타입 ID란 무엇인가요?](../glossary#token-type-ids)

return_attention_mask (`bool`, *선택 사항*) : attention mask를 반환할지 여부입니다. 기본값으로 두면, `return_outputs` 속성으로 정의된 해당 tokenizer의 기본값에 따라 attention mask를 반환합니다. [attention mask란 무엇인가요?](../glossary#attention-mask)

return_overflowing_tokens (`bool`, *선택 사항*, 기본값 `False`) : 넘친 토큰 시퀀스를 반환할지 여부입니다. 입력 ID의 시퀀스 쌍(또는 쌍의 배치)이 `truncation_strategy = longest_first` 또는 `True`와 함께 제공되면, 넘친 토큰을 반환하는 대신 오류가 발생합니다.

return_special_tokens_mask (`bool`, *선택 사항*, 기본값 `False`) : 특수 토큰 마스크 정보를 반환할지 여부.

return_offsets_mapping (`bool`, *선택 사항*, 기본값 `False`) : 각 토큰에 대해 `(char_start, char_end)`를 반환할지 여부입니다. 이 기능은 [PreTrainedTokenizerFast](/docs/transformers/v5.23.0/ko/main_classes/tokenizer#transformers.TokenizersBackend)를 상속하는 fast tokenizer에서만 사용할 수 있으며, Python의 tokenizer를 사용하는 경우 이 메서드는 `NotImplementedError`를 발생시킵니다.

return_length (`bool`, *선택 사항*, 기본값 `False`) : 인코딩된 입력의 길이를 반환할지 여부.

verbose (`bool`, *선택 사항*, 기본값 `True`) : 추가 정보와 경고를 출력할지 여부.

- ****kwargs** : `self.tokenize()` 메서드에 전달됩니다

**반환값:** [BatchEncoding](/docs/transformers/v5.23.0/ko/main_classes/tokenizer#transformers.BatchEncoding)

다음 필드를 가진 [BatchEncoding](/docs/transformers/v5.23.0/ko/main_classes/tokenizer#transformers.BatchEncoding):

- **input_ids** -- 모델에 입력할 토큰 ID 목록.

  [입력 ID란 무엇인가요?](../glossary#input-ids)

- **token_type_ids** -- 모델에 입력할 토큰 유형 ID 목록(`return_token_type_ids=True`인 경우 또는 `self.model_input_names`에 *"token_type_ids"*가 포함된 경우).

  [토큰 타입 ID란 무엇인가요?](../glossary#token-type-ids)

- **attention_mask** -- 모델이 어떤 토큰에 주의를 기울여야 하는지 지정하는 인덱스 목록(`return_attention_mask=True`인 경우 또는 `self.model_input_names`에 *"attention_mask"*가 포함된 경우).

  [어텐션 마스크란 무엇인가요?](../glossary#attention-mask)

- **overflowing_tokens** -- 넘친 토큰 시퀀스 목록(`max_length`이 지정되고 `return_overflowing_tokens=True`인 경우).
- **num_truncated_tokens** -- 잘림된 토큰의 개수(`max_length`가 지정되고 `return_overflowing_tokens=True`인 경우).
- **special_tokens_mask** -- 0과 1의 목록으로, 1은 추가된 특수 토큰을, 0은 일반 시퀀스 토큰을 나타냅니다(`add_special_tokens=True`이고 `return_special_tokens_mask=True`인 경우).
- **length** -- 입력의 길이 (`return_length=True`인 경우)

하나 이상의 시퀀스 또는 하나 이상의 시퀀스 쌍을 토큰화하고 모델에 맞게 준비하는 주요 메서드입니다.

#### batch_decode[[transformers.Wav2Vec2PhonemeCTCTokenizer.batch_decode]]

```python
batch_decode(sequences: typing.Union[list[int], list[list[int]], numpy.ndarray, ForwardRef('torch.Tensor')], skip_special_tokens: bool = False, clean_up_tokenization_spaces: bool | None = None, output_char_offsets: bool = False, **kwargs)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/wav2vec2_phoneme/tokenization_wav2vec2_phoneme.py#L505)

**매개변수:**

sequences (`Union[list[int], list[list[int]], np.ndarray, torch.Tensor]`) : 토큰화된 입력 ID 목록. `__call__` 메서드를 사용하여 얻을 수 있습니다.

skip_special_tokens (`bool`, *선택 사항*, 기본값 `False`) : 디코딩 시 특수 토큰을 제거할지 여부.

clean_up_tokenization_spaces (`bool`, *선택 사항*) : 토큰화 공백을 정리할지 여부.

output_char_offsets (`bool`, *선택 사항*, 기본값 `False`) : 문자 오프셋을 출력할지 여부입니다. 문자 오프셋은 샘플링률과 모델 다운샘플링률을 조합하여 전사된 문자의 타임스탬프를 계산하는 데 사용할 수 있습니다. `output_word_offsets`를 어떻게 활용하는지 더 잘 이해하려면 `~models.wav2vec2.tokenization_wav2vec2.decode`의 예시를 참고하세요. `~model.wav2vec2_phoneme.tokenization_wav2vec2_phoneme.batch_decode`는 음소와 배치 출력에 대해 유사하게 작동합니다.

kwargs (추가 키워드 인자, *선택 사항*) : 기본 모델의 특정 decode 메서드에 전달됩니다.

**반환값:** `list[str]` 또는 `~models.wav2vec2.tokenization_wav2vec2_phoneme.Wav2Vec2PhonemeCTCTokenizerOutput`

복호화된 문장. `output_char_offsets == True`인 경우 `~models.wav2vec2.tokenization_wav2vec2_phoneme.Wav2Vec2PhonemeCTCTokenizerOutput`가 됩니다.

decode를 호출하여 토큰 ID의 리스트로 된 리스트를 문자열의 리스트로 변환합니다.

#### decode[[transformers.Wav2Vec2PhonemeCTCTokenizer.decode]]

```python
decode(token_ids: typing.Union[int, list[int], numpy.ndarray, ForwardRef('torch.Tensor')], skip_special_tokens: bool = False, clean_up_tokenization_spaces: bool | None = None, output_char_offsets: bool = False, **kwargs)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/wav2vec2_phoneme/tokenization_wav2vec2_phoneme.py#L449)

**매개변수:**

token_ids (`Union[int, list[int], np.ndarray, torch.Tensor]`) : 토큰화된 입력 ID 목록. `__call__` 메서드를 사용하여 얻을 수 있습니다.

skip_special_tokens (`bool`, *선택 사항*, 기본값 `False`) : 디코딩 시 특수 토큰을 제거할지 여부.

clean_up_tokenization_spaces (`bool`, *선택 사항*) : 토큰화 공백을 정리할지 여부.

output_char_offsets (`bool`, *선택 사항*, 기본값 `False`) : 문자 오프셋을 출력할지 여부입니다. 문자 오프셋은 샘플링률과 모델 다운샘플링률을 조합하여 전사된 문자의 타임스탬프를 계산하는 데 사용할 수 있습니다. `output_word_offsets`를 어떻게 활용하는지 더 잘 이해하려면 `~models.wav2vec2.tokenization_wav2vec2.decode`의 예시를 참고하세요. `~model.wav2vec2_phoneme.tokenization_wav2vec2_phoneme.batch_decode`도 음소(phoneme)에 대해 동일한 방식으로 작동합니다.

kwargs (추가 키워드 인자, *선택 사항*) : 기본 모델의 특정 decode 메서드에 전달됩니다.

**반환값:** `str` 또는 `~models.wav2vec2.tokenization_wav2vec2_phoneme.Wav2Vec2PhonemeCTCTokenizerOutput`

복호화된 문장. `output_char_offsets == True`인 경우 `~models.wav2vec2.tokenization_wav2vec2_phoneme.Wav2Vec2PhonemeCTCTokenizerOutput`가 됩니다.

토크나이저와 어휘를 사용하여 문자열의 id 시퀀스를 변환하며, 특수 토큰 제거 및 토크나이제이션 공간 정리 옵션을 제공합니다.

`self.convert_tokens_to_string(self.convert_ids_to_tokens(token_ids))`를 실행하는 것과 유사합니다.

#### 음소화[[transformers.Wav2Vec2PhonemeCTCTokenizer.phonemize]]

```python
phonemize(text: str, phonemizer_lang: str | None = None)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/wav2vec2_phoneme/tokenization_wav2vec2_phoneme.py#L252)

