SafeTensors Format Guide

Specification

SafeTensors es un formato de archivo binario desarrollado por Hugging Face para almacenar y cargar pesos de modelos de machine learning de forma segura. Introducido en 2023 como una alternativa segura a los formatos basados en pickle de Python (archivos .bin, .pt de PyTorch), SafeTensors elimina la vulnerabilidad de ejecución de código arbitrario inherente en la deserialización de pickle. Cuando cargas un archivo de modelo basado en pickle, código Python arbitrario incrustado en el archivo se ejecuta automáticamente — un riesgo de seguridad serio al cargar modelos de fuentes no confiables. SafeTensors almacena solo datos de tensores y metadatos, haciendo imposible incrustar código ejecutable.

El formato SafeTensors usa una estructura simple: un tamaño de encabezado de 8 bytes (uint64 little-endian), un encabezado JSON que contiene metadatos de tensores (nombres, tipos de datos, formas y offsets en bytes), seguido de datos de tensores crudos. El formato soporta todos los tipos numéricos comunes incluyendo float32, float16, bfloat16, int8, int32 e int64. Los tensores se almacenan de forma contigua en memoria, permitiendo carga con cero copias a través de mapeo de memoria — los datos de tensores pueden accederse directamente desde disco sin copiarlos a un buffer de memoria separado.

SafeTensors ha sido adoptado como el formato de modelo predeterminado en Hugging Face Hub, con conversión automática disponible para la mayoría de los repositorios de modelos. Los principales frameworks de ML incluyendo PyTorch, TensorFlow, JAX y ONNX Runtime soportan la carga de archivos SafeTensors. El formato también soporta almacenamiento fragmentado, donde los pesos de un solo modelo se dividen entre múltiples archivos con un archivo índice que mapea nombres de tensores a sus fragmentos respectivos — esencial para modelos demasiado grandes para caber en un solo archivo.

When to Use SafeTensors

SafeTensors debería ser tu formato predeterminado para almacenar y distribuir pesos de modelo durante el desarrollo y para inferencia basada en GPU. Es el formato estándar en Hugging Face Hub y es soportado por todos los principales frameworks de entrenamiento e inferencia. Usa SafeTensors siempre que guardes checkpoints de entrenamiento, compartas modelos con colaboradores, subas modelos a registros de modelos, o despliegues modelos con servidores de inferencia GPU como vLLM, TGI o Triton.

Elige SafeTensors sobre los formatos basados en pickle de PyTorch (.bin, .pt) por seguridad — SafeTensors no puede contener código ejecutable, eliminando el riesgo de ataques a la cadena de suministro a través de archivos de modelo maliciosos. Elige SafeTensors sobre GGUF cuando necesites pesos de precisión completa para entrenamiento continuo o inferencia acelerada por GPU, ya que GGUF está diseñado para inferencia cuantizada en CPU. SafeTensors se carga significativamente más rápido que los archivos pickle debido al mapeo de memoria y la ausencia de sobrecarga de deserialización.

SafeTensors es menos adecuado cuando tu objetivo de despliegue es inferencia local basada en CPU (usa GGUF en su lugar) o cuando necesitas portabilidad entre frameworks con optimización de runtime (considera ONNX). Tampoco es la opción correcta para modelos muy pequeños donde la sobrecarga del formato es proporcionalmente grande, aunque en la práctica esto rara vez es una preocupación.

Schema / Structure

{
  "__metadata__": {
    "format": "pt"
  },
  "model.embed_tokens.weight": {
    "dtype": "F16",
    "shape": [32000, 4096],
    "data_offsets": [0, 262144000]
  },
  "model.layers.0.self_attn.q_proj.weight": {
    "dtype": "F16",
    "shape": [4096, 4096],
    "data_offsets": [262144000, 295698432]
  },
  "model.layers.0.self_attn.k_proj.weight": {
    "dtype": "F16",
    "shape": [4096, 4096],
    "data_offsets": [295698432, 329252864]
  }
}

Example Data

from safetensors.torch import save_file, load_file
import torch

# Save model weights to SafeTensors
tensors = {
    "model.embed_tokens.weight": torch.randn(32000, 4096, dtype=torch.float16),
    "model.layers.0.self_attn.q_proj.weight": torch.randn(4096, 4096, dtype=torch.float16),
    "model.layers.0.self_attn.v_proj.weight": torch.randn(4096, 4096, dtype=torch.float16),
    "lm_head.weight": torch.randn(32000, 4096, dtype=torch.float16),
}
metadata = {"format": "pt", "model_type": "llama"}
save_file(tensors, "model.safetensors", metadata=metadata)

# Load weights (zero-copy with memory mapping)
loaded = load_file("model.safetensors", device="cuda:0")
print(loaded["model.embed_tokens.weight"].shape)  # torch.Size([32000, 4096])

# Load a Hugging Face model using SafeTensors
from transformers import AutoModelForCausalLM
model = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Llama-3-8B",
    torch_dtype=torch.float16,
    use_safetensors=True  # default on HF Hub
)