# 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](../quick-start#authentication).

## Enviar um arquivo

Depois de criar um repositório com [create_repo()](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.HfApi.create_repo), você pode enviar um arquivo para o seu repositório usando [upload_file()](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.HfApi.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`.

```py
>>> 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()](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.HfApi.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`.

```py
>>> 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](https://tldp.org/LDP/GNU-Linux-Tools-Summary/html/x11655.htm). 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.

```py
>>> 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/`. Apenas 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.
```py
>>> 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()](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.HfApi.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()](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.HfApi.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()](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.HfApi.upload_file) e [upload_folder()](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.HfApi.upload_folder) descritos acima.

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

```bash
# 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](../package_reference/hf_uris) 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`:

```bash
# 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
```

> [!TIP]
> Para obter o máximo de throughput de upload em arquivos grandes, defina a variável de ambiente [`HF_XET_HIGH_PERFORMANCE=1`](../package_reference/environment_variables#hf_xet_high_performance). 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](./cli#hf-upload).

## Envie uma pasta grande

[upload_folder()](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.HfApi.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.

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

ou pelo terminal:

```sh
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](https://huggingface.co/docs/hub/repositories-recommendations) 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 quantidades 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 [upload_folder()](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.HfApi.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`](../package_reference/environment_variables#hf_xet_high_performance) 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()](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.HfApi.upload_file) e [upload_folder()](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.HfApi.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`](https://github.com/huggingface/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`:

```bash
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](https://huggingface.co/docs/hub/xet/index).

**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`](../package_reference/environment_variables#hfxetcache) 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()](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.HfApi.upload_file) quanto em [upload_folder()](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.HfApi.upload_folder). Isso retornará um objeto [`concurrent.futures.Future`](https://docs.python.org/3/library/concurrent.futures.html#future-objects) que você pode usar para verificar o status do envio.

```py
>>> 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)
...
```

> [!TIP]
> 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()](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.HfApi.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.

```py
>>> 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()](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.HfApi.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](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.CommitOperationCopy).

```py
>>> 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:

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

> [!TIP]
> 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.

> [!TIP]
> [copy_files()](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.HfApi.copy_files) também suporta a cópia de arquivos para [Buckets](./buckets). Consulte o [guia de Buckets](./buckets#copy-files-to-bucket) 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 sobre 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. O principal motivo é que você não deseja versionar cada atualização dos seus dados, pois isso tornaria o repositório git inutilizável. A classe [CommitScheduler](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.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 Space do Gradio que recebe como entrada algum texto e gera duas traduções dele. Em seguida, o usuário pode selecionar a 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 o [CommitScheduler](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.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:

```py
>>> 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](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.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 vai travar ou 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 para [CommitScheduler](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.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](https://huggingface.co/spaces/Wauplin/space_to_dataset_saver) que demonstra como salvar vários formatos de dados diferentes (você pode precisar adaptá-lo para suas necessidades específicas).

#### Uploads personalizados

[CommitScheduler](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.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. Para isso, crie uma classe que herde de [CommitScheduler](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.CommitScheduler) e sobrescreva o método `push_to_hub` (sinta-se à vontade para sobrescrevê-lo da maneira que preferir). É garantido que ele será chamado a cada `every` minutos em uma thread em segundo plano. Você não precisa se preocupar com concorrência nem com erros, mas deve ter cuidado com outros aspectos, como o envio de commits vazios ou de 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:

```py
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](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.CommitScheduler) e, em especial:
- cliente [HfApi](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.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`

> [!TIP]
> Para mais exemplos de agendadores personalizados, confira nosso [espaço de demonstração](https://huggingface.co/spaces/Wauplin/space_to_dataset_saver) que contém diferentes implementações de acordo com seus casos de uso.

### create_commit

As funções [upload_file()](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.HfApi.upload_file) e [upload_folder()](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.HfApi.upload_folder) são APIs de alto nível que geralmente são convenientes de usar. Recomendamos tentar essas funções primeiro, caso você não precise 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()](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.HfApi.create_commit) diretamente.

Existem três tipos de operações suportados por [create_commit()](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.HfApi.create_commit):

- [CommitOperationAdd](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.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](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.CommitOperationDelete) remove um arquivo ou uma pasta de um repositório. Esta operação aceita `path_in_repo` como argumento.

- [CommitOperationCopy](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.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:

```py
>>> 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()](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.HfApi.create_commit):

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

Além de [upload_file()](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.HfApi.upload_file) e [upload_folder()](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.HfApi.upload_folder), as seguintes funções também usam [create_commit()](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.HfApi.create_commit) por baixo dos panos:

- [delete_file()](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.HfApi.delete_file) remove um único arquivo de um repositório no Hub.
- [delete_folder()](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.HfApi.delete_folder) exclui uma pasta inteira de um repositório no Hub.
- [metadata_update()](/docs/huggingface_hub/v2.4.0/pt/package_reference/cards#huggingface_hub.metadata_update) atualiza os metadados de um repositório.

Para mais informações detalhadas, consulte a referência de [HfApi](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.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()](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.HfApi.preupload_lfs_files) em combinação com [create_commit()](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.HfApi.create_commit).

> [!WARNING]
> Este é um método para usuários avançados. Em grande parte dos casos, a melhor abordagem é usar diretamente [upload_file()](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.HfApi.upload_file), [upload_folder()](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.HfApi.upload_folder) ou [create_commit()](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.HfApi.create_commit), em vez de lidar com a lógica de baixo nível de pré-envio de arquivos. A principal ressalva sobre [preupload_lfs_files()](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.HfApi.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 contatar no nosso Discord ou em uma issue no GitHub.

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

```py
>>> 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](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.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()](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.HfApi.preupload_lfs_files), **o objeto `CommitOperationAdd` é mutado**. Você deve usá-lo apenas para passá-lo diretamente para [create_commit()](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.HfApi.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()](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.HfApi.create_commit). Você pode passar operações adicionais (add, delete ou copy) que ainda não foram processadas e elas serão tratadas corretamente.