Hugging Face's logo

Transformers documentation

데이터 콜레이터

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.22.1).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

데이터 콜레이터

Data collator는 train_dataset 또는 eval_dataset의 요소와 동일한 유형의 데이터셋 요소 목록을 입력으로 받아 배치(batch)를 형성하는 객체입니다.

배치를 구성하기 위해 데이터 콜레이터는 패딩과 같은 일부 전처리를 적용할 수 있습니다. 일부 콜레이터(예: DataCollatorForLanguageModeling)는 형성된 배치에 무작위 데이터 증강(예: 무작위 마스킹)도 적용합니다.

사용 예제는 예제 노트북에서 확인할 수 있습니다.

기본 데이터 콜레이터

transformers.default_data_collator

< >

( features: listreturn_tensors = 'pt' )

dict 형태의 객체 배치에 대해 단순히 배치 처리를 수행하고, 다음 이름의 잠재적 키에 대해 특별한 처리를 수행하는 매우 간단한 데이터 콜레이터입니다:

  • label: 개체당 단일 값(int 또는 float)을 처리합니다
  • label_ids: 개체별 값 목록을 처리합니다

추가 전처리 작업을 수행하지 않습니다: 입력 객체의 속성 이름이 모델의 해당 입력으로 사용됩니다. 유용한 사용 예로는 glue와 ner를 참고하세요.

DefaultDataCollator

class transformers.DefaultDataCollator

< >

( return_tensors: str = 'pt' )

매개변수

  • return_tensors (str, 선택 사항, 기본값 "pt") — 반환할 Tensor의 유형입니다. 허용되는 값은 “np” 또는 “pt”입니다.

dict 형태의 객체 배치에 대해 단순히 배치 처리를 수행하고, 다음 이름의 잠재적 키에 대해 특별한 처리를 수행하는 매우 간단한 데이터 콜레이터입니다:

  • label: 개체당 단일 값(int 또는 float)을 처리합니다
  • label_ids: 개체별 값 목록을 처리합니다

추가 전처리 작업을 수행하지 않습니다: 입력 객체의 속성 이름이 모델의 해당 입력으로 사용됩니다. 유용한 사용 예로는 glue와 ner를 참고하세요.

이것은 default_data_collator과 같은 순수 함수가 아니라, 다른 데이터 콜레이터와 마찬가지로 객체입니다. 초기화 시 return_tensors 값을 설정해야 하는 경우 유용할 수 있습니다.

DataCollatorWithPadding

클래스 transformers.DataCollatorWithPadding

< >

( tokenizer: PreTrainedTokenizerBasepadding: bool | str | transformers.utils.generic.PaddingStrategy = Truemax_length: int | None = Nonepad_to_multiple_of: int | None = Nonereturn_tensors: str = 'pt' )

매개변수

  • tokenizer (PreTrainedTokenizer 또는 PreTrainedTokenizerFast) — 데이터 인코딩에 사용되는 토크나이저입니다.
  • padding (bool, str 또는 PaddingStrategy, 선택 사항, 기본값은 True) — 반환되는 시퀀스에 패딩을 적용할 전략을 선택합니다(모델의 패딩 방향 및 패딩 인덱스에 따라). 다음 중 하나를 선택할 수 있습니다:
    • True 또는 'longest' (기본값): 배치 내 가장 긴 시퀀스 길이에 맞게 패딩을 수행합니다(단일 시퀀스만 제공된 경우 패딩을 하지 않음).
    • 'max_length': max_length 인수로 지정된 최대 길이로 패딩하거나, 해당 인수가 제공되지 않으면 모델이 허용하는 최대 입력 길이로 패딩합니다.
    • False 또는 'do_not_pad': 패딩을 하지 않습니다(즉, 서로 다른 길이의 시퀀스를 가진 배치로 출력할 수 있습니다).
  • max_length (int, 선택 사항) — 반환되는 목록의 최대 길이 및 선택적으로 패딩 길이(위 참조).
  • pad_to_multiple_of (int, 선택 사항) — 설정하면 시퀀스를 제공된 값의 배수로 패딩합니다.

    이 기능은 컴퓨트 캐패빌리티가 >= 7.0(Volta)인 NVIDIA 하드웨어에서 Tensor Cores 사용을 활성화하는 데 특히 유용합니다.

  • return_tensors (str, 선택 사항, 기본값 "pt") — 반환할 Tensor의 유형입니다. 허용되는 값은 “np” 또는 “pt”입니다.

