SambaStack チェックポイント変換ツール

チェックポイント変換パッケージは、HuggingFace 形式のチェックポイントを、SambaRack および SambaCloud システムへのデプロイに必要な SambaNova 互換形式に変換します。変換機能は、モデルファミリーごとに 1 つの Python パッケージとして提供され、お使いの SambaStack アーティファクトレジストリからインストールします。各パッケージは、その名前が示すモデルファミリーのチェックポイントを変換します。これらのパッケージは、従来の Docker ベースの変換ツールを置き換えるものです。

チェックポイント変換は、SambaStack または SambaCloud にカスタムチェックポイントをデプロイする際の 1 つのサブステップです。全体のワークフローについては、カスタムチェックポイントのデプロイのページをご参照ください。

前提条件

システム要件

要件	仕様
メモリ	チェックポイントの SafeTensor または .bin ファイルのサイズの 2.5 倍以上。例えば、10GB のチェックポイントには最低 25GB の空きメモリが必要です。
ストレージ	出力用に、入力チェックポイントと同等のサイズ。例えば、14GB のチェックポイントを変換するには、変換後の出力用に 14GB の空きストレージ (元のチェックポイントとは別に) が必要です。
オペレーティングシステム	macOS または Linux ベースのオペレーティングシステム。Windows OS はサポートされていません。
Python	3.11 以降。

変換時間の目安

チェックポイントサイズ	モデルの例	推定時間
約 8GB	Meta-Llama-3.1-8B-Instruct	約 5 分
約 140GB	Meta-Llama-3.3-70B-Instruct	約 1 時間

変換は、チェックポイントのストレージマウントにアクセスできるローカルマシンまたはワークスペース上で実行してください。クラウドのコンピュートインスタンスも使用できますが、チェックポイントのデータ転送に長い時間がかかる場合がある点にご注意ください。

必要なソフトウェア

Python 3.11 以降 (pip を含む)
Google Cloud CLI - インストールガイド

必要なアクセス権

お使いの SambaStack アーティファクトレジストリのレジストリ URL (SambaNova のアカウントチームまたはサポート窓口から提供されます)。この URL がないと変換パッケージをインストールできません
そのレジストリへの読み取りアクセス権
Google Cloud の認証情報 (貴組織の SambaStack アーティファクトレジストリが構成されている場合はそれに使用しているものと同じアカウント。未構成の場合は SambaNova のアカウントチームまたはサポート窓口にお問い合わせください)

SambaNova がホストするレジストリおよびチェックポイントストレージへのアクセスは読み取り専用です。変換パッケージはレジストリから取得し、変換後のチェックポイントはご自身で管理するストレージに書き込みます。詳細はカスタムチェックポイントのデプロイをご参照ください。

対応モデルとチェックポイント形式

対応モデルアーキテクチャ

カスタムチェックポイントは、decoder-only のテキスト生成モデルでサポートされています。対象のモデルファミリーがサポートされているかどうかと現時点の例外については、対応モデルのページをご確認ください。

チェックポイント形式の要件

チェックポイントは HuggingFace 形式で受け付けられます。テンソルは safetensors 形式であり、チェックポイントディレクトリには、カスタムチェックポイントのベースモデルと同じ関連設定ファイルが含まれている必要があります。例えば、カスタムチェックポイントが meta-llama/Llama-3.3-70B-Instruct のファインチューニング済み派生モデルである場合、チェックポイントディレクトリには以下のようなファイルが含まれている必要があります。

ファイル	説明
`config.json`	隠れ層のサイズ、レイヤー数、アテンションヘッド数などの構造パラメータを含む、モデルアーキテクチャの構成を定義します。
`generation_config.json`	サンプリング戦略、温度、最大トークン数など、テキスト生成のデフォルトパラメータを格納します。
`model-00001-of-00030.safetensors` … `model-00030-of-00030.safetensors`	モデルの学習済みテンソルパラメータを含む、シャーディングされたモデル重みファイル。大規模なモデルでは重みが複数のファイルに分割されます。
`model.safetensors.index.json`	モデルの重みテンソルを対応する safetensor シャードファイルにマッピングするインデックスファイル。
`special_tokens_map.json`	BOS、EOS、パディングトークンなど、トークナイザーが使用する特殊トークンを定義します。
`tokenizer.json`	テキストをモデルの入力トークンに変換するために使用する、トークナイザーの語彙とトークン化ルールを含みます。
`tokenizer_config.json`	トークン化の動作や設定を含む、トークナイザーの構成メタデータ。

