Hugging Face's logo

Transformers documentation

Colaborador de dados

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

Colaborador de dados

Data collators são objetos que formam um lote usando uma lista de elementos do dataset como entrada. Esses elementos são do mesmo tipo que os elementos de train_dataset ou eval_dataset.

Para poder montar lotes, os coletores de dados podem aplicar algum processamento (como preenchimento). Alguns deles (como DataCollatorForLanguageModeling) também aplicam alguma ampliação aleatória de dados (como mascaramento aleatório) no lote formado.

Exemplos de uso podem ser encontrados nos notebooks de exemplo.

Colador de dados padrão

transformers.default_data_collator

< >

( features: listreturn_tensors = 'pt' )

Um collator de dados muito simples que apenas agrupa lotes de objetos semelhantes a dicionários e realiza um tratamento especial para chaves potenciais nomeadas:

  • label: trata de um único valor (int ou float) por objeto
  • label_ids: trata uma lista de valores por objeto

Não realiza nenhum pré-processamento adicional: os nomes das propriedades do objeto de entrada serão usados como as entradas correspondentes para o modelo. Veja glue e ner como exemplo de como isso é útil.

DefaultDataCollator

classe transformers.DefaultDataCollator

< >

( return_tensors: str = 'pt' )

Parâmetros

  • return_tensors (str, opcional, padrão "pt") — O tipo de Tensor a ser retornado. Os valores permitidos são “np” ou “pt”.

Um collator de dados muito simples que apenas agrupa lotes de objetos semelhantes a dicionários e realiza um tratamento especial para chaves potenciais nomeadas:

  • label: trata de um único valor (int ou float) por objeto
  • label_ids: trata uma lista de valores por objeto

Não realiza nenhum pré-processamento adicional: os nomes das propriedades do objeto de entrada serão usados como as entradas correspondentes para o modelo. Veja glue e ner como exemplo de como isso é útil.

Este é um objeto (como outros data collators), em vez de uma função pura como default_data_collator. Isso pode ser útil se você precisar definir um valor para return_tensors na inicialização.

DataCollatorWithPadding

classe transformers.DataCollatorWithPadding

< >

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

Parâmetros

  • tokenizer (PreTrainedTokenizer ou PreTrainedTokenizerFast) — O tokenizer usado para codificar os dados.
  • padding (bool, str ou PaddingStrategy, opcional, padrão é True) — Selecione uma estratégia para aplicar padding às sequências retornadas (de acordo com o lado de padding e o índice de padding do modelo) entre: 'True' ou 'longest' (padrão): aplica padding até a sequência mais longa do lote (ou nenhum padding se apenas uma sequência for fornecida). 'max_length': aplica padding até um comprimento máximo especificado com o argumento max_length ou até o comprimento de entrada máximo aceitável para o modelo, se esse argumento não for fornecido. False ou 'do_not_pad': sem padding (ou seja, pode gerar um lote com sequências de comprimentos diferentes).
    • True ou 'longest' (padrão): Preenche até a sequência mais longa do lote (ou não aplica preenchimento se apenas uma sequência for fornecida).
    • 'max_length': Preenche até o comprimento máximo especificado com o argumento max_length ou até o comprimento máximo aceitável de entrada para o modelo, caso esse argumento não seja fornecido.
    • False ou 'do_not_pad': sem padding (ou seja, pode gerar um lote com sequências de comprimentos diferentes).
  • max_length (int, opcional) — Comprimento máximo da lista retornada e, opcionalmente, o comprimento do padding (veja acima).
  • pad_to_multiple_of (int, opcional) — Se definido, a sequência será preenchida até um múltiplo do valor fornecido.

    Isso é especialmente útil para habilitar o uso de Tensor Cores em hardware NVIDIA com capacidade de computação >= 7.0 (Volta).

  • return_tensors (str, opcional, padrão "pt") — O tipo de Tensor a ser retornado. Os valores permitidos são “np” ou “pt”.

Data collator que irá aplicar padding dinamicamente às entradas recebidas.

DataCollatorForTokenClassification

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

