Safetensors: Formato Rápido e Seguro para Armazenamento de Pesos de Modelos

Safetensors é um formato binário para armazenar e carregar pesos de modelos de aprendizado de máquina, desenvolvido pela Hugging Face. Ele resolve vulnerabilidades críticas de segurança presentes em formatos baseados em pickle (como os arquivos .bin e .pt do PyTorch), utilizando uma estrutura simples e estaticamente analisável que não permite a execução de código arbitrário durante a desserialização. O formato alcança tempos de carregamento significativamente mais rápidos por meio de mapeamento de memória e operações sem cópia, tornando-se o formato preferido para distribuição e carregamento de modelos de IA em 2026.

O Que É Safetensors

Safetensors armazena tensores (matrizes multidimensionais de números que representam pesos de redes neurais) em um formato binário simples, com um cabeçalho em JSON. Ao contrário dos formatos baseados em pickle historicamente usados no PyTorch, safetensors contém apenas dados brutos dos tensores e metadados — sem código Python, sem definições de classes e sem instruções executáveis.

A estrutura do arquivo consiste em:

• Um cabeçalho de 8 bytes contendo o tamanho dos metadados
• Uma seção de metadados em JSON que descreve os nomes dos tensores, suas dimensões, tipos de dados e deslocamentos em bytes
• Dados brutos dos tensores armazenados de forma contígua em blocos alinhados à memória

Essa simplicidade permite o carregamento com mapeamento de memória: o sistema operacional mapeia diretamente o arquivo na memória do processo, permitindo acesso instantâneo aos dados dos tensores sem copiar gigabytes para a RAM. Quando você abre um modelo de 7B de parâmetros armazenado como safetensors, o tempo de carregamento é medido em milissegundos, e não em segundos.

Por Que Safetensors Foi Criado

O formato pickle do Python, usado por padrão nas funções torch.save() e torch.load(), pode executar código Python arbitrário durante a desserialização. Um agente malicioso pode criar um arquivo .bin ou .pt que execute malware quando você chamar torch.load(). Essa não é uma vulnerabilidade teórica — diversos incidentes já demonstraram arquivos de modelos comprometidos em ambiente real.

Além da segurança, os formatos baseados em pickle sofrem com problemas de desempenho:

Ao carregar um arquivo pickle, o Python deve desserializar toda a estrutura na memória, reconstruir os objetos Python e, em seguida, copiar os dados dos tensores para o formato nativo da estrutura. O Safetensors elimina essas etapas mapeando diretamente os dados binários dos tensores.

Instalação e Uso do Safetensors

Instale a biblioteca Python:

pip install safetensors

Carregando Arquivos Safetensors

O melhor editor completo safe_open() para carregamento preguiçoso com mapeamento de memória:

from safetensors import safe_open

with safe_open("model.safetensors", framework="pt", device="cpu") as f:
    # Obter lista de nomes de tensores
    tensor_names = f.keys()
    
    # Carregar tensor específico (preguiçoso — carrega apenas este tensor)
    embedding_weights = f.get_tensor("model.embed_tokens.weight")
    
    # Obter metadados do tensor sem carregá-lo
    metadata = f.metadata()

O framework o parâmetro especifica o framework-alvo: "pt" para PyTorch, "tf" para TensorFlow, "np" para NumPy, ou "jax" para JAX. O parâmetro device controla onde os tensores são alocados: "cpu", "cuda:0", ou outros identificadores de dispositivo.

Para carregar todos os tensores de uma vez:

from safetensors.torch import load_file

tensors = load_file("model.safetensors")
# Retorna um dicionário: {"layer.weight": tensor, "layer.bias": tensor, ...}

Salvando arquivos Safetensors

Salve um dicionário de tensores:

from safetensors.torch import save_file
import torch

tensors = {
    "embedding.weight": torch.randn(50000, 768),
    "layer1.weight": torch.randn(768, 768),
    "layer1.bias": torch.randn(768)
}

save_file(tensors, "model.safetensors")

Inclua metadados personalizados:

save_file(
    tensors,
    "model.safetensors",
    metadata={"model_type": "bert", "vocab_size": "50000"}
)

Carregando modelos da Hugging Face

A biblioteca da transformers Hugging Face usa safetensors automaticamente quando disponível:

