Safetensors: Ein schnelles und sicheres Format zur Speicherung von Modellgewichten

Safetensors ist ein binäres Dateiformat zum Speichern und Laden von Gewichten maschineller Lernmodelle, das von Hugging Face entwickelt wurde. Es behebt kritische Sicherheitslücken bei pickle-basierten Formaten (PyTorch-Dateien mit den Endungen .bin oder .pt), indem es eine einfache, statisch analysierbare Struktur verwendet, die während der Deserialisierung keinen beliebigen Code ausführen kann. Dank Memory Mapping und Zero-Copy-Operationen erreicht das Format deutlich kürzere Ladezeiten und ist daher 2026 das bevorzugte Format für die Verteilung und das Laden von KI-Modellen.

Was ist Safetensors?

Safetensors speichert Tensoren (mehrdimensionale Zahlenfelder, die neuronale Netzwerk-Gewichte repräsentieren) in einem rein binären Format mit einem JSON-Header. Im Gegensatz zu den historisch in PyTorch verwendeten pickle-basierten Formaten enthält Safetensors ausschließlich rohe Tensor-Daten und Metadaten – keinen Python-Code, keine Klassendefinitionen und keine ausführbaren Anweisungen.

Die Dateistruktur besteht aus:

• Einem 8-Byte-Header, der die Länge der Metadaten enthält
• Einem JSON-Metadatenabschnitt, der Namen, Formen, Datentypen und Byte-Offsets der Tensoren beschreibt
• Rohdaten der Tensoren, die kontinuierlich in speicherausgerichteten Blöcken gespeichert sind

Diese Einfachheit ermöglicht das Memory-Mapped-Laden: Das Betriebssystem mappt die Datei direkt in den Arbeitsspeicher des Prozesses, sodass auf die Tensor-Daten sofort zugegriffen werden kann, ohne mehrere Gigabyte in den RAM kopieren zu müssen. Wenn Sie ein Modell mit 7 Milliarden Parametern im Safetensors-Format laden, beträgt die Ladezeit Millisekunden statt Sekunden.

Warum wurde Safetensors entwickelt?

Das Python-Pickle-Format, das standardmäßig von PyTorchs torch.save() und torch.load()verwendet wird, kann während der Deserialisierung beliebigen Python-Code ausführen. Ein Angreifer kann eine manipulierte .bin- oder .pt-Datei erstellen, die Schadsoftware ausführt, sobald Sie torch.load()aufrufen. Diese Schwachstelle ist keine theoretische Annahme – mehrere Vorfälle haben bereits die Verwendung manipulierter Modell-Dateien in der Praxis belegt.

Neben der Sicherheit weisen pickle-basierte Formate auch Leistungsprobleme auf:

Beim Laden einer Pickle-Datei muss Python die gesamte Struktur in den Arbeitsspeicher deserialisieren, Python-Objekte rekonstruieren und anschließend die Tensor-Daten in das native Format des jeweiligen Frameworks kopieren. Safetensors eliminiert diese Schritte, indem es die binären Tensor-Daten direkt abbildet.

Installation und Verwendung von Safetensors

Installieren Sie die Python-Bibliothek:

pip install safetensors

Laden von Safetensors-Dateien

Nutzen Sie safe_open() für memory-mapped Lazy Loading:

from safetensors import safe_open

with safe_open("model.safetensors", framework="pt", device="cpu") as f:
    # Liste der Tensor-Namen abrufen
    tensor_names = f.keys()
    
    # Spezifischen Tensor laden (lazy – nur dieser Tensor wird geladen)
    embedding_weights = f.get_tensor("model.embed_tokens.weight")
    
    # Tensor-Metadaten ohne Laden abrufen
    metadata = f.metadata()

Der framework gibt das Ziel-Framework an: "pt" für PyTorch, "tf" für TensorFlow, "np" für NumPy oder "jax" für JAX. Der device -Parameter steuert, wo Tensoren gespeichert werden: "cpu", "cuda:0", oder andere Gerätebezeichner.

Um alle Tensoren auf einmal zu laden:

from safetensors.torch import load_file

tensors = load_file("model.safetensors")
# Gibt ein Dictionary zurück: {"layer.weight": tensor, "layer.bias": tensor, ...}

Safetensors-Dateien speichern

Ein Dictionary aus Tensoren speichern:

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")

Benutzerdefinierte Metadaten einfügen:

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

Modelle von Hugging Face laden

