# LayoutXLM

## Visão geral

O LayoutXLM foi proposto em [LayoutXLM: Multimodal Pre-training for Multilingual Visually-rich Document Understanding](https://huggingface.co/papers/2104.08836) por Yiheng Xu, Tengchao Lv, Lei Cui, Guoxin Wang, Yijuan Lu, Dinei Florencio, Cha Zhang e Furu Wei. Trata-se de uma extensão multilíngue do [modelo LayoutLMv2](https://huggingface.co/papers/2012.14740), treinado em 53 idiomas.

O resumo do artigo é o seguinte:

*O pré-treino multimodal com texto, layout e imagem alcançou recentemente desempenho SOTA em tarefas de compreensão de documentos visualmente ricos, o que demonstra o grande potencial do aprendizado conjunto entre diferentes modalidades. Neste artigo, apresentamos o LayoutXLM, um modelo pré-treinado multimodal para compreensão de documentos multilíngues, que visa superar as barreiras linguísticas na compreensão de documentos visualmente ricos. Para avaliar o LayoutXLM com precisão, também introduzimos um conjunto de dados de referência para compreensão de formulários multilíngues chamado XFUN, que inclui amostras de compreensão de formulários em 7 idiomas (chinês, japonês, espanhol, francês, italiano, alemão e português), e os pares chave-valor foram rotulados manualmente para cada idioma. Os resultados experimentais mostram que o modelo LayoutXLM superou significativamente os modelos pré-treinados cross-lingual SOTA existentes no conjunto de dados XFUN.*

Este modelo foi contribuído por [nielsr](https://huggingface.co/nielsr). O código original pode ser encontrado [aqui](https://github.com/microsoft/unilm).

## Dicas e exemplos de uso

É possível inserir diretamente os pesos do LayoutXLM em um modelo LayoutLMv2, da seguinte forma:

```python
from transformers import LayoutLMv2Model

model = LayoutLMv2Model.from_pretrained("microsoft/layoutxlm-base", device_map="auto")
```

Observe que o LayoutXLM possui seu próprio tokenizer, baseado em [LayoutXLMTokenizer](/docs/transformers/main/pt/model_doc/layoutxlm#transformers.LayoutXLMTokenizer)/[LayoutXLMTokenizerFast](/docs/transformers/main/pt/model_doc/layoutxlm#transformers.LayoutXLMTokenizer). Você pode inicializá-lo da seguinte forma:

```python
from transformers import LayoutXLMTokenizer

tokenizer = LayoutXLMTokenizer.from_pretrained("microsoft/layoutxlm-base")
```

Assim como no LayoutLMv2, você pode usar [LayoutXLMProcessor](/docs/transformers/main/pt/model_doc/layoutxlm#transformers.LayoutXLMProcessor) (que aplica internamente [LayoutLMv2ImageProcessor](/docs/transformers/main/pt/model_doc/layoutlmv2#transformers.LayoutLMv2ImageProcessor) e [LayoutXLMTokenizer](/docs/transformers/main/pt/model_doc/layoutxlm#transformers.LayoutXLMTokenizer)/[LayoutXLMTokenizerFast](/docs/transformers/main/pt/model_doc/layoutxlm#transformers.LayoutXLMTokenizer) em sequência) para preparar todos os dados para o modelo.

Como a arquitetura do LayoutXLM é equivalente à do LayoutLMv2, é possível consultar a [página de documentação do LayoutLMv2](layoutlmv2) para obter todas as dicas, exemplos de código e notebooks.

## LayoutXLMConfig[[transformers.LayoutXLMConfig]]

#### transformers.LayoutXLMConfig[[transformers.LayoutXLMConfig]]

```python
transformers.LayoutXLMConfig(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, is_encoder_decoder: bool = False, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, vocab_size: int = 30522, hidden_size: int = 768, num_hidden_layers: int = 12, num_attention_heads: int = 12, intermediate_size: int = 3072, hidden_act: str = 'gelu', hidden_dropout_prob: float | int = 0.1, attention_probs_dropout_prob: float | int = 0.1, max_position_embeddings: int = 512, type_vocab_size: int = 2, initializer_range: float = 0.02, layer_norm_eps: float = 1e-12, pad_token_id: int | None = 0, max_2d_position_embeddings: int = 1024, max_rel_pos: int = 128, rel_pos_bins: int = 32, fast_qkv: bool = True, max_rel_2d_pos: int = 256, rel_2d_pos_bins: int = 64, convert_sync_batchnorm: bool = True, image_feature_pool_shape: list[int] | tuple[int, ...] = (7, 7, 256), coordinate_size: int = 128, shape_size: int = 128, has_relative_attention_bias: bool = True, has_spatial_attention_bias: bool = True, has_visual_segment_embedding: bool = False, detectron2_config_args: dict | None = None)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/layoutxlm/configuration_layoutxlm.py#L35)

**Parâmetros:**

vocab_size (`int`, *opcional*, padrão `30522`) : Tamanho do vocabulário do modelo. Define o número de tokens diferentes que podem ser representados pelos `input_ids`.

hidden_size (`int`, *opcional*, padrão `768`) : Dimensão das representações ocultas.

num_hidden_layers (`int`, *opcional*, padrão `12`) : Número de camadas ocultas no decodificador do Transformer.

num_attention_heads (`int`, *opcional*, padrão `12`) : Número de cabeças de atenção para cada camada de atenção no decodificador do Transformer.

intermediate_size (`int`, *opcional*, padrão `3072`) : Dimensão das representações do MLP.

hidden_act (`str`, *opcional*, padrão `gelu`) : A função de ativação não linear (função ou string) no decodificador. Por exemplo, `"gelu"`, `"relu"`, `"silu"`, etc.

hidden_dropout_prob (`Union[float, int]`, *opcional*, padrão `0.1`) : A probabilidade de dropout para todas as camadas totalmente conectadas nos embeddings, encoder e pooler.

attention_probs_dropout_prob (`Union[float, int]`, *opcional*, padrão `0.1`) : A taxa de dropout para as probabilidades de atenção.

max_position_embeddings (`int`, *opcional*, padrão `512`) : O comprimento máximo de sequência com o qual este modelo pode ser utilizado.

type_vocab_size (`int`, *opcional*, padrão `2`) : O tamanho do vocabulário dos `token_type_ids`.

initializer_range (`float`, *opcional*, padrão `0.02`) : O desvio padrão do truncated_normal_initializer para inicializar todas as matrizes de pesos.

layer_norm_eps (`float`, *opcional*, padrão `1e-12`) : O epsilon usado pelas camadas de normalização de camada.

pad_token_id (`int`, *opcional*, padrão `0`) : ID do token usado para preenchimento no vocabulário.

max_2d_position_embeddings (`int`, *opcional*, padrão 1024) : O valor máximo com o qual a incorporação de posição 2D pode ser usada. Normalmente, defina este valor para algo grande, apenas por precaução (por exemplo, 1024).

max_rel_pos (`int`, *opcional*, padrão 128) : O número máximo de posições relativas a serem usadas no mecanismo de autoatenção.

rel_pos_bins (`int`, *opcional*, padrão 32) : O número de bins de posição relativa a serem usados no mecanismo de autoatenção.

fast_qkv (`bool`, *opcional*, padrão `True`) : Indica se deve ou não usar uma única matriz para as queries, keys e values nas camadas de autoatenção.

max_rel_2d_pos (`int`, *opcional*, padrão 256) : O número máximo de posições 2D relativas no mecanismo de autoatenção.

rel_2d_pos_bins (`int`, *opcional*, padrão 64) : O número de bins de posição relativa 2D no mecanismo de autoatenção.

convert_sync_batchnorm (`bool`, *opcional*, padrão `True`) : Indica se as camadas de normalização de lote devem ser convertidas em camadas de normalização de lote sincronizada.

image_feature_pool_shape (`list[int]`, *opcional*, padrão `[7, 7, 256]`) : A forma do mapa de recursos com pooling médio.

coordinate_size (`int`, *opcional*, padrão 128) : Dimensão dos embeddings de coordenadas.

shape_size (`int`, *opcional*, padrão 128) : Dimensão dos embeddings de largura e altura.

has_relative_attention_bias (`bool`, *opcional*, padrão `True`) : Indica se deve ou não usar um viés de atenção relativo no mecanismo de autoatenção.

has_spatial_attention_bias (`bool`, *opcional*, padrão `True`) : Indica se deve ou não usar um viés de atenção espacial no mecanismo de autoatenção.

has_visual_segment_embedding (`bool`, *opcional*, padrão `False`) : Indica se deve ou não adicionar embeddings de segmentos visuais.

detectron2_config_args (`dict`, *opcional*) : Dicionário contendo os argumentos de configuração do backbone visual do Detectron2. Consulte [este arquivo](https://github.com/microsoft/unilm/blob/master/layoutlmft/layoutlmft/models/layoutxlm/detectron2_config.py) para obter detalhes sobre os valores padrão.

Esta é a classe de configuração para armazenar a configuração de um LayoutxlmModel. Ela é usada para instanciar um modelo Layoutxlm de acordo com os argumentos especificados, definindo a arquitetura do modelo. Instanciar uma configuração com os padrões resultará em uma configuração semelhante à do [microsoft/layoutxlm-base](https://huggingface.co/microsoft/layoutxlm-base)

Os objetos de configuração herdam de [PreTrainedConfig](/docs/transformers/main/pt/main_classes/configuration#transformers.PreTrainedConfig) e podem ser usados para controlar as saídas do modelo. Leia a documentação de [PreTrainedConfig](/docs/transformers/main/pt/main_classes/configuration#transformers.PreTrainedConfig) para mais informações.

Exemplo:

```python
>>> from transformers import LayoutXLMConfig, LayoutXLMModel

>>> # Initializing a LayoutXLM microsoft/layoutxlm-base style configuration
>>> configuration = LayoutXLMConfig()

>>> # Initializing a model (with random weights) from the microsoft/layoutxlm-base style configuration
>>> model = LayoutXLMModel(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config
```

## LayoutXLMTokenizer[[transformers.LayoutXLMTokenizer]]

#### transformers.LayoutXLMTokenizer[[transformers.LayoutXLMTokenizer]]

```python
transformers.LayoutXLMTokenizer(vocab: str | list | None = None, bos_token = '<s>', eos_token = '</s>', sep_token = '</s>', cls_token = '<s>', unk_token = '<unk>', pad_token = '<pad>', mask_token = '<mask>', cls_token_box = [0, 0, 0, 0], sep_token_box = [1000, 1000, 1000, 1000], pad_token_box = [0, 0, 0, 0], pad_token_label = -100, only_label_first_subword = True, add_prefix_space = True, **kwargs)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/layoutxlm/tokenization_layoutxlm.py#L140)

**Parâmetros:**

vocab (`str`, `dict` ou `list`, *opcional*) : Vocabulário para o tokenizer como um caminho, um dicionário ou uma lista de tuplas `(token, score)`.

bos_token (`str`, *opcional*, padrão `"<s>"`) : 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 `"</s>"`) : 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 `"</s>"`) : 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 `"<s>"`) : 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 `"<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.

mask_token (`str`, *opcional*, padrão `"<mask>"`) : 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.

cls_token_box (`list[int]`, *opcional*, padrão `[0, 0, 0, 0]`) : A bounding box a ser usada para o token especial [CLS].

sep_token_box (`list[int]`, *opcional*, padrão `[1000, 1000, 1000, 1000]`) : A caixa delimitadora a ser usada para o token especial [SEP].

pad_token_box (`list[int]`, *opcional*, padrão `[0, 0, 0, 0]`) : A caixa delimitadora a ser usada para o token especial [PAD].

pad_token_label (`int`, *opcional*, padrão -100) : O rótulo a ser usado para tokens de preenchimento. O padrão é -100, que corresponde ao `ignore_index` do CrossEntropyLoss do PyTorch.

only_label_first_subword (`bool`, *opcional*, padrão `True`) : Indica se apenas o primeiro subtoken deve ser rotulado, caso rótulos de palavras sejam fornecidos.

add_prefix_space (`bool`, *opcional*, padrão `True`) : Indica se deve ou não adicionar um espaço inicial à entrada.

additional_special_tokens (`list[str]`, *opcional*, padrão `["<s>NOTUSED", "</s>NOTUSED"]`) : Tokens especiais adicionais usados pelo tokenizer.

Construa um tokenizador "fast" do LayoutXLM (baseado na biblioteca *tokenizers* do HuggingFace). Adaptado de [RobertaTokenizer](/docs/transformers/main/pt/model_doc/led#transformers.RobertaTokenizer) e [XLNetTokenizer](/docs/transformers/main/pt/model_doc/xlnet#transformers.XLNetTokenizer). Baseado em [BPE](https://huggingface.co/docs/tokenizers/python/latest/components.html?highlight=BPE#models).

Este tokenizer herda de [TokenizersBackend](/docs/transformers/main/pt/main_classes/tokenizer#transformers.TokenizersBackend), 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.LayoutXLMTokenizer.__call__]]

```python
__call__(text: str | list[str] | list[list[str]], text_pair: list[str] | list[list[str]] | None = None, boxes: list[list[int]] | list[list[list[int]]] | None = None, word_labels: list[int] | list[list[int]] | 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, stride: int = 0, 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/layoutxlm/tokenization_layoutxlm.py#L413)

**Parâmetros:**

text (`str`, `list[str]`, `list[list[str]]`) : A sequência ou lote de sequências a serem codificadas. Cada sequência pode ser uma string, uma lista de strings (palavras de um único exemplo ou perguntas de um lote de exemplos) ou uma lista de listas de strings (lote de palavras).

text_pair (`list[str]`, `list[list[str]]`) : A sequência ou lote de sequências a serem codificadas. Cada sequência deve ser uma lista de strings (string pretokenizada).

boxes (`list[list[int]]`, `list[list[list[int]]]`) : Caixas delimitadoras de nível de palavra. Cada caixa delimitadora deve ser normalizada em uma escala de 0 a 1000.

word_labels (`list[int]`, `list[list[int]]`, *opcional*) : Rótulos inteiros em nível de palavra (para tarefas de classificação de tokens, como FUNSD e CORD).

add_special_tokens (`bool`, *opcional*, padrão `True`) : Se as sequências devem ser codificadas com os tokens especiais relativos ao seu modelo.

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.

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

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)

- **bbox** -- Lista de caixas delimitadoras a serem fornecidas a um modelo.

- **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)

- **labels** -- Lista de rótulos a serem fornecidos a um modelo. (quando `word_labels` é especificado).
- **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 para o modelo uma ou várias sequências ou um ou vários pares de sequências com caixas delimitadoras normalizadas em nível de palavra e rótulos opcionais.

#### build_inputs_with_special_tokens[[transformers.LayoutXLMTokenizer.build_inputs_with_special_tokens]]

```python
build_inputs_with_special_tokens(token_ids_0: list, token_ids_1: list[int] | None = None)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/layoutxlm/tokenization_layoutxlm.py#L892)

**Parâmetros:**

token_ids_0 (`list[int]`) : Lista de IDs aos quais os tokens especiais serão adicionados.

token_ids_1 (`list[int]`, *opcional*) : Lista opcional de IDs para pares de sequências.

**Retorna:** `list[int]`

Lista de [IDs de entrada](../glossary#input-ids) com os tokens especiais apropriados.

Construa as entradas do modelo a partir de uma sequência ou de um par de sequências para tarefas de classificação de sequência, concatenando e adicionando tokens especiais. Uma sequência XLM-RoBERTa tem o seguinte formato:

- sequência única: `<s> X </s>`
- par de sequências: `<s> A </s></s> B </s>`

#### get_special_tokens_mask[[transformers.LayoutXLMTokenizer.get_special_tokens_mask]]

```python
get_special_tokens_mask(token_ids_0: list[int], token_ids_1: list[int] | None = None, already_has_special_tokens: bool = False)
```

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

**Parâmetros:**

token_ids_0 : Lista de IDs da sequência (possivelmente já formatada).

token_ids_1 : Não utilizado quando `already_has_special_tokens=True`. Deve ser None nesse caso.

already_has_special_tokens : Indica se a sequência já está formatada com tokens especiais.

**Retorna:** Uma lista de inteiros no intervalo [0, 1]

1 para um token especial, 0 para um token de sequência.

Obter os ids de sequência de uma lista de tokens que não possui tokens especiais adicionados.

Para tokenizadores rápidos, os data collators chamam isso com `already_has_special_tokens=True` para construir uma máscara sobre uma sequência já formatada. Nesse caso, calculamos a máscara verificando a pertença em `all_special_ids`.

#### create_token_type_ids_from_sequences[[transformers.LayoutXLMTokenizer.create_token_type_ids_from_sequences]]

```python
create_token_type_ids_from_sequences(token_ids_0: list, token_ids_1: list[int] | None = None)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/layoutxlm/tokenization_layoutxlm.py#L918)

**Parâmetros:**

token_ids_0 (`list[int]`) : Lista de IDs.

token_ids_1 (`list[int]`, *opcional*) : Lista opcional de IDs para pares de sequências.

**Retorna:** `list[int]`

Lista de zeros.

Cria uma máscara a partir das duas sequências passadas para ser usada em uma tarefa de classificação de pares de sequências. O XLM-RoBERTa não faz uso de ids de tipo de token, portanto, uma lista de zeros é retornada.

#### save_vocabulary[[transformers.LayoutXLMTokenizer.save_vocabulary]]

```python
save_vocabulary(save_directory: str, filename_prefix: str | None = None)
```

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

## LayoutXLMProcessor[[transformers.LayoutXLMProcessor]]

#### transformers.LayoutXLMProcessor[[transformers.LayoutXLMProcessor]]

```python
transformers.LayoutXLMProcessor(image_processor = None, tokenizer = None, **kwargs)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/layoutxlm/processing_layoutxlm.py#L24)

**Parâmetros:**

image_processor (`LayoutLMv2ImageProcessor`) : O processador de imagem é uma entrada obrigatória.

tokenizer (`LayoutXLMTokenizer`) : O tokenizer é uma entrada obrigatória.

Constrói um LayoutXLMProcessor que encapsula um processador de imagem e um tokenizer em um único processador.

[LayoutXLMProcessor](/docs/transformers/main/pt/model_doc/layoutxlm#transformers.LayoutXLMProcessor) oferece todas as funcionalidades de [LayoutLMv2ImageProcessor](/docs/transformers/main/pt/model_doc/layoutlmv2#transformers.LayoutLMv2ImageProcessor) e [LayoutXLMTokenizer](/docs/transformers/main/pt/model_doc/layoutxlm#transformers.LayoutXLMTokenizer). Consulte [~LayoutLMv2ImageProcessor](/docs/transformers/main/pt/model_doc/layoutlmv2#transformers.LayoutLMv2ImageProcessor) e [~LayoutXLMTokenizer](/docs/transformers/main/pt/model_doc/layoutxlm#transformers.LayoutXLMTokenizer) para mais informações.

#### __call__[[transformers.LayoutXLMProcessor.__call__]]

```python
__call__(images, text: str | list[str] | list[list[str]] = None, text_pair: list[str] | list[list[str]] | None = None, boxes: list[list[int]] | list[list[list[int]]] | None = None, word_labels: list[int] | list[list[int]] | None = None, add_special_tokens: bool = True, padding: bool | str | transformers.utils.generic.PaddingStrategy = False, truncation: bool | str | transformers.tokenization_utils_base.TruncationStrategy = None, max_length: int | None = None, stride: int = 0, pad_to_multiple_of: int | 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, return_tensors: str | transformers.utils.generic.TensorType | None = None, **kwargs)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/layoutxlm/processing_layoutxlm.py#L28)

**Parâmetros:**

images (``) : Image to preprocess. Expects a single or batch of images with pixel values ranging from 0 to 255. If passing in images with pixel values between 0 and 1, set `do_rescale=False`

text (`Union[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 você passar uma entrada pretokenizada, defina `is_split_into_words=True` para evitar ambiguidade com entradas em lote.

text_pair (`str, list[str] or list[int]`, *opcional*) : Sequência secundária opcional a ser codificada. Pode ser uma string, uma lista de strings (string tokenizada usando o método `tokenize`) ou uma lista de inteiros (ids de strings tokenizadas usando o método `convert_tokens_to_ids`).

boxes (`list[list[int]] or list[list[list[int]]]`, *opcional*) : Caixas delimitadoras de nível de palavra. Cada caixa delimitadora deve ser normalizada em uma escala de 0 a 1000.

word_labels (`list[int] or list[list[int]]`, *opcional*) : Rótulos inteiros em nível de palavra (para tarefas de classificação de tokens, como FUNSD e CORD).

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*) : 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 pelo 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 pelo 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 pelo 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 pelo 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.

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 permitir o uso de Tensor Cores em hardware NVIDIA com capacidade de computação `>= 7.5` (Volta).

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 os comprimentos das entradas codificadas devem ser retornados.

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

return_tensors (`Union[str, ~utils.generic.TensorType]`, *opcional*) : Se definido, retornará tensors de um framework específico. Os valores aceitos são:  - `'pt'`: Retorna objetos `torch.Tensor` do PyTorch. - `'np'`: Retorna objetos `np.ndarray` do NumPy.

**Retorna:** `~tokenization_utils_base.BatchEncoding`

- **data** (`dict`, *opcional*) -- Dicionário de listas/arrays/tensors retornados pelos métodos `__call__`/`encode_plus`/`batch_encode_plus` ('input_ids', 'attention_mask', etc.).
- **encoding** (`tokenizers.Encoding` ou `Sequence[tokenizers.Encoding]`, *opcional*) -- Se o tokenizer for um fast tokenizer que fornece informações adicionais, como o mapeamento do espaço de palavras/caracteres para o espaço de tokens, a instância de `tokenizers.Encoding` ou a lista de instâncias (para lotes) armazena essas informações.
- **tensor_type** (`Union[None, str, TensorType]`, *opcional*) -- Você pode fornecer um tensor_type aqui para converter as listas de inteiros em Tensors do PyTorch/Numpy na inicialização.
- **prepend_batch_axis** (`bool`, *opcional*, padrão `False`) -- Indica se deve ou não adicionar um eixo de lote ao converter para tensores (veja `tensor_type` acima). Observe que este parâmetro tem efeito se o parâmetro `tensor_type` estiver definido, *caso contrário, não tem efeito*.
- **n_sequences** (`int`, *opcional*) -- O número de sequências de entrada representadas por cada codificação (`None` para desconhecido, `1` para uma única sequência e `2` para um par de sequências).