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

チェックポイント変換ツール (Checkpoint Conversion Tool) は、チェックポイントなどの外部モデルアーティファクトを、SambaRack および SambaCloud システムへのデプロイに必要な SambaNova 互換形式に変換するユーティリティです。このツールはプラットフォーム固有のメタデータを取得するため、お使いの SambaStack インスタンスがサポートするモデルアーキテクチャやリリースと常に整合した状態を保てます。

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

概要

チェックポイント変換ツールは、主に次の 2 つの機能を提供します。

チェックポイント変換: HuggingFace 形式のチェックポイントを、SN40L ハードウェアへのデプロイに適した SambaNova 互換形式に変換します。
投機的デコーディングの検証: 変換済みのドラフトチェックポイントが、投機的デコーディング (speculative decoding) のデプロイにおいてターゲットチェックポイントと互換であるかを検証します。

前提条件

システム要件

チェックポイント変換ツールを使用する前に、システムが以下の要件を満たしていることを確認してください。

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

変換時間の目安

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

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

必要なソフトウェア

Docker Desktop または Docker Engine - インストールガイド（英語）
Google Cloud CLI - インストールガイド

必要なアクセス権

お使いの SambaStack インスタンスのエンドポイントへのネットワークアクセス
Google Cloud の認証情報 (貴組織の SambaStack アーティファクトレジストリが構成されている場合はそれに使用しているものと同じアカウント。未構成の場合は SambaNova のアカウントチームまたはサポート窓口にお問い合わせください)

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

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

カスタムチェックポイントのデプロイは、拡大を続けるベースモデル群でサポートされています。対象のモデルファミリーでカスタムチェックポイントがサポートされているかどうかは、対応モデルの表で、「機能と最適化」列の Custom checkpoints supported フィールドをご確認ください。

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

チェックポイントは 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 プラットフォーム上への変換とデプロイが可能です。

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

ダウンロードとセットアップ

チェックポイント変換ツールは、すべての変換・検証ユーティリティを含む Docker コンテナとして配布されています。

<REGISTRY_HOST> および <REGISTRY_PATH> の値を入手するには、SambaNova のアカウントチームまたはサポート窓口にお問い合わせください。

Docker Desktop または Docker Engine のインストール

変換を実行する環境に Docker エンジンをインストールします。公式の Docker Engine インストールガイド（英語）に従ってください。インストール後、Docker を起動します (macOS ではデスクトップアプリケーションから起動できます)。

Google Cloud CLI のインストール

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

認証とコンテナイメージの取得

まず、Docker クライアントが <REGISTRY_HOST> に対して認証できるように構成します (初回のみ):

gcloud auth configure-docker <REGISTRY_HOST>

<REGISTRY_HOST> は、SambaNova のアカウントチームまたはサポート窓口から提供されるレジストリドメインに置き換えてください。

Google Cloud で認証します。

gcloud auth login

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

Docker イメージを取得します。

docker pull <REGISTRY_PATH>

<REGISTRY_PATH> は、SambaNova のアカウントチームまたはサポート窓口から提供されるチェックポイント変換ツールのイメージパスに置き換えてください。

モデルメタデータの同期

このステップでは、お使いの SambaStack インスタンスからプラットフォーム固有のモデルメタデータをダウンロードし、ローカルに保存します。ツールはこのメタデータを使用してチェックポイント変換を実行します。また、モデルメタデータの内容を確認することで、アーティファクトが SambaNova の SN40L ハードウェア上で動作するようにどのように変換されるかを理解できます。メタデータの取得とキャッシュは、チェックポイント変換ツールのコンテナを download-serving-cache コマンドで実行することで行います。

コマンドテンプレート

docker run -v $HOST_WORKING_DIR:$DOCKER_WORKING_DIR --rm -it \
    --platform linux/amd64 \
    $IMAGE_NAME \
    download-serving-cache \
    --server $SERVER \
    --cache_location $DOCKER_WORKING_DIR/$CACHE_LOCATION

