SafeTensors Formatı: Güvenli ML Model Serileştirme Rehberi

Format ayrıca modern ML işlem hatlarına doğal olarak uyar çünkü çoğu checkpoint'in zaten içerdiğine odaklanır: 

• Tensörler
• Şekiller
• Veri tipleri
• Ağırlık değerleri

Genel amaçlı bir Python serileştirme sistemi gibi davranmak yerine, SafeTensors model parametreleri için özel bir saklama katmanı gibi davranır.

Her ne kadar Hugging Face SafeTensors'ı ekosistemi için ilk olarak geliştirmiş olsa da, formatın kendisi çerçeve bağımsızdır. Yakın zamanda (Nisan 2026'da) PyTorch Foundation'a katıldı ve PyTorch, TensorFlow, JAX, Flax, NumPy ve diğer ML çerçevelerini destekler.

Pickle Sorunu: Neden Yeni Bir Formata İhtiyaç Vardı

Python’un Pickle formatı, geliştiricilerin çoğu zaman tüm Python nesnelerini iç durumları, metodları ve yeniden kurma mantıklarıyla birlikte kaydedip geri yüklemeleri gereken genel Python uygulamaları için oluşturuldu.

Makine öğrenimi checkpoint'leri genellikle bu düzeyde bir saklamaya ihtiyaç duymaz. Çoğu model dosyası esas olarak tensörleri saklar: ağırlık matrisleri, gömmeler (embeddings), bias'lar ve diğer sayısal parametreler. Pratikte bu, checkpoint'in büyük ölçüde yapılandırılmış sayısal veriden oluştuğu anlamına gelir.

Ancak bir .pkl dosyası yalnızca veri saklamaktan fazlasını yapar. Yükleme sırasında Python'un nesneleri nasıl yeniden inşa edeceğine dair talimatlar da içerebilir. Bu da ayrıştırmanın pasif bir okuma işlemi olmadığı; kod çalıştırabileceği anlamına gelir. Ve eğer kod kötü amaçlı ise, bu ciddi bir güvenlik sorunu haline gelir. 

Pickle nasıl keyfi kod çalıştırılmasına olanak tanır

Python, pickle ayrıştırması sırasında nesneleri __reduce__() gibi özel metodlar kullanarak yeniden kurar. Sınıflar, bir nesnenin belleğe geri yüklendiğinde tam olarak nasıl kurulacağını pickle'a söylemek için bu metodu tanımlayabilir.

Örneğin, __reduce__() çağrılabilir bir fonksiyon ve bu fonksiyona ait argümanlar döndürebilir. Ayrıştırma sırasında Python, nesneyi yeniden kurmak için bu çağrılabilir fonksiyonu çalıştırır. Örnek kod:

import pickle
import os

class Demo:
    def __reduce__(self):
        return (os.system, ("echo 'Code executed during deserialization'",))

payload = pickle.dumps(Demo())

pickle.loads(payload)

pickle.loads() çalıştığında, Python __reduce__() tarafından döndürülen fonksiyonu yürütür. Bu örnekte, ayrıştırma os.system() aracılığıyla bir kabuk komutunu tetikler.

Sorun kabuk komutunun kendisi değildir. __reduce__() mantığa bağlı olarak keyfi argümanlarla herhangi bir çağrılabilir değeri döndürebilir. Bu da bir Pickle dosyasının başka fonksiyonlar çağırabileceği, dosya indirebileceği, ortamı değiştirebileceği veya yükleme sırasında kötü amaçlı kod çalıştırabileceği anlamına gelir. Bu yüzden Python dokümantasyonu, güvenilmeyen kaynaklardan pickle verisi yüklemeye karşı açıkça uyarır.

Model paylaşım çağında risk

Hugging Face Hub gibi platformlar artık araştırmacılar, girişimler, meraklılar ve anonim katkıcılar tarafından paylaşılan bir milyondan fazla modele ev sahipliği yapıyor. Ekosistem, geliştiriciler modelleri anında indirip test edebildiği için hızlı ilerliyor. Ancak yüklenen checkpoint'lerin çoğu, dağıtımdan önce tek tek denetlenmiyor.

Birçok PyTorch checkpoint'i hâlâ .pt veya .bin gibi formatlar üzerinden pickle tabanlı serileştirmeye dayanıyor. Birisi bu dosyalardan birini yüklediğinde, Python checkpoint'in içine gömülü ayrıştırma mantığını çalıştırabilir. Checkpoint kötü amaçlıysa, bu mantık kimlik bilgilerini çalabilir, ortam değişkenlerini okuyabilir, yüklemeler indirebilir veya yükleme sırasında uzaktan kod çalıştırabilir.

SafeTensors tam olarak bu sorunu çözmek için geliştirildi. Keyfi Python nesnelerini serileştirmek yerine yalnızca tensör verilerini ve bu tensörleri doğru şekilde yüklemek için gereken metaveriyi saklar. Bir .safetensors dosyasını yüklemek, Python yeniden kurma mantığının çalıştırılmasını gerektirmez ve bu da saldırı yüzeyini önemli ölçüde azaltır.

SafeTensors Formatı Nasıl Çalışır

Artık SafeTensors'ın ne olduğunu ve neden var olduğunu bildiğimize göre, yapısına ve nasıl çalıştığına bakalım.

Başlık-veri yapısı

Bir SafeTensors dosyası iki bölümden oluşur: bir JSON başlığı ve ardından ham tensör verileri.

Bu başlık her tensör için aşağıdaki metaverileri saklar: 

• Tensör adları
• Şekiller
• Veri tipleri
• Bayt ofsetleri

Başlığın ardından, dosya ham tensör baytlarını ardışık şekilde saklar.

Başlık, bir içindekiler tablosu gibi çalışır. Yükleyiciye hangi tensörlerin bulunduğunu ve dosyada nerede konumlandıklarını söyler; tıpkı bir veritabanı indeksinin saklanan kayıtlara işaret etmesi gibi. SafeTensors, aşırı büyük metaveri yüklerini önlemek için bu başlık boyutunu 100 MB ile sınırlar.

Sıfır kopya ve bellek eşlemeli yükleme

SafeTensors, bellek eşlemeli yükleme sayesinde yükleme hızını artırır. Ayrıştırma sırasında Python nesnelerini yeniden inşa etmek yerine, çerçeveler tensör verilerini diskteki konumundan doğrudan belleğe eşleyebilir. Bu, gereksiz bellek kopyalarını azaltır ve yükleme sırasında CPU yükünü düşürür.

Şu kaynağa göre Hugging Face karşılaştırmaları, SafeTensors ağırlıkları CPU üzerinde PyTorch'a kıyasla yaklaşık 76 kat, GPU iş yüklerinde ise yaklaşık 2 kat daha hızlı yükledi. Elbette tam hızlanma hâlâ donanıma ve checkpoint boyutuna bağlıdır, ancak Python ayrıştırmasından kaçınmak yükleme performansını tutarlı şekilde iyileştirir.

Tembel yükleme ve kısmi ayrıştırma

SafeTensors, tüm checkpoint'i bir kerede belleğe okumak yerine belirli tensörleri adlarına göre yükler.

Bu, birden fazla GPU üzerinde çalışan büyük dağıtık modellerde kullanışlıdır. Örneğin BLOOM’un 176B parametreli modeli. Standart PyTorch checkpoint'lerinde, sistem öncelikle tam model ağırlıklarını aygıtlar arasında bölmeden önce ayrıştırmak zorundaydı ve bu işlem yaklaşık 10 dakika sürüyordu. 

SafeTensors ile her GPU yalnızca gerçekten ihtiyaç duyduğu tensör parçalarını (shard) yükledi. Bu, 8 GPU arasında model başlangıç süresini yaklaşık 45 saniyeye düşürdü.

SafeTensors ve Diğer Serileştirme Formatları

SafeTensors, model ağırlıklarını güvenli ve verimli şekilde saklama ve yükleme için iyi çalışır; ancak bu, her formatın yerine geçecek evrensel bir çözüm olduğu anlamına gelmez. Doğru seçim, neyi sakladığınıza ve modelin hattın neresinde bulunduğuna bağlıdır.

Pickle hakkında yeterince konuştuk, bu yüzden farklı formatlara odaklanacağım.

SafeTensors vs GGUF

SafeTensors ve GGUF farklı sorunları çözer. 

GGML Unified Format'ın kısaltması olan GGUF, llama.cpp gibi çalışma zamanlarında niceleştirilmiş (quantized) çıkarım iş yükleri için geliştirildi. Format, özellikle CPU çıkarımı ve uç cihazlar için sıkıştırılmış modellerin verimli dağıtımına odaklanır. 

SafeTensors ise hattın daha erken bir aşamasında yer alır. Çoğu SafeTensors checkpoint'i, eğitim, ince ayar, birleştirme veya dağıtık çıkarım iş akışlarında kullanılan tam hassasiyetli veya eğitime hazır tensörleri saklar. Format; güvenli yüklemeye, PyTorch gibi çerçevelerle uyumluluğa ve eğitim ile sunum sırasında verimli tensör erişimine öncelik verir.

Birbirleriyle doğrudan rekabet etmek yerine birbirlerini tamamlayabilirler. Örnek iş akışı: 

• Modeli PyTorch ve SafeTensors checkpoint'leriyle eğitin veya ince ayar yapın
• Nihai modeli niceleştirin
• Dağıtım için llama.cpp veya uç çıkarım çalışma zamanlarına GGUF olarak dışa aktarın

SafeTensors vs ONNX

SafeTensors, model ağırlıklarını güvenle saklamaya ve PyTorch gibi çerçeveler içinde verimli şekilde yüklemeye odaklanır. Yalnızca tensörleri ve metaveriyi saklar; bu da onu checkpoint paylaşımı, ince ayar ve eğitim iş akışları için hafif ve hızlı kılar.

ONNX daha geniş bir yaklaşım benimser. Model parametreleriyle birlikte tam hesaplama grafiğini de saklar. Bu, bir modeli bir çerçeveden dışa aktarırken tamamen başka bir yerde çalıştırmak istediğinizde ONNX'i kullanışlı kılar.

Örneğin, PyTorch kullanarak LLM'leri eğiten ve ince ayar yapan ekipler genellikle SafeTensors checkpoint'lerini tercih eder çünkü hızlı yüklenir ve mevcut iş akışlarına doğrudan entegre olur. Ancak aynı ekip modeli TensorRT, ONNX Runtime veya bir uç çıkarım motorunda dağıtmak isterse, modeli ONNX'e aktarmak daha mantıklıdır.

SafeTensors'ı Pratikte Kullanma

SafeTensors'ın PyTorch ekosistemi genelinde hızlı yayılmasının bir nedeni de API'nin tanıdık gelmesidir. Hâlâ durum sözlükleri (state dict) ve tensörlerle normalde olduğu gibi çalışırsınız.

Tensörleri kaydetme ve yükleme

Temel iş akışı, standart PyTorch checkpoint işlemlerine birebir benzer. İşte örnek:

import torch
from safetensors.torch import save_file, load_file

tensors = {
    "weights": torch.randn(2, 2),
    "bias": torch.zeros(2)
}

save_file(tensors, "model.safetensors")

loaded_tensors = load_file("model.safetensors")

print(loaded_tensors["weights"])

save_file(), tensörleri .safetensors formatına yazar; load_file() ise onları belleğe geri yükler.

SafeTensors, yalnızca birkaç tensöre ihtiyaç duyduğunuz büyük checkpoint'lerde kullanışlı hale gelen safe_open() üzerinden seçmeli yüklemeyi de destekler.

from safetensors import safe_open

with safe_open("model.safetensors", framework="pt") as f:
    weights = f.get_tensor("weights")

print(weights)

Tüm checkpoint'i yüklemek yerine, get_tensor() yalnızca talep ettiğiniz tensörü okur.

Mevcut modelleri safetensors'a dönüştürme

Standart desen şudur:

1. Mevcut modeli yükleyin
2. Durum sözlüğünü çıkarın
3. save_file() ile kaydedin

from transformers import AutoModel
from safetensors.torch import save_file

model = AutoModel.from_pretrained("bert-base-uncased")

save_file(model.state_dict(), "model.safetensors")

state_dict(), model ağırlıklarını tensörler olarak döndürür ve SafeTensors bunları doğrudan saklayabilir. 

Model zaten Hugging Face Hub'da bulunuyorsa, yerel dönüştürme koduna bile ihtiyaç duymayabilirsiniz. Hugging Face, Hub arayüzü üzerinden barındırılan modeller için yerleşik checkpoint dönüştürme desteği sağlar.

Serileştirme Formatları: Karşılaştırma Tablosu

2026'da SafeTensors: PyTorch Foundation ve Sırada Ne Var

