#
Treinamento a partir de um script

Junto com os 🤗 Transformers notebooks, também há scripts de exemplo demonstrando como treinar um modelo para uma tarefa com PyTorch, TensorFlow ou JAX/Flax.

Você também encontrará scripts que usamos em nossos projetos de pesquisa e exemplos legados que são principalmente contribuições da comunidade. Esses scripts não são mantidos ativamente e exigem uma versão específica de 🤗 Transformers que provavelmente será incompatível com a versão mais recente da biblioteca.

Não se espera que os scripts de exemplo funcionem imediatamente em todos os problemas, você pode precisar adaptar o script ao problema que está tentando resolver. Para ajudá-lo com isso, a maioria dos scripts expõe totalmente como os dados são pré-processados, permitindo que você os edite conforme necessário para seu caso de uso.

Para qualquer recurso que você gostaria de implementar em um script de exemplo, discuta-o no fórum ou em uma issue antes de enviar um Pull Request. Embora recebamos correções de bugs, é improvável que mesclaremos um Pull Request que adicione mais funcionalidades ao custo de legibilidade.

Este guia mostrará como executar um exemplo de script de treinamento de sumarização em PyTorch e TensorFlow. Espera-se que todos os exemplos funcionem com ambas as estruturas, a menos que especificado de outra forma.

##
Configuração

Para executar com êxito a versão mais recente dos scripts de exemplo, você precisa instalar o 🤗 Transformers da fonte em um novo ambiente virtual:

    git clone https://github.com/huggingface/transformers
    cd transformers
    pip install .

Para versões mais antigas dos scripts de exemplo, clique no botão abaixo:

Exemplos para versões antigas dos 🤗 Transformers

- v4.5.1
- v4.4.2
- v4.3.3
- v4.2.2
- v4.1.1
- v4.0.1
- v3.5.1
- v3.4.0
- v3.3.1
- v3.2.0
- v3.1.0
- v3.0.2
- v2.11.0
- v2.10.0
- v2.9.1
- v2.8.0
- v2.7.0
- v2.6.0
- v2.5.1
- v2.4.0
- v2.3.0
- v2.2.0
- v2.1.1
- v2.0.0
- v1.2.0
- v1.1.0
- v1.0.0

Em seguida, mude seu clone atual dos 🤗 Transformers para uma versão específica, como v3.5.1, por exemplo:

    git checkout tags/v3.5.1

Depois de configurar a versão correta da biblioteca, navegue até a pasta de exemplo de sua escolha e instale os requisitos específicos do exemplo:

    pip install -r requirements.txt

##
Executando um script

Pytorch
Hide Pytorch content

O script de exemplo baixa e pré-processa um conjunto de dados da biblioteca 🤗 Datasets. Em seguida, o script ajusta um conjunto de dados com o Trainer em uma arquitetura que oferece suporte à sumarização. O exemplo a seguir mostra como ajustar T5-small no conjunto de dados CNN/DailyMail. O modelo T5 requer um argumento `source_prefix` adicional devido à forma como foi treinado. Este prompt informa ao T5 que esta é uma tarefa de sumarização.

    python examples/pytorch/summarization/run_summarization.py \
        --model_name_or_path t5-small \
        --do_train \
        --do_eval \
        --dataset_name cnn_dailymail \
        --dataset_config "3.0.0" \
        --source_prefix "summarize: " \
        --output_dir /tmp/tst-summarization \
        --per_device_train_batch_size=4 \
        --per_device_eval_batch_size=4 \
        --overwrite_output_dir \
        --predict_with_generate

TensorFlow
Hide TensorFlow content

Este outro script de exemplo baixa e pré-processa um conjunto de dados da biblioteca 🤗 Datasets. Em seguida, o script ajusta um conjunto de dados usando Keras em uma arquitetura que oferece suporte à sumarização. O exemplo a seguir mostra como ajustar T5-small no conjunto de dados CNN/DailyMail. O modelo T5 requer um argumento `source_prefix` adicional devido à forma como foi treinado. Este prompt informa ao T5 que esta é uma tarefa de sumarização.

    python examples/tensorflow/summarization/run_summarization.py  \
        --model_name_or_path t5-small \
        --dataset_name cnn_dailymail \
        --dataset_config "3.0.0" \
        --output_dir /tmp/tst-summarization  \
        --per_device_train_batch_size 8 \
        --per_device_eval_batch_size 16 \
        --num_train_epochs 3 \
        --do_train \
        --do_eval

##
Treinamento distribuído e precisão mista

