# LayoutXLM

## 개요

LayoutXLM은 Yiheng Xu, Tengchao Lv, Lei Cui, Guoxin Wang, Yijuan Lu, Dinei Florencio, Cha Zhang, Furu Wei가 [LayoutXLM: Multimodal Pre-training for Multilingual Visually-rich Document Understanding](https://huggingface.co/papers/2104.08836)에서 제안했습니다. 53개 언어로 학습된 [LayoutLMv2 모델](https://huggingface.co/papers/2012.14740)의 다국어 확장 버전입니다.

해당 논문의 초록은 다음과 같습니다:

*텍스트, 레이아웃, 이미지를 활용한 멀티모달 사전 학습은 최근 시각적으로 풍부한 문서 이해 작업에서 SOTA 성능을 달성했으며, 이는 서로 다른 모달리티 간의 결합 학습이 가진 큰 잠재력을 보여줍니다. 본 논문에서는 시각적으로 풍부한 문서 이해의 언어 장벽을 해소하는 것을 목표로 하는 다국어 문서 이해용 멀티모달 사전 학습 모델인 LayoutXLM을 제시합니다. LayoutXLM을 정확히 평가하기 위해, 7개 언어(중국어, 일본어, 스페인어, 프랑스어, 이탈리아어, 독일어, 포르투갈어)의 양식 이해 샘플을 포함하고 각 언어별로 키-값 쌍이 수동으로 라벨링된 다국어 양식 이해 벤치마크 데이터셋인 XFUN도 소개합니다. 실험 결과에 따르면, LayoutXLM 모델은 XFUN 데이터셋에서 기존 SOTA 크로스 링구얼 사전 학습 모델보다 현저히 우수한 성능을 보였습니다.*

이 모델은 [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/ko/model_doc/layoutxlm#transformers.LayoutXLMTokenizer)/[LayoutXLMTokenizerFast](/docs/transformers/v5.23.0/ko/model_doc/layoutxlm#transformers.LayoutXLMTokenizer)에 기반한 자체 토크나이저를 가지고 있습니다. 다음과 같이 초기화할 수 있습니다:

```python
from transformers import LayoutXLMTokenizer

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

LayoutLMv2와 유사하게, [LayoutXLMProcessor](/docs/transformers/v5.23.0/ko/model_doc/layoutxlm#transformers.LayoutXLMProcessor)(내부적으로 [LayoutLMv2ImageProcessor](/docs/transformers/v5.23.0/ko/model_doc/layoutlmv2#transformers.LayoutLMv2ImageProcessor)와 [LayoutXLMTokenizer](/docs/transformers/v5.23.0/ko/model_doc/layoutxlm#transformers.LayoutXLMTokenizer)/[LayoutXLMTokenizerFast](/docs/transformers/v5.23.0/ko/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`, *선택 사항*, 기본값 `768`) : 숨겨진 표현의 차원.

num_hidden_layers (`int`, *선택 사항*, 기본값 `12`) : Transformer decoder의 숨겨진 레이어 수입니다.

num_attention_heads (`int`, *선택 사항*, 기본값 `12`) : Transformer decoder의 각 attention layer에 사용되는 attention head의 수입니다.

intermediate_size (`int`, *선택 사항*, 기본값 `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`) : attention 확률에 적용할 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`) : layer normalization 레이어에서 사용되는 epsilon 값입니다.

pad_token_id (`int`, *선택 사항*, 기본값 `0`) : 어휘에서 패딩에 사용되는 토큰 ID입니다.

max_2d_position_embeddings (`int`, *선택 사항*, 기본값 1024) : 2D 위치 임베딩이 사용될 수 있는 최대 값입니다. 일반적으로 안전을 위해 큰 값(예: 1024)으로 설정합니다.

max_rel_pos (`int`, *선택 사항*, 기본값 128) : self-attention 메커니즘에서 사용할 상대 위치의 최대 개수입니다.

rel_pos_bins (`int`, *선택 사항*, 기본값 32) : self-attention 메커니즘에서 사용할 상대 위치 bin의 수입니다.

fast_qkv (`bool`, *선택 사항*, 기본값 `True`) : self-attention 레이어에서 쿼리, 키, 값에 단일 행렬을 사용할지 여부.

max_rel_2d_pos (`int`, *선택 사항*, 기본값 256) : self-attention 메커니즘에서 허용되는 최대 상대 2D 위치 수입니다.

rel_2d_pos_bins (`int`, *선택 사항*, 기본값 64) : self-attention 메커니즘에서 사용되는 2D 상대 위치 bin의 수입니다.

convert_sync_batchnorm (`bool`, *선택 사항*, 기본값 `True`) : 배치 정규화 레이어를 동기화 배치 정규화 레이어로 변환할지 여부.

image_feature_pool_shape (`list[int]`, *선택 사항*, 기본값 `[7, 7, 256]`) : 평균 풀링된 특징 맵의 형태입니다.

coordinate_size (`int`, *선택 사항*, 기본값 128) : 좌표 임베딩의 차원.

shape_size (`int`, *선택 사항*, 기본값 128) : 너비 및 높이 임베딩의 차원.

has_relative_attention_bias (`bool`, *선택 사항*, 기본값 `True`) : self-attention 메커니즘에서 상대적 attention bias를 사용할지 여부.

has_spatial_attention_bias (`bool`, *선택 사항*, 기본값 `True`) : self-attention 메커니즘에서 spatial attention bias를 사용할지 여부.

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)와 유사한 구성이 생성됩니다.

Configuration 객체는 [PreTrainedConfig](/docs/transformers/v5.23.0/ko/main_classes/configuration#transformers.PreTrainedConfig)를 상속하며, 모델 출력을 제어하는 데 사용할 수 있습니다. 자세한 내용은 [PreTrainedConfig](/docs/transformers/v5.23.0/ko/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`, *선택 사항*, 기본값 `"<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>"`) : 값을 마스킹하는 데 사용되는 토큰입니다. 이는 masked language modeling으로 이 모델을 학습할 때 사용되는 토큰입니다. 모델이 예측을 시도하는 대상이 되는 토큰입니다.

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`, *선택 사항*, 기본값 -100) : 패딩 토큰에 사용할 라벨입니다. 기본값은 -100이며, 이는 PyTorch의 CrossEntropyLoss의 `ignore_index`입니다.

only_label_first_subword (`bool`, *선택 사항*, 기본값 `True`) : 단어 라벨이 제공된 경우 첫 번째 서브워드만 라벨링할지 여부.

add_prefix_space (`bool`, *선택 사항*, 기본값 `True`) : 입력에 공백을 추가할지 여부.

additional_special_tokens (`list[str]`, *선택 사항*, 기본값 `["<s>NOTUSED", "</s>NOTUSED"]`) : 토크나이저가 사용하는 추가 특수 토큰입니다.

HuggingFace의 *tokenizers* 라이브러리를 기반으로 하는 "fast" LayoutXLM 토크나이저를 생성합니다. [RobertaTokenizer](/docs/transformers/v5.23.0/ko/model_doc/led#transformers.RobertaTokenizer) 및 [XLNetTokenizer](/docs/transformers/v5.23.0/ko/model_doc/xlnet#transformers.XLNetTokenizer)에서 수정했으며, [BPE](https://huggingface.co/docs/tokenizers/python/latest/components.html?highlight=BPE#models)를 기반으로 합니다.

이 토크나이저는 대부분의 주요 메서드를 포함하는 [TokenizersBackend](/docs/transformers/v5.23.0/ko/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/ko/internal/file_utils#transformers.utils.PaddingStrategy), *optional*, 기본값 `False`) : 패딩을 활성화하고 제어합니다. 다음 값을 허용합니다: - `True` 또는 `'longest'`: 배치 내 가장 긴 시퀀스 길이로 패딩합니다(단일 시퀀스만 제공된 경우 패딩하지 않음). - `'max_length'`: `max_length` 인수로 지정된 최대 길이로 패딩하거나, 해당 인수가 제공되지 않은 경우 모델이 허용하는 최대 입력 길이로 패딩합니다. - `False` 또는 `'do_not_pad'` (기본값): 패딩하지 않음(즉, 서로 다른 길이의 시퀀스를 가진 배치를 출력할 수 있음).

truncation (`bool`, `str` 또는 [TruncationStrategy](/docs/transformers/v5.23.0/ko/internal/tokenization_utils#transformers.tokenization_utils_base.TruncationStrategy), *optional*, 기본값 `False`) : 잘림(truncation)을 활성화하고 제어합니다. 다음 값을 허용합니다:  - `True` 또는 `'longest_first'`: `max_length` 인수로 지정된 최대 길이로 잘거나, 해당 인수가 제공되지 않으면 모델이 허용하는 최대 입력 길이로 잘릅니다. 이 경우 토큰 단위로 잘리며, 시퀀스 쌍(또는 쌍의 배치)이 제공되면 쌍에서 가장 긴 시퀀스에서 토큰을 하나씩 제거합니다. - `'only_first'`: `max_length` 인수로 지정된 최대 길이로 잘거나, 해당 인수가 제공되지 않으면 모델이 허용하는 최대 입력 길이로 잘릅니다. 이 경우 시퀀스 쌍(또는 쌍의 배치)이 제공되면 쌍의 첫 번째 시퀀스만 잘릅니다. - `'only_second'`: `max_length` 인수로 지정된 최대 길이로 잘거나, 해당 인수가 제공되지 않으면 모델이 허용하는 최대 입력 길이로 잘릅니다. 이 경우 시퀀스 쌍(또는 쌍의 배치)이 제공되면 쌍의 두 번째 시퀀스만 잘릅니다. - `False` 또는 `'do_not_truncate'` (기본값): 잘리지 않습니다(즉, 모델이 허용하는 최대 입력 크기보다 긴 시퀀스 길이를 가진 배치를 출력할 수 있습니다).

max_length (`int`, *선택 사항*) : truncation/padding 매개변수 중 하나가 사용할 최대 길이를 제어합니다. 설정하지 않거나 `None`으로 설정한 경우, truncation/padding 매개변수 중 하나가 최대 길이를 요구하면 미리 정의된 모델 최대 길이를 사용합니다. 모델에 특정 최대 입력 길이가 없는 경우(XLNet 등) 최대 길이로 truncation/padding하는 기능이 비활성화됩니다.

stride (`int`, *선택 사항*, 기본값 0) : `max_length`와 함께 숫자로 설정하면, `return_overflowing_tokens=True`일 때 반환되는 오버플로 토큰에는 잘림된 시퀀스로 반환되는 시퀀스의 끝부분에서 가져온 일부 토큰이 포함되어 잘림된 시퀀스와 오버플로 시퀀스 사이에 일부 중복이 제공됩니다. 이 인수의 값은 중복되는 토큰의 수를 정의합니다.

pad_to_multiple_of (`int`, *선택 사항*) : 설정된 경우, 시퀀스를 제공된 값의 배수로 패딩합니다. 이는 NVIDIA 하드웨어에서 Volta(컴퓨트 캐피빌리티 `>= 7.5`)와 같은 환경에서 Tensor Cores 사용을 활성화하는 데 특히 유용합니다.

return_tensors (`str` 또는 [TensorType](/docs/transformers/v5.23.0/ko/internal/file_utils#transformers.TensorType), *optional*) : 설정된 경우, python 정수 목록 대신 텐서를 반환합니다. 허용되는 값은 다음과 같습니다:  - `'pt'`: PyTorch `torch.Tensor` 객체를 반환합니다. - `'np'`: Numpy `np.ndarray` 객체를 반환합니다.

return_token_type_ids (`bool`, *선택 사항*) : 토큰 타입 ID를 반환할지 여부입니다. 기본값으로 두면, `return_outputs` 속성으로 정의된 해당 토크나이저의 기본값에 따라 토큰 타입 ID를 반환합니다. [토큰 타입 ID란 무엇인가요?](../glossary#token-type-ids)

return_attention_mask (`bool`, *선택 사항*) : attention mask를 반환할지 여부입니다. 기본값으로 두면, `return_outputs` 속성으로 정의된 해당 tokenizer의 기본값에 따라 attention mask를 반환합니다. [attention mask란 무엇인가요?](../glossary#attention-mask)

return_overflowing_tokens (`bool`, *선택 사항*, 기본값 `False`) : 넘친 토큰 시퀀스를 반환할지 여부입니다. 입력 ID의 시퀀스 쌍(또는 쌍의 배치)이 `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/ko/main_classes/tokenizer#transformers.TokenizersBackend)를 상속하는 fast tokenizer에서만 사용할 수 있으며, Python의 tokenizer를 사용하는 경우 이 메서드는 `NotImplementedError`를 발생시킵니다.

