# mLUKE

## Tổng quan

Mô hình mLUKE được đề xuất trong [mLUKE: The Power of Entity Representations in Multilingual Pretrained Language Models](https://huggingface.co/papers/2110.08151) bởi Ryokan Ri, Ikuya Yamada và Yoshimasa Tsuruoka. Đây là phiên bản đa ngôn ngữ của [mô hình LUKE](https://huggingface.co/papers/2010.01057), được huấn luyện dựa trên XLM-RoBERTa.

Mô hình này được xây dựng dựa trên XLM-RoBERTa và bổ sung entity embeddings, giúp cải thiện hiệu suất trên nhiều tác vụ downstream khác nhau liên quan đến suy luận về các entity, chẳng hạn như nhận thực thể có tên (named entity recognition), trả lời câu hỏi dạng trích xuất (extractive question answering), phân loại quan hệ (relation classification) và hoàn thành kiến thức theo dạng cloze.

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

*Các nghiên cứu gần đây cho thấy các mô hình ngôn ngữ đa ngôn ngữ được huấn luyện trước có thể được cải thiện hiệu quả bằng thông tin căn chỉnh liên ngôn ngữ từ các thực thể Wikipedia. Tuy nhiên, các phương pháp hiện tại chỉ khai thác thông tin thực thể trong giai đoạn huấn luyện trước và không sử dụng thực thể một cách tường minh trong các tác vụ hạ nguồn. Trong nghiên cứu này, chúng tôi khám phá hiệu quả của việc tận dụng các biểu diễn thực thể cho các tác vụ liên ngôn ngữ hạ nguồn. Chúng tôi huấn luyện một mô hình ngôn ngữ đa ngôn ngữ với 24 ngôn ngữ bằng các biểu diễn thực thể và cho thấy mô hình này luôn vượt trội so với các mô hình huấn luyện trước dựa trên từ trong nhiều tác vụ chuyển giao liên ngôn ngữ khác nhau. Chúng tôi cũng phân tích mô hình và nhận thấy rằng việc tích hợp các biểu diễn thực thể vào đầu vào cho phép chúng tôi trích xuất nhiều đặc tính không phụ thuộc vào ngôn ngữ hơn. Chúng tôi cũng đánh giá mô hình với một tác vụ prompt điền khuyết đa ngôn ngữ sử dụng bộ dữ liệu mLAMA. Chúng tôi cho thấy prompt dựa trên thực thể khơi gợi kiến thức thực tế chính xác nhiều hơn so với việc chỉ sử dụng các biểu diễn từ.*

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

## Mẹo sử dụng

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

```python
from transformers import LukeModel

model = LukeModel.from_pretrained("studio-ousia/mluke-base", device_map="auto")
```

Lưu ý rằng mLUKE có bộ phân từ riêng, [MLukeTokenizer](/docs/transformers/main/vi/model_doc/mluke#transformers.MLukeTokenizer). Bạn có thể khởi tạo nó như sau:

```python
from transformers import MLukeTokenizer

tokenizer = MLukeTokenizer.from_pretrained("studio-ousia/mluke-base")
```

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

## MLukeTokenizer[[transformers.MLukeTokenizer]]

#### transformers.MLukeTokenizer[[transformers.MLukeTokenizer]]

```python
transformers.MLukeTokenizer(bos_token = '<s>', eos_token = '</s>', sep_token = '</s>', cls_token = '<s>', unk_token = '<unk>', pad_token = '<pad>', mask_token = '<mask>', task = None, max_entity_length = 32, max_mention_length = 30, entity_1_token = '<ent>', entity_2_token = '<ent2>', entity_unk_token = '[UNK]', entity_pad_token = '[PAD]', entity_mask_token = '[MASK]', entity_mask2_token = '[MASK2]', vocab: str | dict | list | None = None, entity_vocab: str | dict | list | None = None, **kwargs)
```

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/models/mluke/tokenization_mluke.py#L129)

**Tham số:**

vocab_file (`str`) : Đường dẫn đến tệp từ vựng.

entity_vocab_file (`str`) : Đường dẫn đến tệp từ vựng thực thể.

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.

task (`str`, *tùy chọn*) : Nhiệm vụ mà bạn muốn chuẩn bị các chuỗi. Một trong số `"entity_classification"`, `"entity_pair_classification"` hoặc `"entity_span_classification"`. Nếu bạn chỉ định đối số này, chuỗi thực thể sẽ được tạo tự động dựa trên các khoảng thực thể (entity span) được cung cấp.

max_entity_length (`int`, *tuỳ chọn*, mặc định là 32) : Độ dài tối đa của `entity_ids`.

max_mention_length (`int`, *tuỳ chọn*, mặc định là 30) : Số lượng token tối đa bên trong một khoảng thực thể.

entity_1_token (`str`, *tùy chọn*, mặc định là `<ent>`) : Token đặc biệt được dùng để biểu diễn một khoảng thực thể trong chuỗi token từ. Token này chỉ được sử dụng khi `task` được đặt thành `"entity_classification"` hoặc `"entity_pair_classification"`.

entity_2_token (`str`, *tùy chọn*, mặc định là `<ent2>`) : Token đặc biệt được sử dụng để đại diện cho một khoảng thực thể trong chuỗi token từ. Token này chỉ được sử dụng khi `task` được đặt thành `"entity_pair_classification"`.

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.

sp_model_kwargs (`dict`, *tùy chọn*) : Sẽ được truyền vào phương thức `SentencePieceProcessor.__init__()`. [Python wrapper for SentencePiece](https://github.com/google/sentencepiece/tree/master/python) có thể được sử dụng, trong số nhiều mục đích khác, để thiết lập:  - `enable_sampling`: Bật chuẩn hóa subword. - `nbest_size`: Tham số lấy mẫu cho unigram. Không hợp lệ cho BPE-Dropout.  - `nbest_size = {0,1}`: Không thực hiện lấy mẫu. - `nbest_size > 1`: lấy mẫu từ các kết quả nbest_size. - `nbest_size < 0`: giả định rằng nbest_size là vô hạn và lấy mẫu từ tất cả các giả thuyết (lattice) bằng thuật toán forward-filtering-and-backward-sampling.  - `alpha`: Tham số làm mượt cho việc lấy mẫu unigram, và xác suất dropout của các thao tác merge cho BPE-dropout.

sp_model (`SentencePieceProcessor`) : Bộ xử lý *SentencePiece* được sử dụng cho mọi phép chuyển đổi (chuỗi, token và ID).

Được điều chỉnh từ [XLMRobertaTokenizer](/docs/transformers/main/vi/model_doc/xlm-roberta#transformers.XLMRobertaTokenizer) và [LukeTokenizer](/docs/transformers/main/vi/model_doc/luke#transformers.LukeTokenizer). Dựa trên [SentencePiece](https://github.com/google/sentencepiece).

Tokenizer này kế thừa từ [PreTrainedTokenizer](/docs/transformers/main/vi/main_classes/tokenizer#transformers.PythonBackend), 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 siêu lớp này để biết thêm thông tin về các phương thức đó.

#### __call__[[transformers.MLukeTokenizer.__call__]]

```python
__call__(text: str | list[str], text_pair: str | list[str] | None = None, entity_spans: list[tuple[int, int]] | list[list[tuple[int, int]]] | None = None, entity_spans_pair: list[tuple[int, int]] | list[list[tuple[int, int]]] | None = None, entities: list[str] | list[list[str]] | None = None, entities_pair: list[str] | list[list[str]] | None = None, add_special_tokens: bool = True, padding: bool | str | transformers.utils.generic.PaddingStrategy = False, truncation: bool | str | transformers.tokenization_utils_base.TruncationStrategy | None = None, max_length: int | None = None, max_entity_length: int | None = None, stride: int = 0, is_split_into_words: bool | None = False, pad_to_multiple_of: int | None = None, padding_side: str | None = None, return_tensors: str | transformers.utils.generic.TensorType | None = None, return_token_type_ids: bool | None = None, return_attention_mask: bool | None = None, return_overflowing_tokens: bool = False, return_special_tokens_mask: bool = False, return_offsets_mapping: bool = False, return_length: bool = False, verbose: bool = True, **kwargs)
```

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/models/mluke/tokenization_mluke.py#L469)

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

Một [BatchEncoding](/docs/transformers/main/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)

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

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

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

- **entity_position_ids** -- Danh sách các vị trí thực thể trong chuỗi đầu vào sẽ được đưa vào mô hình.

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

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

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

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

- **entity_start_positions** -- Danh sách các vị trí bắt đầu của các thực thể trong chuỗi token từ (khi `task="entity_span_classification"`).
- **entity_end_positions** -- Danh sách các vị trí kết thúc của các thực thể trong chuỗi token từ (khi `task="entity_span_classification"`).
- **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`)

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/main/vi/internal/file_utils#transformers.utils.PaddingStrategy), *tùy 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'`: Lấp đầy đến trình tự dài nhất trong lô (hoặc không lấp đầy nếu chỉ cung cấp một trình tự duy nhất).
- `'max_length'`: Đệm (pad) đế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/main/vi/internal/tokenization_utils#transformers.tokenization_utils_base.TruncationStrategy), *tuỳ chọn*, 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 xuống độ dài tối đa được chỉ định bằng tham số `max_length` hoặc xuống độ dài đầu vào tối đa chấp nhận được của mô hình 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 xuống độ dài tối đa được chỉ định bằng tham số `max_length` hoặc xuống độ 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 xuống độ dài tối đa được chỉ định bằng tham số `max_length` hoặc xuống độ 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 bớt (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`, *tuỳ chọn*): Kiểm soát độ dài tối đa được sử dụng bởi một trong các tham số cắt ngắn/lấp đầy.

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`, *tùy chọn*, 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 được trả về để tạo ra một phần chồng lấn giữa các chuỗi bị cắt và các chuỗi tràn ra. Giá trị của đối số này xác định số lượng token chồng lấn. is_split_into_words (`bool`, *tùy chọn*, mặc định là `False`): Cho biết đầu vào đã được tiền tách token (ví dụ: tách thành các từ) hay chưa. Nếu được đặt thành `True`, bộ tách token sẽ giả định rằng đầu vào đã được tách thành các từ (ví dụ, bằng cách tách theo khoảng trắng) và sẽ tách token chúng. Điều này hữu ích cho NER hoặc phân loại token. pad_to_multiple_of (`int`, *tùy chọn*): Nếu được đặt, sẽ giữ chỗ cho chuỗi đến một 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). padding_side (`str`, *tùy chọn*): Bên mà mô hình nên được áp dụng giữ chỗ. Nên được chọn giữa ['right', 'left']. Giá trị mặc định được chọn từ thuộc tính lớp có cùng tên. return_tensors (`str` hoặc [TensorType](/docs/transformers/main/vi/internal/file_utils#transformers.TensorType), *tùy chọn*): 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 Numpy `np.ndarray`.

return_token_type_ids (`bool`, *tùy chọn*): Xác định có trả về các ID loại token hay không. Nếu giữ nguyên giá trị 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`.

[Token type IDs là gì?](../glossary#token-type-ids) return_attention_mask (`bool`, *tùy 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`.

[Mặt nạ chú ý 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 tràn hay không. Nếu một cặp các 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 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ó trả về `(char_start, char_end)` cho mỗi token hay không.

Tính năng này chỉ khả dụng trên các bộ phân từ nhanh kế thừa từ [PreTrainedTokenizerFast](/docs/transformers/main/vi/main_classes/tokenizer#transformers.TokenizersBackend); nếu sử dụng bộ phân từ 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 đến phương thức `self.tokenize()`

#### save_vocabulary[[transformers.MLukeTokenizer.save_vocabulary]]

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

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/models/mluke/tokenization_mluke.py#L1703)

Chỉ lưu tệp từ vựng thực thể. Tệp tokenizer.json được lưu bởi TokenizersBackend cha.