# Wav2Vec2Phoneme

## Aperçu

Le modèle Wav2Vec2Phoneme a été proposé dans [Simple and Effective Zero-shot Cross-lingual Phoneme Recognition (Xu et al., 2021)](https://huggingface.co/papers/2109.11680) par Qiantong Xu, Alexei Baevski et Michael Auli.

L'abstract de l'article est le suivant :

*Les progrès récents en matière d’auto-entraînement, de pré-entraînement auto-supervisé et d’apprentissage non supervisé ont permis de mettre au point des systèmes de reconnaissance vocale performants sans aucune donnée étiquetée. Toutefois, dans de nombreux cas, des données étiquetées sont disponibles pour des langues apparentées, mais elles ne sont pas exploitées par ces méthodes. Cet article étend les travaux antérieurs sur le transfert interlinguistique en zéro tirage en ajustant finement un modèle wav2vec 2.0 pré-entraîné multilingue afin de transcrire des langues inconnues. Cela est réalisé en associant les phonèmes des langues d’entraînement à la langue cible à l’aide de caractéristiques articulatoires. Les expériences montrent que cette méthode simple surpasse nettement les travaux antérieurs, qui introduisaient des architectures spécifiques à la tâche et n’utilisaient qu’une partie d’un modèle pré-entraîné monolingue.*

Les points de contrôle pertinents peuvent être trouvés sous https://huggingface.co/models?other=phoneme-recognition.

Ce modèle a été contribué par [patrickvonplaten](https://huggingface.co/patrickvonplaten)

Le code original peut être trouvé [ici](https://github.com/pytorch/fairseq/tree/master/fairseq/models/wav2vec).

## Conseils d'utilisation

- Wav2Vec2Phoneme utilise exactement la même architecture que Wav2Vec2
- Wav2Vec2Phoneme est un modèle de parole qui accepte un tableau de nombres flottants correspondant à la forme d’onde brute du signal de parole.
- Le modèle Wav2Vec2Phoneme a été entraîné à l'aide de la classification temporelle connexionniste (CTC), il est donc nécessaire de décoder sa sortie à l'aide de [Wav2Vec2PhonemeCTCTokenizer](/docs/transformers/v5.23.0/fr/model_doc/wav2vec2_phoneme#transformers.Wav2Vec2PhonemeCTCTokenizer).
- Wav2Vec2Phoneme peut être affiné simultanément sur plusieurs langues et décoder des langues non vues en une seule passe avant vers une séquence de phonèmes
- Par défaut, le modèle produit une séquence de phonèmes. Pour transformer les phonèmes en une séquence de mots, il convient d'utiliser un dictionnaire et un modèle de langage.

L'architecture de Wav2Vec2Phoneme est basée sur le modèle Wav2Vec2. Pour la référence de l'API, consultez la page de documentation de [`Wav2Vec2`](wav2vec2), à l'exception du tokenizer.

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

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

**Paramètres :**

vocab_file (`str`) : Fichier contenant le vocabulaire.

bos_token (`str`, *facultatif*, par défaut `"<s>"`) : Jeton de début de phrase.

eos_token (`str`, *facultatif*, valeur par défaut `"</s>"`) : Jeton de fin de phrase.

unk_token (`str`, *facultatif*, par défaut `"<unk>"`) : Le jeton inconnu. Un jeton qui n'est pas dans le vocabulaire ne peut pas être converti en identifiant et est remplacé par ce jeton.

pad_token (`str`, *facultatif*, par défaut `"<pad>"`) : le jeton utilisé pour le bourrage, par exemple lors du groupement de séquences de longueurs différentes.

do_phonemize (`bool`, *facultatif*, valeur par défaut `True`) : Indique si le tokenizer doit phonétiser l'entrée ou non. Si une séquence de phonèmes est transmise au tokenizer, `do_phonemize` doit être défini sur `False`.

phonemizer_lang (`str`, *facultatif*, valeur par défaut `"en-us"`) : La langue de l'ensemble de phonèmes vers lequel le tokenizer doit phonétiser le texte d'entrée.

phonemizer_backend (`str`, *facultatif*. valeur par défaut `"espeak"`) : La bibliothèque de phonétisation backend qui doit être utilisée par la bibliothèque phonemizer. La valeur par défaut est `espeak-ng`. Consultez le [paquet phonemizer](https://github.com/bootphon/phonemizer#readme) pour plus d'informations.

- ****kwargs** : Arguments supplémentaires passés à [PreTrainedTokenizer](/docs/transformers/v5.23.0/fr/main_classes/tokenizer#transformers.PythonBackend)

Construit un tokeniseur Wav2Vec2PhonemeCTC.

Ce tokenizer hérite de [PreTrainedTokenizer](/docs/transformers/v5.23.0/fr/main_classes/tokenizer#transformers.PythonBackend), qui contient certaines des principales méthodes. Les utilisateurs doivent se reporter à la classe parente pour plus d’informations sur ces méthodes.

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

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

**Paramètres :**

text (`str`, `list[str]`, `list[list[str]]`, *facultatif*) : La séquence ou le lot de séquences à encoder. Chaque séquence peut être une chaîne de caractères ou une liste de chaînes de caractères (chaînes pré-tokenisées). Si les séquences sont fournies sous forme de liste de chaînes de caractères (pré-tokenisées), vous devez définir `is_split_into_words=True` (pour lever l'ambiguïté avec un lot de séquences).

text_pair (`str`, `list[str]`, `list[list[str]]`, *facultatif*) : La séquence ou le lot de séquences à encoder. Chaque séquence peut être une chaîne de caractères ou une liste de chaînes de caractères (chaînes pré-tokenisées). Si les séquences sont fournies sous forme de liste de chaînes de caractères (pré-tokenisées), vous devez définir `is_split_into_words=True` (pour lever l'ambiguïté avec un lot de séquences).

text_target (`str`, `list[str]`, `list[list[str]]`, *facultatif*) : La séquence ou le lot de séquences à encoder en tant que textes cibles. Chaque séquence peut être une chaîne de caractères ou une liste de chaînes de caractères (chaîne pré-tokenisée). Si les séquences sont fournies sous forme de liste de chaînes de caractères (pré-tokenisées), vous devez définir `is_split_into_words=True` (pour lever l’ambiguïté avec un lot de séquences).

text_pair_target (`str`, `list[str]`, `list[list[str]]`, *facultatif*) : La séquence ou le lot de séquences à encoder en tant que textes cibles. Chaque séquence peut être une chaîne de caractères ou une liste de chaînes de caractères (chaîne pré-tokenisée). Si les séquences sont fournies sous forme de liste de chaînes de caractères (pré-tokenisées), vous devez définir `is_split_into_words=True` (pour lever l’ambiguïté avec un lot de séquences).

tokenizer_kwargs (`dict[str, Any]`, *facultatif*) : kwargs supplémentaires à passer au tokenizer. Ils seront fusionnés avec les paramètres explicites et les autres kwargs, les paramètres explicites ayant la priorité.

add_special_tokens (`bool`, *facultatif*, valeur par défaut `True`) : Indique s'il faut ajouter des jetons spéciaux lors de l'encodage des séquences. Cette opération utilise la fonction sous-jacente `PretrainedTokenizerBase.build_inputs_with_special_tokens`, qui définit les jetons ajoutés automatiquement aux identifiants d'entrée. Cela est utile si vous souhaitez ajouter automatiquement des jetons `bos` ou `eos`.

padding (`bool`, `str` ou [PaddingStrategy](/docs/transformers/v5.23.0/fr/internal/file_utils#transformers.utils.PaddingStrategy), *facultatif*, par défaut `False`) : Active et contrôle le bourrage. Accepte les valeurs suivantes :  - `True` ou `'longest'` : Bourrage jusqu'à la séquence la plus longue du lot (ou aucun bourrage si une seule séquence est fournie). - `'max_length'` : Bourrage jusqu'à une longueur maximale spécifiée avec l'argument `max_length` ou jusqu'à la longueur d'entrée maximale acceptable pour le modèle si cet argument n'est pas fourni. - `False` ou `'do_not_pad'` (par défaut) : Aucun bourrage (c'est-à-dire, peut produire un lot avec des séquences de longueurs différentes).

truncation (`bool`, `str` ou [TruncationStrategy](/docs/transformers/v5.23.0/fr/internal/tokenization_utils#transformers.tokenization_utils_base.TruncationStrategy), *facultatif*, par défaut `False`) : Active et contrôle la troncature. Accepte les valeurs suivantes :  - `True` ou `'longest_first'` : Tronque à une longueur maximale spécifiée par l'argument `max_length` ou à la longueur d'entrée maximale acceptable pour le modèle si cet argument n'est pas fourni. Cela tronque jeton par jeton, en supprimant un jeton de la séquence la plus longue de la paire si une paire de séquences (ou un lot de paires) est fournie. - `'only_first'` : Tronque à une longueur maximale spécifiée par l'argument `max_length` ou à la longueur d'entrée maximale acceptable pour le modèle si cet argument n'est pas fourni. Cela ne tronque que la première séquence d'une paire si une paire de séquences (ou un lot de paires) est fournie. - `'only_second'` : Tronque à une longueur maximale spécifiée par l'argument `max_length` ou à la longueur d'entrée maximale acceptable pour le modèle si cet argument n'est pas fourni. Cela ne tronque que la deuxième séquence d'une paire si une paire de séquences (ou un lot de paires) est fournie. - `False` ou `'do_not_truncate'` (par défaut) : Aucune troncature (c'est-à-dire, peut produire un lot avec des longueurs de séquences supérieures à la taille d'entrée maximale admissible du modèle).

max_length (`int`, *facultatif*) : Permet de contrôler la longueur maximale à utiliser par l'un des paramètres de troncature/remplissage. S'il n'est pas défini ou s'il est défini sur `None`, la longueur maximale prédéfinie du modèle sera utilisée si l'un des paramètres de troncature/remplissage exige une longueur maximale. Si le modèle n'a pas de longueur d'entrée maximale spécifique (comme XLNet), la troncature/remplissage à une longueur maximale sera désactivée.

stride (`int`, *facultatif*, valeur par défaut 0) : Si défini avec une valeur numérique en plus de `max_length`, les jetons en dépassement renvoyés lorsque `return_overflowing_tokens=True` contiendront certains jetons de la fin de la séquence tronquée renvoyée, afin d'assurer un chevauchement entre les séquences tronquées et celles en dépassement. La valeur de cet argument définit le nombre de jetons en chevauchement.

is_split_into_words (`bool`, *facultatif*, valeur par défaut `False`) : Indique si l'entrée est déjà pré-tokenisée (par exemple, découpée en mots). Si défini sur `True`, le tokenizer suppose que l'entrée est déjà découpée en mots (par exemple, en la séparant sur les espaces) et procède à sa tokenisation. Cela est utile pour la NER ou la classification de tokens.

pad_to_multiple_of (`int`, *facultatif*) : Si défini, la séquence sera rembourdie jusqu'à un multiple de la valeur fournie. Nécessite l'activation de `padding`. Cela est particulièrement utile pour permettre l'utilisation des Tensor Cores sur le matériel NVIDIA avec une capacité de calcul `>= 7.5` (Volta).

padding_side (`str`, *facultatif*) : Le côté sur lequel le modèle doit appliquer le bourrage. Doit être sélectionné parmi ['right', 'left']. La valeur par défaut est choisie à partir de l'attribut de classe du même nom.

return_tensors (`str` ou [TensorType](/docs/transformers/v5.23.0/fr/internal/file_utils#transformers.TensorType), *facultatif*) : Si défini, renverra des tenseurs au lieu d'une liste d'entiers Python. Les valeurs acceptables sont :  - `'pt'` : Renvoie des objets `torch.Tensor` de PyTorch. - `'np'` : Renvoie des objets `np.ndarray` de Numpy.

return_token_type_ids (`bool`, *facultatif*) : Indique s'il faut renvoyer les identifiants de type de jeton. Si la valeur par défaut est conservée, les identifiants de type de jeton seront renvoyés selon la valeur par défaut du tokeniseur spécifique, définie par l'attribut `return_outputs`.  [Qu'est-ce que les identifiants de type de jeton ?](../glossary#token-type-ids)

return_attention_mask (`bool`, *facultatif*) : Indique s'il faut retourner le masque d'attention. Si la valeur par défaut est conservée, le masque d'attention est retourné selon la valeur par défaut du tokenizer spécifique, définie par l'attribut `return_outputs`.  [Qu'est-ce que les masques d'attention ?](../glossary#attention-mask)

return_overflowing_tokens (`bool`, *facultatif*, valeur par défaut `False`) : Indique s'il faut ou non renvoyer les séquences de jetons en dépassement. Si une paire de séquences d'identifiants d'entrée (ou un lot de paires) est fournie avec `truncation_strategy = longest_first` ou `True`, une erreur est levée au lieu de renvoyer les jetons en dépassement.

return_special_tokens_mask (`bool`, *facultatif*, valeur par défaut `False`) : Indique s'il faut ou non retourner les informations du masque des jetons spéciaux.

return_offsets_mapping (`bool`, *facultatif*, valeur par défaut `False`) : Indique s'il faut ou non retourner `(char_start, char_end)` pour chaque jeton. Cette option n'est disponible que pour les tokenizers rapides héritant de [PreTrainedTokenizerFast](/docs/transformers/v5.23.0/fr/main_classes/tokenizer#transformers.TokenizersBackend) ; si vous utilisez le tokenizer Python, cette méthode lèvera `NotImplementedError`.

return_length  (`bool`, *facultatif*, par défaut `False`) : Indique s'il faut retourner les longueurs des entrées encodées.

verbose (`bool`, *facultatif*, par défaut `True`) : Indique s'il faut afficher plus d'informations et d'avertissements.

- ****kwargs** : transmis à la méthode `self.tokenize()`

**Retourne :** [BatchEncoding](/docs/transformers/v5.23.0/fr/main_classes/tokenizer#transformers.BatchEncoding)

Un [BatchEncoding](/docs/transformers/v5.23.0/fr/main_classes/tokenizer#transformers.BatchEncoding) avec les champs suivants :

- **input_ids** -- Liste des identifiants de jetons à fournir au modèle.

  [Qu'est-ce que les identifiants d'entrée ?](../glossary#input-ids)

- **token_type_ids** -- Liste des identifiants de type de jeton à fournir au modèle (lorsque `return_token_type_ids=True` ou si *"token_type_ids"* est présent dans `self.model_input_names`).

  [Qu'est-ce que les identifiants de type de jeton ?](../glossary#token-type-ids)

- **attention_mask** -- Liste d'indices spécifiant les jetons auxquels le modèle doit prêter attention (lorsque `return_attention_mask=True` ou si *"attention_mask"* est présent dans `self.model_input_names`).

  [Qu'est-ce que les masques d'attention ?](../glossary#attention-mask)

- **overflowing_tokens** -- Liste des séquences de jetons en dépassement (lorsqu'une `max_length` est spécifiée et `return_overflowing_tokens=True`).
- **num_truncated_tokens** -- Nombre de jetons tronqués (lorsqu'une `max_length` est spécifiée et `return_overflowing_tokens=True`).
- **special_tokens_mask** -- Liste de 0 et de 1, où 1 indique les jetons spéciaux ajoutés et 0 indique les jetons de séquence réguliers (lorsque `add_special_tokens=True` et `return_special_tokens_mask=True`).
- **length** -- La longueur des entrées (lorsque `return_length=True`)

Méthode principale pour tokeniser et préparer pour le modèle une ou plusieurs séquences ou une ou plusieurs paires de séquences.

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

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

**Paramètres :**

sequences (`Union[list[int], list[list[int]], np.ndarray, torch.Tensor]`) : Liste des identifiants d'entrée tokenisés. Peut être obtenue à l'aide de la méthode `__call__`.

skip_special_tokens (`bool`, *facultatif*, valeur par défaut `False`) : Indique s'il faut supprimer les jetons spéciaux lors du décodage.

clean_up_tokenization_spaces (`bool`, *facultatif*) : Indique s'il faut nettoyer ou non les espaces de tokenisation.

output_char_offsets (`bool`, *facultatif*, valeur par défaut `False`) : Indique s'il faut ou non afficher les décalages de caractères. Les décalages de caractères peuvent être utilisés en combinaison avec le taux d'échantillonnage et le taux de sous-échantillonnage du modèle pour calculer les horodatages des caractères transcrits.    Veuillez consulter l'exemple de `~models.wav2vec2.tokenization_wav2vec2.decode` pour mieux comprendre comment utiliser `output_word_offsets`. `~model.wav2vec2_phoneme.tokenization_wav2vec2_phoneme.batch_decode` fonctionne de manière analogue avec les phonèmes et la sortie par lots.

kwargs (arguments supplémentaires, *facultatifs*) : Seront transmis à la méthode de décodage spécifique du modèle sous-jacent.

**Retourne :** `list[str]` ou `~models.wav2vec2.tokenization_wav2vec2_phoneme.Wav2Vec2PhonemeCTCTokenizerOutput`

La phrase décodée. Sera un `~models.wav2vec2.tokenization_wav2vec2_phoneme.Wav2Vec2PhonemeCTCTokenizerOutput` lorsque `output_char_offsets == True`.

Convertir une liste de listes d'identifiants de jetons en une liste de chaînes en appelant decode.

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

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

**Paramètres :**

token_ids (`Union[int, list[int], np.ndarray, torch.Tensor]`) : Liste des identifiants d'entrée tokenisés. Peut être obtenue à l'aide de la méthode `__call__`.

skip_special_tokens (`bool`, *facultatif*, valeur par défaut `False`) : Indique s'il faut supprimer les jetons spéciaux lors du décodage.

clean_up_tokenization_spaces (`bool`, *facultatif*) : Indique s'il faut nettoyer ou non les espaces de tokenisation.

output_char_offsets (`bool`, *facultatif*, valeur par défaut `False`) : Indique s'il faut ou non afficher les décalages de caractères. Les décalages de caractères peuvent être utilisés en combinaison avec le taux d'échantillonnage et le taux de sous-échantillonnage du modèle pour calculer les horodatages des caractères transcrits. Veuillez consulter l'exemple de `~models.wav2vec2.tokenization_wav2vec2.decode` pour mieux comprendre comment utiliser `output_word_offsets`. `~model.wav2vec2_phoneme.tokenization_wav2vec2_phoneme.batch_decode` fonctionne de la même manière avec les phonèmes.

kwargs (arguments supplémentaires, *facultatifs*) : Seront transmis à la méthode de décodage spécifique du modèle sous-jacent.

**Retourne :** `str` ou `~models.wav2vec2.tokenization_wav2vec2_phoneme.Wav2Vec2PhonemeCTCTokenizerOutput`

La phrase décodée. Sera un `~models.wav2vec2.tokenization_wav2vec2_phoneme.Wav2Vec2PhonemeCTCTokenizerOutput` lorsque `output_char_offsets == True`.

Convertit une séquence d’identifiants en chaîne de caractères, en utilisant le tokenizer et le vocabulaire, avec des options pour supprimer les jetons spéciaux et nettoyer les espaces de tokenization.

Similaire à l'exécution de `self.convert_tokens_to_string(self.convert_ids_to_tokens(token_ids))`.

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

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

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

