Transformers documentation
mLUKE
이 모델은 2021-10-15에 HF papers에 게시되었으며, 2021-12-07에 Hugging Face Transformers에 기여되었습니다.
mLUKE
개요
mLUKE 모델은 Ryokan Ri, Ikuya Yamada, Yoshimasa Tsuruoka가 mLUKE: The Power of Entity Representations in Multilingual Pretrained Language Models에서 제안했습니다. 이는 XLM-RoBERTa를 기반으로 학습된 LUKE 모델의 다국어 확장 버전입니다.
XLM-RoBERTa를 기반으로 하며, 엔티티 임베딩을 추가하여 named entity recognition, extractive question answering, relation classification, cloze-style knowledge completion과 같이 엔티티에 대한 추론이 필요한 다양한 다운스트림 작업의 성능을 향상시킵니다.
해당 논문의 초록은 다음과 같습니다:
최근 연구에 따르면, 다국어 사전 학습 언어 모델은 Wikipedia 엔티티의 언어 간 정렬 정보를 활용하여 효과적으로 개선될 수 있습니다. 그러나 기존 방법들은 사전 학습 단계에서만 엔티티 정보를 활용하며, 하위 작업에서 엔티티를 명시적으로 사용하지 않습니다. 본 연구에서는 하위 언어 간 작업에 엔티티 표현을 활용하는 것의 효과성을 탐구합니다. 24개 언어의 엔티티 표현을 사용하여 다국어 언어 모델을 학습시키고, 다양한 언어 간 전이 작업에서 해당 모델이 단어 기반 사전 학습 모델보다 일관되게 우수한 성능을 보임을 확인했습니다. 또한 모델을 분석한 결과, 입력에 엔티티 표현을 통합하면 언어에 독립적인 특징을 더 많이 추출할 수 있다는 핵심 통찰을 얻었습니다. 또한 mLAMA 데이터셋을 사용하여 다국어 cloze prompt 작업으로 모델을 평가했습니다. 엔티티 기반 prompt가 단어 표현만 사용하는 경우보다 올바른 사실 지식을 더 잘 유도함을 확인했습니다.
이 모델은 ryo0634님이 기여했습니다. 원본 코드는 여기에서 확인할 수 있습니다.
사용 팁
mLUKE의 가중치를 LUKE 모델에 직접 삽입할 수 있습니다. 방법은 다음과 같습니다:
from transformers import LukeModel
model = LukeModel.from_pretrained("studio-ousia/mluke-base", device_map="auto")mLUKE는 자체 토크나이저인 MLukeTokenizer를 사용합니다. 다음과 같이 초기화할 수 있습니다:
from transformers import MLukeTokenizer
tokenizer = MLukeTokenizer.from_pretrained("studio-ousia/mluke-base")mLUKE의 아키텍처가 LUKE와 동일하므로, 모든 팁, 코드 예제 및 노트북은 LUKE 문서 페이지를 참고할 수 있습니다.
MLukeTokenizer
클래스 transformers.MLukeTokenizer
< source >( bos_token = '<s>'eos_token = '</s>'sep_token = '</s>'cls_token = '<s>'unk_token = '<unk>'pad_token = '<pad>'mask_token = '<mask>'task = Nonemax_entity_length = 32max_mention_length = 30entity_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 = Noneentity_vocab: str | dict | list | None = None**kwargs )
매개변수
- vocab_file (
str) — 어휘 파일의 경로입니다. - entity_vocab_file (
str) — 엔티티 어휘 파일의 경로. - bos_token (
str, 선택 사항, 기본값은"<s>") — 사전 학습 시 사용된 시퀀스 시작 토큰입니다. 시퀀스 분류기 토큰으로 사용할 수 있습니다.특수 토큰을 사용하여 시퀀스를 구성할 때, 시퀀스의 시작에 사용되는 토큰은 이 토큰이 아닙니다. 사용되는 토큰은
cls_token입니다. - eos_token (
str, 선택 사항, 기본값은"</s>") — 시퀀스 종료 토큰입니다. 특수 토큰을 사용하여 시퀀스를 구성할 때, 시퀀스 종료에 사용되는 토큰은 이 토큰이 아닙니다. 시퀀스 종료에 사용되는 토큰은 sep_token입니다.특수 토큰을 사용하여 시퀀스를 구성할 때, 시퀀스 끝에는 이 토큰이 사용되지 않습니다. 사용되는 토큰은
sep_token입니다. - sep_token (
str, 선택, 기본값"</s>") — 여러 시퀀스로 시퀀스를 구성할 때 사용되는 구분 토큰입니다. 예를 들어 시퀀스 분류의 두 시퀀스나 질의응답의 텍스트와 질문 등에 사용됩니다. 특수 토큰으로 구성된 시퀀스의 마지막 토큰으로도 사용됩니다. - cls_token (
str, 선택 사항, 기본값"<s>") — 시퀀스 분류(토큰별 분류가 아닌 전체 시퀀스 분류)를 수행할 때 사용되는 분류기 토큰입니다. 특수 토큰을 사용하여 시퀀스를 구성할 경우 시퀀스의 첫 번째 토큰입니다. - unk_token (
str, 선택 사항, 기본값"<unk>") — 미지의 토큰입니다. 어휘에 없는 토큰은 ID로 변환할 수 없으므로, 대신 이 토큰으로 설정됩니다. - pad_token (
str, 선택 사항, 기본값"<pad>") — 패딩에 사용되는 토큰입니다. 예를 들어, 길이가 다른 시퀀스를 배치(batching)할 때 사용됩니다. - mask_token (
str, 선택 사항, 기본값"<mask>") — 값을 마스킹하는 데 사용되는 토큰입니다. 이는 masked language modeling으로 이 모델을 학습할 때 사용되는 토큰이며, 모델이 예측을 시도하는 대상이 되는 토큰입니다. - task (
str, 선택 사항) — 시퀀스를 준비하려는 작업입니다."entity_classification","entity_pair_classification", 또는"entity_span_classification"중 하나입니다. 이 인수를 지정하면 주어진 entity span을 기반으로 entity 시퀀스가 자동으로 생성됩니다. - max_entity_length (
int, 선택 사항, 기본값 32) —entity_ids의 최대 길이입니다. - max_mention_length (
int, 선택 사항, 기본값 30) — 엔티티 스팬 내부의 최대 토큰 수입니다. - entity_1_token (
str, 선택 사항, 기본값<ent>) — 워드 토큰 시퀀스에서 엔티티 스팬을 나타내는 데 사용되는 특수 토큰입니다. 이 토큰은task가"entity_classification"또는"entity_pair_classification"으로 설정된 경우에만 사용됩니다. - entity_2_token (
str, 선택 사항, 기본값<ent2>) — 워드 토큰 시퀀스에서 엔티티 스팬을 나타내는 데 사용되는 특수 토큰입니다. 이 토큰은task가"entity_pair_classification"으로 설정된 경우에만 사용됩니다. - additional_special_tokens (
list[str], 선택, 기본값["<s>NOTUSED", "</s>NOTUSED"]) — 토크나이저에서 사용하는 추가 특수 토큰입니다. - sp_model_kwargs (
dict, 선택 사항) — 다음 메서드에 전달됩니다.SentencePieceProcessor.__init__()SentencePiece의 Python 래퍼 를 사용하여 다음을 설정할 수 있습니다:-
enable_sampling: 서브워드 정규화를 활성화합니다. -
nbest_size: unigram의 샘플링 파라미터입니다. BPE-Dropout에는 사용할 수 없습니다.nbest_size = {0,1}: 샘플링이 수행되지 않습니다.nbest_size > 1: nbest_size 결과에서 샘플링합니다.nbest_size < 0: nbest_size가 무한하다고 가정하고, forward-filtering-and-backward-sampling 알고리즘을 사용하여 모든 가설(lattice)에서 샘플링합니다.
-
alpha: unigram 샘플링의 smoothing parameter 및 BPE-dropout의 merge 작업 dropout 확률
-
- sp_model (
SentencePieceProcessor) — 모든 변환(문자열, 토큰 및 ID)에 사용되는 SentencePiece 프로세서입니다.
XLMRobertaTokenizer 및 LukeTokenizer에서 파생되었습니다. SentencePiece를 기반으로 합니다.
이 토크나이저는 대부분의 주요 메서드를 포함하는 PreTrainedTokenizer를 상속합니다. 해당 메서드에 대한 자세한 내용은 이 상위 클래스를 참고하세요.
__call__
< source >( text: str | list[str]text_pair: str | list[str] | None = Noneentity_spans: list[tuple[int, int]] | list[list[tuple[int, int]]] | None = Noneentity_spans_pair: list[tuple[int, int]] | list[list[tuple[int, int]]] | None = Noneentities: list[str] | list[list[str]] | None = Noneentities_pair: list[str] | list[list[str]] | None = Noneadd_special_tokens: bool = Truepadding: bool | str | transformers.utils.generic.PaddingStrategy = Falsetruncation: bool | str | transformers.tokenization_utils_base.TruncationStrategy | None = Nonemax_length: int | None = Nonemax_entity_length: int | None = Nonestride: int = 0is_split_into_words: bool | None = Falsepad_to_multiple_of: int | None = Nonepadding_side: str | None = Nonereturn_tensors: str | transformers.utils.generic.TensorType | None = Nonereturn_token_type_ids: bool | None = Nonereturn_attention_mask: bool | None = Nonereturn_overflowing_tokens: bool = Falsereturn_special_tokens_mask: bool = Falsereturn_offsets_mapping: bool = Falsereturn_length: bool = Falseverbose: bool = True**kwargs ) → BatchEncoding
반환값
다음 필드를 가진 BatchEncoding:
-
input_ids — 모델에 입력할 토큰 ID 목록.
-
token_type_ids — 모델에 입력할 토큰 유형 ID 목록 (
return_token_type_ids=True인 경우 또는self.model_input_names에 “token_type_ids”가 포함된 경우). -
attention_mask — 모델이 어떤 토큰에 주의를 기울여야 하는지 지정하는 인덱스 목록 (
return_attention_mask=True이거나self.model_input_names에 “attention_mask”가 포함된 경우). -
entity_ids — 모델에 입력할 엔티티 ID 목록.
-
entity_position_ids — 모델에 입력될 입력 시퀀스 내 엔티티 위치 목록.
-
entity_token_type_ids — 모델에 입력할 엔티티 토큰 타입 ID 목록 (
return_token_type_ids=True인 경우 또는self.model_input_names에 “entity_token_type_ids”가 포함된 경우). -
entity_attention_mask — 모델이 주의를 기울여야 할 엔티티를 지정하는 인덱스 목록 (
return_attention_mask=True인 경우 또는self.model_input_names에 “entity_attention_mask”가 포함된 경우). -
entity_start_positions — 워드 토큰 시퀀스에서 엔티티의 시작 위치 목록(
task="entity_span_classification"인 경우). -
entity_end_positions — 워드 토큰 시퀀스에서 엔티티의 끝 위치 목록(
task="entity_span_classification"인 경우). -
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인 경우)
add_special_tokens (bool, 선택 사항, 기본값 True):
시퀀스를 인코딩할 때 특수 토큰을 추가할지 여부입니다. 이는 입력 id에 자동으로 추가되는 토큰을 정의하는 PretrainedTokenizerBase.build_inputs_with_special_tokens 함수를 사용합니다. bos 또는 eos 토큰을 자동으로 추가하려는 경우 유용합니다.
padding (bool, str 또는 PaddingStrategy, 선택 사항, 기본값 False):
패딩을 활성화하고 제어합니다. 다음 값을 허용합니다:
True또는'longest': 배치 내 가장 긴 시퀀스 길이에 맞게 패딩을 수행합니다(단일 시퀀스만 제공된 경우 패딩을 하지 않음).'max_length':max_length인수로 지정된 최대 길이로 패딩하거나, 해당 인수가 제공되지 않으면 모델이 허용하는 최대 입력 길이로 패딩합니다.False또는'do_not_pad'(기본값): 패딩을 하지 않습니다(즉, 길이가 서로 다른 시퀀스로 구성된 배치로 출력할 수 있습니다). truncation(bool,str또는 TruncationStrategy, 선택 사항, 기본값False): 트렁케이션을 활성화하고 제어합니다. 다음 값을 허용합니다:True또는'longest_first':max_length인수로 지정된 최대 길이로 잘라내거나, 해당 인수가 제공되지 않으면 모델이 허용하는 최대 입력 길이로 잘라냅니다. 이 경우 토큰 단위로 잘라내며, 시퀀스 쌍(또는 쌍의 배치)이 제공되면 쌍 중 가장 긴 시퀀스에서 토큰을 하나씩 제거합니다.'only_first':max_length인수로 지정된 최대 길이 또는 해당 인수가 제공되지 않은 경우 모델이 허용하는 최대 입력 길이로 잘립니다. 이 옵션은 시퀀스 쌍(또는 쌍의 배치)이 제공된 경우 쌍의 첫 번째 시퀀스만 잘립니다.'only_second':max_length인수로 지정된 최대 길이로 잘라내거나, 해당 인수가 제공되지 않은 경우 모델이 허용하는 최대 입력 길이로 잘라냅니다. 이 옵션은 시퀀스 쌍(또는 쌍의 배치)이 제공된 경우에만 쌍의 두 번째 시퀀스를 잘라냅니다.False또는'do_not_truncate'(기본값): 잘라내지 않음(즉, 모델이 허용하는 최대 입력 크기보다 긴 시퀀스 길이를 가진 배치로 출력할 수 있음). max_length (int, 선택 사항): 잘라내기/패딩 매개변수 중 하나로 사용할 최대 길이를 제어합니다.
설정하지 않거나 None으로 설정한 경우, truncation/padding 파라미터 중 하나가 최대 길이를 요구하면 미리 정의된 모델 최대 길이를 사용합니다. 모델에 특정 최대 입력 길이가 없는 경우(XLNet 등)에는 최대 길이로 truncation/padding을 수행하는 기능이 비활성화됩니다.
stride (int, 선택 사항, 기본값 0):
max_length와 함께 숫자로 설정하면, return_overflowing_tokens=True일 때 반환되는 overflowing 토큰에는 반환된 truncated 시퀀스의 끝부분에서 가져온 일부 토큰이 포함되어 truncated 시퀀스와 overflowing 시퀀스 사이에 일부 중복이 발생하도록 합니다. 이 인수의 값은 중복되는 토큰의 수를 정의합니다.
is_split_into_words (bool, 선택 사항, 기본값 False):
입력이 이미 사전 토큰화(예: 단어 단위로 분리)되었는지를 나타냅니다. True로 설정하면, 토크나이저는 입력이 이미 단어 단위로 분리되어 있다고 가정합니다(예: 공백 기준으로 분리). 이후 이를 토큰화합니다. 이는 NER 또는 토큰 분류에 유용합니다.
pad_to_multiple_of (int, 선택 사항):
설정하면 시퀀스를 제공된 값의 배수로 패딩합니다. padding이 활성화되어 있어야 합니다. 이는 compute capability가 >= 7.5(Volta)인 NVIDIA 하드웨어에서 Tensor Cores 사용을 가능하게 하는 데 특히 유용합니다.
padding_side (str, 선택 사항):
모델에 패딩을 적용할 쪽을 지정합니다. [‘right’, ‘left’] 중 하나를 선택해야 합니다. 기본값은 동일한 이름의 클래스 속성에서 선택됩니다.
return_tensors (str 또는 TensorType, 선택 사항):
설정하면 python 정수 목록 대신 텐서를 반환합니다. 허용되는 값은 다음과 같습니다:
'pt': PyTorchtorch.Tensor객체를 반환합니다.'np': Numpynp.ndarray객체를 반환합니다.
return_token_type_ids (bool, 선택 사항):
토큰 유형 ID를 반환할지 여부입니다. 기본값을 유지하면 return_outputs 속성으로 정의된 해당 토크나이저의 기본값에 따라 토큰 유형 ID를 반환합니다.
토큰 타입 ID란 무엇인가요? return_attention_mask (bool, 선택 사항):
어텐션 마스크를 반환할지 여부입니다. 기본값으로 두면, return_outputs 속성으로 정의된 해당 토크나이저의 기본값에 따라 어텐션 마스크를 반환합니다.
어텐션 마스크란 무엇인가요? 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를 상속하는 fast tokenizer에서만 사용할 수 있으며, Python의 tokenizer를 사용하는 경우 이 메서드는 NotImplementedError를 발생시킵니다.
return_length (bool, 선택 사항, 기본값 False):
인코딩된 입력의 길이를 반환할지 여부.
verbose (bool, 선택 사항, 기본값 True):
추가 정보와 경고를 출력할지 여부.
**kwargs: self.tokenize() 메서드에 전달됩니다
entity 어휘 파일만 저장합니다. tokenizer.json은 상위 TokenizersBackend에 의해 저장됩니다.