ネイティブの Linux/amd64 環境では、--platform linux/amd64 フラグは任意であり、省略できます。このフラグは主に macOS (特に Apple Silicon) で正しいアーキテクチャが使用されるようにするために有用です。

パラメータ

入力	型	説明
`HOST_WORKING_DIR`		コンテナにマウントするホストマシン上のディレクトリ。ダウンロードしたメタデータがこのディレクトリに保存されるほか、変換予定のチェックポイントを配置しておくこともできます。
`DOCKER_WORKING_DIR`		`HOST_WORKING_DIR` がマウントされるコンテナ内のパス。`-v` フラグの右辺と一致している必要があります。
`IMAGE_NAME`	`str`	チェックポイント変換ツールの Docker イメージの完全な名前。前のステップの `<REGISTRY_PATH>` と同じ値です。
`SERVER`	`str`	お使いの SambaStack プラットフォームと製品バージョンに対応するベースエンドポイント URL。この値の取得方法は、ドキュメントの API キーと URL セクションをご参照ください。
`CACHE_LOCATION`	`str`	コンテナ内でメタデータを保存するパス (`DOCKER_WORKING_DIR` からの相対パス)。メタデータは、ホスト側では `HOST_WORKING_DIR` 配下の対応するパスから参照できます。

これでセットアップは完了です。このセットアップ全体は一度だけ実行すれば十分です。ただし、以下の場合はステップ 4 の再実行が必要になることがあります。

SambaNova または貴組織が、カスタムチェックポイント推論に利用可能なモデルアーキテクチャを追加した場合
お使いの SambaStack インスタンス (ベース URL 単位) に対してモデルメタデータの更新がリリースされた場合
別のプラットフォーム (例: SambaCloud) に切り替える場合、または貴組織が複数の SambaStack インスタンス (ベース URL 単位) を使用している場合

チェックポイントの変換と検証

チェックポイント変換ツールは、カスタムチェックポイント (HuggingFace などから取得したもの) を SambaNova の SN40L ハードウェア上で実行できる形式に変換します。このステップは、SambaStack または SambaCloud にカスタムチェックポイントをアップロード・デプロイする前に実行します。

コマンドテンプレート

docker run -v $HOST_WORKING_DIR:$DOCKER_WORKING_DIR --rm -it \
    --platform linux/amd64 \
    $IMAGE_NAME \
    prepare-ckpt \
    --model $MODEL_NAME \
    --original_checkpoint_path "$DOCKER_WORKING_DIR/$CHECKPOINT_DIR" \
    --output_checkpoint_path "$DOCKER_WORKING_DIR/$OUTPUT_DIR" \
    --transformers_version $TRANSFORMERS_VERSION \
    --server $SERVER \
    --cache_location $DOCKER_WORKING_DIR/$CACHE_LOCATION \
    --ignore_transformers_version

パラメータ

prepare-ckpt コマンドの主な入力フラグは以下のとおりです。