수신된 입력을 동적으로 패딩하는 데이터 콜레이터입니다.

DataCollatorForTokenClassification

클래스 transformers.DataCollatorForTokenClassification

< >

( tokenizer: PreTrainedTokenizerBasepadding: bool | str | transformers.utils.generic.PaddingStrategy = Truemax_length: int | None = Nonepad_to_multiple_of: int | None = Nonelabel_pad_token_id: int = -100return_tensors: str = 'pt' )

매개변수

  • tokenizer (PreTrainedTokenizer 또는 PreTrainedTokenizerFast) — 데이터 인코딩에 사용되는 토크나이저입니다.
  • padding (bool, str 또는 PaddingStrategy, 선택 사항, 기본값은 True) — 반환되는 시퀀스에 패딩을 적용할 전략을 선택합니다(모델의 패딩 방향 및 패딩 인덱스에 따라). 다음 중 하나를 선택할 수 있습니다:
    • True 또는 'longest' (기본값): 배치 내 가장 긴 시퀀스 길이에 맞게 패딩을 수행합니다(단일 시퀀스만 제공된 경우 패딩을 하지 않음).
    • 'max_length': max_length 인수로 지정된 최대 길이로 패딩하거나, 해당 인수가 제공되지 않으면 모델이 허용하는 최대 입력 길이로 패딩합니다.
    • False 또는 'do_not_pad': 패딩을 하지 않습니다(즉, 서로 다른 길이의 시퀀스를 가진 배치로 출력할 수 있습니다).
  • max_length (int, 선택 사항) — 반환되는 목록의 최대 길이 및 선택적으로 패딩 길이(위 참조).
  • pad_to_multiple_of (int, 선택 사항) — 설정하면 시퀀스를 제공된 값의 배수로 패딩합니다.

    이 기능은 컴퓨트 캐패빌리티가 >= 7.0(Volta)인 NVIDIA 하드웨어에서 Tensor Cores 사용을 활성화하는 데 특히 유용합니다.

  • label_pad_token_id (int, 선택 사항, 기본값 -100) — 레이블 패딩에 사용할 id입니다. (-100은 PyTorch 손실 함수에서 자동으로 무시됩니다.)
  • return_tensors (str, 선택 사항, 기본값 "pt") — 반환할 Tensor의 유형입니다. 허용되는 값은 “np” 또는 “pt”입니다.

입력과 라벨을 동적으로 패딩하는 데이터 콜레이터입니다.

DataCollatorForSeq2Seq

클래스 transformers.DataCollatorForSeq2Seq

< >

( tokenizer: PreTrainedTokenizerBasemodel: typing.Any | None = Nonepadding: bool | str | transformers.utils.generic.PaddingStrategy = Truemax_length: int | None = Nonepad_to_multiple_of: int | None = Nonelabel_pad_token_id: int = -100return_tensors: str = 'pt' )

매개변수

  • tokenizer (PreTrainedTokenizer 또는 PreTrainedTokenizerFast) — 데이터 인코딩에 사용되는 토크나이저입니다.
  • model (PreTrainedModel, 선택 사항) — 학습 중인 모델입니다. 설정되어 있고 prepare_decoder_input_ids_from_labels, 이 있으면, 이를 사용하여 decoder_input_ids

    This is useful when using label_smoothing to avoid calculating loss twice.

  • padding (bool, str 또는 PaddingStrategy, 선택 사항, 기본값은 True) — 반환되는 시퀀스에 패딩을 적용할 전략을 선택합니다(모델의 패딩 방향 및 패딩 인덱스에 따라). 다음 중 하나를 선택할 수 있습니다:
    • True 또는 'longest' (기본값): 배치 내 가장 긴 시퀀스 길이에 맞게 패딩을 수행합니다(단일 시퀀스만 제공된 경우 패딩을 하지 않음).
    • 'max_length': max_length 인수로 지정된 최대 길이로 패딩하거나, 해당 인수가 제공되지 않으면 모델이 허용하는 최대 입력 길이로 패딩합니다.
    • False 또는 'do_not_pad': 패딩을 하지 않습니다(즉, 서로 다른 길이의 시퀀스를 가진 배치로 출력할 수 있습니다).
  • max_length (int, 선택 사항) — 반환되는 목록의 최대 길이 및 선택적으로 패딩 길이(위 참조).
  • pad_to_multiple_of (int, 선택 사항) — 설정하면 시퀀스를 제공된 값의 배수로 패딩합니다.

    이 기능은 컴퓨트 캐패빌리티가 >= 7.0(Volta)인 NVIDIA 하드웨어에서 Tensor Cores 사용을 활성화하는 데 특히 유용합니다.

  • label_pad_token_id (int, 선택 사항, 기본값 -100) — 레이블 패딩에 사용할 id입니다. (-100은 PyTorch 손실 함수에서 자동으로 무시됩니다.)
  • return_tensors (str, 선택 사항, 기본값 "pt") — 반환할 Tensor의 유형입니다. 허용되는 값은 “np” 또는 “pt”입니다.

