Hugging Face's logo

Transformers documentation

Trình tổng hợp dữ liệu

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

Trình tổng hợp dữ liệu

Data collators là các đối tượng sẽ tạo thành một batch bằng cách sử dụng một danh sách các phần tử của dataset làm đầu vào. Các phần tử này có cùng kiểu với các phần tử của train_dataset hoặc eval_dataset.

Để có thể tạo các batch, các data collator có thể áp dụng một số xử lý (như padding). Một số trong số đó (như DataCollatorForLanguageModeling) cũng áp dụng một số kỹ thuật tăng cường dữ liệu ngẫu nhiên (như random masking) trên batch đã được tạo.

Các ví dụ về cách sử dụng có thể được tìm thấy trong các notebook ví dụ.

Bộ sắp xếp dữ liệu mặc định

transformers.default_data_collator

< >

( features: listreturn_tensors = 'pt' )

Data collator rất đơn giản, chỉ đơn thuần gom các batch của các đối tượng dạng dict và thực hiện xử lý đặc biệt cho các khóa tiềm năng có tên:

  • label: xử lý một giá trị duy nhất (int hoặc float) cho mỗi đối tượng
  • label_ids: xử lý một danh sách các giá trị cho mỗi đối tượng

Không thực hiện bất kỳ tiền xử lý bổ sung nào: tên thuộc tính của đối tượng đầu vào sẽ được sử dụng làm các đầu vào tương ứng cho mô hình. Xem glue và ner làm ví dụ về cách nó hữu ích.

DefaultDataCollator

lớp transformers.DefaultDataCollator

< >

( return_tensors: str = 'pt' )

Tham số

  • return_tensors (str, tùy chọn, mặc định là "pt") — Loại Tensor cần trả về. Các giá trị cho phép là “np” hoặc “pt”.

Data collator rất đơn giản, chỉ đơn thuần gom các batch của các đối tượng dạng dict và thực hiện xử lý đặc biệt cho các khóa tiềm năng có tên:

  • label: xử lý một giá trị duy nhất (int hoặc float) cho mỗi đối tượng
  • label_ids: xử lý một danh sách các giá trị cho mỗi đối tượng

Không thực hiện bất kỳ tiền xử lý bổ sung nào: tên thuộc tính của đối tượng đầu vào sẽ được sử dụng làm các đầu vào tương ứng cho mô hình. Xem glue và ner làm ví dụ về cách nó hữu ích.

Đây là một đối tượng (giống như các data collator khác) thay vì một hàm thuần túy như default_data_collator. Điều này có thể hữu ích nếu bạn cần đặt giá trị return_tensors khi khởi tạo.

DataCollatorWithPadding

lớp transformers.DataCollatorWithPadding

< >

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

