Compartilhando modelos pré-treinados

Nas etapas abaixo, veremos as maneiras mais fáceis de compartilhar modelos pré-treinados para o Hub 🤗. Há ferramentas e utilitários disponíveis que facilitam o compartilhamento e atualização de modelos diretamente no Hub, que exploraremos a seguir.

Encorajamos todos os usuários que treinam modelos a contribuir compartilhando-os com a comunidade - compartilhar modelos, mesmo quando treinados em conjuntos de dados muito específicos, ajudará outros, economizando tempo e recursos e fornecendo acesso a artefatos úteis treinados. Por sua vez, você pode se beneficiar do trabalho que outros realizaram!

Há três maneiras de se criar novos repositórios modelo:

• Usando a APIpush_to_hub
• Usando a biblioteca Python huggingface_hub
• Usando a interface web

Uma vez criado um repositório, você pode fazer o upload de arquivos para ele via git e git-lfs. Nós o acompanharemos na criação de repositórios modelo e no upload de arquivos para eles nas seções seguintes.

Usando a API push_to_hub

A maneira mais simples de carregar arquivos no Hub é usando a API push_to_hub.

Antes de ir adiante, você precisará gerar um token de autenticação para que a API huggingface_hub saiba quem você é e a que namespaces você tem acesso de escrita. Certifique-se de estar em um ambiente onde você tenha transformers instalado (ver Setup). Se você estiver em um notebook, você pode utilizar a seguinte função para fazer o login:

from huggingface_hub import notebook_login

notebook_login()

Em um terminal, você pode rodar:

huggingface-cli login

Em ambos os casos, você será solicitado seu nome de usuário e senha, que são os mesmos que você usa para fazer o login no Hub. Se você ainda não tem um perfil do Hub, você deve criar um aqui.

Ótimo! Agora você tem seu token de autenticação armazenado em sua pasta de cache. Vamos criar alguns repositórios!

Se você usou a API do Trainer para treinar um modelo, a maneira mais fácil de carregá-lo no Hub é definir push_to_hub=True quando você definir seus TrainingArguments:

from transformers import TrainingArguments

training_args = TrainingArguments(
    "bert-finetuned-mrpc", save_strategy="epoch", push_to_hub=True
)

Quando você chama trainer.train(), o Trainer então carregará seu modelo no Hub cada vez que ele for salvo (aqui a cada época) em um repositório em seu namespace. Esse repositório será nomeado como o diretório de saída que você escolheu (aqui bert-finetuned-mrpc), mas você pode escolher um nome diferente com hub_model_id = "a_diferent_name".

Para enviar seu modelo para uma organização da qual você é membro, basta passá-lo com hub_model_id = "my_organization/my_repo_name".

Uma vez terminado seu treinamento, você deve fazer um último trainer.push_to_hub() para carregar a última versão de seu modelo. Ele também gerará um cartão modelo com todos os metadados relevantes, relatando os hiperparâmetros utilizados e os resultados da avaliação! Aqui está um exemplo do conteúdo que você pode encontrar em um cartão modelo deste tipo:

Em um nível inferior, o acesso ao Model Hub pode ser feito diretamente nos modelos, tokenizers e objetos de configuração através de seu método push_to_hub(). Este método cuida da criação do repositório e empurra os arquivos modelo e tokenizer diretamente para o repositório. Não é necessário nenhum tratamento manual, ao contrário do que acontece com a API, veremos abaixo.

Para se ter uma idéia de como funciona, vamos primeiro inicializar um modelo e um tokenizer:

from transformers import AutoModelForMaskedLM, AutoTokenizer

checkpoint = "camembert-base"

model = AutoModelForMaskedLM.from_pretrained(checkpoint)
tokenizer = AutoTokenizer.from_pretrained(checkpoint)

Você é livre para fazer o que quiser com elas - adicionar fichas ao tokenizer, treinar o modelo, afinar o modelo. Quando você estiver satisfeito com o modelo, pesos e tokenizer resultantes, você pode aproveitar o método push_to_hub() diretamente disponível no objeto model:

model.push_to_hub("dummy-model")

Isto criará o novo repositório dummy-model em seu perfil, e o preencherá com seus arquivos de modelos. Faça o mesmo com o tokenizer, para que todos os arquivos estejam agora disponíveis neste repositório:

tokenizer.push_to_hub("dummy-model")

Se você pertence a uma organização, basta especificar o argumento organization a ser carregado no namespace dessa organização:

tokenizer.push_to_hub("dummy-model", organization="huggingface")

Se você desejar utilizar um toke específica do Hugging Face, você é livre para especificá-la também para o método push_to_hub():

tokenizer.push_to_hub("dummy-model", organization="huggingface", use_auth_token="<TOKEN>")