チェックポイントの互換性

チェックポイントが、お使いのプラットフォームで対応しているモデルのいずれかからファインチューニングまたは派生したものである場合、計算グラフ (すなわちテンソルの重みと形状) が元のチェックポイントから変更されていないことが互換性の条件となります。 変更してはならない要素:

アテンションヘッド数
RoPE のタイプ (rope theta)
モデルの語彙サイズ
オプティマイザのタイプ
config.json 内の静的なアーキテクチャ属性 (head_dim、hidden_act、intermediate_size、attention_bias、attention_dropout、vocab_size など)

変更可能な要素:

モデルの重み、またはモデルの重みテンソルの値
トークナイザーと語彙。ただし、語彙サイズは元のモデルチェックポイントと正確に一致している必要があります。多言語ユースケースで有用です。

静的グラフの観点で考えると理解しやすくなります。TensorRT-LLM などのエンジンで通常静的とされるモデルの要素は、カスタムチェックポイントでも静的である必要があります。

互換性の具体例

ベースモデル meta-llama/Llama-3.3-70B-Instruct (SambaNova が対応しているベースモデル) を例にします。以下のチェックポイントは元の 70B モデルと同じ計算グラフを使用しているため、SambaNova プラットフォーム上への変換とデプロイが可能です。

これらのチェックポイントはモデルの重みが更新されており、パフォーマンスの向上や特定のタスク・データセットへの適応のために調整・改良されています。

変換パッケージの選択

パッケージの名前は、個々のモデルではなくモデルファミリーに対応しています。お使いのチェックポイントの派生元となるベースモデルを確認してください。

ベースモデル	パッケージ	コマンド
Meta-Llama-3.1 および 3.3 (全サイズ)、Llama-3.3-Swallow、DeepSeek-R1-Distill-Llama	`sn-conversion-llama`	`sn-convert-llama`
DeepSeek-V3 および DeepSeek-R1 (全バリアント)	`sn-conversion-deepseek-v3`	`sn-convert-deepseek-v3`
MiniMax-M2.5、MiniMax-M2.7	`sn-conversion-minimax-m2`	`sn-convert-minimax-m2`
Mistral-Large-3	`sn-conversion-mistral-large-3`	`sn-convert-mistral-large-3`
gpt-oss-120b、gpt-oss-20b	`sn-conversion-gpt-oss`	`sn-convert-gpt-oss`
Qwen3-235B-A22B	`sn-conversion-qwen3-moe`	`sn-convert-qwen3-moe`

誤ったパッケージで変換すると、エラーなく読み込まれるのに誤った出力を返すチェックポイントが生成されることがあります。パッケージは、チェックポイントの派生元のベースモデルに合わせて選択してください。

この表は、サポートされている変換パッケージの完全な一覧です。レジストリには、カスタムチェックポイント用にはサポートされていない他の sn-conversion-* パッケージも存在しますが、この表には記載していません。上記のパッケージのみを使用してください。

変換パッケージのインストール

Google Cloud CLI のインストールと認証

変換を実行する環境に、公式の Google Cloud CLI インストールガイドに従って Google Cloud CLI をインストールし、認証を行います。

gcloud auth login

貴組織の SambaStack アーティファクトレジストリへのアクセスに関連付けられた Google アカウントを使用してください。

パッケージのインストール

pip がレジストリから読み取れるようにする認証バックエンドをインストールし、続いてお使いのモデルファミリー用のパッケージをインストールします。

pip install keyring keyrings.google-artifactregistry-auth
pip install --extra-index-url <REGISTRY_URL> sn-conversion-llama

sn-conversion-llama は、変換パッケージの選択で確認したお使いのモデルファミリー用のパッケージに置き換えてください。本ページの例では、すべて sn-conversion-llama とその sn-convert-llama コマンドを使用しています。

<REGISTRY_URL> は、SambaNova のアカウントチームまたはサポート窓口から提供されるレジストリ URL に置き換えてください。URL は https://<REGION>-python.pkg.dev/<PROJECT>/<REPOSITORY>/simple/ という形式です。レジストリには変換パッケージのみが置かれているため、--extra-index-url を使うことで依存パッケージは引き続き PyPI から取得できます。

