# LayoutXLM

## Tổng quan

LayoutXLM được đề xuất trong [LayoutXLM: Multimodal Pre-training for Multilingual Visually-rich Document Understanding](https://huggingface.co/papers/2104.08836) bởi Yiheng Xu, Tengchao Lv, Lei Cui, Guoxin Wang, Yijuan Lu, Dinei Florencio, Cha Zhang, Furu Wei. Đây là phiên bản đa ngôn ngữ của [mô hình LayoutLMv2](https://huggingface.co/papers/2012.14740), được huấn luyện trên 53 ngôn ngữ.

Tóm tắt từ bài báo như sau:

*Việc tiền huấn luyện đa phương thức với văn bản, bố cục và hình ảnh gần đây đã đạt được hiệu suất SOTA cho các tác vụ hiểu tài liệu giàu yếu tố thị giác, cho thấy tiềm năng lớn của việc học liên hợp giữa các phương thức khác nhau. Trong bài báo này, chúng tôi giới thiệu LayoutXLM, một mô hình tiền huấn luyện đa phương thức cho việc hiểu tài liệu đa ngôn ngữ, nhằm xóa bỏ rào cản ngôn ngữ trong việc hiểu tài liệu giàu yếu tố thị giác. Để đánh giá chính xác LayoutXLM, chúng tôi cũng giới thiệu một bộ dữ liệu chuẩn benchmark cho việc hiểu biểu mẫu đa ngôn ngữ có tên là XFUN, bao gồm các mẫu hiểu biểu mẫu trong 7 ngôn ngữ (tiếng Trung, tiếng Nhật, tiếng Tây Ban Nha, tiếng Pháp, tiếng Ý, tiếng Đức, tiếng Bồ Đào Nha), và các cặp khóa-giá trị được gán nhãn thủ công cho từng ngôn ngữ. Kết quả thực nghiệm cho thấy mô hình LayoutXLM đã vượt trội đáng kể so với các mô hình tiền huấn luyện đa ngôn ngữ SOTA hiện có trên bộ dữ liệu XFUN.*

Mô hình này được đóng góp bởi [nielsr](https://huggingface.co/nielsr). Mã gốc có thể được tìm thấy [tại đây](https://github.com/microsoft/unilm).

## Mẹo và ví dụ sử dụng

Bạn có thể trực tiếp chèn trọng số của LayoutXLM vào một mô hình LayoutLMv2, như sau:

```python
from transformers import LayoutLMv2Model

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

Lưu ý rằng LayoutXLM có bộ phân từ riêng, dựa trên [LayoutXLMTokenizer](/docs/transformers/v5.23.0/vi/model_doc/layoutxlm#transformers.LayoutXLMTokenizer)/[LayoutXLMTokenizerFast](/docs/transformers/v5.23.0/vi/model_doc/layoutxlm#transformers.LayoutXLMTokenizer). Bạn có thể khởi tạo nó như sau:

```python
from transformers import LayoutXLMTokenizer

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

Tương tự như LayoutLMv2, bạn có thể sử dụng [LayoutXLMProcessor](/docs/transformers/v5.23.0/vi/model_doc/layoutxlm#transformers.LayoutXLMProcessor) (bên trong sẽ lần lượt áp dụng [LayoutLMv2ImageProcessor](/docs/transformers/v5.23.0/vi/model_doc/layoutlmv2#transformers.LayoutLMv2ImageProcessor) và [LayoutXLMTokenizer](/docs/transformers/v5.23.0/vi/model_doc/layoutxlm#transformers.LayoutXLMTokenizer)/[LayoutXLMTokenizerFast](/docs/transformers/v5.23.0/vi/model_doc/layoutxlm#transformers.LayoutXLMTokenizer)) để chuẩn bị toàn bộ dữ liệu cho mô hình.

Vì kiến trúc của LayoutXLM tương đương với LayoutLMv2, bạn có thể tham khảo [trang tài liệu của LayoutLMv2](layoutlmv2) để xem tất cả các mẹo, ví dụ mã và notebook.

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

[Nguồn](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/layoutxlm/configuration_layoutxlm.py#L35)

**Tham số:**

vocab_size (`int`, *tùy chọn*, mặc định là `30522`) : Kích thước từ vựng của mô hình. Xác định số lượng token khác nhau có thể được biểu diễn bởi `input_ids`.

hidden_size (`int`, *optional*, mặc định là `768`) : Kích thước của các biểu diễn ẩn.

num_hidden_layers (`int`, *tuỳ chọn*, mặc định là `12`) : Số lượng lớp ẩn trong bộ giải mã Transformer.

num_attention_heads (`int`, *tùy chọn*, mặc định là `12`) : Số lượng đầu chú ý cho mỗi lớp chú ý trong bộ giải mã Transformer.

intermediate_size (`int`, *tuỳ chọn*, mặc định là `3072`) : Kích thước của các biểu diễn MLP.

hidden_act (`str`, *tùy chọn*, mặc định là `gelu`) : Hàm kích hoạt phi tuyến (hàm hoặc chuỗi) trong bộ giải mã. Ví dụ, `"gelu"`, `"relu"`, `"silu"`, v.v.

hidden_dropout_prob (`Union[float, int]`, *tùy chọn*, mặc định là `0.1`) : Xác suất dropout cho tất cả các lớp fully connected trong embeddings, encoder và pooler.

attention_probs_dropout_prob (`Union[float, int]`, *tùy chọn*, mặc định là `0.1`) : Tỷ lệ dropout cho các xác suất chú ý.

max_position_embeddings (`int`, *tuỳ chọn*, mặc định là `512`) : Độ dài chuỗi tối đa mà mô hình này có thể được sử dụng.

type_vocab_size (`int`, *tùy chọn*, mặc định là `2`) : Kích thước từ vựng của `token_type_ids`.

initializer_range (`float`, *optional*, mặc định là `0.02`) : Độ lệch chuẩn của truncated_normal_initializer để khởi tạo tất cả các ma trận trọng số.

layer_norm_eps (`float`, *tuỳ chọn*, mặc định là `1e-12`) : Epsilon được sử dụng bởi các lớp chuẩn hóa lớp (layer normalization).

pad_token_id (`int`, *tùy chọn*, mặc định là `0`) : Id của token được sử dụng để đệm (padding) trong từ vựng.

max_2d_position_embeddings (`int`, *optional*, mặc định là 1024) : Giá trị tối đa mà embedding vị trí 2D có thể được sử dụng. Thông thường, hãy đặt giá trị này ở mức lớn để phòng ngừa (ví dụ: 1024).

max_rel_pos (`int`, *tuỳ chọn*, mặc định là 128) : Số lượng vị trí tương đối tối đa được sử dụng trong cơ chế tự chú ý.

rel_pos_bins (`int`, *tuỳ chọn*, mặc định là 32) : Số lượng bin vị trí tương đối được sử dụng trong cơ chế tự chú ý.

fast_qkv (`bool`, *tùy chọn*, mặc định là `True`) : Có sử dụng một ma trận duy nhất cho các truy vấn, khóa và giá trị trong các lớp self-attention hay không.

max_rel_2d_pos (`int`, *tuỳ chọn*, mặc định là 256) : Số lượng vị trí 2D tương đối tối đa trong cơ chế tự chú ý.

rel_2d_pos_bins (`int`, *tuỳ chọn*, mặc định là 64) : Số lượng bin vị trí tương đối 2D trong cơ chế tự chú ý.

convert_sync_batchnorm (`bool`, *tùy chọn*, mặc định là `True`) : Có chuyển các lớp batch normalization sang các lớp synchronized batch normalization hay không.

image_feature_pool_shape (`list[int]`, *tùy chọn*, mặc định là `[7, 7, 256]`) : Hình dạng của bản đồ đặc trưng được pool trung bình.

coordinate_size (`int`, *optional*, mặc định là 128) : Kích thước của các embedding tọa độ.

shape_size (`int`, *optional*, mặc định là 128) : Kích thước của các embedding chiều rộng và chiều cao.

has_relative_attention_bias (`bool`, *tùy chọn*, mặc định là `True`) : Có sử dụng độ chệch chú ý tương đối trong cơ chế tự chú ý hay không.

has_spatial_attention_bias (`bool`, *tùy chọn*, mặc định là `True`) : Có sử dụng độ chệch chú ý không gian trong cơ chế tự chú ý hay không.

has_visual_segment_embedding (`bool`, *tùy chọn*, mặc định là `False`) : Có thêm các embedding phân đoạn thị giác hay không.

detectron2_config_args (`dict`, *tùy chọn*) : Từ điển chứa các đối số cấu hình của visual backbone Detectron2. Tham khảo [tệp này](https://github.com/microsoft/unilm/blob/master/layoutlmft/layoutlmft/models/layoutxlm/detectron2_config.py) để biết chi tiết về các giá trị mặc định.

Đây là lớp cấu hình để lưu trữ cấu hình của một LayoutxlmModel. Nó được sử dụng để khởi tạo một mô hình Layoutxlm theo các đối số được chỉ định, xác định kiến trúc của mô hình. Khởi tạo một cấu hình với các giá trị mặc định sẽ tạo ra một cấu hình tương tự như cấu hình của [microsoft/layoutxlm-base](https://huggingface.co/microsoft/layoutxlm-base)

Các đối tượng cấu hình kế thừa từ [PreTrainedConfig](/docs/transformers/v5.23.0/vi/main_classes/configuration#transformers.PreTrainedConfig) và có thể được sử dụng để kiểm soát đầu ra của mô hình. Đọc tài liệu từ [PreTrainedConfig](/docs/transformers/v5.23.0/vi/main_classes/configuration#transformers.PreTrainedConfig) để biết thêm thông tin.

Ví dụ:

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

[Nguồn](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/layoutxlm/tokenization_layoutxlm.py#L140)

**Tham số:**

vocab (`str`, `dict` hoặc `list`, *tùy chọn*) : Từ vựng cho tokenizer dưới dạng đường dẫn, từ điển hoặc danh sách các bộ `(token, score)`.

bos_token (`str`, *tuỳ chọn*, mặc định là `"<s>"`) : Token bắt đầu chuỗi được sử dụng trong quá trình tiền huấn luyện. Có thể được dùng làm token phân loại chuỗi.    Khi xây dựng một chuỗi bằng các token đặc biệt, đây không phải là token được dùng cho phần bắt đầu của chuỗi. Token được dùng là `cls_token`.

eos_token (`str`, *tùy chọn*, mặc định là `"</s>"`) : Token kết thúc chuỗi. Khi xây dựng một chuỗi bằng các token đặc biệt, đây không phải là token được dùng cho việc kết thúc chuỗi. Token được dùng là `sep_token`.

sep_token (`str`, *tùy chọn*, mặc định là `"</s>"`) : Token phân cách, được sử dụng khi xây dựng một chuỗi từ nhiều chuỗi, ví dụ như hai chuỗi cho phân loại chuỗi hoặc một văn bản và một câu hỏi cho trả lời câu hỏi. Nó cũng được sử dụng làm token cuối cùng của một chuỗi được xây dựng với các token đặc biệt.

cls_token (`str`, *tùy chọn*, mặc định là `"<s>"`) : Token phân loại được sử dụng khi thực hiện phân loại chuỗi (phân loại toàn bộ chuỗi thay vì phân loại theo từng token). Đây là token đầu tiên của chuỗi khi được xây dựng với các token đặc biệt.

unk_token (`str`, *tùy chọn*, mặc định là `"<unk>"`) : Token không xác định. Một token không có trong từ vựng sẽ không thể được chuyển đổi thành ID và sẽ được gán thành token này thay thế.

pad_token (`str`, *tùy chọn*, mặc định là `"<pad>"`) : Token được sử dụng để đệm, chẳng hạn khi xử lý các lô (batch) các chuỗi có độ dài khác nhau.

mask_token (`str`, *tùy chọn*, mặc định là `"<mask>"`) : Token được sử dụng để che các giá trị. Đây là token được dùng khi huấn luyện mô hình này với mô hình hóa ngôn ngữ có che (masked language modeling). Đây là token mà mô hình sẽ cố gắng dự đoán.

cls_token_box (`list[int]`, *tuỳ chọn*, mặc định là `[0, 0, 0, 0]`) : Hộp bao (bounding box) được sử dụng cho token đặc biệt [CLS].

sep_token_box (`list[int]`, *tùy chọn*, mặc định là `[1000, 1000, 1000, 1000]`) : Hộp bao (bounding box) được sử dụng cho token đặc biệt [SEP].

pad_token_box (`list[int]`, *tuỳ chọn*, mặc định là `[0, 0, 0, 0]`) : Hộp bao (bounding box) được sử dụng cho token đặc biệt [PAD].

pad_token_label (`int`, *tuỳ chọn*, mặc định là -100) : Nhãn được sử dụng cho các token đệm. Mặc định là -100, đây là `ignore_index` của CrossEntropyLoss trong PyTorch.

only_label_first_subword (`bool`, *tùy chọn*, mặc định là `True`) : Có chỉ gán nhãn cho subword đầu tiên hay không, trong trường hợp các nhãn từ được cung cấp.

add_prefix_space (`bool`, *tùy chọn*, mặc định là `True`) : Có thêm một khoảng trắng ban đầu vào đầu vào hay không.

additional_special_tokens (`list[str]`, *tùy chọn*, mặc định là `["<s>NOTUSED", "</s>NOTUSED"]`) : Các token đặc biệt bổ sung được sử dụng bởi tokenizer.

Xây dựng bộ phân từ LayoutXLM "nhanh" (dựa trên thư viện *tokenizers* của HuggingFace). Được điều chỉnh từ [RobertaTokenizer](/docs/transformers/v5.23.0/vi/model_doc/led#transformers.RobertaTokenizer) và [XLNetTokenizer](/docs/transformers/v5.23.0/vi/model_doc/xlnet#transformers.XLNetTokenizer). Dựa trên [BPE](https://huggingface.co/docs/tokenizers/python/latest/components.html?highlight=BPE#models).

Tokenizer này kế thừa từ [TokenizersBackend](/docs/transformers/v5.23.0/vi/main_classes/tokenizer#transformers.TokenizersBackend), lớp chứa hầu hết các phương thức chính. Người dùng nên tham khảo lớp cha này để biết thêm thông tin về các phương thức đó.

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

[Nguồn](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/layoutxlm/tokenization_layoutxlm.py#L413)

**Tham số:**

text (`str`, `list[str]`, `list[list[str]]`) : Chuỗi hoặc lô các chuỗi cần được mã hóa. Mỗi chuỗi có thể là một chuỗi ký tự, một danh sách các chuỗi ký tự (các từ của một ví dụ duy nhất hoặc các câu hỏi của một lô ví dụ) hoặc một danh sách các danh sách chuỗi ký tự (lô các từ).

text_pair (`list[str]`, `list[list[str]]`) : Chuỗi hoặc lô các chuỗi cần được mã hóa. Mỗi chuỗi phải là một danh sách các chuỗi (chuỗi đã được tiền phân tách).

boxes (`list[list[int]]`, `list[list[list[int]]]`) : Hộp bao quanh ở cấp độ từ. Mỗi hộp bao quanh nên được chuẩn hóa trên thang đo 0-1000.

word_labels (`list[int]`, `list[list[int]]`, *tùy chọn*) : Nhãn số nguyên ở cấp độ từ (cho các tác vụ phân loại token như FUNSD, CORD).

add_special_tokens (`bool`, *tùy chọn*, mặc định là `True`) : Có mã hóa các chuỗi với các token đặc biệt tương ứng với mô hình của chúng hay không.

padding (`bool`, `str` hoặc [PaddingStrategy](/docs/transformers/v5.23.0/vi/internal/file_utils#transformers.utils.PaddingStrategy), *tuỳ chọn*, mặc định là `False`) : Kích hoạt và kiểm soát việc đệm. Chấp nhận các giá trị sau:  - `True` hoặc `'longest'`: Đệm đến độ dài của chuỗi dài nhất trong lô (hoặc không đệm nếu chỉ có một chuỗi duy nhất được cung cấp). - `'max_length'`: Đệm đến độ dài tối đa được chỉ định bằng tham số `max_length` hoặc đến độ dài đầu vào tối đa mà mô hình chấp nhận được nếu tham số đó không được cung cấp. - `False` hoặc `'do_not_pad'` (mặc định): Không đệm (tức là có thể xuất ra một lô với các chuỗi có độ dài khác nhau).

truncation (`bool`, `str` hoặc [TruncationStrategy](/docs/transformers/v5.23.0/vi/internal/tokenization_utils#transformers.tokenization_utils_base.TruncationStrategy), *optional*, mặc định là `False`) : Kích hoạt và kiểm soát việc cắt ngắn. Chấp nhận các giá trị sau:  - `True` hoặc `'longest_first'`: Cắt ngắn đến độ dài tối đa được chỉ định bằng tham số `max_length` hoặc đến độ dài đầu vào tối đa mà mô hình chấp nhận được nếu tham số đó không được cung cấp. Thao tác này sẽ cắt ngắn theo từng token, loại bỏ một token từ chuỗi dài nhất trong cặp nếu một cặp chuỗi (hoặc một batch các cặp) được cung cấp. - `'only_first'`: Cắt ngắn đến độ dài tối đa được chỉ định bằng tham số `max_length` hoặc đến độ dài đầu vào tối đa mà mô hình chấp nhận được nếu tham số đó không được cung cấp. Thao tác này chỉ cắt ngắn chuỗi đầu tiên của một cặp nếu một cặp chuỗi (hoặc một batch các cặp) được cung cấp. - `'only_second'`: Cắt ngắn đến độ dài tối đa được chỉ định bằng tham số `max_length` hoặc đến độ dài đầu vào tối đa mà mô hình chấp nhận được nếu tham số đó không được cung cấp. Thao tác này chỉ cắt ngắn chuỗi thứ hai của một cặp nếu một cặp chuỗi (hoặc một batch các cặp) được cung cấp. - `False` hoặc `'do_not_truncate'` (mặc định): Không cắt ngắn (tức là có thể xuất ra batch với độ dài chuỗi lớn hơn kích thước đầu vào tối đa được phép của mô hình).

max_length (`int`, *optional*) : Kiểm soát độ dài tối đa được sử dụng bởi một trong các tham số cắt/giữ chỗ. Nếu không được đặt hoặc được đặt thành `None`, tham số này sẽ sử dụng độ dài tối đa định trước của mô hình nếu một trong các tham số cắt/giữ chỗ yêu cầu độ dài tối đa. Nếu mô hình không có độ dài đầu vào tối đa cụ thể (như XLNet), việc cắt/giữ chỗ đến độ dài tối đa sẽ bị vô hiệu hóa.

stride (`int`, *optional*, mặc định là 0) : Nếu được đặt thành một số cùng với `max_length`, các token tràn được trả về khi `return_overflowing_tokens=True` sẽ chứa một số token từ cuối của chuỗi bị cắt ngắn được trả về để tạo ra một phần chồng lấn giữa các chuỗi bị cắt ngắn và các chuỗi tràn. Giá trị của đối số này xác định số lượng token chồng lấn.

pad_to_multiple_of (`int`, *optional*) : Nếu được đặt, sẽ đệm chuỗi đến bội số của giá trị được cung cấp. Điều này đặc biệt hữu ích để cho phép sử dụng Tensor Cores trên phần cứng NVIDIA có khả năng tính toán `>= 7.5` (Volta).

return_tensors (`str` hoặc [TensorType](/docs/transformers/v5.23.0/vi/internal/file_utils#transformers.TensorType), *optional*) : Nếu được đặt, sẽ trả về các tensor thay vì danh sách các số nguyên python. Các giá trị chấp nhận được là:  - `'pt'`: Trả về các đối tượng `torch.Tensor` của PyTorch. - `'np'`: Trả về các đối tượng `np.ndarray` của Numpy.

return_token_type_ids (`bool`, *tuỳ chọn*) : Có trả về các ID loại token hay không. Nếu để mặc định, sẽ trả về các ID loại token theo mặc định của bộ phân tích token cụ thể, được định nghĩa bởi thuộc tính `return_outputs`.  [ID loại token là gì?](../glossary#token-type-ids)

return_attention_mask (`bool`, *tuỳ chọn*) : Có trả về attention mask hay không. Nếu để mặc định, sẽ trả về attention mask theo mặc định của tokenizer cụ thể, được định nghĩa bởi thuộc tính `return_outputs`.  [Attention mask là gì?](../glossary#attention-mask)

return_overflowing_tokens (`bool`, *tùy chọn*, mặc định là `False`) : Có trả về các chuỗi token bị tràn hay không. Nếu một cặp chuỗi id đầu vào (hoặc một lô các cặp) được cung cấp với `truncation_strategy = longest_first` hoặc `True`, một lỗi sẽ được ném thay vì trả về các token bị tràn.

return_special_tokens_mask (`bool`, *tùy chọn*, mặc định là `False`) : Có trả về thông tin mặt nạ token đặc biệt hay không.

return_offsets_mapping (`bool`, *tùy chọn*, mặc định là `False`) : Có nên trả về `(char_start, char_end)` cho từng token hay không. Tính năng này chỉ khả dụng trên các fast tokenizer kế thừa từ [PreTrainedTokenizerFast](/docs/transformers/v5.23.0/vi/main_classes/tokenizer#transformers.TokenizersBackend); nếu sử dụng tokenizer của Python, phương thức này sẽ gây ra `NotImplementedError`.

return_length  (`bool`, *tùy chọn*, mặc định là `False`) : Có trả về độ dài của các đầu vào đã mã hóa hay không.

verbose (`bool`, *tùy chọn*, mặc định là `True`) : Có in thêm thông tin và cảnh báo hay không.

- ****kwargs** : được truyền vào phương thức `self.tokenize()`

**Trả về:** [BatchEncoding](/docs/transformers/v5.23.0/vi/main_classes/tokenizer#transformers.BatchEncoding)

Một [BatchEncoding](/docs/transformers/v5.23.0/vi/main_classes/tokenizer#transformers.BatchEncoding) với các trường sau:

- **input_ids** -- Danh sách các id token để đưa vào mô hình.

  [ID đầu vào là gì?](../glossary#input-ids)

- **bbox** -- Danh sách các hộp bao (bounding box) để đưa vào mô hình.

- **token_type_ids** -- Danh sách các id loại token để đưa vào mô hình (khi `return_token_type_ids=True` hoặc nếu *"token_type_ids"* nằm trong `self.model_input_names`).

  [ID loại token là gì?](../glossary#token-type-ids)

- **attention_mask** -- Danh sách các chỉ số chỉ định những token nào nên được mô hình chú ý đến (khi `return_attention_mask=True` hoặc nếu *"attention_mask"* nằm trong `self.model_input_names`).

  [Mặt nạ chú ý là gì?](../glossary#attention-mask)

- **labels** -- Danh sách các nhãn được đưa vào mô hình. (khi `word_labels` được chỉ định).
- **overflowing_tokens** -- Danh sách các chuỗi token bị tràn (khi `max_length` được chỉ định và `return_overflowing_tokens=True`).
- **num_truncated_tokens** -- Số lượng token bị cắt bỏ (khi chỉ định `max_length` và `return_overflowing_tokens=True`).
- **special_tokens_mask** -- Danh sách các số 0 và 1, trong đó 1 chỉ định các token đặc biệt đã thêm và 0 chỉ định các token chuỗi thông thường (khi `add_special_tokens=True` và `return_special_tokens_mask=True`).
- **length** -- Độ dài của các đầu vào (khi `return_length=True`).

Phương thức chính để mã hóa (tokenize) và chuẩn bị cho mô hình một hoặc nhiều chuỗi, hoặc một hoặc nhiều cặp chuỗi, kèm theo các hộp giới hạn (bounding box) được chuẩn hóa ở cấp độ từ và các nhãn tùy chọn.

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

[Nguồn](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/layoutxlm/tokenization_layoutxlm.py#L892)

**Tham số:**

token_ids_0 (`list[int]`) : Danh sách các ID mà các token đặc biệt sẽ được thêm vào.

token_ids_1 (`list[int]`, *tuỳ chọn*) : Danh sách ID thứ hai tuỳ chọn cho các cặp chuỗi.

**Trả về:** `list[int]`

Danh sách [input IDs](../glossary#input-ids) với các token đặc biệt phù hợp.

Xây dựng đầu vào mô hình từ một chuỗi hoặc một cặp chuỗi cho các tác vụ phân loại chuỗi bằng cách nối và thêm các token đặc biệt. Một chuỗi XLM-RoBERTa có định dạng như sau:

- một chuỗi đơn: `<s> X </s>`
- cặp chuỗi: `<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)
```

[Nguồn](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/tokenization_utils_base.py#L1337)

**Tham số:**

token_ids_0 : Danh sách các ID của chuỗi (có thể đã được định dạng).

token_ids_1 : Không được sử dụng khi `already_has_special_tokens=True`. Trong trường hợp đó, giá trị phải là None.

already_has_special_tokens : Xác định xem chuỗi đã được định dạng với các token đặc biệt hay chưa.

**Trả về:** Một danh sách các số nguyên trong khoảng [0, 1]

1 cho token đặc biệt, 0 cho token chuỗi.

Lấy các id chuỗi từ một danh sách token không có token đặc biệt nào được thêm vào.

Đối với các tokenizer nhanh, các data collator gọi hàm này với `already_has_special_tokens=True` để xây dựng một mask trên một chuỗi đã được định dạng sẵn. Trong trường hợp đó, chúng ta tính mask bằng cách kiểm tra sự thuộc về trong `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)
```

[Nguồn](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/layoutxlm/tokenization_layoutxlm.py#L918)

**Tham số:**

token_ids_0 (`list[int]`) : Danh sách các ID.

token_ids_1 (`list[int]`, *tuỳ chọn*) : Danh sách ID thứ hai tuỳ chọn cho các cặp chuỗi.

**Trả về:** `list[int]`

Danh sách các số 0.

Tạo một mask từ hai chuỗi được truyền vào để sử dụng trong một tác vụ phân loại cặp chuỗi. XLM-RoBERTa không sử dụng token type ids, do đó một danh sách các số 0 được trả về.

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

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

[Nguồn](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)
```

[Nguồn](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/layoutxlm/processing_layoutxlm.py#L24)

**Tham số:**

image_processor (`LayoutLMv2ImageProcessor`) : Bộ xử lý ảnh là một đầu vào bắt buộc.

tokenizer (`LayoutXLMTokenizer`) : Tokenizer là đầu vào bắt buộc.

Tạo một LayoutXLMProcessor, đóng gói một bộ xử lý ảnh và một tokenizer thành một bộ xử lý duy nhất.

[LayoutXLMProcessor](/docs/transformers/v5.23.0/vi/model_doc/layoutxlm#transformers.LayoutXLMProcessor) cung cấp đầy đủ các chức năng của [LayoutLMv2ImageProcessor](/docs/transformers/v5.23.0/vi/model_doc/layoutlmv2#transformers.LayoutLMv2ImageProcessor) và [LayoutXLMTokenizer](/docs/transformers/v5.23.0/vi/model_doc/layoutxlm#transformers.LayoutXLMTokenizer). Xem [~LayoutLMv2ImageProcessor](/docs/transformers/v5.23.0/vi/model_doc/layoutlmv2#transformers.LayoutLMv2ImageProcessor) và [~LayoutXLMTokenizer](/docs/transformers/v5.23.0/vi/model_doc/layoutxlm#transformers.LayoutXLMTokenizer) để biết thêm thông tin.

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

[Nguồn](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/layoutxlm/processing_layoutxlm.py#L28)

**Tham số:**

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]]]`, *tùy chọn*) : Chuỗi hoặc lô các chuỗi cần được mã hóa. Mỗi chuỗi có thể là một chuỗi ký tự hoặc một danh sách các chuỗi ký tự (chuỗi đã được tách token trước). Nếu bạn truyền vào đầu vào đã tách token trước, hãy đặt `is_split_into_words=True` để tránh nhầm lẫn với các đầu vào dạng lô.

text_pair (`str, list[str] or list[int]`, *tùy chọn*) : Chuỗi thứ hai tùy chọn để mã hóa. Đây có thể là một chuỗi, một danh sách các chuỗi (chuỗi đã được tách token bằng phương thức `tokenize`) hoặc một danh sách các số nguyên (id của chuỗi đã được tách token bằng phương thức `convert_tokens_to_ids`).

boxes (`list[list[int]] or list[list[list[int]]]`, *tùy chọn*) : Hộp bao quanh ở cấp độ từ. Mỗi hộp bao quanh nên được chuẩn hóa trên thang đo 0-1000.

word_labels (`list[int] or list[list[int]]`, *tùy chọn*) : Nhãn số nguyên ở cấp độ từ (cho các tác vụ phân loại token như FUNSD, CORD).

add_special_tokens (`bool`, *tùy chọn*, mặc định là `True`) : Có thêm các token đặc biệt khi mã hóa các chuỗi hay không. Điều này sẽ sử dụng hàm `PretrainedTokenizerBase.build_inputs_with_special_tokens` bên dưới, hàm này xác định các token nào được thêm tự động vào các id đầu vào. Điều này hữu ích nếu bạn muốn tự động thêm các token `bos` hoặc `eos`.

padding (bool, str hoặc [PaddingStrategy](/docs/transformers/v5.23.0/vi/internal/file_utils#transformers.utils.PaddingStrategy), *optional*, mặc định là `False`) : Kích hoạt và kiểm soát việc đệm. Chấp nhận các giá trị sau:  - `True` hoặc `'longest'`: Đệm đến độ dài của chuỗi dài nhất trong batch (hoặc không đệm nếu chỉ cung cấp một chuỗi duy nhất). - `'max_length'`: Đệm đến độ dài tối đa được chỉ định bằng tham số `max_length` hoặc đến độ dài đầu vào tối đa mà mô hình chấp nhận được nếu tham số đó không được cung cấp. - `False` hoặc `'do_not_pad'` (mặc định): Không đệm (tức là có thể xuất ra một batch với các chuỗi có độ dài khác nhau).

truncation (bool, str hoặc [TruncationStrategy](/docs/transformers/v5.23.0/vi/internal/tokenization_utils#transformers.tokenization_utils_base.TruncationStrategy), *optional*) : Kích hoạt và kiểm soát việc cắt ngắn. Chấp nhận các giá trị sau:  - `True` hoặc `'longest_first'`: Cắt ngắn đến độ dài tối đa được chỉ định bằng tham số `max_length` hoặc đến độ dài đầu vào tối đa mà mô hình chấp nhận được nếu tham số đó không được cung cấp. Thao tác này sẽ cắt ngắn theo từng token, loại bỏ một token từ chuỗi dài nhất trong cặp nếu một cặp chuỗi (hoặc một lô các cặp) được cung cấp. - `'only_first'`: Cắt ngắn đến độ dài tối đa được chỉ định bằng tham số `max_length` hoặc đến độ dài đầu vào tối đa mà mô hình chấp nhận được nếu tham số đó không được cung cấp. Thao tác này chỉ cắt ngắn chuỗi đầu tiên của một cặp nếu một cặp chuỗi (hoặc một lô các cặp) được cung cấp. - `'only_second'`: Cắt ngắn đến độ dài tối đa được chỉ định bằng tham số `max_length` hoặc đến độ dài đầu vào tối đa mà mô hình chấp nhận được nếu tham số đó không được cung cấp. Thao tác này chỉ cắt ngắn chuỗi thứ hai của một cặp nếu một cặp chuỗi (hoặc một lô các cặp) được cung cấp. - `False` hoặc `'do_not_truncate'` (mặc định): Không cắt ngắn (tức là có thể xuất ra lô có độ dài chuỗi lớn hơn kích thước đầu vào tối đa được phép của mô hình).

max_length (`int`, *optional*) : Kiểm soát độ dài tối đa được sử dụng bởi một trong các tham số cắt/giữ chỗ. Nếu không được đặt hoặc được đặt thành `None`, tham số này sẽ sử dụng độ dài tối đa định trước của mô hình nếu một trong các tham số cắt/giữ chỗ yêu cầu độ dài tối đa. Nếu mô hình không có độ dài đầu vào tối đa cụ thể (như XLNet), việc cắt/giữ chỗ đến độ dài tối đa sẽ bị vô hiệu hóa.

stride (`int`, *optional*, mặc định là `0`) : Nếu được đặt thành một số cùng với `max_length`, các token tràn ra được trả về khi `return_overflowing_tokens=True` sẽ chứa một số token từ cuối của chuỗi bị cắt ngắn được trả về để tạo ra một phần chồng lấn giữa chuỗi bị cắt ngắn và chuỗi tràn ra. Giá trị của đối số này xác định số lượng token chồng lấn.

pad_to_multiple_of (`int`, *optional*) : Nếu được đặt, sẽ đệm chuỗi đến bội số của giá trị được cung cấp. Yêu cầu `padding` phải được kích hoạt. Điều này đặc biệt hữu ích để cho phép sử dụng Tensor Cores trên phần cứng NVIDIA có khả năng tính toán `>= 7.5` (Volta).

return_token_type_ids (`bool`, *tuỳ chọn*) : Có trả về các ID loại token hay không. Nếu để mặc định, sẽ trả về các ID loại token theo mặc định của bộ phân tích token cụ thể, được định nghĩa bởi thuộc tính `return_outputs`.  [ID loại token là gì?](../glossary#token-type-ids)

return_attention_mask (`bool`, *tuỳ chọn*) : Có trả về attention mask hay không. Nếu để mặc định, sẽ trả về attention mask theo mặc định của tokenizer cụ thể, được định nghĩa bởi thuộc tính `return_outputs`.  [Attention mask là gì?](../glossary#attention-mask)

return_overflowing_tokens (`bool`, *tùy chọn*, mặc định là `False`) : Có trả về các chuỗi token bị tràn hay không. Nếu một cặp chuỗi id đầu vào (hoặc một lô các cặp) được cung cấp với `truncation_strategy = longest_first` hoặc `True`, một lỗi sẽ được ném thay vì trả về các token bị tràn.

return_special_tokens_mask (`bool`, *tùy chọn*, mặc định là `False`) : Có trả về thông tin mặt nạ token đặc biệt hay không.

return_offsets_mapping (`bool`, *tùy chọn*, mặc định là `False`) : Có nên trả về `(char_start, char_end)` cho từng token hay không. Tính năng này chỉ khả dụng trên các fast tokenizer kế thừa từ [PreTrainedTokenizerFast](/docs/transformers/v5.23.0/vi/main_classes/tokenizer#transformers.TokenizersBackend); nếu sử dụng tokenizer của Python, phương thức này sẽ gây ra `NotImplementedError`.

return_length (`bool`, *tùy chọn*, mặc định là `False`) : Có trả về độ dài của các đầu vào đã mã hóa hay không.

verbose (`bool`, *tùy chọn*, mặc định là `True`) : Có in thêm thông tin và cảnh báo hay không.

return_tensors (`Union[str, ~utils.generic.TensorType]`, *tùy chọn*) : Nếu được đặt, sẽ trả về các tensor của một framework cụ thể. Các giá trị chấp nhận được là:  - `'pt'`: Trả về các đối tượng `torch.Tensor` của PyTorch. - `'np'`: Trả về các đối tượng `np.ndarray` của NumPy.

**Trả về:** `~tokenization_utils_base.BatchEncoding`

- **data** (`dict`, *tuỳ chọn*) -- Từ điển chứa các danh sách/mảng/tensor được trả về bởi các phương thức `__call__`/`encode_plus`/`batch_encode_plus` ('input_ids', 'attention_mask', v.v.).
- **encoding** (`tokenizers.Encoding` hoặc `Sequence[tokenizers.Encoding]`, *tùy chọn*) -- Nếu tokenizer là fast tokenizer có xuất ra thêm thông tin như ánh xạ từ không gian từ/ký tự sang không gian token thì instance `tokenizers.Encoding` hoặc danh sách các instance (cho các batch) sẽ chứa thông tin này.
- **tensor_type** (`Union[None, str, TensorType]`, *tùy chọn*) -- Bạn có thể cung cấp tensor_type tại đây để chuyển đổi các danh sách số nguyên trong Tensor PyTorch/Numpy khi khởi tạo.
- **prepend_batch_axis** (`bool`, *tùy chọn*, mặc định là `False`) -- Có thêm một trục batch khi chuyển đổi sang tensor hay không (xem `tensor_type` ở trên). Lưu ý rằng tham số này có hiệu lực nếu tham số `tensor_type` được đặt, *ngược lại thì không có hiệu lực*.
- **n_sequences** (`int`, *tùy chọn*) -- Số lượng chuỗi đầu vào được biểu diễn bởi mỗi mã hóa (`None` cho trường hợp không xác định, `1` cho một chuỗi đơn và `2` cho một cặp chuỗi).