입력과 라벨을 동적으로 패딩하는 데이터 콜레이터입니다.

DataCollatorForLanguageModeling

클래스 transformers.DataCollatorForLanguageModeling

< >

( tokenizer: PreTrainedTokenizerBasemlm: bool = Truewhole_word_mask: bool = Falsemlm_probability: float | None = 0.15mask_replace_prob: float = 0.8random_replace_prob: float = 0.1pad_to_multiple_of: int | None = Nonereturn_tensors: str = 'pt'seed: int | None = None )

매개변수

  • tokenizer (PreTrainedTokenizer 또는 PreTrainedTokenizerFast) — 데이터 인코딩에 사용되는 토크나이저입니다.
  • mlm (bool, 선택 사항, 기본값 True) — masked language modeling을 사용할지 여부입니다. False로 설정하면 padding 토큰은 무시(값을 -100으로 설정)하고 labels가 입력과 동일해집니다. 그렇지 않으면 labels는 mask되지 않은 토큰에 대해 -100, mask된 토큰에 대해 예측할 값을 가집니다.
  • whole_word_mask (bool, 선택 사항, 기본값 False) — 개별 토큰 대신 전체 단어를 마스킹할지 여부.
  • mlm_probability (float, 선택 사항, 기본값 0.15) — mlm이 True로 설정된 경우, 입력에서 토큰을 (무작위로) 마스킹할 확률입니다.
  • mask_replace_prob (float, 선택 사항, 기본값 0.8) — 마스크된 토큰이 토크나이저의 마스크 토큰(예: [MASK])으로 대체될 확률입니다. 기본값은 0.8이며, 이는 마스크된 토큰의 80%가 [MASK]로 대체됨을 의미합니다. mlm가 True로 설정된 경우에만 작동합니다.
  • random_replace_prob (float, 선택 사항, 기본값 0.1) — 마스크된 토큰이 토크나이저 어휘의 무작위 토큰으로 대체될 확률입니다. 기본값은 0.1로, 마스크된 토큰의 10%가 무작위 토큰으로 대체됩니다. 나머지 마스크된 토큰(1 - mask_replace_prob - random_replace_prob)은 변경되지 않습니다. mlm이 True로 설정된 경우에만 작동합니다.
  • pad_to_multiple_of (int, 선택 사항) — 설정된 경우, 제공된 값의 배수로 시퀀스를 패딩합니다.
  • return_tensors (str) — 반환할 Tensor의 유형입니다. 허용되는 값은 “np” 또는 “pt”입니다.
  • seed (int, 선택 사항) — 마스킹을 위한 난수 생성기에 사용할 시드입니다. 제공되지 않으면 전역 RNG가 사용됩니다.

언어 모델링에 사용되는 데이터 콜레이터입니다. 입력이 모두 동일한 길이가 아닌 경우, 배치의 최대 길이에 따라 동적으로 패딩됩니다.

최상의 성능을 위해 이 데이터 콜레이터는 PreTrainedTokenizer 또는 return_special_tokens_mask=True 인수를 가진 PreTrainedTokenizerFast가 반환하는 "special_tokens_mask" 키를 포함하는 사전 또는 BatchEncoding 항목을 가진 데이터셋과 함께 사용해야 합니다.