Agora vá até o Model Hub para encontrar seu modelo recém-carregado: https://huggingface.co/user-or-organization/dummy-model.

Clique na aba “Files and versions”, e você deve ver os arquivos visíveis na seguinte captura de tela:

Como você já viu, o método push_to_hub() aceita vários argumentos, tornando possível carregar para um repositório específico ou espaço de nomes de organizações, ou utilizar um token API diferente. Recomendamos que você dê uma olhada na especificação do método disponível diretamente na documentação 🤗 Transformers documentation para ter uma idéia do que é possível.

O método push_to_hub() é apoiado pelo pacote huggingface_hub Python, que oferece uma API direta para o Hub Hugging Face. Está integrado ao 🤗 Transformers e várias outras bibliotecas de aprendizagem de máquinas, como allenlp. Embora nos concentremos na integração do 🤗 Transformers neste capítulo, integrá-lo em seu próprio código ou biblioteca é simples.

Salte para a última seção para ver como carregar arquivos em seu repositório recém-criado!

Usando a biblioteca Python huggingface_hub

A biblioteca Pythonhuggingface_hub é um pacote que oferece um conjunto de ferramentas para os hubs do modelo e dos conjuntos de dados. Ela fornece métodos e classes simples para tarefas comuns como obter informações sobre os repositórios no centro e gerenciá-los. Ele fornece APIs simples que funcionam em cima do git para gerenciar o conteúdo desses repositórios e para integrar o Hub em seus projetos e bibliotecas.

Da mesma forma que a utilização da API push_to_hub, isto exigirá que você tenha seu token API salvo em seu cache. Para fazer isso, você precisará utilizar o comando login do CLI, como mencionado na seção anterior (mais uma vez, certifique-se de utilizar antes desses comandos o caracter ! se estiver rodando no Google Colab):

huggingface-cli login

O pacote huggingface_hub oferece vários métodos e classes que são úteis para nosso propósito. Em primeiro lugar, existem alguns métodos para gerenciar a criação de repositórios, exclusão, e outros:

from huggingface_hub import (
    # Gestão de usuários
    login,
    logout,
    whoami,

    # Criação e gestão de repositório
    create_repo,
    delete_repo,
    update_repo_visibility,

    #E alguns métodos para recuperar/trocar informações sobre o conteúdo
    list_models,
    list_datasets,
    list_metrics,
    list_repo_files,
    upload_file,
    delete_file,
)

Além disso, oferece uma poderosa classe Repository para gerenciar um repositório local. Vamos explorar esses métodos e essa classe na próxima seção para entender como aproveitá-los.

O método create_repo pode ser utilizado para criar um novo repositório no centro:

from huggingface_hub import create_repo

create_repo("dummy-model")

Isto criará o repositório dummy-model em seu namespace. Se desejar, você pode especificar a que organização o repositório deve pertencer utilizando o argumento organization:

from huggingface_hub import create_repo

create_repo("dummy-model", organization="huggingface")

Isto criará o repositório dummy-model no espaço de nomes huggingface, assumindo que você pertença a essa organização. Outros argumentos que podem ser úteis são:

• private, a fim de especificar se o repositório deve ser visível de outros ou não.
• token,se você gostaria de substituir o token armazenada em seu cache por uma determinada token.
• repo_type, se você gostaria de criar um ”dataset ou um “espaço” em vez de um modelo. Os valores aceitos são "dataset" e "space".

Uma vez criado o repositório, devemos adicionar arquivos a ele! Salte para a próxima seção para ver as três maneiras como isto pode ser tratado.

Usando a interface web

A interface web oferece ferramentas para gerenciar os repositórios diretamente no Hub. Usando a interface, você pode facilmente criar repositórios, adicionar arquivos (mesmo grandes!), explorar modelos, visualizar diffs, e muito mais.

Para criar um novo repositório, visite huggingface.co/novo:

Primeiro, especifique o proprietário do repositório: este pode ser você ou qualquer uma das organizações às quais você está afiliado. Se você escolher uma organização, o modelo será apresentado na página da organização e cada membro da organização terá a capacidade de contribuir com o repositório.

A seguir, digite o nome do seu modelo. Este também será o nome do repositório. Finalmente, você pode especificar se deseja que seu modelo seja público ou privado. Os modelos privados não podem ser encontrados publicamente.

Depois de criar seu repositório de modelos, você deve ver uma página como esta:

Aqui é onde seu modelo será hospedado. Para começar a preenchê-lo, você pode adicionar um arquivo README diretamente da interface web.