from transformers import AutoModel

# Baixa e carrega automaticamente .safetensors, se disponível
model = AutoModel.from_pretrained("bert-base-uncased")

Forçar o formato safetensors:

model = AutoModel.from_pretrained(
    "bert-base-uncased",
    use_safetensors=True  # Falha se safetensors não estiver disponível
)

A maioria dos modelos no Hugging Face Hub agora inclui ambos os arquivos model.safetensors e pytorch_model.bin A biblioteca prioriza safetensors quando ambos estiverem presentes.

Conversão Entre Formatos

Conversão de .bin do PyTorch para Safetensors

from safetensors.torch import save_file
import torch

# Carrega o checkpoint do PyTorch
state_dict = torch.load("pytorch_model.bin", map_location="cpu")

# Salva como safetensors
save_file(state_dict, "model.safetensors")

Conversão de Safetensors para .bin do PyTorch

from safetensors.torch import load_file
import torch

tensors = load_file("model.safetensors")
torch.save(tensors, "pytorch_model.bin")

Script de conversão da Hugging Face

O transformers A biblioteca inclui uma ferramenta de conversão:

python -m transformers.convert_safetensors_to_pytorch 
    --model_name_or_path ./model_folder 
    --output_dir ./converted

Detalhes Técnicos do Formato de Arquivo

Um arquivo safetensors tem a seguinte estrutura:

1. Cabeçalho (8 bytes): Inteiro sem sinal de 64 bits em ordem little-endian contendo o tamanho, em bytes, do JSON com metadados
2. Metadados (variável): Objeto JSON com este esquema:

   {
     "layer_name": {
       "dtype": "F32",  // Tipo de dado: F32, F16, BF16, I64, I32, etc.
       "shape": [768, 768],  // Dimensões do tensor
       "data_offsets": [0, 2359296]  // Índices inicial e final, em bytes, na seção de dados
     },
     "__metadata__": {  // Metadados personalizados opcionais
       "key": "value"
     }
   }

3. Seção de dados: Bytes brutos dos tensores, armazenados em ordem C-contígua (row-major) e alinhados em fronteiras de 8 bytes

O formato suporta estes tipos de dados: F64, F32, F16, BF16, I64, U64, I32, U32, I16, U16, I8, U8, BOOL. O intervalo de bytes de cada tensor é especificado nos metadados, permitindo o carregamento seletivo sem análise do arquivo inteiro.

Suporte no Ecossistema

Safetensors é compatível com todo o ecossistema de IA:

Ao avaliar se um modelo caberá na memória da sua GPU, use o Calculadora de VRAM para estimar os requisitos com base na contagem de parâmetros e no nível de quantização. O próprio formato de arquivo não afeta o uso de VRAM — arquivos safetensors e pickle do mesmo modelo consomem memória GPU idêntica após serem carregados.

Características de Desempenho

Benchmarks em um sistema com SSD NVMe e 64 GB de RAM carregando um modelo de 7B de parâmetros:

A abordagem de carregamento preguiçoso com safe_open() é particularmente valiosa quando você precisa inspecionar a arquitetura do modelo, extrair camadas específicas ou carregar modelos que excedem a RAM disponível, carregando tensores de forma seletiva.

Para modelos quantizados, o safetensors suporta todos os tipos de dados padrão, incluindo FP16, BF16, INT8 e INT4. O Banco de dados de modelos de IA inclui os tamanhos dos arquivos safetensors e os requisitos de VRAM para 37 modelos populares em diferentes níveis de quantização.

Modelos Fragmentados (Sharded)

Modelos maiores que alguns gigabytes são frequentemente distribuídos como múltiplos arquivos safetensors (sharding). Um modelo de 70B de parâmetros pode ser dividido em 8 shards:

model-00001-of-00008.safetensors
model-00002-of-00008.safetensors
...
model-00008-of-00008.safetensors
model.safetensors.index.json

O arquivo de índice mapeia os nomes dos tensores para os arquivos de shard:

{
  "metadata": {"total_size": 141123453952},
  "weight_map": {
    "model.embed_tokens.weight": "model-00001-of-00008.safetensors",
    "model.layers.0.self_attn.q_proj.weight": "model-00001-of-00008.safetensors",
    "model.layers.40.mlp.gate_proj.weight": "model-00005-of-00008.safetensors"
  }
}

