Safetensors
Por que isso importa
O safetensors é hoje o formato padrão para compartilhar pesos de modelos. É o padrão nas bibliotecas Transformers e Diffusers da Hugging Face, e é o que a maioria dos criadores de modelos publica. Para quem baixa modelos da internet, ele elimina um risco real de segurança: pesquisadores já encontraram modelos maliciosos baseados em pickle enviados a repositórios públicos.
Ele também é rápido. Arquivos safetensors podem ser mapeados em memória, ou seja, o sistema operacional carrega só as partes de que você precisa, quando precisa, sem cópias extras. Modelos grandes carregam visivelmente mais rápido, e dá para ler só alguns tensores de um arquivo enorme sem carregar o resto.
Em profundidade
Quando você baixa um modelo aberto da Hugging Face, os pesos normalmente vêm em um ou mais arquivos .safetensors. O formato foi criado pela Hugging Face em 2022 para substituir o antigo padrão do PyTorch, que salvava os pesos com o formato pickle do Python em arquivos .bin ou .pt.
O problema do pickle é que carregar um arquivo pickle pode executar código arbitrário. Um arquivo de modelo malicioso poderia instalar malware no instante em que você o carrega. O safetensors guarda só dados, números brutos mais uma pequena descrição de seus formatos, então carregá-lo nunca executa código.
O que há dentro do arquivo
O formato é simples de propósito:
- Um número de 8 bytes dizendo o tamanho do cabeçalho.
- Um cabeçalho JSON que lista cada tensor: o nome, o tipo de dado (como F16, BF16 ou F32), o formato e onde os bytes dele ficam no arquivo. Ele também pode guardar metadados livres.
- Os dados brutos dos tensores, um bloco depois do outro.
É só isso. Como não há código nem estrutura complexa, o formato é fácil de implementar em qualquer linguagem, e uma auditoria de segurança independente encomendada em 2023 não encontrou problemas críticos.
Modelos divididos em partes
Modelos grandes são divididos em vários arquivos, como model-00001-of-00004.safetensors, mais um arquivo de índice (model.safetensors.index.json) que associa cada nome de tensor ao arquivo em que ele está. As ferramentas leem o índice e carregam as partes automaticamente.
Safetensors versus outros formatos
- Pickle (
.bin,.pt,.ckpt): flexível, mas inseguro para carregar de fontes não confiáveis. Use só com arquivos em que você confia, e prefira opções de carregamento que restrinjam o que pode ser executado. - GGUF: o formato de arquivo único usado pelo llama.cpp, pelo Ollama e pelo LM Studio. Ele empacota pesos, tokenizador e configurações juntos e foi pensado para inferência local quantizada. Muitos arquivos GGUF são convertidos de originais em safetensors.
- ONNX: guarda tanto os pesos quanto o grafo de computação, para que um modelo rode em diferentes runtimes e hardwares sem o código original.
Notas práticas
O safetensors guarda os pesos, não a receita inteira do modelo. Você ainda precisa do arquivo de configuração (config.json), dos arquivos do tokenizador e do código que define a arquitetura. Quando um repositório oferece versões .bin e .safetensors, escolha safetensors. Adaptadores LoRA resultantes de fine-tuning também costumam ser distribuídos como pequenos arquivos safetensors (adapter_model.safetensors).