O Trainer oferece suporte a treinamento distribuído e precisão mista, o que significa que você também pode usá-lo em um script. Para habilitar esses dois recursos:

- Adicione o argumento `fp16` para habilitar a precisão mista.
- Defina o número de GPUs a serem usadas com o argumento `nproc_per_node`.

    torchrun \
        --nproc_per_node 8 pytorch/summarization/run_summarization.py \
        --fp16 \
        --model_name_or_path t5-small \
        --do_train \
        --do_eval \
        --dataset_name cnn_dailymail \
        --dataset_config "3.0.0" \
        --source_prefix "summarize: " \
        --output_dir /tmp/tst-summarization \
        --per_device_train_batch_size=4 \
        --per_device_eval_batch_size=4 \
        --overwrite_output_dir \
        --predict_with_generate

Os scripts do TensorFlow utilizam um `MirroredStrategy` para treinamento distribuído, e você não precisa adicionar argumentos adicionais ao script de treinamento. O script do TensorFlow usará várias GPUs por padrão, se estiverem disponíveis.

##
Executando um script em uma TPU

Pytorch
Hide Pytorch content

As Unidades de Processamento de Tensor (TPUs) são projetadas especificamente para acelerar o desempenho. O PyTorch oferece suporte a TPUs com o compilador de aprendizado profundo XLA (consulte aqui para mais detalhes). Para usar uma TPU, inicie o script `xla_spawn.py` e use o argumento `num_cores` para definir o número de núcleos de TPU que você deseja usar.

    python xla_spawn.py --num_cores 8 \
        summarization/run_summarization.py \
        --model_name_or_path t5-small \
        --do_train \
        --do_eval \
        --dataset_name cnn_dailymail \
        --dataset_config "3.0.0" \
        --source_prefix "summarize: " \
        --output_dir /tmp/tst-summarization \
        --per_device_train_batch_size=4 \
        --per_device_eval_batch_size=4 \
        --overwrite_output_dir \
        --predict_with_generate

TensorFlow
Hide TensorFlow content

As Unidades de Processamento de Tensor (TPUs) são projetadas especificamente para acelerar o desempenho. Os scripts do TensorFlow utilizam uma `TPUStrategy` para treinamento em TPUs. Para usar uma TPU, passe o nome do recurso TPU para o argumento `tpu`.

    python run_summarization.py  \
        --tpu name_of_tpu_resource \
        --model_name_or_path t5-small \
        --dataset_name cnn_dailymail \
        --dataset_config "3.0.0" \
        --output_dir /tmp/tst-summarization  \
        --per_device_train_batch_size 8 \
        --per_device_eval_batch_size 16 \
        --num_train_epochs 3 \
        --do_train \
        --do_eval

##
Execute um script com 🤗 Accelerate

🤗 Accelerate é uma biblioteca somente do PyTorch que oferece um método unificado para treinar um modelo em vários tipos de configurações (CPU, multiplas GPUs, TPUs), mantendo visibilidade no loop de treinamento do PyTorch. Certifique-se de ter o 🤗 Accelerate instalado se ainda não o tiver:

> Nota: Como o Accelerate está se desenvolvendo rapidamente, a versão git do Accelerate deve ser instalada para executar os scripts

    pip install git+https://github.com/huggingface/accelerate

Em vez do script `run_summarization.py`, você precisa usar o script `run_summarization_no_trainer.py`. Os scripts suportados pelo 🤗 Accelerate terão um arquivo `task_no_trainer.py` na pasta. Comece executando o seguinte comando para criar e salvar um arquivo de configuração:

    accelerate config

Teste sua configuração para garantir que ela esteja corretamente configurada :

    accelerate test

Agora você está pronto para iniciar o treinamento:

    accelerate launch run_summarization_no_trainer.py \
        --model_name_or_path t5-small \
        --dataset_name cnn_dailymail \
        --dataset_config "3.0.0" \
        --source_prefix "summarize: " \
        --output_dir ~/tmp/tst-summarization

##
Usando um conjunto de dados personalizado

O script de resumo oferece suporte a conjuntos de dados personalizados, desde que sejam um arquivo CSV ou JSON. Ao usar seu próprio conjunto de dados, você precisa especificar vários argumentos adicionais:

- `train_file` e `validation_file` especificam o caminho para seus arquivos de treinamento e validação respectivamente.
- `text_column` é o texto de entrada para sumarização.
- `summary_column` é o texto de destino para saída.

