Format SafeTensors: Panduan Serialisasi Model ML yang Aman

Format ini juga pas secara alami dengan pipeline ML modern karena berfokus pada apa yang sudah dimiliki sebagian besar checkpoint: 

• Tensor
• Bentuk (shape)
• Jenis data (datatype)
• Nilai bobot

Alih-alih bertindak seperti sistem serialisasi Python serbaguna, SafeTensors bertindak seperti lapisan penyimpanan khusus untuk parameter model.

Meskipun Hugging Face awalnya mengembangkan SafeTensors untuk ekosistemnya, format itu sendiri bersifat agnostik kerangka kerja. Format ini baru-baru ini bergabung dengan PyTorch Foundation (pada April 2026) dan mendukung PyTorch, TensorFlow, JAX, Flax, NumPy, dan kerangka ML lainnya.

Masalah Pickle: Mengapa Diperlukan Format Baru

Format Pickle Python dibuat untuk aplikasi Python umum, di mana pengembang sering kali perlu menyimpan dan memulihkan seluruh objek Python beserta status internal, metode, dan logika rekonstruksinya.

Checkpoint machine learning biasanya tidak memerlukan tingkat penyimpanan tersebut. Sebagian besar berkas model terutama menyimpan tensor: matriks bobot, embedding, bias, dan parameter numerik lainnya. Dalam praktiknya, itu berarti checkpoint sebagian besar hanyalah data numerik terstruktur.

Namun berkas .pkl melakukan lebih dari sekadar menyimpan data. Berkas ini juga dapat berisi instruksi untuk Python tentang cara membangun kembali objek saat pemuatan. Artinya, deserialisasi bukan operasi baca pasif; proses ini dapat mengeksekusi kode. Dan jika kodenya berbahaya, itu menjadi masalah keamanan serius. 

Bagaimana pickle memungkinkan eksekusi kode sewenang-wenang

Python membangun kembali objek selama deserialisasi pickle menggunakan metode khusus seperti __reduce__(). Kelas dapat mendefinisikan metode ini untuk memberi tahu pickle secara tepat bagaimana objek harus dibangun kembali saat dimuat kembali ke memori.

Sebagai contoh, __reduce__() dapat mengembalikan fungsi yang dapat dipanggil beserta argumennya. Selama deserialisasi, Python mengeksekusi fungsi tersebut untuk merekonstruksi objek. Contoh kode:

import pickle
import os

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

payload = pickle.dumps(Demo())

pickle.loads(payload)

Saat pickle.loads() dijalankan, Python mengeksekusi fungsi yang dikembalikan oleh __reduce__(). Dalam contoh ini, deserialisasi memicu perintah shell melalui os.system().

Masalahnya bukan perintah shell itu sendiri. __reduce__() dapat mengembalikan fungsi apa pun dengan argumen sewenang-wenang sesuai logika. Artinya, berkas Pickle dapat memanggil fungsi lain, mengunduh berkas, memodifikasi lingkungan, atau mengeksekusi kode berbahaya saat pemuatan. Itulah sebabnya dokumentasi Python secara eksplisit memperingatkan agar tidak memuat data pickle dari sumber yang tidak tepercaya.

Risikonya di era berbagi model

Platform seperti Hugging Face Hub kini menampung lebih dari satu juta model yang dibagikan oleh peneliti, startup, penghobi, dan kontributor anonim. Ekosistem bergerak cepat karena pengembang dapat mengunduh dan menguji model secara instan. Namun sebagian besar checkpoint yang diunggah tidak diaudit satu per satu sebelum didistribusikan.

Banyak checkpoint PyTorch masih mengandalkan serialisasi berbasis pickle melalui format seperti .pt atau .bin. Saat seseorang memuat salah satu berkas tersebut, Python dapat mengeksekusi logika deserialisasi yang tertanam di dalam checkpoint. Jika checkpoint itu berbahaya, logika tersebut dapat mencuri kredensial, membaca variabel lingkungan, mengunduh payload, atau mengeksekusi kode jarak jauh saat pemuatan.

Inilah tepatnya masalah yang ingin dipecahkan oleh SafeTensors. Alih-alih menserialisasi objek Python sewenang-wenang, format ini hanya menyimpan data tensor dan metadata yang dibutuhkan untuk memuat tensor tersebut dengan benar. Memuat berkas .safetensors tidak memerlukan eksekusi logika rekonstruksi Python, yang secara signifikan mengurangi permukaan serangan.

Cara Kerja Format SafeTensors

Sekarang setelah kita tahu apa itu SafeTensors dan mengapa format ini ada, mari lihat strukturnya dan bagaimana cara kerjanya.

Struktur header-data

Berkas SafeTensors memiliki dua bagian: header JSON yang diikuti oleh data tensor mentah.

Bagian header menyimpan metadata untuk setiap tensor, termasuk 

• Nama tensor
• Bentuk (shape)
• Jenis data (datatype)
• Offset byte

Setelah header, berkas menyimpan byte tensor mentah secara berurutan.

Header berfungsi seperti daftar isi. Header memberi tahu pemuat tensor mana yang ada dan di mana lokasinya dalam berkas, mirip dengan cara indeks basis data menunjuk ke rekaman yang disimpan. SafeTensors membatasi ukuran header ini hingga 100MB untuk mencegah payload metadata yang berukuran berlebihan.

Pemuatan zero-copy dan memory-mapped

SafeTensors meningkatkan kecepatan pemuatan melalui pemuatan yang dipetakan ke memori (memory-mapped). Alih-alih membangun kembali objek Python saat deserialisasi, kerangka kerja dapat memetakan data tensor langsung dari disk ke memori. Hal itu mengurangi penyalinan memori yang tidak perlu dan menurunkan beban CPU selama pemuatan.

Menurut tolok ukur Hugging Face, SafeTensors memuat bobot sekitar 76x lebih cepat daripada PyTorch di CPU dan sekitar 2x lebih cepat pada beban kerja GPU. Tentu saja, percepatan tepatnya masih bergantung pada perangkat keras dan ukuran checkpoint, tetapi menghindari deserialisasi Python secara konsisten meningkatkan performa pemuatan.

Pemuatan malas dan deserialisasi parsial

SafeTensors memuat tensor tertentu berdasarkan nama alih-alih membaca seluruh checkpoint ke memori sekaligus.

Hal itu berguna untuk model terdistribusi besar yang berjalan di beberapa GPU. Ambil contoh model 176B parameter BLOOM. Dengan checkpoint PyTorch standar, sistem pertama-tama harus mendeserialisasi bobot model penuh sebelum membaginya antar perangkat, yang memakan waktu sekitar 10 menit. 

Dengan SafeTensors, setiap GPU hanya memuat shard tensor yang benar-benar dibutuhkan. Hal itu mengurangi waktu mulai model menjadi sekitar 45 detik di 8 GPU.

SafeTensors vs Format Serialisasi Lain

SafeTensors bekerja baik untuk menyimpan dan memuat bobot model secara aman dan efisien, tetapi itu tidak menjadikannya pengganti universal untuk setiap format. Pilihan yang tepat bergantung pada apa yang Anda simpan dan di mana model berada dalam pipeline.

Kita sudah banyak membahas pickle, jadi saya akan berfokus pada format lain.

SafeTensors vs GGUF

SafeTensors dan GGUF memecahkan masalah yang berbeda. 

GGUF, singkatan dari GGML Unified Format, dibuat untuk beban kerja inferensi terkuantisasi di runtime seperti llama.cpp. Format ini berfokus pada penerapan model terkompresi secara efisien, khususnya untuk inferensi CPU dan perangkat edge. 

SafeTensors berada lebih awal dalam pipeline. Sebagian besar checkpoint SafeTensors menyimpan tensor presisi penuh atau siap latih yang digunakan untuk pelatihan, fine-tuning, penggabungan, atau workflow inferensi terdistribusi. Format ini memprioritaskan pemuatan yang aman, kompatibilitas dengan kerangka seperti PyTorch, dan akses tensor yang efisien selama pelatihan dan penyajian.

Keduanya bisa saling melengkapi alih-alih bersaing langsung. Contoh alur kerja: 

• Latih atau fine-tune model menggunakan PyTorch dan checkpoint SafeTensors
• Kuantisasi model final
• Ekspor ke GGUF untuk penerapan di llama.cpp atau runtime inferensi edge

SafeTensors vs ONNX

SafeTensors berfokus pada penyimpanan bobot model secara aman dan memuatnya secara efisien di dalam kerangka seperti PyTorch. Format ini hanya menyimpan tensor dan metadata, sehingga ringan dan cepat untuk berbagi checkpoint, fine-tuning, dan workflow pelatihan.

ONNX mengambil pendekatan yang lebih luas. Format ini menyimpan grafik komputasi penuh bersama parameter model. Hal ini membuat ONNX berguna saat Anda ingin mengekspor model dari satu kerangka dan menjalankannya di tempat lain sama sekali.

Sebagai contoh, tim yang melatih dan melakukan fine-tuning LLM menggunakan PyTorch biasanya lebih memilih checkpoint SafeTensors karena pemuatannya cepat dan terintegrasi langsung ke workflow yang ada. Namun jika tim yang sama perlu menerapkan model ke TensorRT, ONNX Runtime, atau mesin inferensi edge, mengekspor model ke ONNX lebih masuk akal.

Menggunakan SafeTensors dalam Praktik

Salah satu alasan SafeTensors cepat menyebar di ekosistem PyTorch adalah karena API-nya terasa familier. Anda tetap bekerja dengan state dictionary dan tensor seperti biasanya.

Menyimpan dan memuat tensor

Alur kerja dasarnya tampak identik dengan penanganan checkpoint PyTorch standar. Berikut contohnya:

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() menulis tensor ke format .safetensors, sementara load_file() memuatnya kembali ke memori.