フラグ / 変数	型	説明
`--model` / `MODEL_NAME`	`str`	変換対象のベースモデル (例: `Meta-Llama-3.1-8B`)。対象のモデルファミリーでカスタムチェックポイントがサポートされているかどうかは、対応モデルとバンドルの表で、「機能と最適化」列の Custom checkpoints supported フィールドをご確認ください。
`--original_checkpoint_path` / `CHECKPOINT_DIR`	`str`	入力チェックポイント (config、トークナイザー、safetensors など) を含むディレクトリのコンテナ内のパス。通常は `$DOCKER_WORKING_DIR/<subdir>` であり、`<subdir>` は `HOST_WORKING_DIR` からマウントされます。
`--output_checkpoint_path` / `OUTPUT_DIR`	`str`	変換後のチェックポイントを書き込むコンテナ内のパス。変換後のアーティファクトは、ホスト側では `$HOST_WORKING_DIR/$OUTPUT_DIR` 配下に出力されます。
`--transformers_version` / `TRANSFORMERS_VERSION`	`str`	(任意ですが推奨。) デプロイに必要な Hugging Face `transformers` のバージョン (例: `4.45.1`) を指定します。ツールは、モデルの保存に使用されたバージョンがデプロイバージョン以下であることを確認します。この検証が不要な場合は、フラグを省略してください。バージョンエラーが発生した場合は、より新しい `transformers` バージョンでチェックポイントを保存し直すか、この値を更新してください。
`--ignore_transformers_version`	`bool`	有効にすると、`transformers` のバージョンチェックをすべてスキップします。デフォルトは `False` です。バージョン検証エラーが発生し、それを明示的に回避したい場合に有用です。チェックポイントの Transformers バージョンを無視した場合、チェックポイントの変換にはバックエンドのデフォルトバージョン (すなわち `4.45.1`) が使用されます。
`--server` / `SERVER`	`str`	サービングメタデータの取得元。`embedded`、ローカルパス、または `https://api.sambanova.ai/` のようなリモート URL を指定できます。通常は、お使いの SambaStack インスタンスのベースエンドポイント URL です。
`--cache_location` / `CACHE_LOCATION`	`str`	サービングメタデータ/設定を保存する場所 (コンテナ内)。通常は `$DOCKER_WORKING_DIR` のサブディレクトリで、ホスト側では `$HOST_WORKING_DIR/$CACHE_LOCATION` 配下から参照できます。

ホスト側の変数

上記のフラグに加えて、通常は Docker コマンド用に以下の環境変数を設定します。

変数	説明
`HOST_WORKING_DIR`	入力チェックポイントを含み、出力の書き込み先にもなるホスト上のディレクトリ。書き込み可能である必要があります。
`DOCKER_WORKING_DIR`	`HOST_WORKING_DIR` がマウントされるコンテナ内のディレクトリ (`-v` の右辺と一致)。
`IMAGE_NAME`	チェックポイント変換ツールのコンテナの完全なイメージ名。
`CHECKPOINT_DIR`	元のチェックポイントを含む、`HOST_WORKING_DIR` 配下のサブディレクトリ (`DOCKER_WORKING_DIR` 配下にミラーされます)。
`OUTPUT_DIR`	変換後のチェックポイントを書き込む、`HOST_WORKING_DIR` 配下のサブディレクトリ (`DOCKER_WORKING_DIR` 配下にミラーされます)。

変換出力の検証

変換が正常に完了したら、出力ディレクトリが完全かつ整合していることを確認します。

チェックリスト

出力ディレクトリに、想定される一連の safetensors ファイルが含まれている。通常は model-00001-of-000NN.safetensors、model-00002-of-000NN.safetensors、…、NN まで
出力ディレクトリに、正常完了を示す DONE ファイルが含まれている
ツールのログにエラーが記録されていない

変換成功時のログ

正常に完了した実行は、次のようなログで終わります。

-----------------------------------------------
[1] STEP: parse_args - Succeeded
-----------------------------------------------


> Errors (None)

-----------------------------------------------
[2] STEP: legalizer - Succeeded
-----------------------------------------------


> Errors (None)

***************************************************
YYYY-MM-DDTHH:MM:SSUTC - byoc_lib - INFO - The process is completed without any errors.

変換失敗時のログ

変換が失敗した場合は、次のようなエラーエントリが表示されることがあります。

-----------------------------------------------
[2] STEP: validate_transformer - Failed
-----------------------------------------------


> Errors
  Id: ByocErrorId.TRANSFORMERS_VERSION_ERROR
  Responsible: ByocErrorOwner.USAGE
  Reason: The transformers version of your checkpoint (4.52.4) is larger than the maximum supported transformers version (4.45.1).
  Suggestion: To fix this, please save your checkpoint with a transformers environment <= 4.45.1. Alternatively, you can include the --ignore_transformers_version flag, but this may lead to errors due to transformers version compatibility issues.

  Stack Trace:
    ...

"One or more failures have occurred. Do not deploy" と "The process is completed without any errors" のどちらも表示されず、プロセスが予期せず終了した場合は、メモリ不足 (OOM) が発生している可能性があります。その場合は、利用可能なメモリを増やして変換を再実行してください。