Die Bibliothek von Hugging Face transformers nutzt Safetensors automatisch, sobald sie verfügbar ist:

from transformers import AutoModel

# Lädt und lädt .safetensors automatisch herunter, falls verfügbar
model = AutoModel.from_pretrained("bert-base-uncased")

Safetensors-Format erzwingen:

model = AutoModel.from_pretrained(
    "bert-base-uncased",
    use_safetensors=True  # Scheitert, falls Safetensors nicht verfügbar ist
)

Die meisten Modelle auf dem Hugging Face Hub enthalten mittlerweile sowohl model.safetensors und als auch pytorch_model.bin

Konvertierung zwischen Formaten

PyTorch .bin in Safetensors konvertieren

from safetensors.torch import save_file
import torch

# PyTorch-Checkpoint laden
state_dict = torch.load("pytorch_model.bin", map_location="cpu")

# Als Safetensors speichern
save_file(state_dict, "model.safetensors")

Safetensors in PyTorch .bin konvertieren

from safetensors.torch import load_file
import torch

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

Konvertierungsskript von Hugging Face

Der transformers Bibliothek enthält ein Konvertierungstool:

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

Technische Details zum Dateiformat

Eine Safetensors-Datei hat folgende Struktur:

1. Header (8 Bytes): Kleiner Endian, vorzeichenlose 64-Bit-Ganzzahl mit der Länge der JSON-Metadaten in Bytes
2. Metadaten (variabel): JSON-Objekt mit folgendem Schema:

   {
     "layer_name": {
       "dtype": "F32",  // Datentyp: F32, F16, BF16, I64, I32 usw.
       "shape": [768, 768],  // Tensor-Dimensionen
       "data_offsets": [0, 2359296]  // Start- und Endbyte im Datenabschnitt
     },
     "__metadata__": {  // Optionale benutzerdefinierte Metadaten
       "key": "value"
     }
   }

3. Datenabschnitt: Rohe Tensor-Bytes, gespeichert in C-kontinuierlicher Reihenfolge (zeilenweise), ausgerichtet an 8-Byte-Grenzen

Das Format unterstützt folgende Datentypen: F64, F32, F16, BF16, I64, U64, I32, U32, I16, U16, I8, U8, BOOL. Der Byte-Bereich jedes Tensors wird in den Metadaten angegeben, wodurch eine selektive Ladung ohne vollständiges Parsen der Datei möglich ist.

Unterstützung im Ökosystem

Safetensors wird im gesamten KI-Ökosystem unterstützt:

Wenn Sie prüfen, ob ein Modell in den GPU-Speicher passt, verwenden Sie die VRAM-Rechner zur Abschätzung des Speicherbedarfs anhand der Parameteranzahl und des Quantisierungsgrads. Das Dateiformat selbst beeinflusst den VRAM-Verbrauch nicht – Safetensors- und Pickle-Dateien desselben Modells beanspruchen nach dem Laden identischen GPU-Speicher.

Leistungsmerkmale

Benchmark-Ergebnisse auf einem System mit NVMe-SSD und 64 GB RAM beim Laden eines Modells mit 7 Milliarden Parametern:

Der Lazy-Loading-Ansatz mit safe_open() ist besonders wertvoll, wenn Sie die Modellarchitektur untersuchen, bestimmte Layer extrahieren oder Modelle laden müssen, die den verfügbaren Arbeitsspeicher überschreiten – indem Sie Tensoren gezielt laden.

Für quantisierte Modelle unterstützt Safetensors alle gängigen Datentypen, darunter FP16, BF16, INT8 und INT4. Die Datenbank für KI-Modelle enthält Safetensors-Dateigrößen und VRAM-Anforderungen für 37 beliebte Modelle bei verschiedenen Quantisierungsstufen.

Sharded-Modelle

Modelle mit mehreren Gigabyte Größe werden häufig als mehrere Safetensors-Dateien (Sharding) verteilt. Ein Modell mit 70 Milliarden Parametern könnte beispielsweise in acht Shards aufgeteilt sein:

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

Die Indexdatei ordnet Tensornamen den Shard-Dateien zu:

{
  "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"
  }
}

Hugging-Face-Bibliotheken übernehmen das Laden von Shards automatisch. Für manuelles Laden:

import json
from safetensors import safe_open

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

weight_map = index["weight_map"]

# Laden eines bestimmten Tensors durch Nachschlagen seiner Shard-Datei
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)