SafeTensors juga mendukung pemuatan selektif melalui safe_open(), yang menjadi berguna untuk checkpoint besar saat Anda hanya membutuhkan beberapa tensor.

from safetensors import safe_open

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

print(weights)

Alih-alih memuat seluruh checkpoint, get_tensor() hanya membaca tensor yang Anda minta.

Mengonversi model yang ada ke safetensors

Pola standarnya adalah:

1. Muat model yang ada
2. Ekstrak state dictionary
3. Simpan dengan save_file()

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() mengembalikan bobot model sebagai tensor, yang dapat disimpan langsung oleh SafeTensors. 

Jika model tersebut sudah ada di Hugging Face Hub, Anda mungkin bahkan tidak memerlukan kode konversi lokal. Hugging Face menyediakan dukungan konversi checkpoint bawaan untuk banyak model yang dihosting melalui antarmuka Hub.

Format Serialisasi: Tabel Perbandingan

SafeTensors pada 2026: PyTorch Foundation dan Arah Berikutnya

Pada April 2026, Hugging Face menyumbangkan SafeTensors ke PyTorch Foundation di bawah Linux Foundation. Proyek ini kini berdampingan dengan PyTorch, vLLM, DeepSpeed, dan Ray di bawah tata kelola foundation.

Langkah itu menandakan bahwa SafeTensors bukan lagi sekadar proyek Hugging Face. Ini menjadi infrastruktur bersama bagi ekosistem ML. 

Pengumuman itu juga menyinggung ke mana arah format ini selanjutnya.

Pemuatan sadar-perangkat (device-aware)

Salah satu fokus utama adalah pemuatan yang sadar-perangkat. Saat ini, banyak workflow masih memuat tensor ke memori CPU sebelum mentransfernya ke perangkat CUDA atau ROCm. Langkah penyangga tambahan itu meningkatkan latensi awal, terutama untuk sistem terdistribusi besar. 

Para maintainer SafeTensors sedang mengerjakan jalur pemuatan langsung ke perangkat yang mengurangi penyalinan CPU yang tidak perlu dan memindahkan tensor langsung ke akselerator. 

Pemuatan terdistribusi

Dukungan pemuatan terdistribusi juga terus berkembang. Sistem inferensi modern jarang menjalankan model pada satu GPU saja. Paralelisme tensor dan paralelisme pipeline kini menjadi pola penerapan standar untuk model besar, namun API pemuatan checkpoint di seluruh kerangka masih terfragmentasi. 

SafeTensors memperluas dukungan untuk pemuatan yang sadar-shard dan tata letak tensor terdistribusi, sehingga kerangka dapat mengoordinasikan pemuatan checkpoint lebih efisien di seluruh perangkat. 

Workflow kuantisasi modern

Format ini juga menyesuaikan diri dengan workflow kuantisasi yang lebih baru. Sistem inferensi semakin mengandalkan format FP8, GPTQ, dan AWQ untuk mengurangi penggunaan memori dan menurunkan biaya penyajian. 

Alih-alih memaksa kerangka menangani ini melalui logika serialisasi khusus, SafeTensors menambahkan dukungan formal untuk format tensor presisi lebih rendah dan kuantisasi blok langsung ke dalam format itu sendiri. 

Saat ini, pengembang masih harus memilih SafeTensors secara manual dengan beralih di antara alur kerja simpan dan muat. Namun ada upaya yang sedang berlangsung untuk integrasi yang lebih dalam dengan sistem serialisasi native PyTorch. Jika itu akhirnya terwujud, SafeTensors dapat berhenti menjadi format checkpoint alternatif dan menjadi cara default PyTorch menyimpan model.

Penutup

Selama bertahun-tahun, pengembang berbagi checkpoint model menggunakan sistem serialisasi yang dapat mengeksekusi kode Python sewenang-wenang saat pemuatan. Begitu hub model publik mulai menampung jutaan checkpoint, risiko keamanan menjadi jauh lebih sulit diabaikan.

SafeTensors mengubah itu dengan mempersempit cakupan format. Alih-alih mencoba menserialisasi seluruh objek Python, format ini hanya berfokus pada penyimpanan tensor dan metadata yang diperlukan untuk memuatnya. Desain yang lebih sederhana itu menghilangkan risiko deserialisasi yang datang dengan checkpoint berbasis pickle sekaligus meningkatkan kecepatan pemuatan dan efisiensi memori.

Jadi ketika Anda hanya membutuhkan bobot model, tidak ada gunanya mengeksekusi kode sewenang-wenang saat deserialisasi, dan lebih baik gunakan SafeTensors untuk kasus-kasus tersebut.

Jika Anda ingin bekerja lebih mendalam dengan peranti ML modern, format model, dan workflow Hugging Face, kursus Deep Learning in Python dan Working with Hugging Face kami adalah langkah berikut yang baik. Keduanya membahas workflow praktis untuk melatih, melakukan fine-tuning, dan menerapkan model dengan alat yang digunakan di ekosistem AI saat ini.