# 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/main/ja/model_doc/wav2vec2_phoneme#transformers.Wav2Vec2PhonemeCTCTokenizer) を使用してデコードする必要があります。
- Wav2Vec2Phonemeは、複数の言語を同時にファインチューニングでき、一度のフォワードパスで未見の言語を音素のシーケンスにデコードできます
- デフォルトでは、モデルは音素のシーケンスを出力します。音素を単語のシーケンスに変換するには、辞書と言語モデルを利用する必要があります。

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/main/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 ライブラリで使用されるバックエンドの音素化ライブラリです。デフォルトは`espeak-ng`です。詳細については、[phonemizer パッケージ](https://github.com/bootphon/phonemizer#readme)を参照してください。

- ****kwargs** : [PreTrainedTokenizer](/docs/transformers/main/ja/main_classes/tokenizer#transformers.PythonBackend) に渡される追加のキーワード引数

Wav2Vec2PhonemeCTC トークナイザーを構築します。

このトークナイザーは、いくつかの主要なメソッドを含む[PreTrainedTokenizer](/docs/transformers/main/ja/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/main/src/transformers/tokenization_utils_base.py#L2449)

**パラメータ:**

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/main/ja/internal/file_utils#transformers.utils.PaddingStrategy)、*optional*、デフォルトは `False`) : パディングの有効化と制御を行います。以下の値を受け取ります:  - `True` または `'longest'`: バッチ内の最長のシーケンスの長さにパディングします（単一のシーケンスのみが提供された場合は、パディングを行いません）。 - `'max_length'`: 引数 `max_length` で指定された最大長、またはその引数が提供されていない場合はモデルが受け入れ可能な最大入力長までパディングします。 - `False` または `'do_not_pad'`（デフォルト）: パディングを行いません（つまり、長さが異なるシーケンスのバッチを出力できます）。

truncation (`bool`、`str` または [TruncationStrategy](/docs/transformers/main/ja/internal/tokenization_utils#transformers.tokenization_utils_base.TruncationStrategy)、*optional*、デフォルトは `False`) : トランケーションを有効化し、制御します。以下の値を受け取ります: - `True` または `'longest_first'`: 引数 `max_length` で指定された最大長、またはその引数が指定されていない場合はモデルが許容する最大入力長まで切り詰めます。ペアのシーケンス（またはペアのバッチ）が提供されている場合、ペアの中で最も長いシーケンスからトークン単位で1トークンずつ削除します。 - `'only_first'`: 引数 `max_length` で指定された最大長、またはその引数が指定されていない場合はモデルが許容する最大入力長まで切り詰めます。ペアのシーケンス（またはペアのバッチ）が提供されている場合、ペアの最初のシーケンスのみを切り詰めます。 - `'only_second'`: 引数 `max_length` で指定された最大長、またはその引数が指定されていない場合はモデルが許容する最大入力長まで切り詰めます。ペアのシーケンス（またはペアのバッチ）が提供されている場合、ペアの2番目のシーケンスのみを切り詰めます。 - `False` または `'do_not_truncate'`（デフォルト）: トランケーションを行いません（つまり、モデルが許容する最大入力サイズを超えるシーケンス長を持つバッチを出力する可能性があります）。

max_length (`int`, *optional*) : 切り詰め/パディングパラメータのいずれかによって使用される最大長を制御します。 未設定のまま、または `None` に設定されている場合、切り詰め/パディングパラメータのいずれかが最大長を必要とする場合、事前に定義されたモデルの最大長が使用されます。 モデルに特定の最大入力長がない場合（XLNet など）、最大長への切り詰め/パディングは無効になります。

stride (`int`、*optional*、デフォルト値は 0) : `max_length` とともに数値が設定されている場合、`return_overflowing_tokens=True` のときに返されるオーバーフローしたトークンは、切り詰められたシーケンスの末尾の一部のトークンを含み、切り詰められたシーケンスとオーバーフローしたシーケンスの間に重複部分を持たせます。この引数の値は、重複するトークンの数を定義します。

is_split_into_words (`bool`、*任意*、デフォルトは `False`) : 入力がすでに事前トークン化済み（例：単語に分割済み）かどうかを示します。`True` に設定すると、トークナイザーは入力がすでに単語に分割済み（たとえば空白で分割済み）であると仮定し、それをトークン化します。これは NER やトークン分類に有用です。

pad_to_multiple_of (`int`, *optional*) : 設定すると、シーケンスを指定された値の倍数にパディングします。`padding` が有効になっている必要があります。これは、計算能力が `>= 7.5` (Volta) の NVIDIA ハードウェア上で Tensor Cores を使用可能にするために特に有用です。

padding_side (`str`, *任意*) : モデルにパディングを適用する側です。['right', 'left'] から選択する必要があります。デフォルト値は、同名のクラス属性から取得されます。

return_tensors (`str` または [TensorType](/docs/transformers/main/ja/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`、*省略可*) : アテンションマスクを返すかどうか。デフォルトのままにすると、`return_outputs` 属性で定義される特定のトークナイザーのデフォルトに従って、アテンションマスクを返します。  [アテンションマスクとは?](../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/main/ja/main_classes/tokenizer#transformers.TokenizersBackend)を継承する fast tokenizer のみで利用可能であり、Python の tokenizer を使用している場合、このメソッドは`NotImplementedError`を送出します。

return_length (`bool`、*任意*、デフォルトは`False`) : エンコードされた入力の長さを返すかどうか。

verbose (`bool`、*任意*、デフォルトは `True`) : 詳細な情報や警告を表示するかどうか。

- ****kwargs** : `self.tokenize()` メソッドに渡されます

**戻り値:** [BatchEncoding](/docs/transformers/main/ja/main_classes/tokenizer#transformers.BatchEncoding)

以下のフィールドを持つ[BatchEncoding](/docs/transformers/main/ja/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`の場合）

1 つ以上のシーケンス、または 1 つ以上のシーケンスのペアをトークナイズし、モデル用に準備するための主要なメソッドです。

#### 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/main/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 （追加のキーワード引数、*任意*）：基礎となるモデル固有のデコードメソッドに渡されます。

**戻り値:** `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/main/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` も、音素に対して同じように動作します。

kwargs （追加のキーワード引数、*任意*）：基礎となるモデル固有のデコードメソッドに渡されます。

**戻り値:** `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/main/src/transformers/models/wav2vec2_phoneme/tokenization_wav2vec2_phoneme.py#L253)