O arquivo README está em Markdown - sinta-se à vontade para ficar louco com ele! A terceira parte deste capítulo é dedicada à construção de um modelo de cartão. Estes são de extrema importância para trazer valor ao seu modelo, pois estão onde você diz aos outros o que ele pode fazer.

Se você olhar a aba “Files and versions”, você verá que ainda não há muitos arquivos - apenas o README.md que você acabou de criar e o arquivo .gitattributes que mantém o controle de arquivos grandes.

A seguir, veremos como adicionar alguns novos arquivos.

Fazendo upload dos arquivos de modelos

O sistema para gerenciar arquivos no Hub Hugging Face Hub é baseado no git para arquivos regulares, e git-lfs (que significa Git Large File Storage) para arquivos maiores.

Na seção seguinte, passamos por três maneiras diferentes de carregar arquivos no Hub: através de huggingface_hub e através de comandos de git.

A abordagem: upload_file

A utilização do upload_file não requer que git e git-lfs sejam instalados em seu sistema. Ele empurra os arquivos diretamente para o Hub 🤗 utilizando solicitações HTTP POST. Uma limitação desta abordagem é que ele não lida com arquivos maiores que 5GB de tamanho. Se seus arquivos forem maiores que 5GB, por favor, siga os dois outros métodos detalhados abaixo.

A API pode ser usada da seguinte forma:

from huggingface_hub import upload_file

upload_file(
    "<path_to_file>/config.json",
    path_in_repo="config.json",
    repo_id="<namespace>/dummy-model",
)

Isto fará o upload do arquivo config.json disponível em <path_to_file> para a raiz do repositório como config.json, para o repositório dummy-model. Outros argumentos que podem ser úteis são:

• token, se você gostaria de substituir o token armazenado em seu cache por um determinado token.
• repo_type, se você gostaria de carregar em um dataset ou em um espaço em vez de um modelo. Os valores aceitos são "dataset" e "space".

A classe: Repository

A classe Repository gerencia um repositório local de forma idiota. Ele resume a maioria dos pontos de dor que se pode ter com o git para fornecer todas as características que necessitamos.

A utilização desta classe requer ter git e git-lfs instalados, portanto certifique-se de ter o git-lfs instalado (veja aqui para instruções de instalação) e configure-o antes de começar.

Para começar a brincar com o repositório que acabamos de criar, podemos começar inicializando-o em uma pasta local através da clonagem do repositório remoto:

from huggingface_hub import Repository

repo = Repository("<path_to_dummy_folder>", clone_from="<namespace>/dummy-model")

Isto criou a pasta <path_to_dummy_folder> em nosso diretório de trabalho. Esta pasta contém apenas o arquivo .gitattributes, pois este é o único arquivo criado ao instanciar o repositório através do create_repo.

A partir deste ponto, podemos aproveitar vários dos métodos tradicionais do gitattributes:

repo.git_pull()
repo.git_add()
repo.git_commit()
repo.git_push()
repo.git_tag()

E outros! Recomendamos dar uma olhada na documentação Repository disponível aqui para uma visão geral de todos os métodos disponíveis.

No momento, temos um modelo e um tokenizer que gostaríamos de empurrar para o centro. Clonamos com sucesso o repositório, portanto, podemos salvar os arquivos dentro desse repositório.

Primeiro nos certificamos de que nosso clone local esteja atualizado, puxando as últimas mudanças:

repo.git_pull()

Uma vez feito isso, salvamos os arquivos do modelo e do tokenizer:

model.save_pretrained("<path_to_dummy_folder>")
tokenizer.save_pretrained("<path_to_dummy_folder>")

O <path_to_dummy_folder> agora contém todos os modelos e arquivos de fichas. Seguimos o fluxo de trabalho habitual do git, adicionando arquivos à área de encenação, comprometendo-os e empurrando-os para o centro:

repo.git_add()
repo.git_commit("Add model and tokenizer files")
repo.git_push()

Parabéns! Você acabou de empurrar seus primeiros arquivos para o centro.

A abordagem: baseada em git

Esta é a própria abordagem do barebone para carregar arquivos: faremos isso com git e git-lfs diretamente. A maior parte da dificuldade é abstraída por abordagens anteriores, mas há algumas advertências com o seguinte método, então seguiremos um caso de uso mais complexo.

O uso desta classe requer ter git e git-lfs instalados, portanto, certifique-se de ter git-lfs instalado (veja aqui as instruções de instalação) e configurado antes de começar.

Primeiro comece inicializando o git-lfs:

git lfs install

Updated git hooks.
Git LFS initialized.

Uma vez feito isso, o primeiro passo é clonar seu repositório modelo:

git clone https://huggingface.co/<namespace>/<your-model-id>

Meu nome de usuário é lysandre e já utilizei o nome modelo dummy, então para mim o comando acaba parecendo o seguinte:

