Formatul safetensors în Hugging Face Hub & Transformers

from safetensors.torch import save_file, load_file

save_file(tensors, "model.safetensors")
tensors = load_file("model.safetensors", device="cpu")

Ce face Formatul safetensors

Checkpoint-urile PyTorch clasice (.bin, .pt) folosesc pickle, care poate executa cod arbitrar la încărcarea unui fișier descărcat. safetensors a fost creat ca alternativă sigură: fișierul conține doar un antet JSON cu metadatele tensorilor și octeții de date.

Structura fișierului: primii 8 octeți sunt un întreg pe 64 de biți cu dimensiunea antetului, urmat de antetul JSON (pentru fiecare tensor: dtype, shape, data_offsets, plus un câmp opțional __metadata__), apoi datele. Formatul permite citirea unui singur tensor fără restul fișierului (lazy loading).

Despre viteză, documentația spune că încărcarea pe CPU este foarte rapidă față de pickle, iar pe GPU este cel puțin la fel de rapidă ca echivalentul PyTorch. Zero-copy real există doar pe CPU, când fișierul este deja în cache-ul sistemului; pe GPU o copie de pe disc este mereu necesară.

Sintaxă și opțiuni

Opțiune / Parametru	Descriere
save_file(tensors, cale)	Salvează un dicționar de tensori.
load_file(cale, device=...)	Încarcă toți tensorii pe dispozitivul dat.
safe_open(cale, framework="pt", device=...)	Deschide fișierul pentru citire parțială.
f.get_tensor(nume)	Citește un singur tensor.
__metadata__	Metadate libere în antet; doar perechi text-text.

Exemple practice

Exemplul 1: Salvare și încărcare

import torch
from safetensors.torch import save_file, load_file

tensors = {
    "weight1": torch.zeros((1024, 1024)),
    "weight2": torch.zeros((1024, 1024)),
}
save_file(tensors, "model.safetensors")
loaded = load_file("model.safetensors")

Exemplul 2: Un singur tensor dintr-un fișier mare

from safetensors import safe_open

with safe_open("model.safetensors", framework="pt", device="cpu") as f:
    strat = f.get_tensor("model.layers.0.self_attn.q_proj.weight")

Greșeli frecvente și bune practici

• Încarci fișiere .bin / .pt din surse necunoscute. Pickle poate rula cod; preferă variantele .safetensors.
• Presupui că safetensors copiază direct de pe disc în memoria GPU. Documentația spune că pe GPU o copie este mereu necesară.
• Pui valori non-text în __metadata__. Formatul acceptă doar perechi șir-șir.

Comenzi înrudite

• automodel-causal-lm
• hf-download
• peft-lora-qlora