return_length (`bool`, *선택 사항*, 기본값 `False`) : 인코딩된 입력의 길이를 반환할지 여부.

verbose (`bool`, *선택 사항*, 기본값 `True`) : 추가 정보와 경고를 출력할지 여부.

- ****kwargs** : `self.tokenize()` 메서드에 전달됩니다

**반환값:** [BatchEncoding](/docs/transformers/v5.23.0/ko/main_classes/tokenizer#transformers.BatchEncoding)

다음 필드를 가진 [BatchEncoding](/docs/transformers/v5.23.0/ko/main_classes/tokenizer#transformers.BatchEncoding):

- **input_ids** -- 모델에 입력할 토큰 ID 목록.

  [입력 ID란 무엇인가요?](../glossary#input-ids)

- **bbox** -- 모델에 입력할 바운딩 박스 목록.

- **token_type_ids** -- 모델에 입력할 토큰 유형 ID 목록(`return_token_type_ids=True`인 경우 또는 `self.model_input_names`에 *"token_type_ids"*가 포함된 경우).

  [토큰 타입 ID란 무엇인가요?](../glossary#token-type-ids)

- **attention_mask** -- 모델이 어떤 토큰에 주의를 기울여야 하는지 지정하는 인덱스 목록(`return_attention_mask=True`인 경우 또는 `self.model_input_names`에 *"attention_mask"*가 포함된 경우).

  [어텐션 마스크란 무엇인가요?](../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** -- 0과 1의 목록으로, 1은 추가된 특수 토큰을, 0은 일반 시퀀스 토큰을 나타냅니다(`add_special_tokens=True`이고 `return_special_tokens_mask=True`인 경우).
- **length** -- 입력의 길이(`return_length=True`인 경우).

word-level 정규화된 바운딩 박스 및 선택적 라벨을 포함하여 하나 이상의 시퀀스 또는 하나 이상의 시퀀스 쌍을 토큰화하고 모델에 맞게 준비하는 주요 메서드입니다.

#### 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]`) : 특수 토큰이 추가될 ID 목록.

token_ids_1 (`list[int]`, *선택 사항*) : 시퀀스 쌍을 위한 선택적 두 번째 ID 목록.

**반환값:** `list[int]`

적절한 특수 토큰이 포함된 [입력 ID](../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 : (이미 포맷된) 시퀀스의 ID 목록.

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`에 대한 멤버십을 확인하여 마스크를 계산합니다.

#### 시퀀스에서 토큰 타입 ID 생성[[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]`) : ID 목록.

token_ids_1 (`list[int]`, *선택 사항*) : 시퀀스 쌍을 위한 선택적 두 번째 ID 목록.

**반환값:** `list[int]`

0으로만 이루어진 리스트.

시퀀스-페어 분류 작업에 사용될 두 시퀀스로부터 마스크를 생성합니다. XLM-RoBERTa는 토큰 타입 ID를 사용하지 않으므로, 0의 목록이 반환됩니다.

#### 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/ko/model_doc/layoutxlm#transformers.LayoutXLMProcessor)는 [LayoutLMv2ImageProcessor](/docs/transformers/v5.23.0/ko/model_doc/layoutlmv2#transformers.LayoutLMv2ImageProcessor)와 [LayoutXLMTokenizer](/docs/transformers/v5.23.0/ko/model_doc/layoutxlm#transformers.LayoutXLMTokenizer)의 모든 기능을 제공합니다. 자세한 내용은 [~LayoutLMv2ImageProcessor](/docs/transformers/v5.23.0/ko/model_doc/layoutlmv2#transformers.LayoutLMv2ImageProcessor)와 [~LayoutXLMTokenizer](/docs/transformers/v5.23.0/ko/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` 메서드를 사용한 토큰화된 문자열 ID)일 수 있습니다.

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`) : 시퀀스를 인코딩할 때 특수 토큰을 추가할지 여부입니다. 이는 입력 id에 자동으로 추가되는 토큰을 정의하는 기반 `PretrainedTokenizerBase.build_inputs_with_special_tokens` 함수를 사용합니다. `bos` 또는 `eos` 토큰을 자동으로 추가하려는 경우 유용합니다.

padding (bool, str 또는 [PaddingStrategy](/docs/transformers/v5.23.0/ko/internal/file_utils#transformers.utils.PaddingStrategy), *optional*, 기본값은 `False`) : 패딩을 활성화하고 제어합니다. 다음 값을 허용합니다: - `True` 또는 `'longest'`: 배치 내 가장 긴 시퀀스 길이로 패딩합니다(단일 시퀀스만 제공된 경우 패딩하지 않음). - `'max_length'`: `max_length` 인수로 지정된 최대 길이로 패딩하거나, 해당 인수가 제공되지 않은 경우 모델이 허용하는 최대 입력 길이로 패딩합니다. - `False` 또는 `'do_not_pad'` (기본값): 패딩하지 않음(즉, 서로 다른 길이의 시퀀스를 가진 배치 출력 가능).

truncation (bool, str 또는 [TruncationStrategy](/docs/transformers/v5.23.0/ko/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`, *선택 사항*) : truncation/padding 매개변수 중 하나가 사용할 최대 길이를 제어합니다. 설정하지 않거나 `None`으로 설정한 경우, truncation/padding 매개변수 중 하나가 최대 길이를 요구하면 미리 정의된 모델 최대 길이를 사용합니다. 모델에 특정 최대 입력 길이가 없는 경우(XLNet 등) 최대 길이로 truncation/padding하는 기능이 비활성화됩니다.

stride (`int`, *선택 사항*, 기본값 `0`) : `max_length`와 함께 숫자로 설정하면, `return_overflowing_tokens=True`일 때 반환되는 오버플로 토큰에는 잘린 시퀀스의 끝부분에서 가져온 일부 토큰이 포함되어 잘린 시퀀스와 오버플로 시퀀스 사이에 일부 중복이 발생하도록 합니다. 이 인수의 값은 중복되는 토큰의 수를 정의합니다.

pad_to_multiple_of (`int`, *선택 사항*) : 설정 시 시퀀스를 제공된 값의 배수로 패딩합니다. `padding`이 활성화되어 있어야 합니다. 이는 Volta와 같은 컴퓨트 캐피빌리티 `>= 7.5`를 지원하는 NVIDIA 하드웨어에서 Tensor Cores를 사용하도록 하는 데 특히 유용합니다.

return_token_type_ids (`bool`, *선택 사항*) : 토큰 타입 ID를 반환할지 여부입니다. 기본값으로 두면, `return_outputs` 속성으로 정의된 해당 토크나이저의 기본값에 따라 토큰 타입 ID를 반환합니다. [토큰 타입 ID란 무엇인가요?](../glossary#token-type-ids)

return_attention_mask (`bool`, *선택 사항*) : attention mask를 반환할지 여부입니다. 기본값으로 두면, `return_outputs` 속성으로 정의된 해당 tokenizer의 기본값에 따라 attention mask를 반환합니다. [attention mask란 무엇인가요?](../glossary#attention-mask)

return_overflowing_tokens (`bool`, *선택 사항*, 기본값 `False`) : 넘친 토큰 시퀀스를 반환할지 여부입니다. 입력 ID의 시퀀스 쌍(또는 쌍의 배치)이 `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/ko/main_classes/tokenizer#transformers.TokenizersBackend)를 상속하는 fast tokenizer에서만 사용할 수 있으며, Python의 tokenizer를 사용하는 경우 이 메서드는 `NotImplementedError`를 발생시킵니다.

return_length (`bool`, *선택 사항*, 기본값 `False`) : 인코딩된 입력의 길이를 반환할지 여부.

verbose (`bool`, *선택 사항*, 기본값 `True`) : 추가 정보와 경고를 출력할지 여부.

return_tensors (`Union[str, ~utils.generic.TensorType]`, *선택*) : 설정된 경우, 특정 프레임워크의 텐서를 반환합니다. 허용되는 값은 다음과 같습니다: - `'pt'`: PyTorch `torch.Tensor` 객체를 반환합니다. - `'np'`: NumPy `np.ndarray` 객체를 반환합니다.

**반환값:** `~tokenization_utils_base.BatchEncoding`

- **data** (`dict`, *선택 사항*) -- `__call__`/`encode_plus`/`batch_encode_plus` 메서드가 반환하는 리스트/배열/텐서 딕셔너리('input_ids', 'attention_mask' 등).
- **encoding** (`tokenizers.Encoding` 또는 `Sequence[tokenizers.Encoding]`, *선택 사항*) -- 토크나이저가 워드/문자 공간에서 토큰 공간으로의 매핑과 같은 추가 정보를 출력하는 fast tokenizer인 경우, `tokenizers.Encoding` 인스턴스 또는 인스턴스 목록(배치의 경우)에 이 정보가 저장됩니다.
- **tensor_type** (`Union[None, str, TensorType]`, *선택 사항*) -- 초기화 시 PyTorch/Numpy 텐서에서 정수 목록을 변환하려면 여기에 tensor_type을 지정할 수 있습니다.
- **prepend_batch_axis** (`bool`, *선택 사항*, 기본값 `False`) -- 텐서로 변환할 때 배치 축을 추가할지 여부(위에서 설명한 `tensor_type` 참조). `tensor_type` 매개변수가 설정된 경우에만 이 매개변수가 효과를 가지며, *그렇지 않으면 효과가 없습니다*.
- **n_sequences** (`int`, *선택 사항*) -- 각 인코딩이 나타내는 입력 시퀀스의 수 (`None`은 미지, `1`은 단일 시퀀스, `2`는 시퀀스 쌍을 의미합니다).