共通の変換エンジンは、依存関係として自動的にインストールされます。仮想環境へのインストールを推奨します。

インストールの確認

sn-convert-llama --help

これでセットアップは完了です。新しいバージョンに更新するには、パッケージ名を指定して pip install --upgrade を実行してください。

チェックポイントの変換

コマンド

まず、変換プランを表示します。

sn-convert-llama \
    --source_path /path/to/checkpoint \
    --target_path /path/to/converted \
    --print-plan

--print-plan を外すと、変換が実行されます。

パラメータ

フラグ	説明
`-s`, `--source_path`	入力チェックポイントを含むディレクトリのパス。
`-t`, `--target_path`	変換後のチェックポイントを書き込むパス。変換元のチェックポイントと同等の空き容量が必要です。
`-f`, `--force`	空でないターゲットディレクトリを上書きします。
`--print-plan`	変換で実行される操作を表示して終了します。
`--dry-run`	出力を書き込まずにプランを実行します。一部のパッケージでは利用できません。既知の問題をご参照ください。
`--set`	変換設定をオーバーライドします。変換設定をご参照ください。
`--strict-ops`	指定した操作に効果がなかった場合に失敗させます。変換結果の検証をご参照ください。

フラグは記載どおり正確に入力してください。--source_path と --target_path はアンダースコアを使用するのに対し、--print-plan、--dry-run、--strict-ops はハイフンを使用します。両者に互換性はなく、--source-path も --strict_ops も拒否されます。

変換設定

各パッケージは独自の設定を宣言しており、ベースモデルに一致するチェックポイントに対してはデフォルト値のままで正しく動作します。--print-plan を使うと、実行時に解決された設定を確認できます。設定のオーバーライドには --set を使用します。ブール値の設定は + または - のプレフィックスを付け、それ以外は key=value 形式で指定します。

sn-convert-llama -s /path/to/checkpoint -t /path/to/converted \
    --set shard_bytes=5

以下の設定は、すべてのパッケージに共通です。

設定	説明
`shard_bytes`	出力される各 safetensors シャードの最大サイズ (GB)。デフォルトは 5 です。
`cache_bytes`	変換中に保持するテンソル用のメモリ予算 (GB)。メモリ不足 (OOM) が発生した場合は、この値を下げてください。
`allow_symlink`	変更のないシャードをコピーする代わりにシンボリックリンクにします。デフォルトでは無効です。下記の警告をご参照ください。

allow_symlink はデフォルトのままにしてください。変換中にいずれかのテンソル形状が変わった場合、シンボリックリンクされたシャードは元のテンソルを提供するため、デプロイ時にチェックポイントの読み込みが失敗します。

認識されない --set キーを指定すると実行は失敗し、そのパッケージが受け付けるキーの一覧が表示されます。

変換結果の検証

出力の確認

変換が成功すると、変換後の safetensors シャード、更新された model.safetensors.index.json、および sn_checkpoint_conversion_metadata.json がターゲットディレクトリに書き込まれ、終了コード 0 で終了します。 sn_checkpoint_conversion_metadata.json には、各操作の実行内容が記録されます。変換は成功したのに出力に問題がありそうな場合は、このファイルを確認してください。

効果のなかった操作の検出

--strict-ops を付けて再実行すると、指定した操作に効果がなかった場合に変換を失敗させることができます。

sn-convert-llama -s /path/to/checkpoint -t /path/to/converted --strict-ops

効果のない操作は、通常、パッケージが想定するテンソルがチェックポイントに含まれていないことを意味し、チェックポイントとそのベースモデルの不一致を示唆します。

PEF との照合

各 PEF には <pef_stem>_coe_meta.json というマニフェストが同梱されており、コンパイル済みモデルが期待するすべてのテンソルが、その形状と dtype とともに記載されています。マニフェストを取得するには、PEF リソースで PEF のストレージパス (spec.versions.<version>.source) を確認します。マニフェストは同じフォルダーにあり、PEF ファイル名から .pef 拡張子を除いた名前が付けられています。

kubectl get pef <pef-name> -o yaml
gcloud storage cp gs://<path>/<pef_stem>_coe_meta.json .

変換後のチェックポイントを、そのマニフェストと照合します。

python -m sn_checkpoint_surgery.coe_meta_validation \
    /path/to/<pef_stem>_coe_meta.json \
    /path/to/converted