Um script para sumarização usando um conjunto de dados customizado ficaria assim:

    python examples/pytorch/summarization/run_summarization.py \
        --model_name_or_path t5-small \
        --do_train \
        --do_eval \
        --train_file path_to_csv_or_jsonlines_file \
        --validation_file path_to_csv_or_jsonlines_file \
        --text_column text_column_name \
        --summary_column summary_column_name \
        --source_prefix "summarize: " \
        --output_dir /tmp/tst-summarization \
        --overwrite_output_dir \
        --per_device_train_batch_size=4 \
        --per_device_eval_batch_size=4 \
        --predict_with_generate

##
Testando um script

Geralmente, é uma boa ideia executar seu script em um número menor de exemplos de conjuntos de dados para garantir que tudo funcione conforme o esperado antes de se comprometer com um conjunto de dados inteiro, que pode levar horas para ser concluído. Use os seguintes argumentos para truncar o conjunto de dados para um número máximo de amostras:

- `max_train_samples`
- `max_eval_samples`
- `max_predict_samples`

    python examples/pytorch/summarization/run_summarization.py \
        --model_name_or_path t5-small \
        --max_train_samples 50 \
        --max_eval_samples 50 \
        --max_predict_samples 50 \
        --do_train \
        --do_eval \
        --dataset_name cnn_dailymail \
        --dataset_config "3.0.0" \
        --source_prefix "summarize: " \
        --output_dir /tmp/tst-summarization \
        --per_device_train_batch_size=4 \
        --per_device_eval_batch_size=4 \
        --overwrite_output_dir \
        --predict_with_generate

Nem todos os scripts de exemplo suportam o argumento `max_predict_samples`. Se você não tiver certeza se seu script suporta este argumento, adicione o argumento `-h` para verificar:

    examples/pytorch/summarization/run_summarization.py -h

##
Retomar o treinamento a partir de um checkpoint

Outra opção útil para habilitar é retomar o treinamento de um checkpoint anterior. Isso garantirá que você possa continuar de onde parou sem recomeçar se o seu treinamento for interrompido. Existem dois métodos para retomar o treinamento a partir de um checkpoint.

O primeiro método usa o argumento `output_dir previous_output_dir` para retomar o treinamento do último checkpoint armazenado em `output_dir`. Neste caso, você deve remover `overwrite_output_dir`:

    python examples/pytorch/summarization/run_summarization.py
        --model_name_or_path t5-small \
        --do_train \
        --do_eval \
        --dataset_name cnn_dailymail \
        --dataset_config "3.0.0" \
        --source_prefix "summarize: " \
        --output_dir /tmp/tst-summarization \
        --per_device_train_batch_size=4 \
        --per_device_eval_batch_size=4 \
        --output_dir previous_output_dir \
        --predict_with_generate

O segundo método usa o argumento `resume_from_checkpoint path_to_specific_checkpoint` para retomar o treinamento de uma pasta de checkpoint específica.

    python examples/pytorch/summarization/run_summarization.py
        --model_name_or_path t5-small \
        --do_train \
        --do_eval \
        --dataset_name cnn_dailymail \
        --dataset_config "3.0.0" \
        --source_prefix "summarize: " \
        --output_dir /tmp/tst-summarization \
        --per_device_train_batch_size=4 \
        --per_device_eval_batch_size=4 \
        --overwrite_output_dir \
        --resume_from_checkpoint path_to_specific_checkpoint \
        --predict_with_generate

##
Compartilhando seu modelo

Todos os scripts podem enviar seu modelo final para o Model Hub. Certifique-se de estar conectado ao Hugging Face antes de começar:

    huggingface-cli login

Em seguida, adicione o argumento `push_to_hub` ao script. Este argumento criará um repositório com seu nome de usuário do Hugging Face e o nome da pasta especificado em `output_dir`.

Para dar um nome específico ao seu repositório, use o argumento `push_to_hub_model_id` para adicioná-lo. O repositório será listado automaticamente em seu namespace.

O exemplo a seguir mostra como fazer upload de um modelo com um nome de repositório específico:

    python examples/pytorch/summarization/run_summarization.py
        --model_name_or_path t5-small \
        --do_train \
        --do_eval \
        --dataset_name cnn_dailymail \
        --dataset_config "3.0.0" \
        --source_prefix "summarize: " \
        --push_to_hub \
        --push_to_hub_model_id finetuned-t5-cnn_dailymail \
        --output_dir /tmp/tst-summarization \
        --per_device_train_batch_size=4 \
        --per_device_eval_batch_size=4 \
        --overwrite_output_dir \
        --predict_with_generate