safetensors/safetensors

safetensors – ML 텐서를 안전하고 빠르게 저장하는 포맷

무엇인가요 – safetensors는 Python 바인딩과 Rust 코어를 포함한 소규모 오픈소스 라이브러리로, Python의 pickle을 사용하지 않고 텐서(가중치, 활성화 등)를 직렬화하기 위한 바이너리 파일 포맷을 정의합니다. 포맷은 의도적으로 단순합니다: 각 텐서를 설명하는 작은 JSON 헤더와 연속된 바이트 버퍼로 구성됩니다. 헤더에는 실행 가능한 코드가 포함되지 않기 때문에 파일은 안전하게 공유하고 로드할 수 있습니다.

왜 중요한가요 – 딥러닝 워크플로우에서 모델 가중치는 종종 큰 바이너리 블롭으로 전달됩니다. 기본 PyTorch 포맷(.pt/pickle)은 로드 시 임의의 코드를 실행할 수 있어, 인터넷에서 모델을 다운로드하는 사용자에게 보안 위험이 있습니다. safetensors는 이러한 위험을 제거하면서도 다음 기능을 제공합니다:

제로 코피 읽기 – 바이트 버퍼를 직접 메모리 매핑하여 텐서로 로드할 수 있어 CPU에서 추가 복사 없이 처리 가능합니다.
지연 로딩 – 헤더를 확인하고 필요한 텐서만 로드할 수 있어 분산 또는 멀티 GPU 추론에 유용합니다.
크기 제한 없음 – 기가바이트 규모의 모델에도 적용 가능합니다.
최신 dtype 지원 (bfloat16, fp8 등).

주요 기능 (README에 기술됨)

기능	작동 방식
안전성	헤더는 순수한 JSON; 로드 시 코드 실행 없음.
제로 코피	텐서 데이터는 연속적으로 저장되며, 라이브러리가 직접 매핑 가능 (`torch.UntypedStorage.from_file`).
지연 로딩	헤더에 각 텐서의 바이트 오프셋이 기록되어 있어 전체 파일을 스캔하지 않고도 단일 텐서만 읽을 수 있음.
레이아웃 제어	생성자가 파일 내 텐서의 순서를 결정할 수 있어 빠른 랜덤 액세스 가능.
무제한 파일 크기	일부 protobuf 기반 포맷에 있는 2 GiB 제한 없음.
bfloat16 / fp8 지원	네이티브 dtype 코드가 사양에 포함됨.

설치

# Python 패키지 (가장 일반적인 사용)
pip install safetensors

소스에서 빌드하려면 Rust 툴체인이 필요합니다:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh   # Rust 설치
git clone https://github.com/huggingface/safetensors
cd safetensors/bindings/python
pip install setuptools_rust
pip install -e .

빠른 시작 예제 (Python)

import torch
from safetensors import safe_open
from safetensors.torch import save_file

# 디스크에 두 개의 텐서 저장
weights = {
    "weight1": torch.zeros((1024, 1024)),
    "weight2": torch.zeros((1024, 1024)),
}
save_file(weights, "model.safetensors")

# 지연 로딩으로 다시 읽기
tensors = {}
with safe_open("model.safetensors", framework="pt", device="cpu") as f:
    for key in f.keys():
        tensors[key] = f.get_tensor(key)

safe_open 컨텍스트는 헤더를 쿼리할 수 있는 가벼운 핸들(f.keys())을 반환하며, 필요한 텐서만 가져올 수 있습니다.

파일 포맷 기본 사항

처음 8바이트 – 리틀엔디안 부호 없는 정수 N (JSON 헤더 길이).
다음 N 바이트 – UTF-8로 인코딩된 JSON 객체. 텐서 이름에서 {dtype, shape, data_offsets}로의 매핑.
나머지 바이트 – 연속된 텐서 데이터.
선택적 __metadata__ 항목은 임의의 문자열 키/값 쌍을 저장할 수 있음.
중복 키 없음, 바이트 버퍼에 빈 공간 없음, 모든 데이터는 리틀엔디안 행 우선(row-major).

ML 생태계에서의 위치

Hugging Face 모델 허브에서 대규모 언어 모델 가중치를 안전하게 배포하는 데 사용.
PyTorch, TensorFlow, NumPy 등과 언어별 바인딩(코어는 Rust이지만 Python이 주요 진입점)으로 호환.
안전성과 빠른 랜덤 액세스가 필요한 경우, Pickle, HDF5, ONNX protobuf, MsgPack, NumPy .npz 등의 대안으로 사용.

라이선스 – Apache-2.0 (허용성 높고 상용 사용에 적합).

위 정보는 리포지토리의 README에서 직접 인용되었으며, 추가 기능은 추측되지 않았습니다.*

safetensors/safetensors

safetensors – ML 텐서를 안전하고 빠르게 저장하는 포맷

관련