Envie arquivos para o Hub

Compartilhar seus arquivos e trabalhos é um aspecto importante do Hub. O huggingface_hub oferece várias opções para enviar seus arquivos ao Hub. Você pode usar essas funções de forma independente ou integrá-las à sua biblioteca, tornando mais conveniente para seus usuários interagir com o Hub.

Sempre que você quiser enviar arquivos para o Hub, é necessário fazer login na sua conta do Hugging Face. Para mais detalhes sobre autenticação, consulte esta seção.

Enviar um arquivo

Depois de criar um repositório com create_repo(), você pode enviar um arquivo para o seu repositório usando upload_file().

Especifique o caminho do arquivo a ser enviado, o local para onde deseja enviar o arquivo no repositório e o nome do repositório ao qual deseja adicionar o arquivo. Dependendo do tipo do seu repositório, você pode definir opcionalmente o tipo do repositório como dataset, model ou space.

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> api.upload_file(
...     path_or_fileobj="/path/to/local/folder/README.md",
...     path_in_repo="README.md",
...     repo_id="username/test-dataset",
...     repo_type="dataset",
... )

Enviar uma pasta

Use a função upload_folder() para enviar uma pasta local para um repositório existente. Especifique o caminho da pasta local a ser enviada, o local para onde deseja enviar a pasta no repositório e o nome do repositório ao qual deseja adicionar a pasta. Dependendo do tipo do seu repositório, você pode definir opcionalmente o tipo do repositório como dataset, model ou space.

>>> from huggingface_hub import HfApi
>>> api = HfApi()

# Upload all the content from the local folder to your remote Space.
# By default, files are uploaded at the root of the repo
>>> api.upload_folder(
...     folder_path="/path/to/local/space",
...     repo_id="username/my-cool-space",
...     repo_type="space",
... )

Por padrão, o arquivo .gitignore será considerado para saber quais arquivos devem ou não ser commitados. Por padrão, verificamos se um arquivo .gitignore está presente em um commit e, caso não esteja, verificamos se ele existe no Hub. Tenha em mente que apenas um arquivo .gitignore presente na raiz do diretório será usado. Não verificamos arquivos .gitignore em subdiretórios.

Se você não quiser usar um arquivo .gitignore pré-definido, pode usar os argumentos allow_patterns e ignore_patterns para filtrar quais arquivos enviar. Esses parâmetros aceitam um único padrão ou uma lista de padrões. Os padrões são curingas padrão (padrões de globbing), conforme documentado aqui. Se ambos allow_patterns e ignore_patterns forem fornecidos, ambas as restrições se aplicam.

Além do arquivo .gitignore e dos padrões de permissão/ignorar, qualquer pasta .git/ presente em qualquer subdiretório será ignorada.

>>> api.upload_folder(
...     folder_path="/path/to/local/folder",
...     path_in_repo="my-dataset/train", # Upload to a specific folder
...     repo_id="username/test-dataset",
...     repo_type="dataset",
...     ignore_patterns="**/logs/*.txt", # Ignore all text logs
... )

Você também pode usar o argumento delete_patterns para especificar os arquivos que deseja excluir do repositório no mesmo commit. Isso pode ser útil se você quiser limpar uma pasta remota antes de enviar arquivos para ela e não souber quais arquivos já existem.

O exemplo abaixo faz o upload da pasta local ./logs para a pasta remota /experiment/logs/. Somente arquivos txt são enviados, mas antes disso, todos os logs anteriores no repositório são excluídos. Tudo isso em um único commit.

>>> api.upload_folder(
...     folder_path="/path/to/local/folder/logs",
...     repo_id="username/trained-model",
...     path_in_repo="experiment/logs/",
...     allow_patterns="*.txt", # Upload all local text files
...     delete_patterns="*.txt", # Delete all remote text files before
... )

Como os arquivos são enviados

Quando o hf_xet está instalado (o que é o padrão), o upload_folder() faz o upload dos arquivos por meio de um pipeline em streaming: os arquivos são verificados em relação ao Hub, enviados para o backend de armazenamento Xet (que faz o chunking, a deduplicação e a repetição de transferências internamente) e commitados em lotes adaptativos, tudo em paralelo. Na prática, isso significa:

• Pastas de qualquer tamanho: pastas pequenas são enviadas em um único commit, enquanto pastas com muitos arquivos são divididas automaticamente em vários commits para permanecer abaixo dos limites do servidor. Quando isso acontece, os commits subsequentes recebem um sufixo (part 2), (part 3), … na mensagem do commit.
• Retomável: se o upload for interrompido por qualquer motivo, basta executar novamente a mesma chamada. Os arquivos já commitados são detectados e ignorados, e os chunks já enviados são deduplicados — reenviá-los transfere (quase) nenhum dado. Não há estado local envolvido: você pode até retomar de uma máquina diferente. Uma exceção: com create_pr=True, reexecutar abre um novo pull request. Recomendamos reexecutar com revision="refs/pr/N" em vez disso ao retomar o upload.
• Sem leitura dupla: os arquivos são hasheados durante a divisão em blocos para upload, em uma única passagem de leitura. Não há uma fase separada de “hashing” antes do início do upload.

A exibição de progresso em tempo real acompanha as três etapas:

Found 5,000 files to upload
  Preparing   ████████████████████  5,000 / 5,000 ✓
  Uploading   ██████████████░░░░░░  423 / 603 files  3.8GB · 19.7MB/s
  Committing  ██████████████████░░  4,580 / 5,000  6 commits

Se hf_xet não estiver instalado, upload_folder() recorre ao comportamento legado: primeiro calcula o hash de tudo, faz o upload via HTTP e, em seguida, cria um único commit. Sempre recomendamos manter hf_xet instalado para maior robustez

Upload a partir da CLI

Você pode usar o comando hf upload do terminal para enviar arquivos diretamente para o Hub. Internamente, ele usa os mesmos auxiliares upload_file() e upload_folder() descritos acima.

Você pode enviar um arquivo único ou uma pasta inteira:

# Usage:  hf upload [repo_id] [local_path] [path_in_repo]
>>> hf upload Wauplin/my-cool-model ./models/model.safetensors model.safetensors
https://huggingface.co/Wauplin/my-cool-model/blob/main/model.safetensors

>>> hf upload Wauplin/my-cool-model ./models .
https://huggingface.co/Wauplin/my-cool-model/tree/main

local_path e path_in_repo são opcionais e podem ser inferidos implicitamente. Se local_path não for definido, a ferramenta verificará se uma pasta ou arquivo local tem o mesmo nome que o repo_id. Se for o caso, seu conteúdo será enviado. Caso contrário, uma exceção será lançada pedindo ao usuário para definir explicitamente local_path. Em qualquer caso, se path_in_repo não for definido, os arquivos serão enviados na raiz do repositório.

O destino também pode ser expresso como um único URI hf:// seguindo a gramática hf://[<TYPE>/]<ID>[@<REVISION>][/<PATH>] (consulte a referência de URIs do HF para a sintaxe completa). O tipo de repositório, a revisão e o path_in_repo são então lidos do URI, que não pode ser combinado com as opções --repo-type e --revision:

# Upload a single file to a dataset on a specific branch
>>> hf upload hf://datasets/Wauplin/my-cool-dataset@my-branch/data/train.csv ./train.csv
https://huggingface.co/datasets/Wauplin/my-cool-dataset/blob/my-branch/data/train.csv

Para obter o máximo de throughput de upload em arquivos grandes, defina a variável de ambiente HF_XET_HIGH_PERFORMANCE=1. Isso habilita o modo de alto desempenho do hf_xet, que satura a largura de banda e os núcleos de CPU disponíveis. Observação: a flag legada HF_HUB_ENABLE_HF_TRANSFER=1 não é mais usada, pois o hf_transfer foi removido em favor do hf_xet — defina HF_XET_HIGH_PERFORMANCE=1 em vez disso.

Para mais detalhes sobre o comando de upload da CLI, consulte o guia da CLI.

Envie uma pasta grande

upload_folder() e o comando hf upload são as soluções padrão para enviar arquivos para o Hub, inclusive para pastas muito grandes. Os arquivos são transmitidos para o Hub em vários commits e o processo retoma automaticamente se for interrompido. Basta executar novamente a mesma chamada e os arquivos já enviados são ignorados.

>>> api.upload_folder(
...     repo_id="HuggingFaceM4/Docmatix",
...     repo_type="dataset",
...     folder_path="/path/to/local/docmatix",
... )

ou pelo terminal:

hf upload HuggingFaceM4/Docmatix --repo-type=dataset /path/to/local/docmatix

Dicas e truques para uploads grandes

Há algumas limitações a serem consideradas ao lidar com uma grande quantidade de dados no seu repositório. Dado o tempo que leva para transmitir os dados, é muito irritante que um upload/push falhe no final do processo ou que você encontre uma experiência degradada, seja no hf.co ou ao trabalhar localmente.

Confira nosso guia Limitações e recomendações de repositórios para as melhores práticas sobre como estruturar seus repositórios no Hub. Vamos seguir com algumas dicas práticas para tornar seu processo de upload o mais suave possível.

• Comece pequeno: Recomendamos começar com uma pequena quantidade de dados para testar seu script de upload. É mais fácil iterar em um script quando as falhas levam pouco tempo.
• Esperar falhas: Transmitir grandes volumes de dados é desafiador. Você não sabe o que pode acontecer, mas é sempre melhor considerar que algo falhará pelo menos uma vez - seja por causa da sua máquina, da sua conexão ou dos nossos servidores. Por exemplo, se você planeja enviar um grande número de arquivos, é melhor manter um registro local de quais arquivos você já enviou antes de enviar o próximo lote. É garantido que um arquivo LFS que já foi commitado nunca será reenviado duas vezes, mas verificá-lo no lado do cliente ainda pode economizar tempo. É isso que o upload_folder() faz para você.
• Use hf_xet: isso aproveita o novo backend de armazenamento do Hub, é escrito em Rust e agora está disponível para todos usarem. Na verdade, hf_xet já está habilitado por padrão ao usar huggingface_hub! Para o máximo desempenho, defina HF_XET_HIGH_PERFORMANCE=1 como uma variável de ambiente. Tenha em mente que, quando o modo de alto desempenho está habilitado, a ferramenta tentará usar toda a largura de banda e todos os núcleos de CPU disponíveis.

Recursos avançados

Na maioria dos casos, você não precisará de mais do que upload_file() e upload_folder() para enviar seus arquivos ao Hub. No entanto, o huggingface_hub possui recursos mais avançados para facilitar as coisas. Vamos dar uma olhada neles!

Uploads mais rápidos

Aproveite uploads mais rápidos por meio do hf_xet, o binding em Python para a biblioteca xet-core que permite deduplicação baseada em chunks para uploads e downloads mais rápidos. O hf_xet se integra perfeitamente ao huggingface_hub, mas usa a biblioteca Rust xet-core e o armazenamento Xet em vez do LFS.

hf_xet usa o sistema de armazenamento Xet, que divide arquivos em blocos imutáveis, armazenando coleções desses blocos (chamados de blocos ou xorbs) remotamente e recuperando-os para reconstituir o arquivo quando solicitado. Durante o upload, após confirmar que o usuário está autorizado a gravar neste repositório, o hf_xet varre os arquivos, dividindo-os em seus blocos e agrupando esses blocos em xorbs (e deduplicando entre blocos conhecidos), e então envia esses xorbs para o serviço de endereçamento por conteúdo (CAS) do Xet, que verifica a integridade dos xorbs, registra os metadados dos xorbs junto com o hash SHA256 do LFS (para suportar consulta/download) e grava os xorbs no armazenamento remoto.

Para ativá-lo, basta instalar a versão mais recente do huggingface_hub:

pip install -U "huggingface_hub"

A partir da versão 0.32.0 do huggingface_hub, isso também instalará o hf_xet.

Todas as outras APIs do huggingface_hub continuarão a funcionar sem qualquer modificação. Para saber mais sobre os benefícios do armazenamento Xet e do hf_xet, consulte esta seção.

Considerações para upload em cluster / sistema de arquivos distribuído

Ao fazer upload de um cluster, os arquivos enviados geralmente residem em um sistema de arquivos distribuído ou de rede (NFS, EBS, Lustre, Fsx, etc). O armazenamento Xet dividirá esses arquivos em blocos (também chamados de xorbs) localmente e, assim que um bloco for concluído, fará o upload dele. Para um melhor desempenho ao fazer upload de um sistema de arquivos distribuído, certifique-se de definir HF_XET_CACHE para um diretório que esteja em um disco local (por exemplo, um disco NVMe ou SSD local). A localização padrão para o cache do Xet está sob HF_HOME em (~/.cache/huggingface/xet) e, como isso está no diretório home do usuário, frequentemente também está localizado no sistema de arquivos distribuído.

Uploads não bloqueantes

Em alguns casos, você deseja enviar dados sem bloquear sua thread principal. Isso é particularmente útil para enviar logs e artefatos enquanto continua um treinamento. Para isso, você pode usar o argumento run_as_future tanto em upload_file() quanto em upload_folder(). Isso retornará um objeto concurrent.futures.Future que você pode usar para verificar o status do envio.

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> future = api.upload_folder( # Upload in the background (non-blocking action)
...     repo_id="username/my-model",
...     folder_path="checkpoints-001",
...     run_as_future=True,
... )
>>> future
Future(...)
>>> future.done()
False
>>> future.result() # Wait for the upload to complete (blocking action)
...

Tarefas em segundo plano são enfileiradas ao usar run_as_future=True. Isso significa que você tem a garantia de que as tarefas serão executadas na ordem correta.

Embora os jobs em segundo plano sejam principalmente úteis para enviar dados/criar commits, você pode enfileirar qualquer método que desejar usando run_as_future(). Por exemplo, você pode usá-lo para criar um repositório e, em seguida, enviar dados para ele em segundo plano. O argumento embutido run_as_future nos métodos de upload é apenas um alias em torno dele.

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> api.run_as_future(api.create_repo, "username/my-model", exists_ok=True)
Future(...)
>>> api.upload_file(
...     repo_id="username/my-model",
...     path_in_repo="file.txt",
...     path_or_fileobj=b"file content",
...     run_as_future=True,
... )
Future(...)

Copiar arquivos entre repositórios

Use copy_files() para copiar arquivos ou pastas entre repositórios no Hub sem baixar ou reenviar grandes volumes de dados. Isso é útil quando você deseja duplicar pesos entre variantes de modelos, copiar arquivos de conjuntos de dados entre repositórios ou reorganizar arquivos entre seus repositórios. Internamente, ele cria um commit com operações CommitOperationCopy.

>>> from huggingface_hub import HfApi
>>> api = HfApi()

# Copy a single file between repos
>>> api.copy_files(
...     "hf://username/source-model/weights.safetensors",
...     "hf://username/target-model/weights.safetensors",
... )

# Copy an entire folder
>>> api.copy_files(
...     "hf://datasets/username/source-dataset/data/",
...     "hf://datasets/username/target-dataset/data/",
... )

Você também pode copiar dentro do mesmo repositório:

# Duplicate a file in the same repo
>>> api.copy_files(
...     "hf://username/my-model/config.json",
...     "hf://username/my-model/backup/config.json",
... )

Ao copiar uma pasta, um / final na origem usa semântica estilo rsync, o que significa que o conteúdo da pasta é copiado, sem aninhar a própria pasta. Sem um / final, a própria pasta é aninhada no destino.

copy_files() também suporta a cópia de arquivos para Buckets. Consulte o guia de Buckets para mais detalhes.

Uploads agendados

O Hugging Face Hub facilita o salvamento e o versionamento de dados. No entanto, existem algumas limitações ao atualizar o mesmo arquivo milhares de vezes. Por exemplo, você pode querer salvar logs de um processo de treinamento ou feedback de usuários em um Space implantado. Nesses casos, fazer o upload dos dados como um dataset no Hub faz sentido, mas pode ser difícil de fazer corretamente. A principal razão é que você não deseja versionar cada atualização dos seus dados, pois isso tornaria o repositório git inutilizável. A classe CommitScheduler oferece uma solução para esse problema.