Sprachbindungen

Obwohl die Referenzimplementierung in Python vorliegt, bietet Safetensors Bindings für mehrere Programmiersprachen:

• Rust: Kernimplementierung in Rust für Leistung und Sicherheit
• Python: Offizielle Bindings über PyPI
• JavaScript/Node.js: @huggingface/safetensors npm-Paket
• C/C++: Verfügbar über FFI an die Rust-Bibliothek
• Go: Community-Implementierungen verfügbar

Die Rust-Implementierung ist die maßgebliche Referenz. Die Python-Bindings umschließen diese Implementierung und erben deren Leistungsmerkmale.

Häufig gestellte Fragen

Kann ich Safetensors mit bestehenden PyTorch-Modellen ohne Codeänderungen verwenden?

Ja, sofern Sie Hugging-Face-Bibliotheken nutzen. Für benutzerdefinierte Modelle müssen Sie torch.load() auf load_file() aus Safetensors und torch.save() auf save_file()ersetzen. Die Tensordaten und die Modellarchitektur bleiben unverändert – lediglich das Serialisierungsformat wechselt. Die Konvertierung bestehender Checkpoints ist ein einmaliger Vorgang, der nur Sekunden dauert.

Funktionieren Safetensors-Dateien mit unterschiedlichen PyTorch-Versionen?

Ja. Im Gegensatz zu Pickle-Dateien, die bei Änderungen der Python- oder PyTorch-Version brechen können, speichert Safetensors rohe Binärdaten ohne versionsabhängige Serialisierung. Eine Safetensors-Datei, die mit PyTorch 1.12 erstellt wurde, lässt sich korrekt in PyTorch 2.x laden – und umgekehrt. Damit eignet sich Safetensors hervorragend für langfristige Modellarchivierung und -verteilung.

Warum werden einige Modelle auf dem Hugging Face Hub noch immer als .bin-Dateien verteilt?

Ältere Modelle, die vor 2023 hochgeladen wurden, enthalten möglicherweise ausschließlich pickle-basierte Dateien. Hugging Face konvertiert den Modell-Hub schrittweise, doch einige Modelle bleiben weiterhin ausschließlich in Pickle-Form, falls der ursprüngliche Uploader keine Safetensors-Version bereitgestellt hat. Wenn beide Formate vorhanden sind, wird Safetensors automatisch bevorzugt. Lokal können Sie mithilfe der oben im Abschnitt „Konvertierung“ beschriebenen Methode konvertieren.

Erhöht Safetensors die Dateigröße im Vergleich zu PyTorch .bin?

Nein. Die Dateigrößen sind typischerweise identisch oder weichen um nur 1–2 % voneinander ab, da beide Formate dieselben rohen Tensordaten speichern. Safetensors fügt nur minimale Overhead-Kosten hinzu (einen JSON-Header von wenigen Kilobyte), während Pickle Overhead durch die Serialisierung von Python-Objekten verursacht. Bei einem 7B-Modell ergeben beide Formate Dateigrößen von etwa 13–14 GB. Der Unterschied liegt in Geschwindigkeit und Sicherheit beim Laden – nicht in der Speichereffizienz.

Kann ich Safetensors-Dateien untersuchen, ohne das gesamte Modell in den Arbeitsspeicher zu laden?

Ja, dies ist einer der zentralen Vorteile von Safetensors. Verwenden Sie safe_open() um Metadaten zu lesen und gezielt bestimmte Tensoren zu laden. Sie können sämtliche Tensornamen auflisten, deren Dimensionen und Datentypen prüfen sowie einzelne Layer extrahieren – ohne die gesamte mehrere Gigabyte große Datei in den Arbeitsspeicher zu laden. Dies ist besonders nützlich für Modellanalyse, Debugging und Extraktion einzelner Komponenten.

Sind GGUF und Safetensors dasselbe?

Nein. GGUF (GPT-Generated Unified Format) ist ein anderes Format, das vorrangig von llama.cpp für quantisierte Inferenz verwendet wird. GGUF enthält Quantisierungsschemata, die speziell für CPU-Inferenz optimiert sind und die Safetensors nicht unterstützt. Safetensors ist für Training und allgemeine Modellverteilung konzipiert, während GGUF für effiziente Inferenz auf Consumer-Hardware optimiert ist. Viele Tools wie Ollama akzeptieren Safetensors als Eingabe und konvertieren intern nach GGUF für die Inferenz.