# Wav2Vec2Phoneme

## Visão geral

O modelo Wav2Vec2Phoneme foi proposto em [Simple and Effective Zero-shot Cross-lingual Phoneme Recognition (Xu et al., 2021)](https://huggingface.co/papers/2109.11680) por Qiantong Xu, Alexei Baevski e Michael Auli.

O resumo do artigo é o seguinte:

*Os avanços recentes em auto-treinamento, pré-treinamento auto-supervisionado e aprendizado não supervisionado permitiram sistemas de reconhecimento de fala de alto desempenho sem nenhum dado rotulado. No entanto, em muitos casos, há dados rotulados disponíveis para idiomas relacionados que não são utilizados por esses métodos. Este artigo estende trabalhos anteriores sobre transferência de aprendizado cross-lingual zero-shot ao ajustar finamente um modelo wav2vec 2.0 pré-treinado multilíngue para transcrever idiomas não vistos. Isso é feito mapeando os fonemas dos idiomas de treinamento para o idioma de destino usando características articulatórias. Os experimentos mostram que esse método simples supera significativamente trabalhos anteriores que introduziram arquiteturas específicas para a tarefa e usaram apenas parte de um modelo pré-treinado monolíngue.*

Os checkpoints relevantes podem ser encontrados em https://huggingface.co/models?other=phoneme-recognition.

Este modelo foi contribuído por [patrickvonplaten](https://huggingface.co/patrickvonplaten)

O código original pode ser encontrado [aqui](https://github.com/pytorch/fairseq/tree/master/fairseq/models/wav2vec).

## Dicas de uso

- Wav2Vec2Phoneme usa exatamente a mesma arquitetura que Wav2Vec2
- Wav2Vec2Phoneme é um modelo de fala que aceita um array de float correspondente à forma de onda bruta do sinal de fala.
- O modelo Wav2Vec2Phoneme foi treinado usando classificação temporal conexionista (CTC), portanto a saída do modelo precisa ser decodificada usando [Wav2Vec2PhonemeCTCTokenizer](/docs/transformers/main/pt/model_doc/wav2vec2_phoneme#transformers.Wav2Vec2PhonemeCTCTokenizer).
- Wav2Vec2Phoneme pode ser ajustado em várias línguas ao mesmo tempo e decodificar línguas não vistas em uma única passagem direta para uma sequência de fonemas
- Por padrão, o modelo gera uma sequência de fonemas. Para transformar os fonemas em uma sequência de palavras, é necessário utilizar um dicionário e um modelo de linguagem.

A arquitetura do Wav2Vec2Phoneme é baseada no modelo Wav2Vec2; para referência da API, consulte a página de documentação do [`Wav2Vec2`](wav2vec2), exceto pelo 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)
```

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

**Parâmetros:**

vocab_file (`str`) : Arquivo contendo o vocabulário.

bos_token (`str`, *opcional*, padrão `"<s>"`) : O token de início de frase.

eos_token (`str`, *opcional*, padrão `"</s>"`) : O token de fim de sentença.

unk_token (`str`, *opcional*, padrão `"<unk>"`) : O token desconhecido. Um token que não está no vocabulário não pode ser convertido em um ID e é definido como este token em vez disso.

pad_token (`str`, *opcional*, padrão `"<pad>"`) : O token usado para preenchimento, por exemplo, ao agrupar sequências de comprimentos diferentes.

do_phonemize (`bool`, *opcional*, padrão `True`) : Se o tokenizer deve fonetizar a entrada ou não. Somente se uma sequência de fonemas for passada ao tokenizer, `do_phonemize` deve ser definido como `False`.

phonemizer_lang (`str`, *opcional*, padrão `"en-us"`) : O idioma do conjunto de fonemas para o qual o tokenizer deve fonetizar o texto de entrada.

phonemizer_backend (`str`, *opcional*. padrão é `"espeak"`) : A biblioteca de fonetização de backend que deve ser usada pela biblioteca phonemizer. O padrão é `espeak-ng`. Consulte o [pacote phonemizer](https://github.com/bootphon/phonemizer#readme). para mais informações.

- ****kwargs** : Argumentos de palavra-chave adicionais passados para [PreTrainedTokenizer](/docs/transformers/main/pt/main_classes/tokenizer#transformers.PythonBackend)

Constrói um tokenizador Wav2Vec2PhonemeCTC.

Este tokenizer herda de [PreTrainedTokenizer](/docs/transformers/main/pt/main_classes/tokenizer#transformers.PythonBackend), que contém alguns dos principais métodos. Os usuários devem consultar a superclasse para mais informações sobre esses métodos.

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

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/tokenization_utils_base.py#L2449)

**Parâmetros:**

text (`str`, `list[str]`, `list[list[str]]`, *opcional*) : A sequência ou lote de sequências a ser codificada. Cada sequência pode ser uma string ou uma lista de strings (string pretokenizada). Se as sequências forem fornecidas como lista de strings (pretokenizadas), você deve definir `is_split_into_words=True` (para eliminar a ambiguidade com um lote de sequências).

text_pair (`str`, `list[str]`, `list[list[str]]`, *opcional*) : A sequência ou lote de sequências a ser codificada. Cada sequência pode ser uma string ou uma lista de strings (string pretokenizada). Se as sequências forem fornecidas como lista de strings (pretokenizadas), você deve definir `is_split_into_words=True` (para eliminar a ambiguidade com um lote de sequências).

text_target (`str`, `list[str]`, `list[list[str]]`, *opcional*) : A sequência ou lote de sequências a serem codificadas como textos de destino. Cada sequência pode ser uma string ou uma lista de strings (string pretokenizada). Se as sequências forem fornecidas como lista de strings (pretokenizadas), você deve definir `is_split_into_words=True` (para eliminar a ambiguidade com um lote de sequências).

text_pair_target (`str`, `list[str]`, `list[list[str]]`, *opcional*) : A sequência ou lote de sequências a serem codificadas como textos de destino. Cada sequência pode ser uma string ou uma lista de strings (string pretokenizada). Se as sequências forem fornecidas como lista de strings (pretokenizadas), você deve definir `is_split_into_words=True` (para eliminar a ambiguidade com um lote de sequências).

tokenizer_kwargs (`dict[str, Any]`, *opcional*) : Kwargs adicionais para passar ao tokenizer. Eles serão mesclados com os parâmetros explícitos e outros kwargs, com os parâmetros explícitos tendo precedência.

add_special_tokens (`bool`, *opcional*, padrão `True`) : Indica se tokens especiais devem ser adicionados ao codificar as sequências. Isso utiliza a função subjacente `PretrainedTokenizerBase.build_inputs_with_special_tokens`, que define quais tokens são adicionados automaticamente aos ids de entrada. Isso é útil se você deseja adicionar automaticamente tokens `bos` ou `eos`.

padding (`bool`, `str` ou [PaddingStrategy](/docs/transformers/main/pt/internal/file_utils#transformers.utils.PaddingStrategy), *opcional*, padrão `False`) : Ativa e controla o padding. Aceita os seguintes valores:  - `True` ou `'longest'`: Preenche até a sequência mais longa do lote (ou não aplica padding se apenas uma sequência for fornecida). - `'max_length'`: Preenche até o comprimento máximo especificado com o argumento `max_length` ou até o comprimento máximo aceitável de entrada para o modelo, caso esse argumento não seja fornecido. - `False` ou `'do_not_pad'` (padrão): Sem padding (ou seja, pode gerar um lote com sequências de comprimentos diferentes).

truncation (`bool`, `str` ou [TruncationStrategy](/docs/transformers/main/pt/internal/tokenization_utils#transformers.tokenization_utils_base.TruncationStrategy), *opcional*, padrão `False`) : Ativa e controla a truncagem. Aceita os seguintes valores:  - `True` ou `'longest_first'`: Trunca para um comprimento máximo especificado com o argumento `max_length` ou para o comprimento máximo de entrada aceitável para o modelo, caso esse argumento não seja fornecido. Isso trunca token por token, removendo um token da sequência mais longa do par, se um par de sequências (ou um lote de pares) for fornecido. - `'only_first'`: Trunca para um comprimento máximo especificado com o argumento `max_length` ou para o comprimento máximo de entrada aceitável para o modelo, caso esse argumento não seja fornecido. Isso trunca apenas a primeira sequência de um par, se um par de sequências (ou um lote de pares) for fornecido. - `'only_second'`: Trunca para um comprimento máximo especificado com o argumento `max_length` ou para o comprimento máximo de entrada aceitável para o modelo, caso esse argumento não seja fornecido. Isso trunca apenas a segunda sequência de um par, se um par de sequências (ou um lote de pares) for fornecido. - `False` ou `'do_not_truncate'` (padrão): Sem truncagem (ou seja, pode gerar um lote com comprimentos de sequência maiores que o tamanho máximo de entrada admissível do modelo).

max_length (`int`, *opcional*) : Controla o comprimento máximo a ser usado por um dos parâmetros de truncamento/preenchimento. Se não for definido ou for definido como `None`, será usado o comprimento máximo predefinido do modelo, caso um dos parâmetros de truncamento/preenchimento exija um comprimento máximo. Se o modelo não tiver um comprimento máximo de entrada específico (como o XLNet), o truncamento/preenchimento até um comprimento máximo será desativado.

stride (`int`, *opcional*, padrão 0) : Se definido como um número junto com `max_length`, os tokens excedentes retornados quando `return_overflowing_tokens=True` conterão alguns tokens do final da sequência truncada retornada, para fornecer alguma sobreposição entre as sequências truncada e excedente. O valor deste argumento define o número de tokens sobrepostos.

is_split_into_words (`bool`, *opcional*, padrão `False`) : Indica se a entrada já está pré-tokenizada (por exemplo, dividida em palavras). Se definido como `True`, o tokenizer assume que a entrada já foi dividida em palavras (por exemplo, separando por espaços em branco) e a tokenizará. Isso é útil para NER ou classificação de tokens.

pad_to_multiple_of (`int`, *opcional*) : Se definido, a sequência será preenchida até um múltiplo do valor fornecido. Exige que `padding` esteja ativado. Isso é especialmente útil para habilitar o uso de Tensor Cores em hardware NVIDIA com capacidade de computação `>= 7.5` (Volta).

padding_side (`str`, *opcional*) : O lado em que o modelo deve ter padding aplicado. Deve ser selecionado entre ['right', 'left']. O valor padrão é obtido do atributo de classe com o mesmo nome.

return_tensors (`str` ou [TensorType](/docs/transformers/main/pt/internal/file_utils#transformers.TensorType), *opcional*) : Se definido, retornará tensores em vez de lista de inteiros do Python. Os valores aceitos são:  - `'pt'`: Retorna objetos `torch.Tensor` do PyTorch. - `'np'`: Retorna objetos `np.ndarray` do Numpy.

return_token_type_ids (`bool`, *opcional*) : Se deve retornar os IDs de tipo de token. Se mantido no padrão, retornará os IDs de tipo de token de acordo com o padrão do tokenizer específico, definido pelo atributo `return_outputs`.  [O que são IDs de tipo de token?](../glossary#token-type-ids)

return_attention_mask (`bool`, *opcional*) : Indica se a máscara de atenção deve ser retornada. Se mantido o valor padrão, a máscara de atenção será retornada de acordo com o padrão do tokenizer específico, definido pelo atributo `return_outputs`.  [O que são máscaras de atenção?](../glossary#attention-mask)

return_overflowing_tokens (`bool`, *opcional*, padrão `False`) : Indica se as sequências de tokens que excedem o limite devem ser retornadas. Se um par de sequências de ids de entrada (ou um lote de pares) for fornecido com `truncation_strategy = longest_first` ou `True`, um erro será lançado em vez de retornar os tokens excedentes.

return_special_tokens_mask (`bool`, *opcional*, padrão `False`) : Se deve ou não retornar informações da máscara de tokens especiais.

return_offsets_mapping (`bool`, *opcional*, padrão `False`) : Indica se deve ou não retornar `(char_start, char_end)` para cada token. Isso está disponível apenas em tokenizadores rápidos que herdam de [PreTrainedTokenizerFast](/docs/transformers/main/pt/main_classes/tokenizer#transformers.TokenizersBackend); se estiver usando o tokenizador do Python, este método lançará `NotImplementedError`.

return_length  (`bool`, *opcional*, padrão `False`) : Indica se as comprimentos das entradas codificadas devem ser retornados.

verbose (`bool`, *opcional*, padrão `True`) : Se deve ou não exibir mais informações e avisos.

- ****kwargs** : passados para o método `self.tokenize()`

**Retorna:** [BatchEncoding](/docs/transformers/main/pt/main_classes/tokenizer#transformers.BatchEncoding)

Um [BatchEncoding](/docs/transformers/main/pt/main_classes/tokenizer#transformers.BatchEncoding) com os seguintes campos:

- **input_ids** -- Lista de ids de tokens a serem fornecidos a um modelo.

  [O que são IDs de entrada?](../glossary#input-ids)

- **token_type_ids** -- Lista de ids de tipo de token a serem fornecidos a um modelo (quando `return_token_type_ids=True` ou se *"token_type_ids"* estiver em `self.model_input_names`).

  [O que são IDs de tipo de token?](../glossary#token-type-ids)

- **attention_mask** -- Lista de índices que especifica quais tokens devem ser considerados pelo modelo (quando `return_attention_mask=True` ou se *"attention_mask"* estiver em `self.model_input_names`).

  [O que são máscaras de atenção?](../glossary#attention-mask)

- **overflowing_tokens** -- Lista de sequências de tokens excedentes (quando um `max_length` é especificado e `return_overflowing_tokens=True`).
- **num_truncated_tokens** -- Número de tokens truncados (quando um `max_length` é especificado e `return_overflowing_tokens=True`).
- **special_tokens_mask** -- Lista de 0s e 1s, em que 1 especifica tokens especiais adicionados e 0 especifica tokens regulares da sequência (quando `add_special_tokens=True` e `return_special_tokens_mask=True`).
- **length** -- O comprimento das entradas (quando `return_length=True`)

Método principal para tokenizar e preparar uma ou várias sequências ou um ou vários pares de sequências para o modelo.

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

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

**Parâmetros:**

sequences (`Union[list[int], list[list[int]], np.ndarray, torch.Tensor]`) : Lista de ids de entrada tokenizados. Pode ser obtido usando o método `__call__`.

skip_special_tokens (`bool`, *opcional*, padrão `False`) : Indica se os tokens especiais devem ser removidos durante a decodificação.

clean_up_tokenization_spaces (`bool`, *opcional*) : Se deve ou não limpar os espaços de tokenização.

output_char_offsets (`bool`, *opcional*, padrão `False`) : Se deve ou não imprimir os deslocamentos de caracteres. Os deslocamentos de caracteres podem ser usados em combinação com a taxa de amostragem e a taxa de redução de amostragem do modelo para calcular os carimbos de tempo dos caracteres transcritos.    Por favor, veja o Exemplo de `~models.wav2vec2.tokenization_wav2vec2.decode` para entender melhor como usar `output_word_offsets`. `~model.wav2vec2_phoneme.tokenization_wav2vec2_phoneme.batch_decode` funciona de forma análoga com fonemas e saída em lote.

kwargs (argumentos de palavra-chave adicionais, *opcional*) : Serão passados para o método de decodificação específico do modelo subjacente.

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

A frase decodificada. Será um `~models.wav2vec2.tokenization_wav2vec2_phoneme.Wav2Vec2PhonemeCTCTokenizerOutput` quando `output_char_offsets == True`.

Converta uma lista de listas de ids de tokens em uma lista de strings chamando 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)
```

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

**Parâmetros:**

token_ids (`Union[int, list[int], np.ndarray, torch.Tensor]`) : Lista de ids de entrada tokenizados. Pode ser obtido usando o método `__call__`.

skip_special_tokens (`bool`, *opcional*, padrão `False`) : Indica se os tokens especiais devem ser removidos durante a decodificação.

clean_up_tokenization_spaces (`bool`, *opcional*) : Se deve ou não limpar os espaços de tokenização.

output_char_offsets (`bool`, *opcional*, padrão `False`) : Se deve ou não imprimir os deslocamentos de caracteres. Os deslocamentos de caracteres podem ser usados em combinação com a taxa de amostragem e a taxa de redução de amostragem do modelo para calcular os carimbos de tempo dos caracteres transcritos.    Por favor, veja o Exemplo de `~models.wav2vec2.tokenization_wav2vec2.decode` para entender melhor como usar `output_word_offsets`. `~model.wav2vec2_phoneme.tokenization_wav2vec2_phoneme.batch_decode` funciona da mesma maneira com fonemas.

kwargs (argumentos de palavra-chave adicionais, *opcional*) : Serão passados para o método de decodificação específico do modelo subjacente.

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

A frase decodificada. Será um `~models.wav2vec2.tokenization_wav2vec2_phoneme.Wav2Vec2PhonemeCTCTokenizerOutput` quando `output_char_offsets == True`.

Converte uma sequência de ids em uma string, usando o tokenizer e o vocabulário, com opções para remover tokens especiais e limpar os espaços de tokenização.

Semelhante a executar `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)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/wav2vec2_phoneme/tokenization_wav2vec2_phoneme.py#L253)