Hugging Face's logo

Transformers documentation

Data collator

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

Data collator adalah objek yang akan membentuk batch dengan menggunakan daftar elemen dataset sebagai input. Elemen-elemen ini memiliki tipe yang sama dengan elemen dari train_dataset atau eval_dataset.

Untuk dapat membangun batch, data collator dapat menerapkan beberapa pemrosesan (seperti padding). Beberapa di antaranya (seperti DataCollatorForLanguageModeling) juga menerapkan beberapa augmentasi data acak (seperti random masking) pada batch yang terbentuk.

Contoh penggunaan dapat ditemukan di notebook contoh.

Collator data default

transformers.default_data_collator

< >

( features: listreturn_tensors = 'pt' )

Collator data yang sangat sederhana yang hanya menggabungkan batch objek seperti dict dan melakukan penanganan khusus untuk kunci potensial bernama:

  • label: menangani satu nilai (int atau float) per objek
  • label_ids: menangani daftar nilai per objek

Tidak melakukan pra-pemrosesan tambahan: nama properti dari objek input akan digunakan sebagai input yang sesuai untuk model. Lihat glue dan ner sebagai contoh bagaimana hal ini berguna.

DefaultDataCollator

kelas transformers.DefaultDataCollator

< >

( return_tensors: str = 'pt' )

Parameter

  • return_tensors (str, opsional, defaultnya "pt") — Jenis Tensor yang akan dikembalikan. Nilai yang diizinkan adalah “np” atau “pt”.

Collator data yang sangat sederhana yang hanya menggabungkan batch objek seperti dict dan melakukan penanganan khusus untuk kunci potensial bernama:

  • label: menangani satu nilai (int atau float) per objek
  • label_ids: menangani daftar nilai per objek

Tidak melakukan pra-pemrosesan tambahan: nama properti dari objek input akan digunakan sebagai input yang sesuai untuk model. Lihat glue dan ner sebagai contoh bagaimana hal ini berguna.

Ini adalah sebuah objek (seperti data collator lainnya) alih-alih fungsi murni seperti default_data_collator. Hal ini dapat membantu jika Anda perlu mengatur nilai return_tensors saat inisialisasi.

DataCollatorWithPadding

kelas transformers.DataCollatorWithPadding

< >

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

Parameter

  • tokenizer (PreTrainedTokenizer atau PreTrainedTokenizerFast) — Tokenizer yang digunakan untuk mengkodekan data.
  • padding (bool, str atau PaddingStrategy, opsional, defaultnya True) — Pilih strategi untuk melakukan padding pada urutan yang dikembalikan (sesuai sisi padding dan indeks padding model) di antara:
    • True atau 'longest' (default): Pad hingga urutan terpanjang dalam batch (atau tanpa padding jika hanya satu urutan yang diberikan).
    • 'max_length': Pad hingga panjang maksimum yang ditentukan dengan argumen max_length atau hingga panjang input maksimum yang dapat diterima oleh model jika argumen tersebut tidak diberikan.
    • False atau 'do_not_pad': Tanpa padding (yaitu, dapat menghasilkan batch dengan urutan yang panjangnya berbeda).
  • max_length (int, opsional) — Panjang maksimum dari daftar yang dikembalikan dan secara opsional panjang padding (lihat di atas).
  • pad_to_multiple_of (int, opsional) — Jika diset, akan melakukan padding pada urutan hingga menjadi kelipatan dari nilai yang diberikan.

    Hal ini sangat berguna untuk memungkinkan penggunaan Tensor Cores pada perangkat keras NVIDIA dengan compute capability >= 7.0 (Volta).

  • return_tensors (str, opsional, defaultnya "pt") — Jenis Tensor yang akan dikembalikan. Nilai yang diizinkan adalah “np” atau “pt”.

Data collator yang akan melakukan padding secara dinamis pada input yang diterima.

DataCollatorForTokenClassification

kelas 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' )