<Example Options and Expectations>

  1. 기본 동작:

    • mask_replace_prob=0.8, random_replace_prob=0.1.
    • 마스크된 토큰의 80%는 [MASK]로, 10%는 무작위 토큰으로 대체되고, 10%는 변경되지 않는 것을 예상합니다.

  2. [MASK]로 대체된 모든 마스킹 토큰:

    • mask_replace_prob=1.0, random_replace_prob=0.0.
    • 모든 마스킹된 토큰이 [MASK]로 대체되도록 기대합니다. 그대로 유지되거나 무작위 토큰으로 대체되는 토큰은 없습니다.

  3. [MASK] 대체 없이 랜덤 토큰만 사용:

    • mask_replace_prob=0.0, random_replace_prob=1.0.
    • 모든 마스킹된 토큰이 무작위 토큰으로 대체되도록 기대합니다. [MASK] 대체나 변경되지 않은 토큰은 없습니다.

  4. 균형 대체:

    • mask_replace_prob=0.5, random_replace_prob=0.4.
    • 마스크된 토큰의 50%는 [MASK]로, 40%는 무작위 토큰으로 대체되고, 10%는 변경되지 않는 것을 예상할 수 있습니다.

Note: mask_replace_prob와 random_replace_prob의 합은 1을 초과할 수 없습니다. 두 값의 합이 1보다 작으면, 나머지 비율은 변경되지 않은 masked token으로 구성됩니다.

numpy_mask_tokens

< >

( inputs: Anyspecial_tokens_mask: typing.Any | None = Noneoffset_mapping: typing.Any | None = None )

마스크 언어 모델링을 위해 마스크된 토큰의 입력/레이블을 준비합니다.

torch_mask_tokens

< >

( inputs: Anyspecial_tokens_mask: typing.Any | None = Noneoffset_mapping: typing.Any | None = None )

마스크 언어 모델링을 위해 마스크된 토큰의 입력/레이블을 준비합니다.

DataCollatorForPermutationLanguageModeling

class transformers.DataCollatorForPermutationLanguageModeling

< >

( tokenizer: PreTrainedTokenizerBaseplm_probability: float = 0.16666666666666666max_span_length: int = 5return_tensors: str = 'pt' )

치환 언어 모델링에 사용되는 데이터 콜레이터

  • collates는 배치의 텐서들을 collate하며, 해당 토크나이저의 pad_token을 준수합니다
  • XLNet에 특화된 절차로 순열 언어 모델링을 위한 배치 전처리를 수행합니다

numpy_mask_tokens

< >

( inputs: Any )

…

  1. cur_len = 0(지금까지 처리된 토큰 수)를 설정하여 시퀀스의 처음부터 시작합니다.
  2. [1, max_span_length] 구간의 span_length를 샘플링합니다(마스킹할 토큰 스팬의 길이)
  3. 마스킹할 span을 감싸기 위해 context_length = span_length / plm_probability 길이의 context를 예약합니다
  4. 구간 [cur_len, cur_len + context_length - span_length]에서 시작 지점 start_index를 샘플링하고 토큰 start_index:start_index + span_length를 마스킹합니다
  5. cur_len = cur_len + context_length을 설정합니다. cur_len < max_len인 경우(즉, 처리할 시퀀스에 남은 토큰이 있는 경우) Step 1부터 반복합니다.

torch_mask_tokens

< >

( inputs: Any )

…

  1. cur_len = 0(지금까지 처리된 토큰 수)를 설정하여 시퀀스의 처음부터 시작합니다.
  2. [1, max_span_length] 구간의 span_length를 샘플링합니다(마스킹할 토큰 스팬의 길이)
  3. 마스킹할 span을 감싸기 위해 context_length = span_length / plm_probability 길이의 context를 예약합니다
  4. 구간 [cur_len, cur_len + context_length - span_length]에서 시작 지점 start_index를 샘플링하고 토큰 start_index:start_index + span_length를 마스킹합니다
  5. cur_len = cur_len + context_length을 설정합니다. cur_len < max_len인 경우(즉, 처리할 시퀀스에 남은 토큰이 있는 경우) Step 1부터 반복합니다.

DataCollatorWithFlattening

클래스 transformers.DataCollatorWithFlattening

< >

( *argsreturn_position_ids = Trueseparator_id = -100return_flash_attn_kwargs = Falsereturn_seq_idx = Falseposition_ids_start = 0**kwargs )

