Criar e gerenciar um repositório

O Hugging Face Hub é uma coleção de repositórios git. Git é uma ferramenta amplamente utilizada no desenvolvimento de software para versionar projetos com facilidade ao trabalhar de forma colaborativa. Este guia mostrará como interagir com os repositórios no Hub, especialmente:

• Crie e exclua um repositório.
• Gerencie ramos e tags.
• Renomeie seu repositório.
• Atualize a visibilidade do seu repositório.
• Gerencie uma cópia local do seu repositório.

Se você está acostumado a trabalhar com plataformas como GitLab/GitHub/Bitbucket, seu primeiro instinto pode ser usar o CLI git para clonar seu repositório (git clone), commitar alterações (git add, git commit) e enviá-las (git push). Isso é válido ao usar o Hugging Face Hub. No entanto, a engenharia de software e o aprendizado de máquina não compartilham os mesmos requisitos e fluxos de trabalho. Os repositórios de modelos podem manter arquivos grandes de pesos de modelos para diferentes frameworks e ferramentas, portanto, clonar o repositório pode levar você a manter pastas locais grandes com tamanhos massivos. Como resultado, pode ser mais eficiente usar nossos métodos HTTP personalizados. Você pode ler nossa página de explicação Paradigma Git vs HTTP para mais detalhes.

Se você deseja criar e gerenciar um repositório no Hub, sua máquina deve estar conectada. Caso contrário, consulte esta seção. No restante deste guia, assumiremos que sua máquina está conectada.

Liste seus repositórios

Você pode listar todos os repositórios (modelos, conjuntos de dados, espaços e buckets) da sua conta ou de uma organização usando list_user_repos(). Os resultados incluem informações de armazenamento e são ordenados pelo uso de armazenamento.

>>> from huggingface_hub import list_user_repos

# List repos for the authenticated user
>>> repos = list(list_user_repos())
>>> for repo in repos[:3]:
...     print(f"{repo.id} ({repo.type}) - {repo.storage} bytes")
username/my-model (model) - 4828692480 bytes
username/my-dataset (dataset) - 598427559 bytes
username/my-space (space) - 120620146 bytes

# List repos from an organization
>>> repos = list(list_user_repos(namespace="my-org"))

Ou via CLI (mostra 30 repositórios por padrão, use --limit 0 para listar todos):

>>> hf repos ls
>>> hf repos ls --namespace my-org --type model
>>> hf repos ls --limit 0 --format json | jq '.[].id'

Criação e exclusão de repositórios

O primeiro passo é saber como criar e excluir repositórios. Você só pode gerenciar repositórios que possui (no namespace do seu nome de usuário) ou de organizações nas quais você tem permissões de escrita.

Criar um repositório

Crie um repositório vazio com create_repo() e dê um nome a ele com o parâmetro repo_id. O repo_id é o seu namespace seguido pelo nome do repositório: username_or_org/repo_name.

>>> from huggingface_hub import create_repo
>>> create_repo("lysandre/test-model")
'https://huggingface.co/lysandre/test-model'

Ou via CLI:

>>> hf repos create lysandre/test-model
Successfully created lysandre/test-model on the Hub.
Your repo is now available at https://huggingface.co/lysandre/test-model

Por padrão, create_repo() cria um repositório de modelo. Mas você pode usar o parâmetro repo_type para especificar outro tipo de repositório. Por exemplo, se você quiser criar um repositório de dataset:

>>> from huggingface_hub import create_repo
>>> create_repo("lysandre/test-dataset", repo_type="dataset")
'https://huggingface.co/datasets/lysandre/test-dataset'

Ou via CLI:

>>> hf repos create lysandre/test-dataset --repo-type dataset

Ao criar um repositório, você pode definir a visibilidade do seu repositório com o parâmetro visibility:

>>> from huggingface_hub import create_repo
>>> create_repo("lysandre/test-private", visibility="private")

Ou via CLI:

>>> hf repos create lysandre/test-private --private

Se você quiser alterar a visibilidade do repositório em um momento posterior, pode usar a função update_repo_settings().

Se você faz parte de uma organização com um plano Enterprise, pode criar um repositório em um grupo de recursos específico passando resource_group_id como parâmetro para create_repo(). Grupos de recursos são um recurso de segurança para controlar quais membros da sua organização podem acessar um determinado recurso. Você pode obter o ID do grupo de recursos copiando-o da URL da página de configurações da sua organização no Hub (por exemplo, "https://huggingface.co/organizations/huggingface/settings/resource-groups/66670e5163145ca562cb1988" => "66670e5163145ca562cb1988"). Para mais detalhes sobre grupos de recursos, confira este guia.

Você também pode criar um repositório em uma região de nuvem específica passando region como parâmetro:

>>> from huggingface_hub import create_repo
>>> create_repo("lysandre/test-model", region="us")

Excluir um repositório

Exclua um repositório com delete_repo(). Certifique-se de que deseja excluir um repositório, pois esse é um processo irreversível!

Especifique o repo_id do repositório que você deseja excluir:

>>> delete_repo(repo_id="lysandre/my-corrupted-dataset", repo_type="dataset")

Pass missing_ok=True para ignorar silenciosamente a chamada se o repositório não existir:

>>> delete_repo(repo_id="lysandre/my-corrupted-dataset", repo_type="dataset", missing_ok=True)

Ou via CLI:

>>> hf repos delete lysandre/my-corrupted-dataset --repo-type dataset

Duplicar um repositório

Em alguns casos, você deseja copiar o repositório de outra pessoa para adaptá-lo ao seu caso de uso. Isso é possível usando o método duplicate_repo(). Ele duplicará o repositório inteiro, preservando o histórico completo do git. Isso funciona para modelos, conjuntos de dados e Spaces. Para Spaces, você ainda precisará configurar seus próprios parâmetros (hardware, tempo de inatividade, armazenamento, variáveis e segredos). Consulte nosso guia Gerenciar seu Space para mais detalhes.

>>> from huggingface_hub import duplicate_repo

# Duplicate a Space
>>> duplicate_repo("multimodalart/dreambooth-training", repo_type="space", private=False)
RepoUrl('https://huggingface.co/spaces/nateraw/dreambooth-training',...)

# Duplicate a dataset
>>> duplicate_repo("openai/gdpval", repo_type="dataset")
RepoUrl('https://huggingface.co/datasets/nateraw/gdpval',...)

Assim como create_repo(), duplicate_repo() aceita um resource_group_id para criar a cópia diretamente dentro de um grupo de recursos da sua organização Enterprise (--resource-group-id com hf repos duplicate).

O histórico do git é copiado imediatamente, mas os arquivos LFS/Xet ainda podem estar sendo copiados em segundo plano após o retorno de duplicate_repo(). Até que a cópia seja concluída, o download desses arquivos do novo repositório pode falhar. Verifique files_copy_pending no valor retornado para saber se a cópia ainda está em andamento:

>>> from huggingface_hub import duplicate_repo
>>> repo_url = duplicate_repo("openai/gdpval", repo_type="dataset")
>>> repo_url.files_copy_pending
True

Pesquisar por Spaces

O Hub fornece uma API de busca semântica para descobrir Spaces. Você pode pesquisar usando consultas em linguagem natural com search_spaces():

>>> from huggingface_hub import search_spaces
>>> results = list(search_spaces("generate image"))
>>> results[0].id
'mrfakename/Z-Image-Turbo'

Para mais detalhes e opções de filtragem, consulte o guia Gerenciar seus Spaces.

Carregar e baixar arquivos

Agora que você criou seu repositório, você está interessado em enviar alterações para ele e baixar arquivos dele.

Esses 2 tópicos merecem seus próprios guias. Consulte os guias de upload e download para aprender a usar seu repositório.

Copiar arquivos

Use copy_files() para copiar arquivos que já estão hospedados no Hub de um repositório para outro (ou até mesmo dentro do mesmo repositório) sem baixá-los e reenviá-los. Tanto arquivos individuais quanto pastas inteiras são suportados, e arquivos rastreados com Xet ou LFS são copiados no servidor por hash.

>>> from huggingface_hub import copy_files

# Copy a single file from one repo to another
>>> copy_files(
...     "hf://username/source-model/config.json",
...     "hf://username/dest-model/config.json",
... )

# Copy an entire folder (a trailing "/" copies the folder *contents*, rsync-style)
>>> copy_files(
...     "hf://datasets/username/my-dataset/data/",
...     "hf://datasets/username/my-dataset-copy/data/",
... )

Ou via CLI, com o comando unificado hf cp (também disponível como hf repos cp):

# Copy a single file between repositories
>>> hf cp hf://username/source-model/config.json hf://username/dest-model/config.json

# Copy a file from a repo to your local machine
>>> hf repos cp hf://username/my-model/config.json ./config.json

# Upload a local file to a repository
>>> hf repos cp ./model.safetensors hf://username/my-model/model.safetensors

copy_files (e hf cp) também podem copiar arquivos de um repositório para um Bucket. Copiar de um bucket para um repositório não é suportado. Consulte o guia de Buckets para mais detalhes.

Cópias no lado do servidor funcionam apenas dentro da mesma região de armazenamento.

Branches e tags

Repositórios Git frequentemente fazem uso de ramos para armazenar diferentes versões de um mesmo repositório. Tags também podem ser usadas para marcar um estado específico do seu repositório, por exemplo, ao lançar uma versão. De forma mais geral, ramos e tags são referidos como git references.