Parâmetros

  • tokenizer (PreTrainedTokenizer ou PreTrainedTokenizerFast) — O tokenizer usado para codificar os dados.
  • padding (bool, str ou PaddingStrategy, opcional, padrão é True) — Selecione uma estratégia para aplicar padding às sequências retornadas (de acordo com o lado de padding e o índice de padding do modelo) entre: True ou 'longest' (padrão): aplica padding até a sequência mais longa do lote (ou nenhum padding se apenas uma sequência for fornecida). 'max_length': aplica padding até um comprimento máximo especificado com o argumento max_length ou até o comprimento de entrada máximo aceitável para o modelo, se esse argumento não for fornecido. False ou 'do_not_pad': sem padding (ou seja, pode gerar um lote com sequências de comprimentos diferentes).
    • True ou 'longest' (padrão): Preenche até a sequência mais longa do lote (ou não aplica preenchimento se apenas uma sequência for fornecida).
    • 'max_length': Preenche até o comprimento máximo especificado com o argumento max_length ou até o comprimento máximo aceitável de entrada para o modelo, caso esse argumento não seja fornecido.
    • False ou 'do_not_pad': sem padding (ou seja, pode gerar um lote com sequências de comprimentos diferentes).
  • max_length (int, opcional) — Comprimento máximo da lista retornada e, opcionalmente, o comprimento do padding (veja acima).
  • pad_to_multiple_of (int, opcional) — Se definido, a sequência será preenchida até um múltiplo do valor fornecido.

    Isso é especialmente útil para habilitar o uso de Tensor Cores em hardware NVIDIA com capacidade de computação >= 7.0 (Volta).

  • label_pad_token_id (int, opcional, padrão -100) — O id a ser usado ao aplicar padding nos rótulos (-100 será automaticamente ignorado pelas funções de perda do PyTorch).
  • return_tensors (str, opcional, padrão "pt") — O tipo de Tensor a ser retornado. Os valores permitidos são “np” ou “pt”.

Data collator que irá preencher dinamicamente os inputs recebidos, bem como os labels.

DataCollatorForSeq2Seq

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

Parâmetros

  • tokenizer (PreTrainedTokenizer ou PreTrainedTokenizerFast) — O tokenizer usado para codificar os dados.
  • model (PreTrainedModel, opcional) — O modelo que está sendo treinado. Se definido e tiver o método prepare_decoder_input_ids_from_labels, use-o para preparar os decoder_input_ids

    Isso é útil ao usar label_smoothing para evitar o cálculo da perda duas vezes.

  • padding (bool, str ou PaddingStrategy, opcional, padrão é True) — Selecione uma estratégia para aplicar padding às sequências retornadas (de acordo com o lado de padding e o índice de padding do modelo) entre:
    • True ou 'longest' (padrão): Preenche até a sequência mais longa do lote (ou não aplica preenchimento se apenas uma sequência for fornecida).
    • 'max_length': Preenche até o comprimento máximo especificado com o argumento max_length ou até o comprimento máximo aceitável de entrada para o modelo, caso esse argumento não seja fornecido.
    • False ou 'do_not_pad': sem padding (ou seja, pode gerar um lote com sequências de comprimentos diferentes).
  • max_length (int, opcional) — Comprimento máximo da lista retornada e, opcionalmente, o comprimento do padding (veja acima).
  • pad_to_multiple_of (int, opcional) — Se definido, a sequência será preenchida até um múltiplo do valor fornecido.

    Isso é especialmente útil para habilitar o uso de Tensor Cores em hardware NVIDIA com capacidade de computação >= 7.0 (Volta).

  • label_pad_token_id (int, opcional, padrão -100) — O id a ser usado ao aplicar padding nos rótulos (-100 será automaticamente ignorado pelas funções de perda do PyTorch).
  • return_tensors (str, opcional, padrão "pt") — O tipo de Tensor a ser retornado. Os valores permitidos são “np” ou “pt”.

Data collator que irá preencher dinamicamente os inputs recebidos, bem como os labels.

DataCollatorForLanguageModeling

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

