Começando com Repositórios

Este guia, amigável para iniciantes, ajudará você a adquirir as habilidades básicas necessárias para criar e gerenciar seu repositório no Hub. Cada seção se baseia na anterior, então sinta-se à vontade para escolher por onde começar!

Requisitos

Este documento mostra como gerenciar repositórios por meio da interface web e também por meio do terminal. Não há requisitos ao trabalhar com a interface. Se você deseja trabalhar com o terminal, siga estas instruções de instalação.

Se você ainda não tiver o git disponível como um comando de CLI, será necessário instalar o Git para sua plataforma. Você também precisará instalar o Git-Xet, que será usado para lidar com arquivos grandes, como imagens e pesos de modelos.

Para poder baixar e enviar arquivos grandes do Git, você precisa instalar a extensão Git Xet.

Para poder enviar seu código para o Hub, você precisará se autenticar de alguma forma. A maneira mais fácil de fazer isso é instalando o hf CLI e executando o comando de login:

# Install hf:
#   brew install hf
#   or
#   pip install hf
hf auth login

O conteúdo da seção Getting Started deste documento também está disponível em vídeo!

Criando um repositório

Usando a interface web do Hub, você pode criar repositórios com facilidade, adicionar arquivos (mesmo os grandes!), explorar modelos, visualizar diffs e muito mais. Existem três tipos de repositórios no Hub, e neste guia você criará um repositório de modelo para fins de demonstração. Para informações sobre a criação e o gerenciamento de modelos, conjuntos de dados e Spaces, consulte a documentação respectiva.

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

2. Especifique o proprietário do repositório: pode ser você ou qualquer uma das organizações às quais você está afiliado.

3. Digite o nome do seu modelo. Este também será o nome do repositório.

4. Especifique se você deseja que seu modelo seja público ou privado.

5. Especifique a licença. Você pode deixar o campo License em branco por enquanto. Para saber mais sobre licenças, visite a documentação de Licenses.

Após criar o repositório do seu modelo, você deve ver uma página como esta:

Observe que o Hub solicita que você crie um Model Card, sobre o qual você pode saber mais na documentação de Model Cards. Incluir um Model Card no repositório do seu modelo é uma boa prática, mas, como estamos criando apenas um repositório de teste no momento, podemos pular essa etapa.

Adicionando arquivos a um repositório (interface web)

Para adicionar arquivos ao seu repositório pela interface web, comece selecionando a aba Files, navegando até o diretório desejado e, em seguida, clicando em Add file. Você terá a opção de criar um novo arquivo ou fazer o upload de um arquivo diretamente do seu computador.

Criando um novo arquivo

Ao escolher criar um novo arquivo, você será levado à tela de editor a seguir, onde pode escolher um nome para o arquivo, adicionar conteúdo e salvar o arquivo com uma mensagem que resume suas alterações. Em vez de commitar diretamente o novo arquivo no branch main do seu repositório, você pode selecionar Open as a pull request para criar um Pull Request.

Enviando um arquivo

Se você escolher Upload file, poderá selecionar um arquivo local para enviar, junto com uma mensagem resumindo suas alterações no repositório.

Assim como ao criar novos arquivos, você pode selecionar Open as a pull request para criar um Pull Request em vez de adicionar suas alterações diretamente ao ramo main do seu repositório.

Adicionando arquivos a um repositório (CLI)

Você pode enviar arquivos para o seu repositório diretamente do terminal usando o CLI hf. Use o comando hf upload para enviar arquivos locais ou pastas inteiras:

# Upload a single file to your model repo
hf upload your-username/your-model-name model.safetensors

# Upload an entire directory
hf upload your-username/your-model-name ./my-model-directory

# Upload to a dataset repo
hf upload your-username/your-dataset-name ./data --repo-type dataset

O CLI hf trata arquivos grandes automaticamente — não é necessário nenhum ajuste extra.

Adicionando arquivos a um repositório (git)

Clonando repositórios

Baixar repositórios para sua máquina local é chamado de clonagem. Você pode usar os seguintes comandos para carregar seu repositório e navegar até ele:

git clone https://huggingface.co/<your-username>/<your-model-name>
cd <your-model-name>

Ou para um repositório de dataset:

git clone https://huggingface.co/datasets/<your-username>/<your-dataset-name>
cd <your-dataset-name>

Você pode clonar via SSH com o seguinte comando:

git clone git@hf.co:<your-username>/<your-model-name>
cd <your-model-name>

Você precisará adicionar sua chave pública SSH em suas configurações de usuário para enviar alterações ou acessar repositórios privados.

Configuração

Agora é a hora, você pode adicionar qualquer arquivo que quiser ao repositório! 🔥

Você tem arquivos maiores que 10MB? Esses arquivos devem ser rastreados com git-xet, que você pode inicializar com:

git xet install

Ao usar o Hugging Face para criar um repositório, o Hugging Face fornece automaticamente uma lista de extensões de arquivo comuns para arquivos grandes de Machine Learning no arquivo .gitattributes, que o git-xet usa para rastrear eficientemente as alterações nos seus arquivos grandes. No entanto, você pode precisar adicionar novas extensões se os tipos de arquivo não forem tratados. Você pode fazer isso com git xet track "*.your_extension".

Enviando arquivos

Você pode usar o Git para salvar novos arquivos e quaisquer alterações em arquivos já existentes como um conjunto de alterações chamado commit, que pode ser pensado como uma “revisão” do seu projeto. Para criar um commit, você precisa add os arquivos para informar ao Git que estamos planejando salvar as alterações e, em seguida, commit essas alterações. Para sincronizar o novo commit com o Hugging Face Hub, você então push o commit para o Hub.

# Create any files you like! Then...
git add .
git commit -m "First model version"  # You can choose any descriptive message
git push

E você terminou! Você pode verificar seu repositório no Hugging Face com todos os arquivos adicionados recentemente. Por exemplo, no screenshot abaixo, o usuário adicionou uma série de arquivos. Observe que alguns arquivos neste exemplo têm um tamanho de 1.04 GB, então o repositório usa Xet para rastreá-lo.

Se você clonou o repositório com HTTP, pode ser solicitado que você preencha seu nome de usuário e senha em cada operação de push. A maneira mais simples de evitar a repetição é mudar para SSH, em vez de HTTP. Alternativamente, se você tiver que usar HTTP, pode ser útil configurar um git credential helper para preencher automaticamente seu nome de usuário e senha.

Visualizando o histórico de um repositório

Sempre que você percorre o ciclo add-commit-push, o repositório mantém o registro de todas as alterações que você fez nos seus arquivos. A interface permite explorar os arquivos do modelo e os commits e ver a diferença (também conhecida como diff) introduzida por cada commit. Para ver o histórico, você pode clicar no link History: X commits.

Você pode clicar em um commit individual para ver quais alterações esse commit introduziu: