Como conferir se o arquivo do modelo baixou inteiro
Compare o SHA256 do arquivo com o publicado no Hugging Face, pelo PowerShell ou com o hf cache verify, e veja como é o erro quando não bate.
- Nível
- Começando
- Você vai precisar
- Windows 10 ou 11
- Um arquivo de modelo já baixado
- Opcional: o comando hf instalado
- Testado em
- , Windows 11 Pro, Windows PowerShell 5.1, Python 3.14.4 e huggingface_hub 2.4.0
Arquivo de modelo que baixou pela metade ou corrompido costuma dar erros que não dizem a causa: o programa trava ao carregar, reclama de formato ou gera lixo. Antes de reinstalar tudo, confira o arquivo. A mesma conferência serve para saber se um arquivo que veio de outro lugar é igual ao original.
A conferência usa o SHA256, uma impressão digital do conteúdo: se um único byte muda, o resultado muda inteiro.
1. Achar o SHA256 oficial
No Hugging Face, abra a página do arquivo (aba de arquivos do repositório, clique no nome do arquivo). Para arquivos grandes, a página mostra uma linha SHA256 com o valor. No exemplo deste tutorial, o VAE do Z-Image-Turbo (vae/diffusion_pytorch_model.safetensors, 167666902 bytes), o valor publicado é:
f5b59a26851551b67ae1fe58d32e76486e1e812def4696a4bea97f16604d40a3
2. Calcular o SHA256 do seu arquivo
No PowerShell, sem instalar nada:
Get-FileHash .\modelos\z-image-turbo\vae\diffusion_pytorch_model.safetensors -Algorithm SHA256 | Format-List Algorithm, Hash
Resposta no teste:
Algorithm : SHA256
Hash : F5B59A26851551B67AE1FE58D32E76486E1E812DEF4696A4BEA97F16604D40A3
O PowerShell mostra em maiúsculas e o site em minúsculas; é o mesmo valor. Para não comparar 64 caracteres no olho, peça a comparação ao próprio PowerShell:
(Get-FileHash .\modelos\z-image-turbo\vae\diffusion_pytorch_model.safetensors -Algorithm SHA256).Hash -eq 'f5b59a26851551b67ae1fe58d32e76486e1e812def4696a4bea97f16604d40a3'
A resposta True quer dizer que o arquivo é idêntico ao publicado. False quer dizer que não é.
No Prompt de Comando, o equivalente é certutil -hashfile CAMINHO_DO_ARQUIVO SHA256, que no teste devolveu o mesmo valor.
3. Conferir tudo de uma vez com o hf
Quem baixou com o comando hf (veja como baixar um modelo do Hugging Face) pode conferir todos os arquivos de uma pasta sem procurar valor nenhum:
.\venv\Scripts\hf cache verify Tongyi-MAI/Z-Image-Turbo --local-dir .\modelos\z-image-turbo
Com os arquivos em ordem, a resposta no teste foi:
Warning: 30 remote file(s) are missing locally. Use --fail-on-missing-files for details.
repo_id=Tongyi-MAI/Z-Image-Turbo repo_type=model checked=2 path=...\modelos\z-image-turbo
O aviso só lembra que o repositório tem outros arquivos que não foram baixados, o que é esperado quando você pega só uma parte. O que importa é checked=2 sem mensagem de erro. Sem --local-dir, o comando confere o que está no cache padrão.
Como é quando o arquivo está errado
Para ver o erro acontecer, o teste trocou o arquivo por uma cópia com um único byte a mais no final (167666903 bytes em vez de 167666902). O SHA256 dessa cópia ficou completamente diferente:
9fa7e9a6b48d9a758623b8e2160713aebf316aa5527ad81cb245a0fee778f2e9
E o hf cache verify acusou:
Checksum verification failed for the following file(s):
- vae/diffusion_pytorch_model.safetensors: expected f5b59a26...40a3 (sha256), got 9fa7e9a6...f2e9
Error: Verification failed for 'Tongyi-MAI/Z-Image-Turbo' (model)
O conserto é baixar de novo o mesmo arquivo para a mesma pasta. No teste, repetir o comando de download substituiu a cópia estragada e a conferência voltou a passar.
O que a conferência garante e o que não garante
- Garante que o seu arquivo é idêntico ao que está no repositório.
- Não garante que o repositório é confiável. Um arquivo malicioso também tem um SHA256 que "confere". Baixe do repositório indicado na ficha do modelo, que diz de onde vem cada link.
- Prefira arquivos
.safetensors. Formatos antigos baseados em pickle (.ckpt,.pt,.bin) podem conter código que roda ao carregar, como a documentação do Hugging Face explica.