AWS 2026-06-14

SageMaker のモデルアーティファクトはフレームワークごとにどう形式が違うのか

前提: SageMaker の入れ物は共通、中身は自由

SageMaker の学習ジョブでは、コンテナ内の /opt/ml/model に書き出したファイル群が、ジョブ完了時に SageMaker によって自動で tar + gzip 圧縮され、model.tar.gz として S3 の出力パスに置かれます。SageMaker 自体は中のファイル形式を規定しません。つまり「どんなバイナリ形式で保存するか」は、使ったフレームワーク(の保存 API)が決めます。

# 学習コンテナ内: ここに置いたものが model.tar.gz になる
/opt/ml/model/
├── model.pth            # 例) PyTorch の重み(pickle ベース)
└── code/
    ├── inference.py     # 推論ハンドラ
    └── requirements.txt

S3 上では次のような 1 ファイルになります(中身はフレームワーク次第)。

フレームワーク別のバイナリ形式

XGBoost — UBJSON / JSON(旧バイナリは廃止)

XGBoost は学習済みの木構造(Booster)を保存します。歴史的には独自バイナリ形式でしたが、移植性のため v1.0.0 で JSON、v1.6.0 で UBJSON(Universal Binary JSON)に対応し、v2.1.0 から UBJSON がデフォルトになりました。UBJSON は浮動小数点をバイナリで持つため、JSON テキスト化で起きる精度劣化を避けつつ JSON と同じ文書構造を保てます。旧来の独自バイナリ形式は v3.1 で削除され、best_iteration や特徴量名など新しい属性を保存できないという制約がありました。

# 推奨される保存(拡張子で形式が決まる)
booster.save_model("model.ubj")   # UBJSON(2.1 以降のデフォルト)
booster.save_model("model.json")  # JSON(人間が読める)
# .pkl での pickle 保存はバージョン間の互換が保証されない点に注意

PyTorch — .pth / .pt(pickle ベース)

PyTorch は標準で torch.save を使い、Python の pickle でシリアライズします。保存対象は「state_dict(重みのみ)」が推奨で、モデル全体を保存することもできます。いずれも Python 専用で、ロード時に nn.Module を定義したクラスコードと PyTorch ランタイムが必要です。pickle ベースのため、信頼できないファイルのロードは任意コード実行のリスクがあります(近年は weights_only=True での読み込みが推奨)。

# 推奨: 重みだけ保存
torch.save(model.state_dict(), "model.pth")
# 復元にはモデルクラス定義が必須
model.load_state_dict(torch.load("model.pth", weights_only=True))

TensorFlow / Keras — SavedModel(Protocol Buffers)

TensorFlow の SavedModel は単一ファイルではなくディレクトリで、計算グラフを Protocol Buffers でエンコードした saved_model.pb と、重みを格納する variables/ などから構成されます。グラフ(計算そのもの)を含むため言語非依存で、Python だけでなく C++ / Java など TF ランタイムから読み込めます。本番の推論サーバ(TensorFlow Serving)との相性がよい形式です。Keras は .keras(zip)や旧 HDF5(.h5)でも保存できます。

model/
├── saved_model.pb          # Protobuf: グラフ + シグネチャ
├── variables/              # 重み(チェックポイント形式)
│   ├── variables.data-00000-of-00001
│   └── variables.index
└── assets/                 # 語彙ファイルなど(任意)

scikit-learn — pickle / joblib

scikit-learn の推定器は pickle(または NumPy 配列を効率的に扱う joblib)で保存します。PyTorch 同様 Python 専用で、ライブラリのバージョン差で復元できないことがあるため、保存時の sklearn バージョンを記録しておくのが定石です。

Hugging Face Transformers — safetensors

LLM など Transformers 系の重み配布では safetensors が標準になりました。テンソル(数値データ)とメタデータだけを格納する形式で、pickle を使わず実行コードを一切含みません。外部監査でも任意コード実行につながる重大な欠陥は見つからず、Hugging Face Hub のデフォルトになっています。さらに 遅延ロード(lazy loading)に対応し、CPU では従来比で大幅に高速にロードできます。

ONNX — フレームワーク非依存の交換形式

ONNX は Microsoft と Facebook(Meta)が共同で作ったオープンな交換フォーマットで、内部は Protobuf スキーマで定義されます。あるフレームワーク(例: PyTorch)で学習したモデルを別のランタイム(ONNX Runtime や TensorFlow)で動かせるため、学習と推論でフレームワークを分けたい場合や、特定ランタイムへの最適化に使われます。学習よりも推論に最適化された位置づけです。

3 系統で捉えると整理しやすい

用途別の使い分けの目安

• 表形式(テーブル)データの予測: XGBoost(UBJSON)。SageMaker 組み込みアルゴリズムとしても提供され、軽量で扱いやすい。
• 研究・カスタム学習・柔軟なモデル設計: PyTorch(.pth)。ただし配布・本番では safetensors や ONNX への変換を検討。
• クロス言語のサービング・大規模本番推論: TensorFlow SavedModel(TF Serving)や ONNX(ONNX Runtime)。
• LLM・生成 AI の重み配布: safetensors。安全性とロード速度の両面で有利。
• 学習と推論で環境を分けたい / ベンダー中立にしたい: ONNX に変換して交換。

運用上の注意

• pickle 系は信頼できないファイルをロードしない。任意コード実行の恐れがあるため、出所不明の .pth / .pkl をそのまま読み込まない。XGBoost も「XGBoost 自身が出力した JSON 以外を load しない」ことが推奨されています。
• バージョン互換: pickle 系・XGBoost の pickle 保存はライブラリのバージョン差で壊れることがある。学習時のフレームワークバージョンを必ず記録する。
• SageMaker での解凍方法: 既定では推論コンテナ起動時に model.tar.gz を展開しますが、大規模モデルでは非圧縮(uncompressed)で S3 プレフィックスのまま配置して起動を速める方法も用意されています。