Limites de armazenamento

Na Hugging Face, nosso objetivo é fornecer à comunidade de IA volumes significativos de espaço de armazenamento gratuito para repositórios públicos, com a opção de comprar mais armazenamento, se necessário. Também cobramos pelo espaço de armazenamento de repositórios privados, acima de uma franquia gratuita (veja a tabela abaixo).

Limites e políticas de armazenamento se aplicam a todos os tipos de repositórios (modelos, conjuntos de dados, buckets, …) no Hub.

Otimizamos continuamente nossa infraestrutura para escalar nosso armazenamento nos próximos anos de crescimento em IA e aprendizado de máquina.

Temos medidas de mitigação para evitar o abuso do armazenamento público gratuito e, em geral, pedimos que usuários e organizações garantam que qualquer modelo ou conjunto de dados grande enviado seja o mais útil possível para a comunidade (representado, por exemplo, pelo número de curtidas ou downloads). Faça o upgrade para uma Organização paga ou uma conta de Usuário (PRO) para desbloquear limites mais altos.

Planos de armazenamento

💡 Equipes ou Organizações Enterprise incluem 1TB de armazenamento privado por assento na assinatura: por exemplo, se sua organização tiver 40 membros, você terá 40TB de armazenamento privado incluído.

* Nosso objetivo é continuar oferecendo à comunidade de IA um espaço de armazenamento gratuito generoso para repositórios públicos. Além dos primeiros gigabytes, use esse recurso com responsabilidade, enviando conteúdo que ofereça valor genuíno a outros usuários. Se você precisar de um espaço de armazenamento substancial, será necessário fazer o upgrade para PRO, Team ou Enterprise.

† Em alguns casos, são disponibilizadas concessões adicionais de armazenamento para trabalhos de alto impacto em código aberto em que um plano pago realmente não consegue cobrir a necessidade. Entre em contato conosco com evidências de impacto na comunidade (curtidas, downloads, citações).

Add-on de armazenamento público

Usuários de um plano pago (PRO, Team ou Enterprise) podem assinar um acréscimo de armazenamento público para obter armazenamento público adicional além do limite base do plano.

Você pode se inscrever ou alterar seu plano na página de configurações de Faturamento da sua conta ou organização. Os upgrades entram em vigor imediatamente; os downgrades são agendados para entrar em vigor no início do próximo mês. Se você precisar de mais armazenamento, pode entrar em contato conosco para aproveitar a preços personalizados em larga escala.

Armazenamento privado Pagamento conforme o uso

Acima dos 1 TB (ou 1 TB por assento) de armazenamento privado incluídos no PRO e em Organizações Team ou Enterprise, o armazenamento privado adicional é cobrado no seu método de pagamento no modo Pay-as-you-go, com um preço base de US$ 18/TB/mês. Descontos adicionais estão disponíveis para volumes em larga escala por meio de nossos executivos de conta:

Consulte nosso documento de faturamento para mais detalhes ou visualize os preços mais recentes em huggingface.co/pricing.

Limitações e recomendações do repositório

Esta seção não se aplica a Storage Buckets

Além dos limites de armazenamento no nível da conta (usuário ou organização), existem algumas limitações a serem consideradas ao lidar com grandes quantidades de dados em um repositório específico baseado em Git. Dado o tempo que leva para transmitir os dados, ter um upload/push falhando no final do processo ou encontrar uma experiência degradada, seja no hf.co ou ao trabalhar localmente, pode ser muito irritante. Na seção a seguir, descrevemos nossas recomendações sobre como estruturar melhor seus repositórios grandes.

Recomendações

Reunimos uma lista de dicas e recomendações para estruturar seu repositório. Se você está procurando dicas mais práticas, confira este guia sobre como enviar grandes quantidades de dados usando a biblioteca Python.

* Não relevante ao usar o git CLI diretamente

Leia a próxima seção para entender melhor esses limites e como lidar com eles.

Explicações

Sobre o que estamos falando quando dizemos “uploads grandes” e quais são as limitações associadas a eles? Uploads grandes podem ser muito diversos, desde repositórios com alguns arquivos enormes (por exemplo, pesos de modelo) até repositórios com milhares de arquivos pequenos (por exemplo, um conjunto de dados de imagens).

Por baixo dos panos, o Hub usa Git para versionar os dados, o que tem implicações estruturais sobre o que você pode fazer no seu repositório. Se o seu repositório está ultrapassando alguns dos números mencionados na seção anterior, fortemente recomendamos que você verifique git-sizer, que possui documentação muito detalhada sobre os diferentes fatores que impactarão sua experiência. Aqui está um resumo dos fatores a considerar:

• Tamanho do repositório: o tamanho total dos dados que você planeja enviar. Não há limite de tamanho por repositório para modelos e conjuntos de dados, mas os uploads contam para a cota total de armazenamento da sua conta (veja Planos de armazenamento acima). Se você precisar de mais armazenamento, faça upgrade do seu plano ou compre um acréscimo de armazenamento.
• Number of files:
  • Para uma experiência ideal, recomendamos manter o número total de arquivos abaixo de 100 mil, e idealmente muito menos. Tente mesclar os dados em menos arquivos, caso tenha mais. Por exemplo, arquivos json podem ser mesclados em um único arquivo jsonl, ou grandes conjuntos de dados podem ser exportados como arquivos Parquet ou no formato WebDataset.
  • O número máximo de arquivos por pasta não pode exceder 10 mil arquivos por pasta. Uma solução simples é criar uma estrutura de repositório que usa subdiretórios. Por exemplo, um repositório com 1 mil pastas de 000/ a 999/, cada uma contendo no máximo 1000 arquivos, já é suficiente.
• File size: No caso de upload de arquivos grandes (por exemplo, pesos de modelo), recomendamos fortemente dividi-los em blocos de menos de 200GB cada.. Existem alguns motivos para isso:
  • Fazer upload e download de arquivos menores é muito mais fácil tanto para você quanto para os outros usuários. Problemas de conexão podem sempre ocorrer ao transmitir dados, e arquivos menores evitam a necessidade de retomar do início em caso de erros.
  • Os arquivos são fornecidos aos usuários usando CloudFront. Com base em nossa experiência, arquivos muito grandes não são armazenados em cache por esse serviço, o que leva a uma velocidade de download mais lenta. Em todos os casos, nenhum arquivo individual excederá 500GB. Ou seja, 500GB é o limite rígido para o tamanho de um arquivo individual.
• Número de commits: Não há um limite rígido para o número total de commits no histórico do seu repositório. No entanto, com base na nossa experiência, a experiência do usuário no Hub começa a se degradar após alguns milhares de commits. Estamos trabalhando constantemente para melhorar o serviço, mas é importante lembrar que um repositório git não foi projetado para funcionar como um banco de dados com muitas gravações. Se o histórico do seu repositório ficar muito grande, é sempre possível compactar todos os commits para recomeçar do zero usando super_squash_history do huggingface_hub. Tenha em mente que esta é uma operação irreversível.
• Número de operações por commit: Novamente, não há um limite rígido aqui. Quando um commit é enviado no Hub, cada operação git (adição ou exclusão) é verificada pelo servidor. Quando cem Arquivos Grandes são commitados de uma vez, cada arquivo é verificado individualmente para garantir que foi enviado corretamente. Ao enviar dados via HTTP, um timeout de 60s é definido na solicitação, o que significa que, se o processo levar mais tempo, um erro é lançado. No entanto, pode acontecer (em casos raros) que, mesmo que o timeout seja lançado no lado do cliente, o processo ainda seja concluído no lado do servidor. Isso pode ser verificado manualmente navegando pelo repositório no Hub. O método upload_folder e o comando hf upload evitam isso automaticamente dividindo pastas grandes em vários commits. Se você fizer o commit manualmente, mantenha cerca de 50-100 arquivos por commit.

Compartilhando grandes conjuntos de dados no Hub

Uma das principais formas como o Hugging Face apoia o ecossistema de machine learning é hospedando datasets no Hub, incluindo os de grande porte. Datasets grandes contam para a cota total de armazenamento da sua conta, portanto, verifique se o seu plano de armazenamento tem capacidade suficiente antes de fazer o upload. Armazenamento público adicional pode ser adquirido como um add-on.

Para hospedar grandes conjuntos de dados no Hub, exigimos o seguinte:

• Um cartão de dataset: queremos garantir que seu dataset possa ser usado de forma eficaz pela comunidade, e uma das principais maneiras de viabilizar isso é por meio de um cartão de dataset. Este guia fornece uma visão geral de como escrever um cartão de dataset.
• Você está compartilhando o conjunto de dados para permitir a reutilização pela comunidade. Se você planeja enviar um conjunto de dados que não deve ter mais reutilizações, outras plataformas provavelmente são mais adequadas.
• Você deve seguir as limitações do repositório descritas acima.
• Use formatos de arquivo bem integrados ao ecossistema do Hugging Face. Temos bom suporte para os formatos Parquet e WebDataset, que são frequentemente boas opções para compartilhar grandes conjuntos de dados de forma eficiente. Isso também garantirá que o visualizador de conjuntos de dados funcione para o seu conjunto de dados.
• Evite o uso de scripts de carregamento personalizados ao utilizar datasets. Em nossa experiência, datasets que exigem código personalizado para uso geralmente acabam com reutilização limitada.

Entre em contato conosco se algum desses requisitos for difícil de atender devido ao tipo de dados ou domínio em que você está trabalhando.

Compartilhando grandes volumes de modelos no Hub

Assim como os conjuntos de dados, modelos grandes ou grandes volumes de modelos (por exemplo, centenas de quants automatizados) contam para a cota total de armazenamento da sua conta. Verifique se o seu plano de armazenamento tem capacidade suficiente ou compre um acréscimo de armazenamento.

Concessões para equipes de pesquisa e organizações sem fins lucrativos