A ideia é executar um job em segundo plano que faz o push de uma pasta local para o Hub regularmente. Vamos supor que você tenha um Gradio Space que recebe como entrada algum texto e gera duas traduções dele. Em seguida, o usuário pode selecionar sua tradução preferida. Para cada execução, você deseja salvar a entrada, a saída e a preferência do usuário para analisar os resultados. Este é um caso de uso perfeito para CommitScheduler; você deseja salvar dados no Hub (potencialmente milhões de feedbacks de usuários), mas não precisa salvar em tempo real a entrada de cada usuário. Em vez disso, você pode salvar os dados localmente em um arquivo JSON e enviá-los a cada 10 minutos. Por exemplo:

>>> import json
>>> import uuid
>>> from pathlib import Path
>>> import gradio as gr
>>> from huggingface_hub import CommitScheduler

# Define the file where to save the data. Use UUID to make sure not to overwrite existing data from a previous run.
>>> feedback_file = Path("user_feedback/") / f"data_{uuid.uuid4()}.json"
>>> feedback_folder = feedback_file.parent

# Schedule regular uploads. Remote repo and local folder are created if they don't already exist.
>>> scheduler = CommitScheduler(
...     repo_id="report-translation-feedback",
...     repo_type="dataset",
...     folder_path=feedback_folder,
...     path_in_repo="data",
...     every=10,
... )

# Define the function that will be called when the user submits its feedback (to be called in Gradio)
>>> def save_feedback(input_text:str, output_1: str, output_2:str, user_choice: int) -> None:
...     """
...     Append input/outputs and user feedback to a JSON Lines file using a thread lock to avoid concurrent writes from different users.
...     """
...     with scheduler.lock:
...         with feedback_file.open("a") as f:
...             f.write(json.dumps({"input": input_text, "output_1": output_1, "output_2": output_2, "user_choice": user_choice}))
...             f.write("\n")

# Start Gradio
>>> with gr.Blocks() as demo:
>>>     ... # define Gradio demo + use `save_feedback`
>>> demo.launch()

E é isso! As entradas/saídas do usuário e o feedback estarão disponíveis como um dataset no Hub. Ao usar um nome de arquivo JSON único, você garante que não sobrescreverá dados de uma execução anterior ou dados de outros Spaces/réplicas que estejam enviando dados simultaneamente para o mesmo repositório.

Para mais detalhes sobre o CommitScheduler, aqui está o que você precisa saber:

• apenas adição: Assume-se que você apenas adicionará conteúdo à pasta. Você deve apenas anexar dados a arquivos existentes ou criar novos arquivos. Excluir ou sobrescrever um arquivo pode corromper seu repositório.
• histórico do git: O agendador fará o commit da pasta a cada every minutos. Para evitar poluir demais o repositório git, recomenda-se definir um valor mínimo de 5 minutos. Além disso, o agendador foi projetado para evitar commits vazios. Se nenhum novo conteúdo for detectado na pasta, o commit agendado é descartado.
• erros: O agendador é executado como uma thread em segundo plano. Ele é iniciado quando você instancia a classe e continua rodando até que stop() seja chamado ou o processo seja encerrado. Se um erro ocorrer durante o upload (exemplo: problema de conexão), o erro é registrado e o agendador tenta novamente no próximo commit agendado.
• scripts: Em um script com tempo de vida limitado (por exemplo, treinamento), use o agendador como um gerenciador de contexto. Sair do bloco with dispara um último upload, aguarda sua conclusão e interrompe o agendador.
• segurança de threads: Na maioria dos casos, é seguro assumir que você pode escrever em um arquivo sem se preocupar com um arquivo de bloqueio. O agendador não terá falhas nem será corrompido se você escrever conteúdo na pasta enquanto ele está fazendo upload. Na prática, é possível que problemas de concorrência ocorram em aplicativos com alta carga. Nesse caso, recomendamos usar o bloqueio scheduler.lock para garantir a segurança de threads. O bloqueio é acionado apenas quando o agendador varre a pasta em busca de alterações, e não quando ele faz upload de dados. Você pode assumir com segurança que isso não afetará a experiência do usuário no seu Space.

Demonstração de persistência de espaço