Tham số

  • tokenizer (PreTrainedTokenizer hoặc PreTrainedTokenizerFast) — Tokenizer được sử dụng để mã hóa dữ liệu.
  • padding (bool, str hoặc PaddingStrategy, tùy chọn, mặc định là True) — Chọn một chiến lược để đệm các chuỗi được trả về (theo phía đệm và chỉ số đệm của mô hình) trong số các lựa chọn:
    • True hoặc 'longest' (mặc định): Lấp đầy (padding) đến độ dài của chuỗi dài nhất trong batch (hoặc không lấp đầy nếu chỉ cung cấp một chuỗi 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': 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).
  • max_length (int, tùy chọn) — Độ dài tối đa của danh sách trả về và tùy chọn độ dài padding (xem bên trên).
  • pad_to_multiple_of (int, tuỳ chọn) — Nếu được đặt, chuỗi sẽ được đệm (pad) đế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.0 (Volta).

  • return_tensors (str, tùy chọn, mặc định là "pt") — Loại Tensor cần trả về. Các giá trị cho phép là “np” hoặc “pt”.

Data collator sẽ đệm động các đầu vào nhận được.

DataCollatorForTokenClassification

lớp 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' )

Tham số

  • tokenizer (PreTrainedTokenizer hoặc PreTrainedTokenizerFast) — Tokenizer được sử dụng để mã hóa dữ liệu.
  • padding (bool, str hoặc PaddingStrategy, tùy chọn, mặc định là True) — Chọn một chiến lược để đệm các chuỗi được trả về (theo phía đệm và chỉ số đệm của mô hình) trong số các lựa chọn:
    • True hoặc 'longest' (mặc định): Lấp đầy (padding) đến độ dài của chuỗi dài nhất trong batch (hoặc không lấp đầy nếu chỉ cung cấp một chuỗi 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': 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).
  • max_length (int, tùy chọn) — Độ dài tối đa của danh sách trả về và tùy chọn độ dài padding (xem bên trên).
  • pad_to_multiple_of (int, tuỳ chọn) — Nếu được đặt, chuỗi sẽ được đệm (pad) đế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.0 (Volta).

  • label_pad_token_id (int, tùy chọn, mặc định là -100) — Id được sử dụng khi đệm (padding) các nhãn (-100 sẽ được các hàm loss của PyTorch tự động bỏ qua).
  • return_tensors (str, tùy chọn, mặc định là "pt") — Loại Tensor cần trả về. Các giá trị cho phép là “np” hoặc “pt”.

Data collator sẽ đệm động các đầu vào nhận được, cũng như các nhãn.

DataCollatorForSeq2Seq

lớp 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' )

Tham số

  • tokenizer (PreTrainedTokenizer hoặc PreTrainedTokenizerFast) — Tokenizer được sử dụng để mã hóa dữ liệu.
  • model (PreTrainedModel, tùy chọn) — Mô hình đang được huấn luyện. Nếu được đặt và có prepare_decoder_input_ids_from_labels, hãy sử dụng nó để chuẩn bị decoder_input_ids

    Điều này hữu ích khi sử dụng label_smoothing để tránh tính toán loss hai lần.

  • padding (bool, str hoặc PaddingStrategy, tùy chọn, mặc định là True) — Chọn một chiến lược để đệm các chuỗi được trả về (theo phía đệm và chỉ số đệm của mô hình) trong số các lựa chọn:
    • True hoặc 'longest' (mặc định): Lấp đầy (padding) đến độ dài của chuỗi dài nhất trong batch (hoặc không lấp đầy nếu chỉ cung cấp một chuỗi 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': 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).
  • max_length (int, tùy chọn) — Độ dài tối đa của danh sách trả về và tùy chọn độ dài padding (xem bên trên).
  • pad_to_multiple_of (int, tuỳ chọn) — Nếu được đặt, chuỗi sẽ được đệm (pad) đế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.0 (Volta).

  • label_pad_token_id (int, tùy chọn, mặc định là -100) — Id được sử dụng khi đệm (padding) các nhãn (-100 sẽ được các hàm loss của PyTorch tự động bỏ qua).
  • return_tensors (str, tùy chọn, mặc định là "pt") — Loại Tensor cần trả về. Các giá trị cho phép là “np” hoặc “pt”.

Data collator sẽ đệm động các đầu vào nhận được, cũng như các nhãn.

DataCollatorForLanguageModeling

lớp 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 )

Tham số

  • tokenizer (PreTrainedTokenizer hoặc PreTrainedTokenizerFast) — Tokenizer được sử dụng để mã hóa dữ liệu.
  • mlm (bool, tùy chọn, mặc định là True) — Có sử dụng mô hình hóa ngôn ngữ có che hay không. Nếu đặt thành False, nhãn sẽ giống với đầu vào với các token đệm bị bỏ qua (bằng cách đặt chúng thành -100). Ngược lại, nhãn sẽ là -100 cho các token không bị che và là giá trị cần dự đoán cho token bị che.
  • whole_word_mask (bool, tùy chọn, mặc định là False) — Có nên che toàn bộ từ thay vì các token riêng lẻ hay không.
  • mlm_probability (float, tùy chọn, mặc định là 0.15) — Xác suất để (ngẫu nhiên) che các token trong đầu vào, khi mlm được đặt thành True.
  • mask_replace_prob (float, tùy chọn, mặc định là 0.8) — Xác suất để các token bị che được thay thế bằng token mask của tokenizer (ví dụ: [MASK]). Mặc định là 0.8, có nghĩa là 80% các token bị che sẽ được thay thế bằng [MASK]. Chỉ hoạt động khi mlm được đặt thành True.
  • random_replace_prob (float, tùy chọn, mặc định là 0.1) — Xác suất để các token bị che được thay thế bằng các token ngẫu nhiên từ từ điển của tokenizer. Mặc định là 0.1, có nghĩa là 10% số token bị che sẽ được thay thế bằng các token ngẫu nhiên. Các token bị che còn lại (1 - mask_replace_prob - random_replace_prob) sẽ được giữ nguyên. Chỉ hoạt động khi mlm được đặt thành True.
  • pad_to_multiple_of (int, tùy chọn) — Nếu được đặt, sẽ đệm chuỗi đến một bội số của giá trị được cung cấp.
  • return_tensors (str) — Loại Tensor cần trả về. Các giá trị cho phép là “np” hoặc “pt”.
  • seed (int, tùy chọn) — Hạt giống (seed) được sử dụng cho bộ tạo số ngẫu nhiên để che mặt nạ (masking). Nếu không được cung cấp, bộ tạo số ngẫu nhiên toàn cục (global RNG) sẽ được sử dụng.

Data collator được sử dụng cho mô hình hóa ngôn ngữ. Đầu vào sẽ được đệm động đến độ dài tối đa của một batch nếu chúng không có cùng độ dài.

Để đạt hiệu suất tốt nhất, data collator này nên được sử dụng với một dataset có các phần tử là dictionary hoặc BatchEncoding, có khóa "special_tokens_mask", như được trả về bởi một PreTrainedTokenizer hoặc một PreTrainedTokenizerFast với đối số return_special_tokens_mask=True.

<Example Options and Expectations>

  1. Hành vi mặc định:

    • mask_replace_prob=0.8, random_replace_prob=0.1.
    • Hãy kỳ vọng 80% các token bị che sẽ được thay thế bằng [MASK], 10% được thay thế bằng các token ngẫu nhiên, và 10% được giữ nguyên.

  2. Tất cả các token bị che được thay thế bằng [MASK]:

    • mask_replace_prob=1.0, random_replace_prob=0.0.
    • Mọi token bị mask đều được thay thế bằng [MASK]. Không có token nào được giữ nguyên hoặc thay thế bằng token ngẫu nhiên.

  3. Không có thay thế [MASK], chỉ có các token ngẫu nhiên:

    • mask_replace_prob=0.0, random_replace_prob=1.0.
    • Mọi token bị mask đều được thay thế bằng các token ngẫu nhiên. Không có thay thế bằng [MASK] hay token không thay đổi.

  4. Thay thế cân bằng:

    • mask_replace_prob=0.5, random_replace_prob=0.4.
    • Hãy kỳ vọng 50% các token bị che sẽ được thay thế bằng [MASK], 40% được thay thế bằng các token ngẫu nhiên, và 10% được giữ nguyên.

Note: Tổng của mask_replace_prob và random_replace_prob không được vượt quá 1. Nếu tổng của chúng nhỏ hơn 1, phần tỷ lệ còn lại sẽ bao gồm các token bị mask được giữ nguyên.

numpy_mask_tokens

< >

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

Chuẩn bị đầu vào/nhãn cho các token bị che trong mô hình hóa ngôn ngữ có che.

torch_mask_tokens

< >

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

Chuẩn bị đầu vào/nhãn cho các token bị che trong mô hình hóa ngôn ngữ có che.

DataCollatorForPermutationLanguageModeling

lớp transformers.DataCollatorForPermutationLanguageModeling

< >

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

Data collator được sử dụng cho mô hình hóa ngôn ngữ hoán vị.

  • gộp các lô tensor, tuân theo pad_token của tokenizer
  • tiền xử lý các lô dữ liệu cho mô hình hóa ngôn ngữ hoán vị với các quy trình đặc thù của XLNet

numpy_mask_tokens

< >

( inputs: Any )

Các token bị che cần dự đoán cho một chuỗi cụ thể được xác định bởi thuật toán sau:

  1. Bắt đầu từ đầu chuỗi bằng cách đặt cur_len = 0 (số lượng token đã xử lý cho đến nay).
  2. Lấy mẫu một span_length từ khoảng [1, max_span_length] (độ dài của chuỗi token sẽ bị che)
  3. Dự trữ một ngữ cảnh có độ dài context_length = span_length / plm_probability để bao quanh phần span cần bị che
  4. Mẫu một điểm bắt đầu start_index từ khoảng [cur_len, cur_len + context_length - span_length] và che các token start_index:start_index + span_length
  5. Đặt cur_len = cur_len + context_length. Nếu cur_len < max_len (tức là vẫn còn token trong chuỗi cần xử lý), lặp lại từ Bước 1.

torch_mask_tokens

< >

( inputs: Any )

Các token bị che cần dự đoán cho một chuỗi cụ thể được xác định bởi thuật toán sau:

  1. Bắt đầu từ đầu chuỗi bằng cách đặt cur_len = 0 (số lượng token đã xử lý cho đến nay).
  2. Lấy mẫu một span_length từ khoảng [1, max_span_length] (độ dài của chuỗi token sẽ bị che)
  3. Dự trữ một ngữ cảnh có độ dài context_length = span_length / plm_probability để bao quanh phần span cần bị che
  4. Mẫu một điểm bắt đầu start_index từ khoảng [cur_len, cur_len + context_length - span_length] và che các token start_index:start_index + span_length
  5. Đặt cur_len = cur_len + context_length. Nếu cur_len < max_len (tức là vẫn còn token trong chuỗi cần xử lý), lặp lại từ Bước 1.

DataCollatorWithFlattening

lớp transformers.DataCollatorWithFlattening

< >

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

Tham số

  • return_position_ids (bool, tùy chọn, mặc định là True) — Có nên trả về position_ids, vốn được khởi động lại từ position_ids_start cho mỗi chuỗi đã được làm phẳng hay không.
  • separator_id (int, tùy chọn, mặc định là -100) — Giá trị được dùng để phân tách các chuỗi trong labels đã được nối lại.
  • return_flash_attn_kwargs (bool, tùy chọn, mặc định là False) — Có nên trả về các kwargs ranh giới chuỗi được sử dụng bởi FlashAttention (cu_seq_lens_q, cu_seq_lens_k, max_length_q và max_length_k) hay không.
  • return_seq_idx (bool, tùy chọn, mặc định là False) — Có nên trả về seq_idx, chỉ ra chuỗi mà mỗi token thuộc về hay không.
  • position_ids_start (int, tùy chọn, mặc định là 0) — ID vị trí được gán cho token đầu tiên của mỗi chuỗi.

Data collator được sử dụng cho phương pháp không đệm (padding free). Thực hiện các bước sau:

  • nối toàn bộ mini batch thành một chuỗi dài duy nhất có hình dạng [1, total_tokens]
  • sử dụng separator_id để phân tách các chuỗi trong labels đã nối, giá trị mặc định là -100
  • không có padding nào được thêm vào, mặc định trả về input_ids, labels và position_ids
  • tùy chọn trả về các kwargs chứa trong FlashAttentionKwargs
  • tùy chọn trả về seq_idx chỉ ra trình tự mà mỗi token thuộc về

Việc sử dụng DataCollatorWithFlattening sẽ làm phẳng toàn bộ mini batch thành một chuỗi dài duy nhất. Hãy đảm bảo rằng phép tính attention của bạn có thể xử lý được điều này!

Không phải mọi model đều đánh số vị trí bắt đầu từ 0 khi tự tính toán position ids. Các kiến trúc kiểu RoBERTa (trong đó có roberta, xlm_roberta, camembert, mpnet và esm với absolute position embeddings) bắt đầu từ padding_idx + 1, thường là 2. Việc truyền cho các model này position_ids mặc định dựa trên 0 sẽ âm thầm làm lệch position embeddings và làm giảm chất lượng đầu ra, do đó hãy đặt position_ids_start tương ứng cho những model đó.

DataCollatorForMultipleChoice

lớp transformers.DataCollatorForMultipleChoice

< >

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

Tham số

  • tokenizer (PreTrainedTokenizer hoặc PreTrainedTokenizerFast) — Tokenizer được sử dụng để mã hóa dữ liệu.
  • padding (bool, str hoặc PaddingStrategy, tùy chọn, mặc định là True) — Chọn một chiến lược để đệm các chuỗi trả về theo phía đệm và chỉ số đệm của mô hình, trong số các lựa chọn:
    • True hoặc 'longest': Lấp đầy (pad) đến độ dài của chuỗi dài nhất trong batch (hoặc không lấp đầy nếu chỉ cung cấp một chuỗi 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).
  • max_length (int, tùy chọn) — Độ dài tối đa của danh sách trả về và tùy chọn độ dài padding (xem bên trên).
  • pad_to_multiple_of (int, tuỳ chọn) — Đệm (pad) 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, tùy chọn, mặc định là "pt") — Loại Tensor cần trả về. Các giá trị cho phép là “np” hoặc “pt”.

Data collator động để đệm một batch các ví dụ lồng nhau cho bài toán lựa chọn nhiều phương án, sao cho tất cả các phương án của tất cả các ví dụ có cùng độ dài.

Update on GitHub

←Lô liên tục Ghi nhật ký→