Parâmetros

  • tokenizer (PreTrainedTokenizer ou PreTrainedTokenizerFast) — O tokenizer usado para codificar os dados.
  • mlm (bool, opcional, padrão True) — Indica se deve ou não usar modelagem de linguagem mascarada. Se definido como False, os rótulos são os mesmos que as entradas, com os tokens de preenchimento ignorados (definindo-os como -100). Caso contrário, os rótulos são -100 para tokens não mascarados e o valor a prever para o token mascarado.
  • whole_word_mask (bool, opcional, padrão False) — Se deve mascarar palavras inteiras em vez de tokens individuais.
  • mlm_probability (float, opcional, padrão 0.15) — A probabilidade com a qual mascarar (aleatoriamente) tokens na entrada, quando mlm está definido como True.
  • mask_replace_prob (float, opcional, padrão 0.8) — A probabilidade com que os tokens mascarados são substituídos pelo token de máscara do tokenizer (por exemplo, [MASK]). O padrão é 0.8, o que significa que 80% dos tokens mascarados serão substituídos por [MASK]. Funciona apenas quando mlm está definido como True.
  • random_replace_prob (float, opcional, padrão 0.1) — A probabilidade com que os tokens mascarados são substituídos por tokens aleatórios do vocabulário do tokenizer. O padrão é 0.1, o que significa que 10% dos tokens mascarados serão substituídos por tokens aleatórios. Os tokens mascarados restantes (1 - mask_replace_prob - random_replace_prob) permanecem inalterados. Funciona apenas quando mlm está definido como True.
  • pad_to_multiple_of (int, opcional) — Se definido, a sequência será preenchida até um múltiplo do valor fornecido.
  • return_tensors (str) — O tipo de Tensor a ser retornado. Os valores permitidos são “np” ou “pt”.
  • seed (int, opcional) — A semente a ser usada para o gerador de números aleatórios para mascaramento. Se não for fornecida, o RNG global será utilizado.

Data collator usado para modelagem de linguagem. As entradas são dinamicamente preenchidas até o comprimento máximo de um lote, caso não tenham todas o mesmo comprimento.

Para o melhor desempenho, este data collator deve ser usado com um conjunto de dados cujos itens são dicionários ou BatchEncoding, com a chave "special_tokens_mask", conforme retornado por um PreTrainedTokenizer ou um PreTrainedTokenizerFast com o argumento return_special_tokens_mask=True.

<Example Options and Expectations>

  1. Comportamento padrão:

    • mask_replace_prob=0.8, random_replace_prob=0.1.
    • Espera-se que 80% dos tokens mascarados sejam substituídos por [MASK], 10% por tokens aleatórios e 10% permaneçam inalterados.

  2. Todos os tokens mascarados substituídos por [MASK]:

    • mask_replace_prob=1.0, random_replace_prob=0.0.
    • Espera-se que todos os tokens mascarados sejam substituídos por [MASK]. Nenhum token permanece inalterado ou é substituído por tokens aleatórios.

  3. Na substituição de [MASK], apenas tokens aleatórios:

    • mask_replace_prob=0.0, random_replace_prob=1.0.
    • Espera-se que todos os tokens mascarados sejam substituídos por tokens aleatórios. Sem substituições por [MASK] ou tokens inalterados.

  4. Substituição equilibrada:

    • mask_replace_prob=0.5, random_replace_prob=0.4.
    • Espera-se que 50% dos tokens mascarados sejam substituídos por [MASK], 40% por tokens aleatórios e 10% permaneçam inalterados.

Nota: A soma de mask_replace_prob e random_replace_prob não deve exceder 1. Se a soma for menor que 1, a proporção restante consistirá em tokens mascarados mantidos inalterados.

numpy_mask_tokens

< >

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

Prepare os tokens mascarados de entrada/rótulos para modelagem de linguagem mascarada.

torch_mask_tokens

< >

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

Prepare os tokens mascarados de entrada/rótulos para modelagem de linguagem mascarada.

DataCollatorForPermutationLanguageModeling

classe transformers.DataCollatorForPermutationLanguageModeling

< >

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

Data collator usado para modelagem de linguagem por permutação.

  • agrupa lotes de tensores, respeitando o pad_token do seu tokenizador
  • pré-processa lotes para modelagem de linguagem por permutação com procedimentos específicos do XLNet

numpy_mask_tokens

< >

( inputs: Any )

Os tokens mascarados a serem previstos para uma sequência específica são determinados pelo seguinte algoritmo:

  1. Comece do início da sequência definindo cur_len = 0 (número de tokens processados até o momento).
  2. Amostrar um span_length do intervalo [1, max_span_length] (comprimento do trecho de tokens a ser mascarado)
  3. Reserve um contexto de comprimento context_length = span_length / plm_probability para envolver o trecho a ser mascarado
  4. Amostrar um ponto de partida start_index do intervalo [cur_len, cur_len + context_length - span_length] e mascarar os tokens start_index:start_index + span_length
  5. Defina cur_len = cur_len + context_length. Se cur_len < max_len (ou seja, ainda há tokens na sequência a serem processados), repita a partir da Etapa 1.

torch_mask_tokens

< >

( inputs: Any )

