safetensors 파일 포맷 — 안전한 설계

safetensors 파일 포맷 — 안전한 설계

safetensors는 파일 포맷 자체를 안전하게 설계해서, 임의 코드 실행 위험이 있는 pickle을 대체하는 게 핵심 목표예요. 파일 구조가 단순하고 결정적이라 파서도 간단해요.

출처: safetensors GitHub 저장소

파일 구조

  1. 8바이트: N — 헤더 크기를 담은 unsigned little-endian 64-bit 정수
  2. N 바이트: 헤더를 나타내는 JSON UTF-8 문자열
    • 헤더는 { 문자(0x7B)로 반드시 시작
    • 헤더는 공백(0x20)으로 trailing padding 가능
    • 헤더는 {"TENSOR_NAME": {"dtype": "F16", "shape": [1, 16, 256], "data_offsets": [BEGIN, END]}, ...} 형태
    • data_offsets는 바이트 버퍼 시작 기준 상대 오프셋. 텐서 바이트 크기 = END - BEGIN
    • 특수 키 __metadata__는 자유 형식 string-to-string 맵 허용
  3. 나머지: byte-buffer (텐서 데이터)

주요 규칙

  • 중복 키 금지
  • 바이트 버퍼는 전부 인덱스되어야 하고 구멍(hole)이 없어야 함 — polyglot 파일 생성 방지
  • 엔디안: Little-endian
  • 순서: 'C' 또는 row-major
  • 0-rank 텐서(스칼라) 허용, 빈 텐서 허용

안전성·성능 장점

  • DOS 방지: 헤더 크기 100MB 제한 → 과도한 JSON 파싱 방지. 파일 내 주소가 겹치지 않도록 보장 → 메모리에 파일 크기 초과 로드 불가
  • 빠른 로드: CPU에서 pickle보다 훨씬 빠름, GPU 로드는 PyTorch와 같거나 더 빠름
  • Lazy loading(게으른 로드): 분산(멀티 노드/멀티 GPU) 환경에서 텐서 일부만 로드 가능. BLOOM의 경우 8 GPU 로드가 정규 PyTorch 가중치 10분 → 45초로 단축

비교 요약

pickle(PyTorch)만 '안전하지 않음(Safe=✗)'이면서 'zero-copy'도 아니에요. safetensors는 Safe·Zero-copy·Lazy loading·Bfloat16/Fp8·No file size limit 전부 ✔예요.

더 알아보기