変換が正常に完了し、出力ディレクトリに想定されるすべてのファイルが含まれていることを確認できたら、カスタムチェックポイントのデプロイのアップロードとデプロイの手順に進めます。

出力ログの読み方とトラブルシューティング

チェックポイント変換ツールは、実行ごとに構造化されたログを出力します。これにより、問題の診断、プロセスのどの部分が失敗したかの特定、次に取るべき対応の判断がしやすくなります。

ログ構造の概要

大まかには、各実行のログには以下が含まれます。

実行されたコマンドを示す最終レポートヘッダー
実行中のモジュールやテストを示す一連の STEP エントリ
(失敗が発生した場合) 詳細と対応案を含む Errors セクション
プロセスが正常完了したか失敗したかを示す最終ステータス行

出力ログの例

FINAL REPORT FOR: `prepare-ckpt --model Meta-Llama-3.1-8B --original_checkpoint_path /data/Meta-Llama-3.1-8B --output_checkpoint_path /data/outputs/Meta-Llama-3.1-8B --transformers_version 4.45.1`
***************************************************

-----------------------------------------------
[1] STEP: parse_args - Succeeded
-----------------------------------------------


> Errors (None)

-----------------------------------------------
[2] STEP: validate_transformer - Failed
-----------------------------------------------