Recomendamos que instituições acadêmicas e de pesquisa façam o upgrade para Team, Enterprise, or Academia Hub para limites de armazenamento garantidos. Em alguns casos, concessões de armazenamento podem estar disponíveis para trabalhos de código aberto de alto impacto em que um plano pago realmente não consegue cobrir a necessidade. Essas concessões são avaliadas caso a caso e exigem impacto demonstrado na comunidade (downloads, citações, adoção pela comunidade, etc.). Entre em contato com datasets@huggingface.co ou models@huggingface.co com uma proposta detalhada.

Como posso liberar espaço de armazenamento na minha conta/organização?

Existem várias formas de gerenciar e liberar espaço de armazenamento na sua conta ou organização. Primeiro, se você precisar de mais espaço de armazenamento, faça o upgrade para um plano PRO, Team ou Enterprise para obter limites de armazenamento maiores.

⚠️ Importante: A exclusão de arquivos grandes é uma operação destrutiva que não pode ser desfeita. Certifique-se de fazer um backup dos seus arquivos antes de prosseguir.

Pontos-chave para lembrar:

• Excluir apenas os ponteiros LFS não libera espaço
• Se você não reescrever o histórico do Git, futuros checkouts de branches/tags que contenham arquivos LFS excluídos com ponteiros lfs existentes falharão (para evitar erros, adicione a seguinte linha ao seu arquivo .gitconfig: lfs.skipdownloaderrors=true)

Excluindo arquivos LFS individuais

1. Acesse a página de Configurações do seu repositório
2. Clique em “List LFS files” na seção “Storage”
3. Use o menu de ações para excluir arquivos específicos

Excluindo refs de Pull request

Pull requests criam refs do git que armazenam seus commits. Após fechar ou mesclar um PR, você pode excluir sua ref para liberar espaço de armazenamento. Isso é especialmente útil quando:

• Os PRs contêm arquivos grandes que nunca foram mesclados
• Você compactou a branch principal e removeu arquivos posteriormente — esses arquivos permanecem no histórico da branch do PR, mesmo que não tenham sido adicionados pelo próprio PR

Para excluir uma ref de PR, abra o PR fechado ou mesclado e procure pelo aviso de armazenamento na parte inferior, que mostra o espaço estimado que pode ser liberado. Clique em “Delete ref” para removê-lo permanentemente.

Excluir uma ref de PR é irreversível e impedirá que qualquer pessoa faça o fetch ou o checkout desses commits localmente.

Super-comprima seu repositório usando a API

A operação super-squash comprime todo o seu histórico Git em um único commit. Considere usar o super-squash quando precisar recuperar armazenamento de versões antigas do LFS que você não está usando. Esta operação está disponível apenas por meio da Hub Python Library ou da API.

⚠️ Importante: Esta é uma operação destrutiva que não pode ser desfeita, o histórico de commits será perdido permanentemente e o histórico de arquivos LFS será removido

Os efeitos da operação de compactação na sua cota de armazenamento não são imediatos e serão refletidos na sua cota em até 36 horas.

Avançado: Rastrear referências de arquivos LFS

Quando você encontra um arquivo LFS no “List LFS files” do seu repositório, mas não sabe de onde ele veio, você pode rastrear seu histórico usando seu OID SHA-256 com o comando git log:

git log --all -p -S <SHA-256-OID>

Por exemplo:

git log --all -p -S 68d45e234eb4a928074dfd868cead0219ab85354cc53d20e772753c6bb9169d3

commit 5af368743e3f1d81c2a846f7c8d4a028ad9fb021
Date:   Sun Apr 28 02:01:18 2024 +0200

    Update LayerNorm tensor names to weight and bias

diff --git a/model.safetensors b/model.safetensors
index a090ee7..e79c80e 100644
--- a/model.safetensors
+++ b/model.safetensors
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:68d45e234eb4a928074dfd868cead0219ab85354cc53d20e772753c6bb9169d3
+oid sha256:0bb7a1683251b832d6f4644e523b325adcf485b7193379f5515e6083b5ed174b
 size 440449768

commit 0a6aa9128b6194f4f3c4db429b6cb4891cdb421b (origin/pr/28)
Date:   Wed Nov 16 15:15:39 2022 +0000

    Adding `safetensors` variant of this model (#15)
    
    
    - Adding `safetensors` variant of this model (18c87780b5e54825a2454d5855a354ad46c5b87e)
    
    
    Co-authored-by: Nicolas Patry <Narsil@users.noreply.huggingface.co>

diff --git a/model.safetensors b/model.safetensors
new file mode 100644
index 0000000..a090ee7
--- /dev/null
+++ b/model.safetensors
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:68d45e234eb4a928074dfd868cead0219ab85354cc53d20e772753c6bb9169d3
+size 440449768

commit 18c87780b5e54825a2454d5855a354ad46c5b87e (origin/pr/15)
Date:   Thu Nov 10 09:35:55 2022 +0000

    Adding `safetensors` variant of this model

diff --git a/model.safetensors b/model.safetensors
new file mode 100644
index 0000000..a090ee7
--- /dev/null
+++ b/model.safetensors
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:68d45e234eb4a928074dfd868cead0219ab85354cc53d20e772753c6bb9169d3
+size 440449768