Os tokens mascarados a serem previstos para uma sequência específica são determinados pelo seguinte algoritmo:

  1. Comece do início da sequência definindo cur_len = 0 (número de tokens processados até o momento).
  2. Amostrar um span_length do intervalo [1, max_span_length] (comprimento do trecho de tokens a ser mascarado)
  3. Reserve um contexto de comprimento context_length = span_length / plm_probability para envolver o trecho a ser mascarado
  4. Amostrar um ponto de partida start_index do intervalo [cur_len, cur_len + context_length - span_length] e mascarar os tokens start_index:start_index + span_length
  5. Defina cur_len = cur_len + context_length. Se cur_len < max_len (ou seja, ainda há tokens na sequência a serem processados), repita a partir da Etapa 1.

DataCollatorWithFlattening

classe transformers.DataCollatorWithFlattening

< >

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

Parâmetros

  • return_position_ids (bool, opcional, padrão True) — Se deve retornar position_ids, que reiniciam em position_ids_start para cada sequência achatada.
  • separator_id (int, opcional, padrão -100) — O valor usado para separar sequências dentro das labels concatenadas.
  • return_flash_attn_kwargs (bool, opcional, padrão False) — Se deve retornar os kwargs de limites de sequência usados pelo FlashAttention (cu_seq_lens_q, cu_seq_lens_k, max_length_q e max_length_k).
  • return_seq_idx (bool, opcional, padrão False) — Indica se deve retornar seq_idx, que especifica a sequência à qual cada token pertence.
  • position_ids_start (int, opcional, padrão 0) — O id de posição atribuído ao primeiro token de cada sequência.

Data collator usado para a abordagem sem padding. Faz o seguinte:

  • concatena todo o mini lote em uma única sequência longa de forma [1, total_tokens]
  • usa separator_id para separar sequências dentro das labels concatenadas, o valor padrão é -100
  • nenhum padding será adicionado, retorna input_ids, labels e position_ids por padrão
  • retorna opcionalmente os kwargs contidos em FlashAttentionKwargs
  • opcionalmente retorna seq_idx indicando a qual sequência cada token pertence

O uso de DataCollatorWithFlattening aplainará o mini lote inteiro em uma única sequência longa. Certifique-se de que o cálculo de atenção seja capaz de lidar com isso!

Nem todo modelo numera as posições a partir de 0 ao calcular os position ids por conta própria. Arquiteturas semelhantes à RoBERTa (entre elas roberta, xlm_roberta, camembert, mpnet e esm com embeddings de posição absolutos) começam em padding_idx + 1, que geralmente é 2. Passar para esses modelos o position_ids padrão baseado em 0 desloca silenciosamente os embeddings de posição e degrada suas saídas, portanto, defina position_ids_start de forma adequada para esses modelos.

DataCollatorForMultipleChoice

classe transformers.DataCollatorForMultipleChoice

< >

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

Parâmetros

  • tokenizer (PreTrainedTokenizer ou PreTrainedTokenizerFast) — O tokenizer usado para codificar os dados.
  • padding (bool, str ou PaddingStrategy, opcional, padrão é True) — Selecione uma estratégia para aplicar padding às sequências retornadas de acordo com o lado de padding e o índice de padding do modelo, entre:
    • True ou 'longest': Preenche até a sequência mais longa do lote (ou não aplica preenchimento se apenas uma sequência for fornecida).
    • 'max_length': Preenche até o comprimento máximo especificado com o argumento max_length ou até o comprimento máximo aceitável de entrada para o modelo, caso esse argumento não seja fornecido.
    • False ou 'do_not_pad' (padrão): Sem padding (ou seja, pode gerar um lote com sequências de comprimentos diferentes).
  • max_length (int, opcional) — Comprimento máximo da lista retornada e, opcionalmente, o comprimento do padding (veja acima).
  • pad_to_multiple_of (int, opcional) — Preenche a sequência até um múltiplo do valor fornecido.

    Isso é especialmente útil para habilitar o uso de Tensor Cores em hardware NVIDIA com capacidade de computação >= 7.5 (Volta).

  • return_tensors (str, opcional, padrão "pt") — O tipo de Tensor a ser retornado. Os valores permitidos são “np” ou “pt”.

Data collator que faz o padding dinâmico de um lote de exemplos aninhados para múltipla escolha, de modo que todas as escolhas de todos os exemplos tenham o mesmo comprimento.

Update on GitHub

←Loteamento contínuo Registro→