Nisan 2026'da, Hugging Face SafeTensors'ı Linux Foundation çatısı altındaki PyTorch Foundation'a bağışladı. Proje artık PyTorch, vLLM, DeepSpeed ve Ray ile birlikte vakıf yönetişimi altında yer alıyor.

Bu hamle, SafeTensors'ın artık yalnızca bir Hugging Face projesi olmadığını gösteriyor. ML ekosistemi için paylaşılan bir altyapıya dönüşüyor. 

Duyuru, formatın bir sonraki adımlarına da değiniyor.

Cihaza duyarlı yükleme

Önemli odak alanlarından biri cihaza duyarlı yüklemedir. Bugün pek çok iş akışı, tensörleri CUDA veya ROCm aygıtlarına aktarmadan önce hâlâ CPU belleğine yüklüyor. Bu ekstra ara aşama, özellikle büyük dağıtık sistemlerde başlangıç gecikmesini artırıyor. 

SafeTensors geliştiricileri, gereksiz CPU kopyalarını azaltan ve tensörleri doğrudan hızlandırıcılara taşıyan doğrudan cihaza yükleme yolları üzerinde çalışıyor. 

Dağıtık yükleme

Dağıtık yükleme desteği de gelişiyor. Modern çıkarım sistemleri artık modelleri nadiren tek bir GPU'da çalıştırıyor. Tensör paralelliği ve boru hattı paralelliği büyük modeller için standart dağıtım desenleri haline geldi, ancak çerçeveler genelinde checkpoint yükleme API'leri hâlâ parçalı durumda. 

SafeTensors, parçaya duyarlı yükleme ve dağıtık tensör yerleşimlerine desteği genişletiyor; böylece çerçeveler aygıtlar arasında checkpoint yüklemeyi daha verimli şekilde koordine edebiliyor. 

Modern niceleme iş akışları

Format, daha yeni niceleme iş akışlarına da uyum sağlıyor. Çıkarım sistemleri, bellek kullanımını azaltmak ve sunum maliyetlerini düşürmek için giderek daha fazla FP8, GPTQ ve AWQ formatlarına dayanıyor. 

Çerçeveleri bunları özel serileştirme mantıklarıyla ele almaya zorlamak yerine, SafeTensors daha düşük hassasiyetli ve blok nicelemeli tensör formatlarına yönelik resmi desteği doğrudan formatın kendisine ekliyor. 

Şu anda, geliştiricilerin kaydetme ve yükleme iş akışları arasında geçiş yaparak SafeTensors'a manuel olarak dahil olmaları gerekiyor. Ancak PyTorch'un yerel serileştirme sistemiyle daha derin entegrasyon üzerinde çalışmalar sürüyor. Bu nihayet hayata geçerse, SafeTensors alternatif bir checkpoint formatı olmaktan çıkıp PyTorch'un modelleri saklamasının varsayılan yolu haline gelebilir.

Son Düşünceler

Yıllarca, geliştiriciler yükleme sırasında keyfi Python kodu çalıştırabilen serileştirme sistemleriyle model checkpoint'lerini paylaştı. Halka açık model hub'ları milyonlarca checkpoint'e ev sahipliği yapmaya başlayınca, güvenlik risklerini görmezden gelmek çok daha zorlaştı.

SafeTensors, formatın kapsamını daraltarak bunu değiştirdi. Tüm Python nesnelerini serileştirmeye çalışmak yerine yalnızca tensörleri ve onları yüklemek için gereken metaveriyi saklamaya odaklanır. Bu daha basit tasarım, pickle tabanlı checkpoint'lerle gelen ayrıştırma risklerini ortadan kaldırırken aynı zamanda yükleme hızını ve bellek verimliliğini de artırır.

Dolayısıyla yalnızca model ağırlıklarına ihtiyacınız olduğunda, ayrıştırma sırasında keyfi kod çalıştırmanın bir anlamı yoktur; bu gibi durumlarda SafeTensors kullanmak daha iyidir.

Modern ML araçları, model formatları ve Hugging Face iş akışlarıyla daha derin çalışmak isteyenler için Python ile Derin Öğrenme ve Hugging Face ile Çalışmak kurslarımız iyi bir sonraki adımdır. Bugünün yapay zekâ ekosisteminde kullanılan araçlarla modelleri eğitme, ince ayar yapma ve dağıtma için pratik iş akışlarını kapsarlar.