# mLUKE ## Visão geral O modelo mLUKE foi proposto em [mLUKE: The Power of Entity Representations in Multilingual Pretrained Language Models](https://huggingface.co/papers/2110.08151) por Ryokan Ri, Ikuya Yamada e Yoshimasa Tsuruoka. Trata-se de uma extensão multilíngue do [modelo LUKE](https://huggingface.co/papers/2010.01057) treinada com base no XLM-RoBERTa. É baseado no XLM-RoBERTa e adiciona embeddings de entidades, o que ajuda a melhorar o desempenho em diversas tarefas downstream que envolvem raciocínio sobre entidades, como reconhecimento de entidades nomeadas, resposta a perguntas extrativas, classificação de relações e conclusão de conhecimento no estilo cloze. O resumo do artigo é o seguinte: *Estudos recentes demonstraram que modelos de linguagem pré-treinados multilíngues podem ser aprimorados de forma eficaz com informações de alinhamento cross-lingual derivadas de entidades da Wikipédia. No entanto, os métodos existentes exploram as informações de entidades apenas no pré-treinamento e não utilizam explicitamente as entidades em tarefas downstream. Neste estudo, exploramos a eficácia de aproveitar representações de entidades para tarefas cross-lingual downstream. Treinamos um modelo de linguagem multilíngue com 24 idiomas utilizando representações de entidades e demonstramos que o modelo supera consistentemente os modelos pré-treinados baseados em palavras em diversas tarefas de transferência cross-lingual. Também analisamos o modelo, e a principal conclusão é que a incorporação de representações de entidades na entrada nos permite extrair recursos mais agnósticos em relação ao idioma. Além disso, avaliamos o modelo em uma tarefa de prompt cloze multilíngue com o conjunto de dados mLAMA. Mostramos que prompts baseados em entidades elicita conhecimento factual correto com mais probabilidade do que o uso de apenas representações de palavras.* Este modelo foi contribuído por [ryo0634](https://huggingface.co/ryo0634). O código original pode ser encontrado [aqui](https://github.com/studio-ousia/luke). ## Dicas de uso É possível inserir diretamente os pesos do mLUKE em um modelo LUKE, da seguinte forma: ```python from transformers import LukeModel model = LukeModel.from_pretrained("studio-ousia/mluke-base", device_map="auto") ``` Observe que o mLUKE possui seu próprio tokenizador, [MLukeTokenizer](/docs/transformers/main/pt/model_doc/mluke#transformers.MLukeTokenizer). Você pode inicializá-lo da seguinte forma: ```python from transformers import MLukeTokenizer tokenizer = MLukeTokenizer.from_pretrained("studio-ousia/mluke-base") ``` Como a arquitetura da mLUKE é equivalente à da LUKE, é possível consultar a [página de documentação da LUKE](luke) para obter todas as dicas, exemplos de código e notebooks. ## MLukeTokenizer[[transformers.MLukeTokenizer]] #### transformers.MLukeTokenizer[[transformers.MLukeTokenizer]] ```python transformers.MLukeTokenizer(bos_token = '~~', eos_token = '~~', sep_token = '', cls_token = '', unk_token = '', pad_token = '', mask_token = '', task = None, max_entity_length = 32, max_mention_length = 30, entity_1_token = '', entity_2_token = '', entity_unk_token = '[UNK]', entity_pad_token = '[PAD]', entity_mask_token = '[MASK]', entity_mask2_token = '[MASK2]', vocab: str | dict | list | None = None, entity_vocab: str | dict | list | None = None, **kwargs) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/mluke/tokenization_mluke.py#L129) **Parâmetros:** vocab_file (`str`) : Caminho para o arquivo de vocabulário. entity_vocab_file (`str`) : Caminho para o arquivo de vocabulário de entidades. bos_token (`str`, *opcional*, padrão `""`) : O token de início de sequência usado durante o pré-treinamento. Pode ser usado como token de classificador de sequência. Ao construir uma sequência usando tokens especiais, este não é o token utilizado para o início da sequência. O token utilizado é o `cls_token`. eos_token (`str`, *opcional*, padrão `""`) : O token de fim de sequência. Ao construir uma sequência usando tokens especiais, este não é o token utilizado para o fim da sequência. O token utilizado é o `sep_token`. sep_token (`str`, *opcional*, padrão `""`) : O token separador, usado ao montar uma sequência a partir de múltiplas sequências, por exemplo, duas sequências para classificação de sequência ou um texto e uma pergunta para resposta a perguntas. Também é usado como o último token de uma sequência montada com tokens especiais. cls_token (`str`, *opcional*, padrão `""`) : O token de classificador usado na classificação de sequência (classificação da sequência inteira, em vez da classificação por token). É o primeiro token da sequência quando esta é construída com tokens especiais. unk_token (`str`, *opcional*, padrão `""`) : 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 `""`) : O token usado para preenchimento, por exemplo, ao agrupar sequências de comprimentos diferentes. mask_token (`str`, *opcional*, padrão `""`) : O token usado para mascarar valores. Este é o token utilizado ao treinar este modelo com modelagem de linguagem mascarada. É o token que o modelo tentará prever. task (`str`, *opcional*) : Tarefa para a qual você deseja preparar sequências. Uma de `"entity_classification"`, `"entity_pair_classification"` ou `"entity_span_classification"`. Se você especificar este argumento, a sequência de entidades é criada automaticamente com base no(s) span(s) de entidade fornecido(s). max_entity_length (`int`, *opcional*, padrão 32) : O comprimento máximo de `entity_ids`. max_mention_length (`int`, *opcional*, padrão 30) : O número máximo de tokens dentro de um intervalo de entidade. entity_1_token (`str`, *opcional*, padrão ``) : O token especial usado para representar um trecho de entidade em uma sequência de tokens de palavras. Este token é usado apenas quando `task` está definido como `"entity_classification"` ou `"entity_pair_classification"`. entity_2_token (`str`, *opcional*, padrão ``) : O token especial usado para representar um intervalo de entidade em uma sequência de tokens de palavras. Este token é usado apenas quando `task` está definido como `"entity_pair_classification"`. additional_special_tokens (`list[str]`, *opcional*, padrão `["~~NOTUSED", "~~NOTUSED"]`) : Tokens especiais adicionais usados pelo tokenizer. sp_model_kwargs (`dict`, *opcional*) : Será passado para o método `SentencePieceProcessor.__init__()`. O [Python wrapper for SentencePiece](https://github.com/google/sentencepiece/tree/master/python) pode ser usado, entre outras coisas, para definir: - `enable_sampling`: Habilita a regularização de subpalavras. - `nbest_size`: Parâmetros de amostragem para unigramas. Inválido para BPE-Dropout. - `nbest_size = {0,1}`: Nenhuma amostragem é realizada. - `nbest_size > 1`: amostra dos resultados de nbest_size. - `nbest_size < 0`: assume que nbest_size é infinito e amostra de todas as hipóteses (lattice) usando o algoritmo forward-filtering-and-backward-sampling. - `alpha`: Parâmetro de suavização para amostragem de unigramas e probabilidade de dropout para operações de mesclagem no BPE-dropout. sp_model (`SentencePieceProcessor`) : o processador *SentencePiece* utilizado em todas as conversões (string, tokens e IDs). Adaptado de [XLMRobertaTokenizer](/docs/transformers/main/pt/model_doc/xlm-roberta#transformers.XLMRobertaTokenizer) e [LukeTokenizer](/docs/transformers/main/pt/model_doc/luke#transformers.LukeTokenizer). Baseado em [SentencePiece](https://github.com/google/sentencepiece). Este tokenizer herda de [PreTrainedTokenizer](/docs/transformers/main/pt/main_classes/tokenizer#transformers.PythonBackend), que contém a maioria dos métodos principais. Os usuários devem consultar essa superclasse para obter mais informações sobre esses métodos. #### __call__[[transformers.MLukeTokenizer.__call__]] ```python __call__(text: str | list[str], text_pair: str | list[str] | None = None, entity_spans: list[tuple[int, int]] | list[list[tuple[int, int]]] | None = None, entity_spans_pair: list[tuple[int, int]] | list[list[tuple[int, int]]] | None = None, entities: list[str] | list[list[str]] | None = None, entities_pair: list[str] | list[list[str]] | None = None, add_special_tokens: bool = True, padding: bool | str | transformers.utils.generic.PaddingStrategy = False, truncation: bool | str | transformers.tokenization_utils_base.TruncationStrategy | None = None, max_length: int | None = None, max_entity_length: int | None = None, stride: int = 0, is_split_into_words: bool | None = False, pad_to_multiple_of: int | None = None, padding_side: str | None = None, return_tensors: str | transformers.utils.generic.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, **kwargs) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/mluke/tokenization_mluke.py#L469) **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) - **entity_ids** -- Lista de ids de entidades a serem fornecidas a um modelo. [O que são IDs de entrada?](../glossary#input-ids) - **entity_position_ids** -- Lista de posições de entidades na sequência de entrada a ser fornecida a um modelo. - **entity_token_type_ids** -- Lista de ids de tipo de token de entidade a serem fornecidos a um modelo (quando `return_token_type_ids=True` ou se *"entity_token_type_ids"* estiver em `self.model_input_names`). [O que são IDs de tipo de token?](../glossary#token-type-ids) - **entity_attention_mask** -- Lista de índices que especifica quais entidades devem ser consideradas pelo modelo (quando `return_attention_mask=True` ou se *"entity_attention_mask"* estiver em `self.model_input_names`). [O que são máscaras de atenção?](../glossary#attention-mask) - **entity_start_positions** -- Lista das posições iniciais das entidades na sequência de tokens de palavras (quando `task="entity_span_classification"`). - **entity_end_positions** -- Lista das posições finais das entidades na sequência de tokens de palavras (quando `task="entity_span_classification"`). - **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`) 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 preenchimento se apenas uma sequência for fornecida). - `'max_length'`: Preenche até o comprimento máximo especificado pelo 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 aceitável de entrada 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 o comprimento máximo especificado com o argumento `max_length` ou para o comprimento máximo aceitável de entrada do 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 aceitável de entrada 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 truncamento (ou seja, pode gerar um lote com comprimentos de sequência maiores que o tamanho máximo de entrada aceito pelo modelo). max_length (`int`, *opcional*): Controla o comprimento máximo a ser usado por um dos parâmetros de truncamento/padronização. If left unset or set to `None`, this will use the predefined model maximum length if a maximum length is required by one of the truncation/padding parameters. If the model has no specific maximum input length (like XLNet) truncation/padding to a maximum length will be deactivated. stride (`int`, *optional*, defaults to 0): If set to a number along with `max_length`, the overflowing tokens returned when `return_overflowing_tokens=True` will contain some tokens from the end of the truncated sequence returned to provide some overlap between truncated and overflowing sequences. The value of this argument defines the number of overlapping tokens. is_split_into_words (`bool`, *optional*, defaults to `False`): Whether or not the input is already pre-tokenized (e.g., split into words). If set to `True`, the tokenizer assumes the input is already split into words (for instance, by splitting it on whitespace) which it will tokenize. This is useful for NER or token classification. pad_to_multiple_of (`int`, *optional*): If set will pad the sequence to a multiple of the provided value. Requires `padding` to be activated. This is especially useful to enable the use of Tensor Cores on NVIDIA hardware with compute capability `>= 7.5` (Volta). padding_side (`str`, *optional*): The side on which the model should have padding applied. Should be selected between ['right', 'left']. Default value is picked from the class attribute of the same name. return_tensors (`str` or [TensorType](/docs/transformers/main/pt/internal/file_utils#transformers.TensorType), *optional*): If set, will return tensors instead of list of python integers. Acceptable values are: - `'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*): Se deve retornar a máscara de atenção. Se mantido no padrão, retornará a máscara de atenção 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`): Se deve ou não retornar sequências de tokens excedentes. 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 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`): 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 em Python, este método lançará `NotImplementedError`. return_length (`bool`, *opcional*, padrão `False`): Indica se os comprimentos das entradas codificadas devem ser retornados. verbose (`bool`, *opcional*, padrão `True`): Indica se mais informações e avisos devem ser exibidos. **kwargs: passados para o método `self.tokenize()` #### save_vocabulary[[transformers.MLukeTokenizer.save_vocabulary]] ```python save_vocabulary(save_directory: str, filename_prefix: str | None = None) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/mluke/tokenization_mluke.py#L1703) Salve apenas o arquivo de vocabulário de entidades. O tokenizer.json é salvo pelo TokenizersBackend pai.