テンソルの欠落や形状の不一致があると、非ゼロの終了コードで終了し、該当するテンソル名が表示されます。dtype の違いは報告されますが、チェックの失敗にはなりません。ランタイムが読み込み時に dtype を変換するためです。

このチェックは、テンソル名・形状・dtype を比較します。変換後のチェックポイントが、その PEF のビルド対象であるモデルに適合することを確認するものであり、変換によって数値的に正しい値が生成されたことを検証するものではありません。

変換後の注意点

変換は safetensors ファイルを書き換えますが、config.json は更新しません。デプロイ時に次元や量子化の不一致が報告された場合は、config.json を変換後のテンソルと照合してください。

トラブルシューティング

問題	原因	解決方法
プロセスがエラーも成功メッセージも出さずに終了する	メモリ不足 (OOM)	利用可能なメモリをチェックポイントサイズの 2.5 倍以上に増やすか、`cache_bytes` を下げてください
`--set` キーが拒否される	そのパッケージには存在しない設定	`--print-plan` を実行して、パッケージが受け付ける設定を確認してください
開始時にファイルの欠落が報告される	チェックポイントディレクトリが不完全	`config.json`、すべての safetensors シャード、トークナイザーファイルが存在することを確認してください
デプロイ時にチェックポイントは読み込まれるが出力が正しくない	誤ったパッケージで変換した、または `allow_symlink` をオーバーライドした	ベースモデルに一致するパッケージとデフォルト設定で再変換してください
`sn-convert-<model>: command not found`	アクティブな環境にパッケージがインストールされていない	使用中の仮想環境に再インストールしてください

エラーには CKPT-CNV-012 のような固定のエラーコードが付与されます。SambaNova のサポート窓口にお問い合わせの際は、このコードを添えてください。

既知の問題

sn-conversion-gpt-oss、sn-conversion-deepseek-v3、sn-conversion-qwen3-moe では --dry-run が失敗する これらのパッケージでも変換自体は動作します。影響を受けるのは --dry-run フラグのみなので、このフラグを付けずに変換を実行してください。事前に操作内容を確認するには、--print-plan を使用してください。

次のステップ

チェックポイントの変換が正常に完了したら、次の手順に進みます。

変換済みチェックポイントを GCS バケットまたは NFS マウントにアップロードする
Model リソースまたはチェックポイントのオーバーライドからチェックポイントを参照する
互換性のある ModelProfile を使用してチェックポイントをデプロイする

完全なワークフローについては、カスタムチェックポイントのデプロイをご参照ください。

はじめに

サービス管理

ハードウェア管理

リファレンスアーキテクチャ

リソース

チェックポイント変換ツール

前提条件

システム要件

変換時間の目安

必要なソフトウェア

必要なアクセス権

対応モデルとチェックポイント形式

対応モデルアーキテクチャ

チェックポイント形式の要件

チェックポイントの互換性

互換性の具体例

変換パッケージの選択

変換パッケージのインストール

Google Cloud CLI のインストールと認証

パッケージのインストール

インストールの確認

チェックポイントの変換

コマンド

パラメータ

変換設定

変換結果の検証

出力の確認

効果のなかった操作の検出

PEF との照合

変換後の注意点

トラブルシューティング

既知の問題

次のステップ

​前提条件

​システム要件

​変換時間の目安

​必要なソフトウェア

​必要なアクセス権

​対応モデルとチェックポイント形式

​対応モデルアーキテクチャ

​チェックポイント形式の要件

​チェックポイントの互換性

​互換性の具体例

​変換パッケージの選択

​変換パッケージのインストール

Google Cloud CLI のインストールと認証

パッケージのインストール

インストールの確認

​チェックポイントの変換

​コマンド

​パラメータ

​変換設定

​変換結果の検証

​出力の確認

​効果のなかった操作の検出

​PEF との照合

​変換後の注意点

​トラブルシューティング

​既知の問題

​次のステップ

前提条件

システム要件

変換時間の目安

必要なソフトウェア

必要なアクセス権

対応モデルとチェックポイント形式

対応モデルアーキテクチャ

チェックポイント形式の要件

チェックポイントの互換性

互換性の具体例

変換パッケージの選択

変換パッケージのインストール

チェックポイントの変換

コマンド

パラメータ

変換設定

変換結果の検証

出力の確認

効果のなかった操作の検出

PEF との照合

変換後の注意点

トラブルシューティング

既知の問題

次のステップ