> Errors
  Id: ByocErrorId.TRANSFORMERS_VERSION_ERROR
  Responsible: ByocErrorOwner.USAGE
  Reason: The transformers version of your checkpoint (4.52.4) is larger than the maximum supported transformers version (4.45.1).
  Suggestion: To fix this, please save your checkpoint with a transformers environment <= 4.45.1. Alternatively, you can include the --ignore_transformers_version flag, but this may lead to errors due to transformers version compatibility issues.

  Stack Trace:
    Traceback (most recent call last):
    File "/byoc_core/main.runfiles/_main/byoc_core/byoc.py", line 46, in _byoc
    warning = validate_transformer(convert_checkpoint_path,
    File "/byoc_core/main.runfiles/_main/byoc_core/transformers_validator/check_transformers.py", line 115, in validate_transformer
    raise TransformersVersionError(model_config_transformers_version,
    byoc_core.transformers_validator.check_transformers.TransformersVersionError: (<Version('4.52.4')>, '4.45.1')
    (<Version('4.52.4')>, '4.45.1')


***************************************************
2025-08-25T17:49:10UTC - byoc_lib - ERROR - One or more failures have occurred. Do not deploy

ログの構成要素の解説

最終レポートヘッダー 実行されたコマンドと引数がそのまま表示されます。

FINAL REPORT FOR: `prepare-ckpt --model Meta-Llama-3.1-8B --original_checkpoint_path /data/Meta-Llama-3.1-8B --output_checkpoint_path /data/outputs/Meta-Llama-3.1-8B --transformers_version 4.45.1`
***************************************************

STEP ブロック 各ステップは、ワークフローのモジュール化されたフェーズ (引数の解析、検証、変換など) を表します。

-----------------------------------------------
[1] STEP: parse_args - Succeeded
-----------------------------------------------
...
-----------------------------------------------
[2] STEP: validate_transformer - Failed
-----------------------------------------------

エラーブロック 各ステップの後には、構造化された詳細を含む Errors ブロックが続きます。

エラーがない場合:
> Errors (None)

ステップがエラーになった場合:

> Errors
  Id: ByocErrorId.TRANSFORMERS_VERSION_ERROR
  Responsible: ByocErrorOwner.USAGE
  Reason: The transformers version of your checkpoint (4.52.4) is larger than the maximum supported transformers version (4.45.1).
  Suggestion: To fix this, please save your checkpoint with a transformers environment <= 4.45.1. Alternatively, you can include the --ignore_transformers_version flag, but this may lead to errors due to transformers version compatibility issues.

  Stack Trace:
    ...

最終ステータス行 ログの末尾には、成功または失敗のメッセージが表示されます。

2025-08-25T17:49:10UTC - byoc_lib - ERROR - One or more failures have occurred. Do not deploy

エラーブロックの構成要素

ステップが失敗した場合、各エラーブロックには以下のフィールドが含まれます。

フィールド	説明
`Id`	コンテナを調査する際に、失敗した特定のチェックやプロセスを追跡するために使用できるマーカー。
`Responsible`	エラーがユーザー側で解決できるもの (`ByocErrorOwner.USAGE`) か、変換ツール自体の問題 (`ByocErrorOwner.LIBRARY`) かを示します。
`Reason`	何が問題であった可能性があるかについての、人間が読める形式の説明。
`Suggestion`	エラーの修正または切り分けに使用できる推奨対応。
`Stack Trace`	エラーの発生箇所を特定するのに役立ちます。

よくあるエラーと解決方法

エラー ID	原因	解決方法
`TRANSFORMERS_VERSION_ERROR`	チェックポイントが、サポートされているものより新しい Transformers バージョンで保存された	Transformers 4.45.1 以下でチェックポイントを保存し直すか、`--ignore_transformers_version` フラグを使用してください
メモリ不足 (OOM)	チェックポイントのサイズに対してシステムメモリが不足している	利用可能なメモリをチェックポイントサイズの 2.5 倍以上に増やしてください
ファイルの欠落	チェックポイントディレクトリが不完全	必要なファイル (config.json、safetensors、トークナイザーファイル) がすべて存在することを確認してください

次のステップ

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

変換済みチェックポイントを GCS バケットにアップロードする
モデルマニフェスト (Model Manifest) にチェックポイントを登録する
Bundle 構成を使用してチェックポイントをデプロイする

完全なワークフローについては、カスタムチェックポイントのデプロイをご参照ください。投機的デコーディングを使用するデプロイについては、ドラフト/ターゲットの検証とデプロイ手順を解説した投機的デコーディングによるデプロイをご参照ください。

はじめに

サービス管理

ハードウェア管理

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

リソース

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

概要

前提条件

システム要件

変換時間の目安

必要なソフトウェア

必要なアクセス権

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

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

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

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

互換性の具体例

ダウンロードとセットアップ

Docker Desktop または Docker Engine のインストール

Google Cloud CLI のインストール

認証とコンテナイメージの取得

モデルメタデータの同期

コマンドテンプレート

パラメータ

チェックポイントの変換と検証

コマンドテンプレート

パラメータ

ホスト側の変数

変換出力の検証

チェックリスト

変換成功時のログ

変換失敗時のログ

出力ログの読み方とトラブルシューティング

ログ構造の概要

出力ログの例

ログの構成要素の解説

エラーブロックの構成要素

よくあるエラーと解決方法

次のステップ

​概要

​前提条件

​システム要件

​変換時間の目安

​必要なソフトウェア

​必要なアクセス権

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

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

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

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

​互換性の具体例

​ダウンロードとセットアップ

Docker Desktop または Docker Engine のインストール

Google Cloud CLI のインストール

認証とコンテナイメージの取得

モデルメタデータの同期

​コマンドテンプレート

​パラメータ

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

​コマンドテンプレート

​パラメータ

​ホスト側の変数

​変換出力の検証

​チェックリスト

​変換成功時のログ

​変換失敗時のログ

​出力ログの読み方とトラブルシューティング

​ログ構造の概要

​出力ログの例

​ログの構成要素の解説

​エラーブロックの構成要素

​よくあるエラーと解決方法

​次のステップ

概要

前提条件

システム要件

変換時間の目安

必要なソフトウェア

必要なアクセス権

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

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

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

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

互換性の具体例

ダウンロードとセットアップ

コマンドテンプレート

パラメータ

チェックポイントの変換と検証

コマンドテンプレート

パラメータ

ホスト側の変数

変換出力の検証

チェックリスト

変換成功時のログ

変換失敗時のログ

出力ログの読み方とトラブルシューティング

ログ構造の概要

出力ログの例

ログの構成要素の解説

エラーブロックの構成要素

よくあるエラーと解決方法

次のステップ