Persistir dados de um Space em um Dataset no Hub é o principal caso de uso do CommitScheduler. Dependendo do caso de uso, você pode querer estruturar seus dados de forma diferente. A estrutura precisa ser robusta para usuários concorrentes e reinicializações, o que frequentemente implica em gerar UUIDs. Além da robustez, você deve enviar os dados em um formato legível pela biblioteca 🤗 Datasets para reutilização posterior. Criamos um Space que demonstra como salvar vários formatos de dados diferentes (você pode precisar adaptá-lo para suas necessidades específicas).

Uploads personalizados

CommitScheduler pressupõe que seus dados são apenas de acréscimo (append-only) e que devem ser enviados “como estão”. No entanto, você pode querer personalizar a forma como os dados são enviados. Você pode fazer isso criando uma classe que herde de CommitScheduler e sobrescrevendo o método push_to_hub (sinta-se à vontade para sobrescrevê-lo da forma que quiser). É garantido que ele será chamado a cada every minutos em uma thread em segundo plano. Você não precisa se preocupar com concorrência e erros, mas deve ter cuidado com outros aspectos, como enviar commits vazios ou dados duplicados.

No exemplo (simplificado) abaixo, sobrescrevemos push_to_hub para compactar todos os arquivos PNG em um único arquivo zipado, a fim de evitar sobrecarregar o repositório no Hub:

class ZipScheduler(CommitScheduler):
    def push_to_hub(self):
        # 1. List PNG files
        png_files = list(self.folder_path.glob("*.png"))
        if len(png_files) == 0:
            return None  # return early if nothing to commit

        # 2. Zip png files in a single archive
        with tempfile.TemporaryDirectory() as tmpdir:
            archive_path = Path(tmpdir) / "train.zip"
            with zipfile.ZipFile(archive_path, "w", zipfile.ZIP_DEFLATED) as zip:
                for png_file in png_files:
                    zip.write(filename=png_file, arcname=png_file.name)

            # 3. Upload archive
            self.api.upload_file(..., path_or_fileobj=archive_path)

        # 4. Delete local png files to avoid re-uploading them later
        for png_file in png_files:
            png_file.unlink()

Ao sobrescrever push_to_hub, você tem acesso aos atributos de CommitScheduler e, em especial:

• cliente HfApi: api
• Parâmetros de pasta: folder_path e path_in_repo
• Parâmetros do repositório: repo_id, repo_type, revision
• O bloqueio da thread: lock

Para mais exemplos de agendadores personalizados, confira nosso espaço de demonstração que contém diferentes implementações de acordo com seus casos de uso.

create_commit

As funções upload_file() e upload_folder() são APIs de alto nível que são geralmente convenientes de usar. Recomendamos tentar essas funções primeiro se você não precisar trabalhar em um nível mais baixo. No entanto, se você quiser trabalhar em nível de commit, pode usar a função create_commit() diretamente.

Existem três tipos de operações suportados por create_commit():

• CommitOperationAdd faz o upload de um arquivo para o Hub. Se o arquivo já existir, o conteúdo do arquivo será sobrescrito. Esta operação aceita dois argumentos:

  • path_in_repo: o caminho do repositório para onde o arquivo será enviado.
  • path_or_fileobj: um caminho para um arquivo no seu sistema de arquivos ou um objeto semelhante a um arquivo. Este é o conteúdo do arquivo a ser enviado para o Hub.

• CommitOperationDelete remove um arquivo ou uma pasta de um repositório. Esta operação aceita path_in_repo como argumento.

• CommitOperationCopy copia um arquivo dentro de um repositório ou entre repositórios. Esta operação aceita os seguintes argumentos:

  • src_path_in_repo: o caminho do repositório do arquivo a ser copiado.
  • path_in_repo: o caminho do repositório para onde o arquivo deve ser copiado.
  • src_revision: opcional - a revisão do arquivo a ser copiado, caso você queira copiar um arquivo de um branch/revisão diferente.
  • src_repo_id: opcional - o repositório de origem a ser copiado (por exemplo, "username/source-model"). O padrão é o repositório de destino.
  • src_repo_type: opcional - o tipo do repositório de origem ("model", "dataset" ou "space"). Obrigatório quando src_repo_id está definido.