Parameter

  • tokenizer (PreTrainedTokenizer atau PreTrainedTokenizerFast) — Tokenizer yang digunakan untuk mengkodekan data.
  • padding (bool, str atau PaddingStrategy, opsional, defaultnya True) — Pilih strategi untuk melakukan padding pada urutan yang dikembalikan (sesuai sisi padding dan indeks padding model) di antara:
    • True atau 'longest' (default): Pad hingga urutan terpanjang dalam batch (atau tanpa padding jika hanya satu urutan yang diberikan).
    • 'max_length': Pad hingga panjang maksimum yang ditentukan dengan argumen max_length atau hingga panjang input maksimum yang dapat diterima oleh model jika argumen tersebut tidak diberikan.
    • False atau 'do_not_pad': Tanpa padding (yaitu, dapat menghasilkan batch dengan urutan yang panjangnya berbeda).
  • max_length (int, opsional) — Panjang maksimum dari daftar yang dikembalikan dan secara opsional panjang padding (lihat di atas).
  • pad_to_multiple_of (int, opsional) — Jika diset, akan melakukan padding pada urutan hingga menjadi kelipatan dari nilai yang diberikan.

    Hal ini sangat berguna untuk memungkinkan penggunaan Tensor Cores pada perangkat keras NVIDIA dengan compute capability >= 7.0 (Volta).

  • label_pad_token_id (int, opsional, default -100) — ID yang digunakan saat melakukan padding pada label (-100 akan diabaikan secara otomatis oleh fungsi loss PyTorch).
  • return_tensors (str, opsional, defaultnya "pt") — Jenis Tensor yang akan dikembalikan. Nilai yang diizinkan adalah “np” atau “pt”.

Data collator yang akan secara dinamis melakukan padding pada input yang diterima, serta label.

DataCollatorForSeq2Seq

kelas 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' )

Parameter

  • tokenizer (PreTrainedTokenizer atau PreTrainedTokenizerFast) — Tokenizer yang digunakan untuk mengkodekan data.
  • model (PreTrainedModel, opsional) — Model yang sedang dilatih. Jika disetel dan memiliki prepare_decoder_input_ids_from_labels, gunakan untuk menyiapkan decoder_input_ids

    Ini berguna saat menggunakan label_smoothing untuk menghindari perhitungan loss dua kali.

  • padding (bool, str atau PaddingStrategy, opsional, defaultnya True) — Pilih strategi untuk melakukan padding pada urutan yang dikembalikan (sesuai sisi padding dan indeks padding model) di antara:
    • True atau 'longest' (default): Pad hingga urutan terpanjang dalam batch (atau tanpa padding jika hanya satu urutan yang diberikan).
    • 'max_length': Pad hingga panjang maksimum yang ditentukan dengan argumen max_length atau hingga panjang input maksimum yang dapat diterima oleh model jika argumen tersebut tidak diberikan.
    • False atau 'do_not_pad': Tanpa padding (yaitu, dapat menghasilkan batch dengan urutan yang panjangnya berbeda).
  • max_length (int, opsional) — Panjang maksimum dari daftar yang dikembalikan dan secara opsional panjang padding (lihat di atas).
  • pad_to_multiple_of (int, opsional) — Jika diset, akan melakukan padding pada urutan hingga menjadi kelipatan dari nilai yang diberikan.

    Hal ini sangat berguna untuk memungkinkan penggunaan Tensor Cores pada perangkat keras NVIDIA dengan compute capability >= 7.0 (Volta).

  • label_pad_token_id (int, opsional, default -100) — ID yang digunakan saat melakukan padding pada label (-100 akan diabaikan secara otomatis oleh fungsi loss PyTorch).
  • return_tensors (str, opsional, defaultnya "pt") — Jenis Tensor yang akan dikembalikan. Nilai yang diizinkan adalah “np” atau “pt”.

Data collator yang akan secara dinamis melakukan padding pada input yang diterima, serta label.

DataCollatorForLanguageModeling

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

Parameter

  • tokenizer (PreTrainedTokenizer atau PreTrainedTokenizerFast) — Tokenizer yang digunakan untuk mengkodekan data.
  • mlm (bool, opsional, default True) — Apakah akan menggunakan masked language modeling. Jika diset ke False, label sama dengan input dengan token padding diabaikan (dengan menyetelnya ke -100). Sebaliknya, label adalah -100 untuk token yang tidak di-mask dan nilai yang diprediksi untuk token yang di-mask.
  • whole_word_mask (bool, opsional, default False) — Apakah akan memasker seluruh kata alih-alih token individual.
  • mlm_probability (float, opsional, default 0.15) — Probabilitas untuk (secara acak) mem-mask token dalam input, ketika mlm diatur ke True.
  • mask_replace_prob (float, opsional, default 0.8) — Probabilitas di mana token yang dimasker diganti dengan token mask dari tokenizer (misalnya, [MASK]). Default 0,8, yang berarti 80% dari token yang dimasker akan diganti dengan [MASK]. Hanya berfungsi ketika mlm diatur ke True.
  • random_replace_prob (float, opsional, default 0.1) — Probabilitas di mana token yang dimasker diganti dengan token acak dari kosakata tokenizer. Default 0.1, artinya 10% dari token yang dimasker akan diganti dengan token acak. Token yang dimasker sisanya (1 - mask_replace_prob - random_replace_prob) dibiarkan tanpa perubahan. Hanya berfungsi ketika mlm diatur ke True.
  • pad_to_multiple_of (int, opsional) — Jika diatur, akan melakukan padding pada urutan hingga menjadi kelipatan dari nilai yang diberikan.
  • return_tensors (str) — Jenis Tensor yang akan dikembalikan. Nilai yang diizinkan adalah “np” atau “pt”.
  • seed (int, opsional) — Seed yang akan digunakan untuk generator angka acak untuk masking. Jika tidak disediakan, RNG global akan digunakan.