git clone https://huggingface.co/lysandre/dummy

Agora tenho uma pasta com o nome dummy em meu diretório de trabalho. Eu posso cd dentro da pasta e dar uma olhada no conteúdo:

cd dummy && ls

README.md

Se você acabou de criar seu repositório utilizando o método create_repo do Hugging Face Hub, esta pasta deve conter apenas um arquivo oculto .gitattributes. Se você seguiu as instruções da seção anterior para criar um repositório utilizando a interface web, a pasta deve conter um único arquivo README.md ao lado do arquivo oculto .gitattributes, como mostrado aqui.

Adicionar um arquivo de tamanho normal, como um arquivo de configuração, um arquivo de vocabulário, ou basicamente qualquer arquivo sob alguns megabytes, é feito exatamente como se faria em qualquer sistema baseado no gitattributes. Entretanto, arquivos maiores devem ser registrados através do git-lfs a fim de empurrá-los para huggingface.co.

Vamos voltar a Python para gerar um modelo e tokenizer que gostaríamos de comprometer com nosso repositório dummy:

from transformers import AutoModelForMaskedLM, AutoTokenizer

checkpoint = "camembert-base"

model = AutoModelForMaskedLM.from_pretrained(checkpoint)
tokenizer = AutoTokenizer.from_pretrained(checkpoint)

# Do whatever with the model, train it, fine-tune it...

model.save_pretrained("<path_to_dummy_folder>")
tokenizer.save_pretrained("<path_to_dummy_folder>")

Agora que salvamos alguns artefatos de modelo e tokenizer, vamos dar outra olhada na pasta dummy:

ls

config.json  pytorch_model.bin  README.md  sentencepiece.bpe.model  special_tokens_map.json tokenizer_config.json  tokenizer.json

Se você olhar para os tamanhos de arquivo (por exemplo, com ls -lh), você deve ver que o arquivo de estado do modelo (pytorch_model.bin) é o único outlier, com mais de 400 MB.

Agora podemos ir em frente e proceder como normalmente faríamos com os repositórios tradicionais da Git. Podemos adicionar todos os arquivos ao ambiente de encenação do Git utilizando o comando git add:

git add .

Podemos, então, dar uma olhada nos arquivos que estão atualmente em fase de montagem:

git status

On branch main
Your branch is up to date with 'origin/main'.

Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
  modified:   .gitattributes
	new file:   config.json
	new file:   pytorch_model.bin
	new file:   sentencepiece.bpe.model
	new file:   special_tokens_map.json
	new file:   tokenizer.json
	new file:   tokenizer_config.json

Da mesma forma, podemos ter certeza de que o git-lfs está rastreando os arquivos corretos, utilizando seu comando status:

git lfs status

On branch main
Objects to be pushed to origin/main:


Objects to be committed:

	config.json (Git: bc20ff2)
	pytorch_model.bin (LFS: 35686c2)
	sentencepiece.bpe.model (LFS: 988bc5a)
	special_tokens_map.json (Git: cb23931)
	tokenizer.json (Git: 851ff3e)
	tokenizer_config.json (Git: f0f7783)

Objects not staged for commit:

Podemos ver que todos os arquivos têm Git como manipulador, exceto pytorch_model.bin e sentencepiece.bpe.model, que têm LFS. Ótimo!

Vamos prosseguir para as etapas finais, comprometendo-nos e empurrando para o repositório remoto huggingface.co:

git commit -m "First model version"

[main b08aab1] First model version
 7 files changed, 29027 insertions(+)
  6 files changed, 36 insertions(+)
 create mode 100644 config.json
 create mode 100644 pytorch_model.bin
 create mode 100644 sentencepiece.bpe.model
 create mode 100644 special_tokens_map.json
 create mode 100644 tokenizer.json
 create mode 100644 tokenizer_config.json

O push pode levar um pouco de tempo, dependendo da velocidade de sua conexão à Internet e do tamanho de seus arquivos:

git push

Uploading LFS objects: 100% (1/1), 433 MB | 1.3 MB/s, done.
Enumerating objects: 11, done.
Counting objects: 100% (11/11), done.
Delta compression using up to 12 threads
Compressing objects: 100% (9/9), done.
Writing objects: 100% (9/9), 288.27 KiB | 6.27 MiB/s, done.
Total 9 (delta 1), reused 0 (delta 0), pack-reused 0
To https://huggingface.co/lysandre/dummy
   891b41d..b08aab1  main -> main

Se dermos uma olhada no repositório modelo quando este estiver terminado, podemos ver todos os arquivos recentemente adicionados:

A IU permite que você explore os arquivos modelo e os commits e veja as diferenças introduzidas por cada commit: