Usando o Xet Storage

Python

Para acessar uma versão do huggingface_hub com suporte a Xet, basta instalar a versão mais recente:

pip install -U huggingface_hub

A partir da versão 0.32.0 do huggingface_hub, isso também instalará o hf_xet. O pacote hf_xet integra o huggingface_hub ao xet-core, o cliente em Rust para o backend Xet.

Se você usa as bibliotecas transformers ou datasets, elas já utilizam o huggingface_hub. Desde que a versão do huggingface_hub seja >= 0.32.0, nenhuma ação adicional precisa ser tomada.

Quando as versões do huggingface_hub >= 0.30.0 e < 0.32.0 estão instaladas, o hf_xet deve ser instalado explicitamente:

pip install -U hf-xet

E é isso! Agora você obtém os benefícios da deduplicação do Xet para uploads e downloads. Membros da equipe que usam uma versão do huggingface_hub < 0.30.0 ainda poderão fazer upload e download de repositórios por meio da compatibilidade reversa fornecida pela ponte LFS.

Para ver a documentação de uso mais detalhada, consulte a documentação do huggingface_hub para:

• Upload
• Baixar
• Gerenciando o cache do hf_xet

Git

Usuários do Git podem acessar os benefícios do Xet baixando e instalando a extensão Git Xet. Uma vez instalada, basta usar os fluxos de trabalho padrão para gerenciar repositórios do Hub com Git - nenhuma alteração adicional é necessária.

Pré-requisitos

Instale o Git e o Git LFS.

Instale no macOS ou Linux (amd64 ou aarch64)

Instale usando um script de instalação com o seguinte comando no seu terminal (requer curl e unzip):

curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/huggingface/xet-core/refs/heads/main/git_xet/install.sh | sh

Ou, instale usando o Homebrew:

brew install git-xet
git xet install

Para verificar a instalação, execute:

git xet --version

Windows (amd64)

Usando winget:

winget install git-xet

Usando um instalador:

• Baixe git-xet-windows-installer-x86_64.zip (disponível aqui) e descompacte.
• Execute o arquivo de instalador msi e siga as instruções.

Instalação manual:

• Baixe git-xet-windows-x86_64.zip (disponível aqui) e descompacte.
• Coloque o git-xet.exe extraído em um diretório do PATH.
• Execute git xet install em um terminal.

Para verificar a instalação, execute:

git xet --version

Usando Git Xet

Uma vez instalado na sua plataforma, usar o Git Xet é tão simples quanto seguir os fluxos de trabalho padrão do Git do Hub.

Certifique-se de que todos os pré-requisitos estão instalados e configurados, siga as instruções de configuração para trabalhar com repositórios no Hub, em seguida, faça o commit das suas alterações e push para o Hub:

# Create any files you like! Then...
git add .
git commit -m "Uploading new models"  # You can choose any descriptive message
git push

Por baixo dos panos, o protocolo Xet é acionado para enviar arquivos grandes diretamente para o armazenamento Xet, aumentando as velocidades de upload por meio do poder da deduplicação em nível de chunk.

Desinstalar no macOS ou Linux

Usando o Homebrew:

git xet uninstall
brew uninstall git-xet

Se você usou o script de instalação (para MacOS ou Linux), execute o seguinte no seu terminal:

git xet uninstall
sudo rm $(which git-xet)

Desinstalar no Windows

Se você usou winget:

winget uninstall git-xet

Se você usou o instalador:

• Acesse Configurações -> Aplicativos -> Aplicativos instalados
• Encontre “Git-Xet”.
• Selecione a opção “Desinstalar” disponível no menu de contexto.

Se você instalou manualmente:

• Execute git xet uninstall em um terminal.
• Exclua o arquivo git-xet.exe do local onde ele foi originalmente colocado.

Recomendações

O Xet se integra perfeitamente a todos os fluxos de trabalho do Hub. No entanto, há algumas etapas que você pode considerar para aproveitar ao máximo os benefícios do armazenamento Xet.

Ao fazer upload ou download com Python:

• Verifique se hf_xet está instalado: Embora o Xet mantenha compatibilidade reversa com clientes legados otimizados para Git LFS, a integração do hf_xet com o huggingface_hub oferece desempenho ideal baseado em chunks e iterações mais rápidas em arquivos grandes.
• A concorrência adaptativa está ativada por padrão: hf_xet ajusta automaticamente o número de fluxos de transferência paralelos com base nas condições de rede em tempo real — sem necessidade de configuração. As configurações padrão saturarão a maioria dos caminhos de rede sem qualquer ajuste.
• Os buffers de download são dimensionados de acordo com a memória do sistema: a partir da versão 1.7.0 do hf_xet, os buffers de download são dimensionados com base na memória disponível para o hf_xet, incluindo os limites de memória de contêineres. Contêineres pequenos usam menos memória para downloads e máquinas grandes usam mais, sem a necessidade de configurações. Consulte Buffers de download.
• Ajuste avançado: Para controle de granularidade fina, HF_XET_FIXED_DOWNLOAD_CONCURRENCY e HF_XET_FIXED_UPLOAD_CONCURRENCY permitem fixar a concorrência em um valor específico, ignorando o controlador adaptativo. Consulte as variáveis de ambiente do hf_xet para a lista completa de opções.

Ao fazer upload ou download no Git ou Python:

• Aproveite-se de commits frequentes e incrementais: a deduplicação em nível de chunk do Xet significa que você pode fazer atualizações incrementais em modelos ou conjuntos de dados com segurança. Apenas os chunks alterados são enviados, o que torna os commits frequentes rápidos e eficientes em termos de armazenamento.
• Seja específico no .gitattributes: ao definir padrões para Xet ou LFS, use extensões de arquivo precisas (por exemplo, *.safetensors, *.bin) para evitar rotear arquivos menores desnecessariamente pelo armazenamento de arquivos grandes.
• Dê prioridade ao acesso da comunidade: o Xet aumenta substancialmente a eficiência e a escala da transferência de arquivos grandes. Em vez de estruturar seu repositório para reduzir seu tamanho total (ou o tamanho de arquivos individuais), organize-o para colaboradores e usuários da comunidade, para que eles possam navegar e recuperar facilmente o conteúdo de que precisam.

Fazendo upload por trás de um proxy ou firewall

A partir da versão 1.8.0 do hf_xet, os uploads podem enviar dados diretamente para o Amazon S3, em vez de apenas através do serviço de armazenamento Xet. O Hub decide para cada upload se deve usar o upload direto e está ativando essa funcionalidade gradualmente. Os downloads não mudam.

Se sua rede restringe o tráfego de saída, permita esses nomes de host (HTTPS, porta 443) além dos listados em Baixando atrás de um proxy ou firewall:

Esses nomes de host não estão sob hf.co ou huggingface.co, portanto, a lista de permissões desses sufixos não os cobre.

Se o hf_xet não consegue acessar o S3, ele tenta novamente o upload direto e, em seguida, envia esses dados pelo serviço de armazenamento Xet. O upload ainda é concluído, mas pode ser muito mais lento, pois cada bloco aguarda a conclusão das novas tentativas primeiro. O log do hf_xet exibe Upload grant URL unreachable, falling back to legacy xorb upload path (may be slower) quando isso ocorre. Se você não puder permitir os nomes de host do S3, defina HF_XET_CLIENT_LEGACY_DIRECT_XORB_UPLOAD=1 para desativar os uploads diretos.

Variáveis de Ambiente

Tanto o hf_xet quanto o Git Xet são impulsionados pelo xet-core, que pode ser configurado por meio de variáveis de ambiente. As tabelas abaixo listam as variáveis individuais para controle granular. A maioria dos usuários não precisará alterar nenhuma delas — os valores padrão são ajustados para saturar automaticamente a maioria dos caminhos de rede.

HF_XET_HIGH_PERFORMANCE=1 é uma flag de conveniência que ajusta várias configurações de uma vez (limites de concorrência, tamanhos de buffer e limites de arquivos paralelos). Ela é destinada a máquinas com alta largura de banda e disco rápido. A partir da versão 1.7.0 do hf_xet, os tamanhos de buffer que ela define são baseados na memória disponível para o hf_xet (veja Buffers de Download), portanto, ela não requer mais 64 GB de RAM, e qualquer variável que você definir manualmente tem precedência sobre esta flag. Em versões anteriores, use-a apenas em máquinas com pelo menos 64 GB de RAM.

Geral

Flags de alto nível que a maioria dos usuários procura primeiro.

Concorrência Adaptativa

Por padrão, o xet-core usa concorrência adaptativa — ajustando dinamicamente o paralelismo com base nas condições de rede em tempo real. Estas são configurações avançadas que provavelmente não serão necessárias na maioria dos casos. As variáveis abaixo controlam o comportamento do controlador adaptativo:

Para fixar a concorrência em um valor específico (ignorando o controlador adaptativo), use os aliases de conveniência HF_XET_FIXED_UPLOAD_CONCURRENCY e HF_XET_FIXED_DOWNLOAD_CONCURRENCY. Esses definem a concorrência inicial, mínima e máxima para o mesmo valor.

Rede e Tentativa

Transferência de Dados

Baixar Buffers

Esses controlam o uso de memória durante os downloads.

A partir da versão 1.7.0 do hf_xet, os valores padrão das três variáveis DOWNLOAD_BUFFER são baseados na quantidade de memória que o hf_xet pode utilizar. Isso corresponde à RAM do computador ou ao limite de memória do contêiner, caso este seja menor. Cada valor padrão é uma fração dessa memória, mantida entre o mínimo e o máximo indicados na tabela. O modo HP utiliza o dobro da fração, com o mesmo mínimo e máximo. Por exemplo, um contêiner limitado a 4 GB recebe um buffer de aproximadamente 256 MB com um limite de 1 GB, e um computador com 32 GB recebe aproximadamente o mesmo buffer de 2 GB e limite de 8 GB das versões anteriores.

Versões anteriores, ou qualquer versão que não consiga determinar a quantidade de memória disponível, usam padrões fixos de 2gb, 512mb e 8gb (16gb, 2gb e 64gb no modo HP). Os valores em uso são gravados no arquivo de log hf_xet quando ele inicia (veja Logging).

Cache de Shards

O shard cache armazena o índice de deduplicação (os “shards” que descrevem os blocos já enviados) no disco, dentro do diretório de cache do Xet. Um cache maior permite que o cliente deduplique contra mais dados previamente vistos, de modo que menos bytes são reenviados.

Cache de Chunk

hf_xet não usa mais um cache local de blocos para downloads. Os arquivos baixados ainda são armazenados no cache baseado em arquivos do huggingface_hub.

Registro

Telemetria

hf_xet envia um relatório curto após cada upload e download. Consulte Telemetria para saber o que ele contém. Para desativá-lo, defina HF_HUB_DISABLE_TELEMETRY=1.

Limitações Atuais

Embora o Xet traga deduplicação de granularidade fina e desempenho aprimorado para o armazenamento baseado em Git, alguns recursos e compatibilidades de plataforma ainda estão em desenvolvimento. Como resultado, mantenha as seguintes restrições em mente ao trabalhar com um repositório habilitado para Xet:

• Somente sistemas de 64 bits: Tanto o hf_xet quanto o Git Xet atualmente exigem uma arquitetura de 64 bits; sistemas de 32 bits não são suportados.