Criar branches e tags

Você pode criar novos ramos e tags usando create_branch() e create_tag():

>>> from huggingface_hub import create_branch, create_tag

# Create a branch on a Space repo from `main` branch
>>> create_branch("Matthijs/speecht5-tts-demo", repo_type="space", branch="handle-dog-speaker")

# Create a tag on a Dataset repo from `v0.1-release` branch
>>> create_tag("bigcode/the-stack", repo_type="dataset", revision="v0.1-release", tag="v0.1.1", tag_message="Bump release version.")

Ou via CLI:

>>> hf repos branch create Matthijs/speecht5-tts-demo handle-dog-speaker --repo-type space
>>> hf repos tag create bigcode/the-stack v0.1.1 --repo-type dataset --revision v0.1-release -m "Bump release version."

Você pode usar as funções delete_branch() e delete_tag() da mesma forma para excluir um branch ou uma tag, ou hf repos branch delete e hf repos tag delete, respectivamente, na CLI.

Liste todos os ramos e tags

Você também pode listar os refs git existentes de um repositório usando list_repo_refs():

>>> from huggingface_hub import list_repo_refs
>>> list_repo_refs("bigcode/the-stack", repo_type="dataset")
GitRefs(
   branches=[
         GitRefInfo(name='main', ref='refs/heads/main', target_commit='18edc1591d9ce72aa82f56c4431b3c969b210ae3'),
         GitRefInfo(name='v1.1.a1', ref='refs/heads/v1.1.a1', target_commit='f9826b862d1567f3822d3d25649b0d6d22ace714')
   ],
   converts=[],
   tags=[
         GitRefInfo(name='v1.0', ref='refs/tags/v1.0', target_commit='c37a8cd1e382064d8aced5e05543c5f7753834da')
   ]
)

Alterar configurações do repositório

Os repositórios vêm com algumas configurações que você pode ajustar. Na maioria das vezes, você fará isso manualmente na página de configurações do repositório no seu navegador. Você precisa ter acesso de escrita a um repositório para configurá-lo (seja o proprietário ou faça parte de uma organização). Nesta seção, veremos as configurações que também podem ser ajustadas programaticamente usando huggingface_hub.

Algumas configurações são específicas para Spaces (hardware, variáveis de ambiente, ...). Para configurá-las, consulte nosso guia Gerenciar seus Spaces.

Atualizar visibilidade

Um repositório pode ser público ou privado. Um repositório privado é visível apenas para você ou para os membros da organização na qual o repositório está localizado. Altere um repositório para privado conforme mostrado a seguir:

>>> from huggingface_hub import update_repo_settings
>>> update_repo_settings(repo_id=repo_id, private=True)

Ou via CLI:

>>> hf repos settings lysandre/test-private --private true

Configurar acesso restrito

Para oferecer mais controle sobre o uso dos repositórios, o Hub permite que os autores de repositórios ativem requisições de acesso para seus repositórios. Quando ativado, o usuário deve concordar em compartilhar suas informações de contato (nome de usuário e endereço de e-mail) com os autores do repositório para acessar os arquivos. Um repositório com requisições de acesso ativadas é chamado de repositório com controle de acesso.

Você pode definir um repositório como restrito usando update_repo_settings():

>>> from huggingface_hub import HfApi

>>> api = HfApi()
>>> api.update_repo_settings(repo_id=repo_id, gated="auto")  # Set automatic gating for a model

Ou via CLI:

>>> hf repos settings lysandre/test-private --gated auto

Renomear seu repositório

Você pode renomear seu repositório no Hub usando move_repo(). Com esse método, você também pode mover o repositório de um usuário para uma organização. Ao fazer isso, há algumas limitações das quais você deve estar ciente. Por exemplo, você não pode transferir seu repositório para outro usuário.

>>> from huggingface_hub import move_repo
>>> move_repo(from_id="Wauplin/cool-model", to_id="huggingface/cool-model")

Ou via CLI:

>>> hf repos move Wauplin/cool-model huggingface/cool-model

Repositórios de kernels

O Hub suporta um tipo de repositório "kernel" para hospedar kernels de computação. Este não é um tipo de repositório totalmente compatível. Apenas um conjunto limitado de métodos foi testado e é oficialmente suportado:

• kernel_info()
• hf_hub_download()
• snapshot_download()
• list_repo_refs()
• list_repo_files()
• list_repo_tree()

Observe que create_repo() e delete_repo() também são compatíveis, mas restritos a um pequeno subconjunto de usuários e organizações permitidos no Hub.

For building, publishing, and using kernel repos, please use the dedicated kernels package instead. Refer to the Kernels documentation for more details.