As bibliotecas Hugging Face lidam automaticamente com o carregamento fragmentado. Carregamento manual:

import json
from safetensors import safe_open

with open("model.safetensors.index.json") as f:
    index = json.load(f)

weight_map = index["weight_map"]

# Carregar um tensor específico consultando seu shard
tensor_name = "model.layers.20.mlp.down_proj.weight"
shard_file = weight_map[tensor_name]

with safe_open(shard_file, framework="pt", device="cpu") as f:
    tensor = f.get_tensor(tensor_name)

Ligações para Diferentes Linguagens (Language Bindings)

Embora a implementação de referência seja em Python, o safetensors possui bindings para múltiplas linguagens:

• Rust: Implementação principal em Rust, voltada para desempenho e segurança
• Python: Bindings oficiais via PyPI
• JavaScript/Node.js: @huggingface/safetensors Pacote npm
• C/C++: Disponível por meio de FFI para a biblioteca em Rust
• Go: Implementações comunitárias disponíveis

A implementação em Rust é a referência canônica. Os bindings em Python envolvem essa implementação, herdando suas características de desempenho.

Perguntas frequentes

Posso usar safetensors com modelos PyTorch existentes sem alterações no código?

Sim, se você estiver usando bibliotecas Hugging Face. Para modelos personalizados, é necessário substituir torch.load() para load_file() do safetensors e torch.save() para save_file()Os dados dos tensores e a arquitetura do modelo permanecem idênticos — apenas o formato de serialização muda. Converter checkpoints existentes é uma operação única que leva segundos.

Arquivos safetensors funcionam em diferentes versões do PyTorch?

Sim. Ao contrário dos arquivos pickle, que podem apresentar incompatibilidades entre versões do Python ou do PyTorch, o safetensors armazena dados binários brutos sem serialização específica de versão. Um arquivo safetensors criado com PyTorch 1.12 é carregado corretamente no PyTorch 2.x, e vice-versa. Isso torna o safetensors superior para arquivamento de longo prazo e distribuição de modelos.

Por que alguns modelos no Hugging Face Hub ainda são distribuídos como arquivos .bin?

Modelos mais antigos, enviados antes de 2023, podem conter apenas arquivos baseados em pickle. O Hugging Face está convertendo gradualmente o modelo hub, mas alguns modelos ainda permanecem exclusivamente em pickle caso o autor original não tenha disponibilizado versões em safetensors. Quando ambos os formatos estão presentes, o safetensors é preferido automaticamente. Você pode converter localmente usando o método mostrado na seção de conversão acima.

O safetensors aumenta o tamanho do arquivo em comparação com o .bin do PyTorch?

Não. Os tamanhos dos arquivos são tipicamente idênticos ou diferem em apenas 1–2%, pois ambos armazenam os mesmos dados brutos dos tensores. O safetensors adiciona sobrecarga mínima (um cabeçalho JSON de poucos quilobytes), enquanto o pickle acrescenta sobrecarga de serialização de objetos Python. Para um modelo de 7B, ambos os formatos geram arquivos de aproximadamente 13–14 GB. A diferença está na velocidade de carregamento e na segurança, não na eficiência de armazenamento.

Posso inspecionar arquivos safetensors sem carregar o modelo inteiro na memória?

Sim, essa é uma das principais vantagens do safetensors. Use safe_open() para ler os metadados e carregar seletivamente tensores específicos. É possível listar todos os nomes dos tensores, verificar suas dimensões e tipos de dados, e extrair camadas individuais sem carregar o arquivo inteiro, que pode ter vários gigabytes. Isso é particularmente útil para análise de modelos, depuração e extração de componentes.

GGUF e safetensors são a mesma coisa?

Não. GGUF (GPT-Generated Unified Format) é um formato diferente, usado principalmente pelo llama.cpp para inferência quantizada. O GGUF inclui esquemas de quantização otimizados para inferência em CPU, que o safetensors não suporta. O safetensors foi projetado para treinamento e distribuição geral de modelos, enquanto o GGUF é otimizado para inferência eficiente em hardware de consumo. Muitas ferramentas, como o Ollama, aceitam safetensors como entrada e convertem internamente para GGUF durante a inferência.