Data collator yang digunakan untuk pemodelan bahasa. Input akan dipadati secara dinamis hingga panjang maksimum dari batch jika panjangnya tidak semuanya sama.

Untuk kinerja terbaik, data collator ini sebaiknya digunakan dengan dataset yang itemnya berupa dictionary atau BatchEncoding, dengan kunci "special_tokens_mask", sebagaimana dikembalikan oleh PreTrainedTokenizer atau PreTrainedTokenizerFast dengan argumen return_special_tokens_mask=True.

<Example Options and Expectations>

  1. Perilaku Default:

    • mask_replace_prob=0.8, random_replace_prob=0.1.
    • Diharapkan 80% token yang dimasker diganti dengan [MASK], 10% diganti dengan token acak, dan 10% dibiarkan tanpa perubahan.

  2. Semua token yang dimasker diganti dengan [MASK]:

    • mask_replace_prob=1.0, random_replace_prob=0.0.
    • Harap semua token yang dimasker diganti dengan [MASK]. Tidak ada token yang dibiarkan tanpa perubahan atau diganti dengan token acak.

  3. Tidak ada penggantian [MASK], hanya token acak:

    • mask_replace_prob=0.0, random_replace_prob=1.0.
    • Harap semua token yang dimasker diganti dengan token acak. Tidak ada penggantian [MASK] atau token yang tidak berubah.

  4. Penggantian yang seimbang:

    • mask_replace_prob=0.5, random_replace_prob=0.4.
    • Diharapkan 50% token yang dimasker diganti dengan [MASK], 40% diganti dengan token acak, dan 10% dibiarkan tanpa perubahan.

Catatan: Jumlah mask_replace_prob dan random_replace_prob tidak boleh melebihi 1. Jika jumlahnya kurang dari 1, proporsi sisanya akan terdiri dari token yang dimasker dan dibiarkan tanpa perubahan.

numpy_mask_tokens

< >

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

Siapkan input/label token yang dimasker untuk pemodelan bahasa yang dimasker.

torch_mask_tokens

< >

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

Siapkan input/label token yang dimasker untuk pemodelan bahasa yang dimasker.

DataCollatorForPermutationLanguageModeling

kelas transformers.DataCollatorForPermutationLanguageModeling

< >

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

Data collator yang digunakan untuk pemodelan bahasa permutasi.

  • menggabungkan batch tensor, dengan menghormati pad_token tokenizer-nya
  • memproses batch untuk pemodelan bahasa permutasi dengan prosedur yang spesifik untuk XLNet

numpy_mask_tokens

< >

( inputs: Any )

Token yang dimasker untuk diprediksi pada urutan tertentu ditentukan oleh algoritme berikut:

  1. Mulai dari awal urutan dengan mengatur cur_len = 0 (jumlah token yang telah diproses sejauh ini).
  2. Ambil sampel span_length dari interval [1, max_span_length] (panjang rentang token yang akan dimasker)
  3. Cadangkan konteks dengan panjang context_length = span_length / plm_probability untuk mengelilingi span yang akan di-mask
  4. Ambil titik awal start_index dari interval [cur_len, cur_len + context_length - span_length] dan mask token start_index:start_index + span_length
  5. Set cur_len = cur_len + context_length. Jika cur_len < max_len (yaitu masih ada token dalam urutan yang perlu diproses), ulangi dari Langkah 1.

torch_mask_tokens

< >

( inputs: Any )

