# LayoutXLM

## Обзор

LayoutXLM был предложен в статье [LayoutXLM: Multimodal Pre-training for Multilingual Visually-rich Document Understanding](https://huggingface.co/papers/2104.08836) авторами Yiheng Xu, Tengchao Lv, Lei Cui, Guoxin Wang, Yijuan Lu, Dinei Florencio, Cha Zhang, Furu Wei. Это многоязычное расширение модели [LayoutLMv2](https://huggingface.co/papers/2012.14740), обученной на 53 языках.

Аннотация из статьи следующая:

*Мультимодальная предварительная обучение с использованием текста, макета и изображений недавно достигла SOTA-результатов в задачах понимания документов с богатым визуальным содержанием, что демонстрирует большой потенциал совместного обучения в разных модальностях. В данной статье мы представляем LayoutXLM — мультимодальную предварительно обученную модель для многоязычного понимания документов, которая направлена на преодоление языковых барьеров в понимании документов с богатым визуальным содержанием. Для точной оценки LayoutXLM мы также вводим многоязычный бенчмарк для понимания форм под названием XFUN, который включает образцы понимания форм на 7 языках (китайский, японский, испанский, французский, итальянский, немецкий, португальский), при этом пары «ключ-значение» для каждого языка размечены вручную. Результаты экспериментов показывают, что модель LayoutXLM значительно превосходит существующие SOTA-модели кросс-языкового предварительного обучения на наборе данных XFUN.*

Эта модель была предоставлена пользователем [nielsr](https://huggingface.co/nielsr). Исходный код можно найти [здесь](https://github.com/microsoft/unilm).

## Советы по использованию и примеры

Можно напрямую подставить веса LayoutXLM в модель LayoutLMv2, как показано ниже:

```python
from transformers import LayoutLMv2Model

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

Обратите внимание, что у LayoutXLM есть собственный токенизатор, основанный на [LayoutXLMTokenizer](/docs/transformers/v5.23.0/ru/model_doc/layoutxlm#transformers.LayoutXLMTokenizer)/[LayoutXLMTokenizerFast](/docs/transformers/v5.23.0/ru/model_doc/layoutxlm#transformers.LayoutXLMTokenizer). Вы можете инициализировать его следующим образом:

```python
from transformers import LayoutXLMTokenizer

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

Аналогично LayoutLMv2, вы можете использовать [LayoutXLMProcessor](/docs/transformers/v5.23.0/ru/model_doc/layoutxlm#transformers.LayoutXLMProcessor) (который последовательно применяет [LayoutLMv2ImageProcessor](/docs/transformers/v5.23.0/ru/model_doc/layoutlmv2#transformers.LayoutLMv2ImageProcessor) и [LayoutXLMTokenizer](/docs/transformers/v5.23.0/ru/model_doc/layoutxlm#transformers.LayoutXLMTokenizer)/[LayoutXLMTokenizerFast](/docs/transformers/v5.23.0/ru/model_doc/layoutxlm#transformers.LayoutXLMTokenizer)) для подготовки всех данных для модели.

Поскольку архитектура LayoutXLM эквивалентна архитектуре LayoutLMv2, все советы, примеры кода и ноутбуки можно найти на [странице документации LayoutLMv2](layoutlmv2).

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

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/layoutxlm/configuration_layoutxlm.py#L35)

**Параметры:**

vocab_size (`int`, *необязательный*, по умолчанию `30522`) : Размер словаря модели. Определяет количество различных токенов, которые могут быть представлены в `input_ids`.

hidden_size (`int`, *optional*, по умолчанию `768`) : Размерность скрытых представлений.

num_hidden_layers (`int`, *необязательный*, по умолчанию `12`) : Количество скрытых слоев в декодере Transformer.

num_attention_heads (`int`, *необязательный*, по умолчанию `12`) : Количество головок внимания для каждого слоя внимания в декодере Transformer.

intermediate_size (`int`, *optional*, по умолчанию `3072`) : Размерность представлений MLP.

hidden_act (`str`, *необязательный*, по умолчанию `gelu`) : Нелинейная функция активации (функция или строка) в декодере. Например, `"gelu"`, `"relu"`, `"silu"` и т. д.

hidden_dropout_prob (`Union[float, int]`, *необязательный*, по умолчанию `0.1`) : Вероятность dropout для всех полносвязных слоев в эмбеддингах, энкодере и пулере.

attention_probs_dropout_prob (`Union[float, int]`, *необязательный*, по умолчанию `0.1`) : Доля dropout для вероятностей внимания.

max_position_embeddings (`int`, *необязательный*, по умолчанию `512`) : Максимальная длина последовательности, с которой может использоваться данная модель.

type_vocab_size (`int`, *необязательный*, по умолчанию `2`) : Размер словаря для `token_type_ids`.

initializer_range (`float`, *необязательный*, по умолчанию `0.02`) : Стандартное отклонение truncated_normal_initializer для инициализации всех матриц весов.

layer_norm_eps (`float`, *необязательный*, по умолчанию `1e-12`) : Значение epsilon, используемое слоями нормализации.

pad_token_id (`int`, *необязательный*, по умолчанию `0`) : Идентификатор токена, используемый для выравнивания в словаре.

max_2d_position_embeddings (`int`, *optional*, по умолчанию 1024) : Максимальное значение, с которым может использоваться встраивание двумерного положения. Как правило, стоит задать достаточно большое значение на всякий случай (например, 1024).

max_rel_pos (`int`, *optional*, по умолчанию 128) : Максимальное количество относительных позиций, используемых в механизме само-внимания.

rel_pos_bins (`int`, *optional*, по умолчанию 32) : Количество относительных позиционных бинов, используемых в механизме само-внимания.

fast_qkv (`bool`, *необязательный*, по умолчанию `True`) : Использовать ли единую матрицу для запросов, ключей и значений в слоях само-внимания.

max_rel_2d_pos (`int`, *optional*, по умолчанию 256) : Максимальное количество относительных 2D-позиций в механизме само-внимания.

rel_2d_pos_bins (`int`, *необязательный*, по умолчанию 64) : Количество 2D-бинар относительных позиций в механизме само-внимания.

convert_sync_batchnorm (`bool`, *необязательный*, по умолчанию `True`) : Преобразовывать ли слои batch normalization в слои synchronized batch normalization.

image_feature_pool_shape (`list[int]`, *необязательный*, по умолчанию `[7, 7, 256]`) : Форма карты признаков после усредняющего пулинга.

coordinate_size (`int`, *optional*, по умолчанию 128) : Размерность координатных эмбеддингов.

shape_size (`int`, *optional*, по умолчанию 128) : Размерность встраиваний ширины и высоты.

has_relative_attention_bias (`bool`, *необязательный*, по умолчанию `True`) : Использовать ли относительное смещение внимания в механизме само-внимания.

has_spatial_attention_bias (`bool`, *необязательный*, по умолчанию `True`) : Использовать ли пространственное смещение внимания в механизме само-внимания.

has_visual_segment_embedding (`bool`, *необязательный*, по умолчанию `False`) : Добавлять ли визуальные сегментные эмбеддинги.

detectron2_config_args (`dict`, *необязательный*) : Словарь, содержащий аргументы конфигурации визуального бэкбона Detectron2. Подробности о значениях по умолчанию см. в [этом файле](https://github.com/microsoft/unilm/blob/master/layoutlmft/layoutlmft/models/layoutxlm/detectron2_config.py).

Это класс конфигурации для хранения настроек модели LayoutxlmModel. Он используется для создания экземпляра модели Layoutxlm в соответствии с указанными аргументами, определяя архитектуру модели. Создание конфигурации с параметрами по умолчанию даст конфигурацию, аналогичную конфигурации [microsoft/layoutxlm-base](https://huggingface.co/microsoft/layoutxlm-base)

Объекты конфигурации наследуются от [PreTrainedConfig](/docs/transformers/v5.23.0/ru/main_classes/configuration#transformers.PreTrainedConfig) и могут использоваться для управления выводами модели. Подробнее см. в документации [PreTrainedConfig](/docs/transformers/v5.23.0/ru/main_classes/configuration#transformers.PreTrainedConfig).

Пример:

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

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/layoutxlm/tokenization_layoutxlm.py#L140)

**Параметры:**

vocab (`str`, `dict` или `list`, *необязательный*) : Словарь токенизатора в виде пути, словаря или списка кортежей `(token, score)`.

bos_token (`str`, *optional*, по умолчанию `"<s>"`) : Токен начала последовательности, использовавшийся во время предварительного обучения. Может использоваться в качестве токена классификатора последовательности. При построении последовательности с использованием специальных токенов этот токен не используется для обозначения начала последовательности. Для этой цели применяется токен `cls_token`.

eos_token (`str`, *необязательный*, по умолчанию `"</s>"`) : Токен конца последовательности. При построении последовательности с использованием специальных токенов этот токен не используется для обозначения конца последовательности. Вместо него применяется токен `sep_token`.

sep_token (`str`, *необязательный*, по умолчанию `"</s>"`) : Токен-разделитель, который используется при построении последовательности из нескольких последовательностей, например, двух последовательностей для классификации последовательностей или текста и вопроса для ответа на вопросы. Он также используется в качестве последнего токена последовательности, построенной с помощью специальных токенов.

cls_token (`str`, *необязательный*, по умолчанию `"<s>"`) : Токен классификатора, используемый при классификации последовательности (классификация всей последовательности, а не посимвольная классификация). Это первый токен последовательности, если она построена с использованием специальных токенов.

unk_token (`str`, *необязательный*, по умолчанию `"<unk>"`) : Неизвестный токен. Токен, отсутствующий в словаре, не может быть преобразован в ID, вместо этого ему присваивается данный токен.

pad_token (`str`, *необязательный*, по умолчанию `"<pad>"`) : токен, используемый для выравнивания, например, при пакетной обработке последовательностей разной длины.

mask_token (`str`, *необязательный*, по умолчанию `"<mask>"`) : Токен, используемый для маскирования значений. Это тот токен, который применяется при обучении модели с использованием маскированного языкового моделирования. Именно этот токен модель будет пытаться предсказать.

cls_token_box (`list[int]`, *необязательный*, по умолчанию `[0, 0, 0, 0]`) : Граничный прямоугольник, используемый для специального токена [CLS].

sep_token_box (`list[int]`, *необязательный*, по умолчанию `[1000, 1000, 1000, 1000]`) : Граничный прямоугольник, используемый для специального токена [SEP].

pad_token_box (`list[int]`, *необязательный*, по умолчанию `[0, 0, 0, 0]`) : Граничный прямоугольник, используемый для специального токена [PAD].

pad_token_label (`int`, *optional*, по умолчанию -100) : Метка, используемая для токенов отступов. По умолчанию -100, что соответствует `ignore_index` в CrossEntropyLoss PyTorch.

only_label_first_subword (`bool`, *необязательный*, по умолчанию `True`) : Указывает, следует ли размечать только первый сабворд, если предоставлены метки слов.

add_prefix_space (`bool`, *необязательный*, по умолчанию `True`) : Добавлять ли начальный пробел к входным данным.

additional_special_tokens (`list[str]`, *необязательный*, по умолчанию `["<s>NOTUSED", "</s>NOTUSED"]`) : Дополнительные специальные токены, используемые токенизатором.

Создайте «быстрый» токенизатор LayoutXLM (на базе библиотеки *tokenizers* от HuggingFace). Адаптировано из [RobertaTokenizer](/docs/transformers/v5.23.0/ru/model_doc/led#transformers.RobertaTokenizer) и [XLNetTokenizer](/docs/transformers/v5.23.0/ru/model_doc/xlnet#transformers.XLNetTokenizer). Основано на [BPE](https://huggingface.co/docs/tokenizers/python/latest/components.html?highlight=BPE#models).

Этот токенизатор наследуется от [TokenizersBackend](/docs/transformers/v5.23.0/ru/main_classes/tokenizer#transformers.TokenizersBackend), который содержит большинство основных методов. За дополнительной информацией об этих методах следует обращаться к этому суперклассу.

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

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/layoutxlm/tokenization_layoutxlm.py#L413)

**Параметры:**

text (`str`, `list[str]`, `list[list[str]]`) : Последовательность или батч последовательностей для кодирования. Каждая последовательность может быть строкой, списком строк (слова одного примера или вопросы батча примеров) или списком списков строк (батч слов).

text_pair (`list[str]`, `list[list[str]]`) : Последовательность или батч последовательностей для кодирования. Каждая последовательность должна быть списком строк (предтокенизированных строк).

boxes (`list[list[int]]`, `list[list[list[int]]]`) : Ограничивающие рамки на уровне слов. Каждая рамка должна быть нормализована в диапазоне от 0 до 1000.

word_labels (`list[int]`, `list[list[int]]`, *необязательный*) : Целочисленные метки на уровне слов (для задач классификации токенов, таких как FUNSD, CORD).

add_special_tokens (`bool`, *необязательный*, по умолчанию `True`) : Нужно ли кодировать последовательности со специальными токенами в соответствии с их моделью.

padding (`bool`, `str` или [PaddingStrategy](/docs/transformers/v5.23.0/ru/internal/file_utils#transformers.utils.PaddingStrategy), *необязательный*, по умолчанию `False`) : Включает и управляет выравниванием. Принимает следующие значения:  - `True` или `'longest'`: Выравнивание до самой длинной последовательности в батче (или без выравнивания, если предоставлена только одна последовательность). - `'max_length'`: Выравнивание до максимальной длины, указанной в аргументе `max_length`, или до максимально допустимой входной длины для модели, если этот аргумент не указан. - `False` или `'do_not_pad'` (по умолчанию): Без выравнивания (т. е. может выдать батч с последовательностями разной длины).

truncation (`bool`, `str` или [TruncationStrategy](/docs/transformers/v5.23.0/ru/internal/tokenization_utils#transformers.tokenization_utils_base.TruncationStrategy), *необязательный*, по умолчанию `False`) : Включает и управляет усечением. Принимает следующие значения:  - `True` или `'longest_first'`: Усечение до максимальной длины, указанной в аргументе `max_length`, или до максимально допустимой входной длины для модели, если этот аргумент не указан. Усечение выполняется посимвольно: если предоставлена пара последовательностей (или пакет пар), то символ удаляется из самой длинной последовательности в паре. - `'only_first'`: Усечение до максимальной длины, указанной в аргументе `max_length`, или до максимально допустимой входной длины для модели, если этот аргумент не указан. Если предоставлена пара последовательностей (или пакет пар), усечение выполняется только для первой последовательности в паре. - `'only_second'`: Усечение до максимальной длины, указанной в аргументе `max_length`, или до максимально допустимой входной длины для модели, если этот аргумент не указан. Если предоставлена пара последовательностей (или пакет пар), усечение выполняется только для второй последовательности в паре. - `False` или `'do_not_truncate'` (по умолчанию): Усечение не выполняется (т. е. на выходе может быть пакет с длинами последовательностей, превышающими максимально допустимый размер входных данных модели).

max_length (`int`, *optional*) : Управляет максимальной длиной, используемой одним из параметров усечения/дополнения. Если значение не задано или равно `None`, будет использована предопределённая максимальная длина модели, если один из параметров усечения/дополнения требует указания максимальной длины. Если у модели нет конкретной максимальной длины входных данных (как у XLNet), усечение/дополнение до максимальной длины будет отключено.

stride (`int`, *optional*, по умолчанию 0) : Если задано число вместе с `max_length`, то переполненные токены, возвращаемые при `return_overflowing_tokens=True`, будут содержать некоторые токены из конца усечённой последовательности, чтобы обеспечить перекрытие между усечённой и переполненной последовательностями. Значение этого аргумента определяет количество перекрывающихся токенов.

pad_to_multiple_of (`int`, *optional*) : Если задано, последовательность будет дополнена нулями до кратного указанного значения. Это особенно полезно для использования Tensor Cores на аппаратных платформах NVIDIA с вычислительной способностью `>= 7.5` (Volta).

return_tensors (`str` или [TensorType](/docs/transformers/v5.23.0/ru/internal/file_utils#transformers.TensorType), *optional*) : Если задано, возвращает тензоры вместо списка целых чисел Python. Допустимые значения:  - `'pt'`: Возвращает объекты `torch.Tensor` PyTorch. - `'np'`: Возвращает объекты `np.ndarray` Numpy.

return_token_type_ids (`bool`, *необязательный*) : Указывает, следует ли возвращать идентификаторы типов токенов. Если значение не задано, идентификаторы типов токенов будут возвращены в соответствии со значением по умолчанию конкретного токенизатора, определяемым атрибутом `return_outputs`.  [Что такое идентификаторы типов токенов?](../glossary#token-type-ids)

return_attention_mask (`bool`, *необязательный*) : Указывает, следует ли возвращать маску внимания. Если значение не задано, маска внимания будет возвращена в соответствии со значением по умолчанию конкретного токенизатора, определяемым атрибутом `return_outputs`.  [Что такое маски внимания?](../glossary#attention-mask)

return_overflowing_tokens (`bool`, *необязательный*, по умолчанию `False`) : Возвращать ли переполненные последовательности токенов. Если передана пара последовательностей входных идентификаторов (или батч пар) с `truncation_strategy = longest_first` или `True`, вместо возврата переполненных токенов будет выброшена ошибка.

return_special_tokens_mask (`bool`, *необязательный*, по умолчанию `False`) : Нужно ли возвращать информацию о маске специальных токенов.

return_offsets_mapping (`bool`, *необязательный*, по умолчанию `False`) : Возвращать или нет `(char_start, char_end)` для каждого токена. Это доступно только для быстрых токенизаторов, наследующихся от [PreTrainedTokenizerFast](/docs/transformers/v5.23.0/ru/main_classes/tokenizer#transformers.TokenizersBackend); при использовании токенизатора на Python этот метод вызовет `NotImplementedError`.

return_length  (`bool`, *необязательный*, по умолчанию `False`) : Возвращать ли длины закодированных входных данных.

verbose (`bool`, *необязательный*, по умолчанию `True`) : Выводить ли дополнительную информацию и предупреждения.

- ****kwargs** : передаются в метод `self.tokenize()`

**Возвращает:** [BatchEncoding](/docs/transformers/v5.23.0/ru/main_classes/tokenizer#transformers.BatchEncoding)

[BatchEncoding](/docs/transformers/v5.23.0/ru/main_classes/tokenizer#transformers.BatchEncoding) со следующими полями:

- **input_ids** -- Список идентификаторов токенов, которые подаются в модель.

  [Что такое входные идентификаторы?](../glossary#input-ids)

- **bbox** -- Список ограничивающих прямоугольников, которые передаются в модель.

- **token_type_ids** -- Список идентификаторов типов токенов, передаваемых в модель (если `return_token_type_ids=True` или если *"token_type_ids"* входит в `self.model_input_names`).

  [Что такое идентификаторы типов токенов?](../glossary#token-type-ids)

- **attention_mask** -- список индексов, указывающих, на какие токены модель должна обращать внимание (когда `return_attention_mask=True` или если *"attention_mask"* входит в `self.model_input_names`).

  [Что такое маски внимания?](../glossary#attention-mask)

- **labels** -- Список меток, передаваемых в модель (если задан `word_labels`).
- **overflowing_tokens** -- Список переполненных последовательностей токенов (если заданы `max_length` и `return_overflowing_tokens=True`).
- **num_truncated_tokens** -- Количество отсечённых токенов (если задано `max_length` и `return_overflowing_tokens=True`).
- **special_tokens_mask** -- Список нулей и единиц, где 1 указывает на добавленные специальные токены, а 0 — на обычные токены последовательности (при `add_special_tokens=True` и `return_special_tokens_mask=True`).
- **length** -- Длина входных данных (когда `return_length=True`).

Основной метод для токенизации и подготовки одной или нескольких последовательностей или одной или нескольких пар последовательностей с нормализованными ограничивающими рамками на уровне слов и необязательными метками для модели.

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

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

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/layoutxlm/tokenization_layoutxlm.py#L892)

**Параметры:**

token_ids_0 (`list[int]`) : Список идентификаторов, к которым будут добавлены специальные токены.

token_ids_1 (`list[int]`, *необязательный*) : Необязательный второй список идентификаторов для пар последовательностей.

**Возвращает:** `list[int]`

Список [идентификаторов входных токенов](../glossary#input-ids) с соответствующими специальными токенами.

Создайте входные данные модели из последовательности или пары последовательностей для задач классификации последовательностей, объединяя их и добавляя специальные токены. Последовательность XLM-RoBERTa имеет следующий формат:

- одна последовательность: `<s> X </s>`
- пара последовательностей: `<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)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/tokenization_utils_base.py#L1337)

**Параметры:**

token_ids_0 : список идентификаторов для (возможно, уже отформатированной) последовательности.

token_ids_1 : Не используется, если `already_has_special_tokens=True`. В этом случае должно быть None.

already_has_special_tokens : Указывает, уже ли последовательность отформатирована со специальными токенами.

**Возвращаемое значение:** список целых чисел в диапазоне [0, 1]

1 для специального токена, 0 для токена последовательности.

Получить идентификаторы последовательностей из списка токенов, в который не добавлены специальные токены.

Для быстрых токенизаторов коллабораторы данных вызывают этот метод с `already_has_special_tokens=True`, чтобы построить маску для уже отформатированной последовательности. В этом случае маска вычисляется путём проверки принадлежности элементов `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[int], token_ids_1: list[int] | None = None)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/layoutxlm/tokenization_layoutxlm.py#L918)

**Параметры:**

token_ids_0 (`list[int]`) : Список идентификаторов.

token_ids_1 (`list[int]`, *необязательный*) : Необязательный второй список идентификаторов для пар последовательностей.

**Возвращает:** `list[int]`

Список нулей.

Создаёт маску на основе двух переданных последовательностей для использования в задаче классификации пар последовательностей. XLM-RoBERTa не использует идентификаторы типов токенов, поэтому возвращается список нулей.

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

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

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/tokenization_utils_tokenizers.py#L547)

## LayoutXLMProcessor[[transformers.LayoutXLMProcessor]]

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

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

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/layoutxlm/processing_layoutxlm.py#L24)

**Параметры:**

image_processor (`LayoutLMv2ImageProcessor`) : процессор изображений является обязательным входным параметром.

tokenizer (`LayoutXLMTokenizer`) : Токенизатор является обязательным входным параметром.

Создаёт LayoutXLMProcessor, который объединяет процессор изображений и токенизатор в единый процессор.

[LayoutXLMProcessor](/docs/transformers/v5.23.0/ru/model_doc/layoutxlm#transformers.LayoutXLMProcessor) предоставляет все возможности [LayoutLMv2ImageProcessor](/docs/transformers/v5.23.0/ru/model_doc/layoutlmv2#transformers.LayoutLMv2ImageProcessor) и [LayoutXLMTokenizer](/docs/transformers/v5.23.0/ru/model_doc/layoutxlm#transformers.LayoutXLMTokenizer). Подробнее см. в документации [~LayoutLMv2ImageProcessor](/docs/transformers/v5.23.0/ru/model_doc/layoutlmv2#transformers.LayoutLMv2ImageProcessor) и [~LayoutXLMTokenizer](/docs/transformers/v5.23.0/ru/model_doc/layoutxlm#transformers.LayoutXLMTokenizer).

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

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/layoutxlm/processing_layoutxlm.py#L28)

**Параметры:**

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]]]`, *необязательный*) : Последовательность или батч последовательностей для кодирования. Каждая последовательность может быть строкой или списком строк (предтокенизированная строка). Если вы передаёте предтокенизированный вход, установите `is_split_into_words=True`, чтобы избежать неоднозначности с батчированными входами.

text_pair (`str, list[str] or list[int]`, *необязательный*) : Необязательная вторая последовательность для кодирования. Это может быть строка, список строк (токенизированная строка с помощью метода `tokenize`) или список целых чисел (идентификаторы токенов строки, полученные с помощью метода `convert_tokens_to_ids`).

boxes (`list[list[int]] or list[list[list[int]]]`, *необязательный*) : Ограничивающие рамки на уровне слов. Каждая рамка должна быть нормализована в диапазоне от 0 до 1000.

word_labels (`list[int] or list[list[int]]`, *необязательный*) : Целочисленные метки на уровне слов (для задач классификации токенов, таких как FUNSD, CORD).

add_special_tokens (`bool`, *необязательный*, по умолчанию `True`) : Указывает, следует ли добавлять специальные токены при кодировании последовательностей. Для этого используется базовая функция `PretrainedTokenizerBase.build_inputs_with_special_tokens`, которая определяет, какие токены автоматически добавляются к входным идентификаторам. Это полезно, если вы хотите автоматически добавлять токены `bos` или `eos`.

padding (bool, str or [PaddingStrategy](/docs/transformers/v5.23.0/ru/internal/file_utils#transformers.utils.PaddingStrategy), *optional*, по умолчанию `False`) : Включает и управляет выравниванием. Принимает следующие значения:  - `True` или `'longest'`: Выравнивание до самой длинной последовательности в батче (или без выравнивания, если предоставлена только одна последовательность). - `'max_length'`: Выравнивание до максимальной длины, указанной в аргументе `max_length`, или до максимально допустимой входной длины для модели, если этот аргумент не указан. - `False` или `'do_not_pad'` (по умолчанию): Без выравнивания (т. е. может выдать батч с последовательностями разной длины).

truncation (bool, str or [TruncationStrategy](/docs/transformers/v5.23.0/ru/internal/tokenization_utils#transformers.tokenization_utils_base.TruncationStrategy), *optional*) : Включает и управляет усечением. Принимает следующие значения:  - `True` или `'longest_first'`: Усечение до максимальной длины, указанной аргументом `max_length`, или до максимально допустимой входной длины для модели, если этот аргумент не указан. Усечение выполняется посимвольно: если предоставлена пара последовательностей (или батч пар), то токен удаляется из самой длинной последовательности в паре. - `'only_first'`: Усечение до максимальной длины, указанной аргументом `max_length`, или до максимально допустимой входной длины для модели, если этот аргумент не указан. Если предоставлена пара последовательностей (или батч пар), усечение применяется только к первой последовательности пары. - `'only_second'`: Усечение до максимальной длины, указанной аргументом `max_length`, или до максимально допустимой входной длины для модели, если этот аргумент не указан. Если предоставлена пара последовательностей (или батч пар), усечение применяется только ко второй последовательности пары. - `False` или `'do_not_truncate'` (по умолчанию): Усечение не выполняется (т.е. на выходе может быть батч с длинами последовательностей, превышающими максимально допустимый размер входа модели).

max_length (`int`, *optional*) : Управляет максимальной длиной, используемой одним из параметров усечения/дополнения. Если значение не задано или равно `None`, будет использована предопределённая максимальная длина модели, если один из параметров усечения/дополнения требует указания максимальной длины. Если у модели нет конкретной максимальной длины входных данных (как у XLNet), усечение/дополнение до максимальной длины будет отключено.

stride (`int`, *optional*, по умолчанию `0`) : Если задано число вместе с `max_length`, то переполненные токены, возвращаемые при `return_overflowing_tokens=True`, будут содержать некоторые токены из конца усечённой последовательности, чтобы обеспечить перекрытие между усечённой и переполненной последовательностями. Значение этого аргумента определяет количество перекрывающихся токенов.

pad_to_multiple_of (`int`, *optional*) : Если задано, последовательность будет дополнена до кратного указанного значения. Требуется активация `padding`. Это особенно полезно для использования Tensor Cores на аппаратных средствах NVIDIA с вычислительной способностью `>= 7.5` (Volta).

return_token_type_ids (`bool`, *необязательный*) : Указывает, следует ли возвращать идентификаторы типов токенов. Если значение не задано, идентификаторы типов токенов будут возвращены в соответствии со значением по умолчанию конкретного токенизатора, определяемым атрибутом `return_outputs`.  [Что такое идентификаторы типов токенов?](../glossary#token-type-ids)

return_attention_mask (`bool`, *необязательный*) : Указывает, следует ли возвращать маску внимания. Если значение не задано, маска внимания будет возвращена в соответствии со значением по умолчанию конкретного токенизатора, определяемым атрибутом `return_outputs`.  [Что такое маски внимания?](../glossary#attention-mask)

return_overflowing_tokens (`bool`, *необязательный*, по умолчанию `False`) : Возвращать ли переполненные последовательности токенов. Если передана пара последовательностей входных идентификаторов (или батч пар) с `truncation_strategy = longest_first` или `True`, вместо возврата переполненных токенов будет выброшена ошибка.

return_special_tokens_mask (`bool`, *необязательный*, по умолчанию `False`) : Нужно ли возвращать информацию о маске специальных токенов.

return_offsets_mapping (`bool`, *необязательный*, по умолчанию `False`) : Возвращать или нет `(char_start, char_end)` для каждого токена. Это доступно только для быстрых токенизаторов, наследующихся от [PreTrainedTokenizerFast](/docs/transformers/v5.23.0/ru/main_classes/tokenizer#transformers.TokenizersBackend); при использовании токенизатора на Python этот метод вызовет `NotImplementedError`.

return_length (`bool`, *необязательный*, по умолчанию `False`) : Возвращать ли длины закодированных входных данных.

verbose (`bool`, *необязательный*, по умолчанию `True`) : Выводить ли дополнительную информацию и предупреждения.

return_tensors (`Union[str, ~utils.generic.TensorType]`, *необязательный*) : Если задано, возвращает тензоры конкретного фреймворка. Допустимые значения:  - `'pt'`: возвращает объекты `torch.Tensor` PyTorch. - `'np'`: возвращает объекты `np.ndarray` NumPy.

**Возвращает:** `~tokenization_utils_base.BatchEncoding`

- **data** (`dict`, *необязательный*) -- Словарь списков/массивов/тензоров, возвращаемый методами `__call__`/`encode_plus`/`batch_encode_plus` ('input_ids', 'attention_mask' и т. д.).
- **encoding** (`tokenizers.Encoding` или `Sequence[tokenizers.Encoding]`, *необязательный*) -- Если токенизатор является быстрым токенизатором, который выводит дополнительную информацию, например, отображение из пространства слов/символов в пространство токенов, то экземпляр `tokenizers.Encoding` или список экземпляров (для батчей) содержит эту информацию.
- **tensor_type** (`Union[None, str, TensorType]`, *необязательный*) -- Здесь можно указать tensor_type, чтобы при инициализации преобразовать списки целых чисел в тензоры PyTorch/Numpy.
- **prepend_batch_axis** (`bool`, *необязательный*, по умолчанию `False`) — добавлять ли ось батча при преобразовании в тензоры (см. `tensor_type` выше). Обратите внимание, что этот параметр имеет значение, если параметр `tensor_type` задан, *иначе не влияет на результат*.
- **n_sequences** (`int`, *необязательный*) -- Количество входных последовательностей, представленных каждым кодированием (`None` для неизвестного значения, `1` для одной последовательности и `2` для пары последовательностей).

