safetensors/safetensors

safetensors – 機械学習テンソルを安全に高速に保存するフォーマット

何であるか – safetensors は、PythonバインディングとRustコアを備えた小さなオープンソースライブラリであり、Pythonの pickle を使用せずにテンソル（重み、活性化など）をシリアル化するためのバイナリーファイルフォーマットを定義しています。このフォーマットは意図的にシンプルです：各テンソルを記述する小さなJSONヘッダーと、連続したバイトバッファで構成されています。ヘッダーには実行可能なコードが含まれないため、ファイルは安全に共有・読み込みできます。

なぜ重要か – 深層学習ワークフローでは、モデル重みが大きなバイナリブロブとして送信されることがよくあります。デフォルトのPyTorchフォーマット（.pt/pickle）は読み込み時に任意のコードを実行できるため、インターネットからモデルをダウンロードするユーザーにとってセキュリティリスクがあります。safetensors はそのリスクを排除しつつ、以下の利点を提供します：

• ゼロコピー読み取り – バイトバッファを直接メモリマップしてテンソルに読み込むことができ、CPU上で余分なコピーを回避できます。
• 遅延読み込み – ヘッダーを確認して必要なテンソルのみを読み込むことができ、分散処理やマルチGPU推論に有用です。
• サイズ制限なし – ギガバイト規模のモデルにも対応可能です。
• 最新のdtypes（bfloat16やfp8など）のサポート。

主な機能（READMEに記載）

機能	動作方法
安全性	ヘッダーは純粋なJSON；読み込み時にコード実行なし。
ゼロコピー	テンソルデータは連続して保存；ライブラリが直接マップ可能（torch.UntypedStorage.from_file）。
遅延読み込み	ヘッダーに各テンソルのバイトオフセットが記録されているため、ファイル全体をスキャンせずに1つのテンソルだけを読み取れます。
レイアウト制御	作成者がファイル内のテンソルの順序を決定できるため、高速なランダムアクセスが可能。
無制限のファイルサイズ	一部の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

# ディスクに2つのテンソルを保存
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）。

機械学習エコシステムにおける位置づけ

• Hugging Faceモデルハブで、大規模言語モデルの重みを安全に配布するために使用。
• PyTorch、TensorFlow、NumPyなどと、言語固有のバインディング（Rustコアだが、Pythonが主なエントリポイント）で互換性あり。
• セキュリティと高速なランダムアクセスが必要な場合、Pickle、HDF5、ONNX protobuf、MsgPack、NumPy .npz などの代替として機能。

ライセンス – Apache-2.0（許容性が高く、商用利用に適している）。

---

• 上記のすべての情報はリポジトリのREADMEから直接引用；追加の機能は推測されていません。*