Por exemplo, se você deseja enviar dois arquivos e excluir um arquivo em um repositório do Hub:

1. Use a CommitOperation apropriada para adicionar ou excluir um arquivo e para excluir uma pasta:

>>> from huggingface_hub import HfApi, CommitOperationAdd, CommitOperationDelete
>>> api = HfApi()
>>> operations = [
...     CommitOperationAdd(path_in_repo="LICENSE.md", path_or_fileobj="~/repo/LICENSE.md"),
...     CommitOperationAdd(path_in_repo="weights.h5", path_or_fileobj="~/repo/weights-final.h5"),
...     CommitOperationDelete(path_in_repo="old-weights.h5"),
...     CommitOperationDelete(path_in_repo="logs/"),
...     CommitOperationCopy(src_path_in_repo="image.png", path_in_repo="duplicate_image.png"),
... ]

2. Passe suas operações para create_commit():

>>> api.create_commit(
...     repo_id="lysandre/test-model",
...     operations=operations,
...     commit_message="Upload my model weights and license",
... )

Além de upload_file() e upload_folder(), as seguintes funções também usam create_commit() por baixo dos panos:

• delete_file() remove um único arquivo de um repositório no Hub.
• delete_folder() exclui uma pasta inteira de um repositório no Hub.
• metadata_update() atualiza os metadados de um repositório.

Para mais informações detalhadas, consulte a referência de HfApi.

Pré-enviar arquivos LFS antes do commit

Em alguns casos, você pode querer enviar arquivos enormes para o S3 antes de fazer a chamada de commit. Por exemplo, se você estiver commitando um dataset em vários shards gerados em memória, precisará enviar os shards um por um para evitar um problema de estouro de memória. Uma solução é enviar cada shard como um commit separado no repositório. Embora seja perfeitamente válido, essa solução tem a desvantagem de potencialmente bagunçar o histórico do git ao gerar dezenas de commits. Para contornar esse problema, você pode enviar seus arquivos um por um para o S3 e, em seguida, criar um único commit no final. Isso é possível usando preupload_lfs_files() em combinação com create_commit().

Este é um método para usuários avançados. Em vez de lidar com a lógica de baixo nível de pré-envio de arquivos, a abordagem recomendada na grande maioria dos casos é usar diretamente upload_file(), upload_folder() ou create_commit(). A principal ressalva de preupload_lfs_files() é que, até que o commit seja efetivamente realizado, os arquivos enviados não ficam acessíveis no repositório no Hub. Se você tiver alguma dúvida, fique à vontade para nos chamar no nosso Discord ou em uma issue no GitHub.

Aqui está um exemplo simples ilustrando como pré-enviar arquivos:

>>> from huggingface_hub import CommitOperationAdd, preupload_lfs_files, create_commit, create_repo

>>> repo_id = create_repo("test_preupload").repo_id

>>> operations = [] # List of all `CommitOperationAdd` objects that will be generated
>>> for i in range(5):
...     content = ... # generate binary content
...     addition = CommitOperationAdd(path_in_repo=f"shard_{i}_of_5.bin", path_or_fileobj=content)
...     preupload_lfs_files(repo_id, additions=[addition])
...     operations.append(addition)

>>> # Create commit
>>> create_commit(repo_id, operations=operations, commit_message="Commit all shards")

Primeiro, criamos os objetos CommitOperationAdd um a um. Em um exemplo do mundo real, esses objetos conteriam os shards gerados. Cada arquivo é enviado antes de gerar o próximo. Durante a etapa preupload_lfs_files(), o objeto CommitOperationAdd é mutado. Você deve usá-lo apenas para passá-lo diretamente para create_commit(). A principal atualização do objeto é que o conteúdo binário é removido dele, o que significa que ele será coletado pelo garbage collector se você não armazenar outra referência a ele. Isso é esperado, pois não queremos manter em memória o conteúdo que já foi enviado. Por fim, criamos o commit passando todas as operações para create_commit(). Você pode passar operações adicionais (add, delete ou copy) que ainda não foram processadas e elas serão tratadas corretamente.