매개변수

  • return_position_ids (bool, 선택 사항, 기본값 True) — 각 평탄화 시퀀스마다 position_ids_start에서 다시 시작하는 position_ids를 반환할지 여부.
  • separator_id (int, 선택 사항, 기본값 -100) — labels 내에서 시퀀스를 구분하는 데 사용되는 값입니다.
  • return_flash_attn_kwargs (bool, 선택 사항, 기본값 False) — FlashAttention에서 사용하는 시퀀스 경계 kwargs(cu_seq_lens_q, cu_seq_lens_k, max_length_q, max_length_k)를 반환할지 여부.
  • return_seq_idx (bool, 선택 사항, 기본값 False) — 각 토큰이 속한 시퀀스를 나타내는 seq_idx를 반환할지 여부입니다.
  • position_ids_start (int, 선택 사항, 기본값 0) — 각 시퀀스의 첫 번째 토큰에 부여할 위치 ID입니다.

패딩 없는 접근에 사용되는 데이터 콜레이터입니다. 다음을 수행합니다:

  • concatenates는 전체 미니 배치를 [1, total_tokens] 모양의 단일 긴 시퀀스로 연결합니다
  • separator_id를 사용하여 연결된 labels 내의 시퀀스를 구분하며, 기본값은 -100입니다
  • 패딩이 추가되지 않으며 기본적으로 input_ids, labels, position_ids를 반환합니다
  • FlashAttentionKwargs에 포함된 kwargs를 선택적으로 반환합니다
  • 각 토큰이 어떤 시퀀스에 속하는지를 나타내는 seq_idx를 선택적으로 반환합니다

DataCollatorWithFlattening를 사용하면 미니 배치 전체가 하나의 긴 시퀀스로 평탄화됩니다. 어텐션 계산이 이를 처리할 수 있는지 확인하세요!

모든 모델이 자체적으로 position ids를 계산할 때 위치를 0부터 매핑하는 것은 아닙니다. RoBERTa 계열 아키텍처(roberta, xlm_roberta, camembert, mpnet, 절대 위치 임베딩을 사용하는 esm 포함)는 padding_idx + 1, 즉 보통 2부터 시작합니다. 이러한 모델에 기본 0-based position_ids를 전달하면 위치 임베딩이 조용히 이동하여 출력이 저하되므로, 해당 모델의 경우 position_ids_start를 적절히 설정해야 합니다.

DataCollatorForMultipleChoice

클래스 transformers.DataCollatorForMultipleChoice

< >

( tokenizer: PreTrainedTokenizerBasepadding: bool | str | transformers.utils.generic.PaddingStrategy = Truemax_length: int | None = Nonepad_to_multiple_of: int | None = Nonereturn_tensors: str = 'pt' )

매개변수

  • tokenizer (PreTrainedTokenizer 또는 PreTrainedTokenizerFast) — 데이터 인코딩에 사용되는 토크나이저입니다.
  • padding (bool, str 또는 PaddingStrategy, 선택 사항, 기본값은 True) — 모델의 패딩 방향과 패딩 인덱스에 따라 반환된 시퀀스를 패딩할 전략을 다음 중 선택합니다:
    • True 또는 'longest': 배치 내 가장 긴 시퀀스 길이로 패딩합니다(단일 시퀀스만 제공된 경우 패딩하지 않음).
    • 'max_length': max_length 인수로 지정된 최대 길이로 패딩하거나, 해당 인수가 제공되지 않으면 모델이 허용하는 최대 입력 길이로 패딩합니다.
    • False 또는 'do_not_pad' (기본값): 패딩을 하지 않습니다(즉, 서로 다른 길이의 시퀀스로 구성된 배치로 출력할 수 있습니다).
  • max_length (int, 선택 사항) — 반환되는 목록의 최대 길이 및 선택적으로 패딩 길이(위 참조).
  • pad_to_multiple_of (int, 선택 사항) — 시퀀스를 제공된 값의 배수로 패딩합니다. 이는 Volta와 같은 compute capability >= 7.5를 지원하는 NVIDIA 하드웨어에서 Tensor Cores 사용을 활성화하는 데 특히 유용합니다.

    이 기능은 컴퓨트 캐패빌리티가 >= 7.5(Volta)인 NVIDIA 하드웨어에서 Tensor Cores 사용을 활성화하는 데 특히 유용합니다.

  • return_tensors (str, 선택 사항, 기본값 "pt") — 반환할 Tensor의 유형입니다. 허용되는 값은 “np” 또는 “pt”입니다.

여러 선택지 문제를 위한 중첩된 예시 배치에 동적으로 패딩을 적용하여 모든 예시의 모든 선택지가 동일한 길이를 갖도록 하는 데이터 콜레이터

Update on GitHub

←연속 배치 로깅→