Token yang dimasker untuk diprediksi pada urutan tertentu ditentukan oleh algoritme berikut:

  1. Mulai dari awal urutan dengan mengatur cur_len = 0 (jumlah token yang telah diproses sejauh ini).
  2. Ambil sampel span_length dari interval [1, max_span_length] (panjang rentang token yang akan dimasker)
  3. Cadangkan konteks dengan panjang context_length = span_length / plm_probability untuk mengelilingi span yang akan di-mask
  4. Ambil titik awal start_index dari interval [cur_len, cur_len + context_length - span_length] dan mask token start_index:start_index + span_length
  5. Set cur_len = cur_len + context_length. Jika cur_len < max_len (yaitu masih ada token dalam urutan yang perlu diproses), ulangi dari Langkah 1.

DataCollatorWithFlattening

kelas transformers.DataCollatorWithFlattening

< >

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

Parameter

  • return_position_ids (bool, opsional, default True) — Apakah akan mengembalikan position_ids, yang dimulai ulang dari position_ids_start untuk setiap urutan yang diratakan.
  • separator_id (int, opsional, default -100) — Nilai yang digunakan untuk memisahkan urutan di dalam labels yang digabungkan.
  • return_flash_attn_kwargs (bool, opsional, defaultnya False) — Apakah akan mengembalikan kwargs batas urutan yang digunakan oleh FlashAttention (cu_seq_lens_q, cu_seq_lens_k, max_length_q dan max_length_k).
  • return_seq_idx (bool, opsional, defaultnya False) — Apakah akan mengembalikan seq_idx, yang menunjukkan urutan (sequence) tempat setiap token berada.
  • position_ids_start (int, opsional, default 0) — ID posisi yang diberikan ke token pertama dari setiap urutan.

Data collator yang digunakan untuk pendekatan tanpa padding. Melakukan hal berikut:

  • menggabungkan seluruh mini batch menjadi satu urutan panjang dengan bentuk [1, total_tokens]
  • menggunakan separator_id untuk memisahkan urutan di dalam labels yang digabungkan, nilai default adalah -100
  • tidak ada padding yang akan ditambahkan, secara default mengembalikan input_ids, labels dan position_ids
  • secara opsional mengembalikan kwargs yang terkandung dalam FlashAttentionKwargs
  • secara opsional mengembalikan seq_idx yang menunjukkan urutan mana yang dimiliki oleh setiap token

Menggunakan DataCollatorWithFlattening akan meratakan seluruh mini batch menjadi satu urutan panjang. Pastikan perhitungan attention Anda mampu menanganinya!

Tidak semua model menghitung posisi dari 0 saat menghitung position ids-nya sendiri. Arsitektur mirip RoBERTa (di antaranya roberta, xlm_roberta, camembert, mpnet dan esm dengan absolute position embeddings) dimulai dari padding_idx + 1, yang biasanya bernilai 2. Jika model seperti ini diberikan position_ids default berbasis 0, position embeddings akan bergeser secara diam-diam dan menurunkan kualitas outputnya, sehingga aturlah position_ids_start secara sesuai untuk model-model tersebut.

DataCollatorForMultipleChoice

kelas transformers.DataCollatorForMultipleChoice

< >

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

Parameter

  • tokenizer (PreTrainedTokenizer atau PreTrainedTokenizerFast) — Tokenizer yang digunakan untuk mengkodekan data.
  • padding (bool, str atau PaddingStrategy, opsional, defaultnya True) — Pilih strategi untuk mengisi (padding) urutan yang dikembalikan sesuai dengan sisi padding dan indeks padding model, antara:
    • True atau 'longest': Pad hingga urutan terpanjang dalam batch (atau tanpa padding jika hanya satu urutan yang diberikan).
    • 'max_length': Pad hingga panjang maksimum yang ditentukan dengan argumen max_length atau hingga panjang input maksimum yang dapat diterima oleh model jika argumen tersebut tidak diberikan.
    • False atau 'do_not_pad' (default): Tidak ada padding (yaitu, dapat menghasilkan batch dengan urutan yang panjangnya berbeda).
  • max_length (int, opsional) — Panjang maksimum dari daftar yang dikembalikan dan secara opsional panjang padding (lihat di atas).
  • pad_to_multiple_of (int, opsional) — Pad sequence menjadi kelipatan dari nilai yang diberikan.

    Hal ini sangat berguna untuk memungkinkan penggunaan Tensor Cores pada perangkat keras NVIDIA dengan compute capability >= 7.5 (Volta).

  • return_tensors (str, opsional, defaultnya "pt") — Jenis Tensor yang akan dikembalikan. Nilai yang diizinkan adalah “np” atau “pt”.

Data collator yang secara dinamis melakukan padding pada batch contoh bersarang untuk pilihan ganda, sehingga semua pilihan dari semua contoh memiliki panjang yang sama.

Update on GitHub

←Batching berkelanjutan Pencatatan→