> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sambanova.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

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

チェックポイント変換パッケージは、HuggingFace 形式のチェックポイントを、SambaRack および SambaCloud システムへのデプロイに必要な SambaNova 互換形式に変換します。

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

<Note>
  チェックポイント変換は、SambaStack または SambaCloud にカスタムチェックポイントをデプロイする際の 1 つのサブステップです。全体のワークフローについては、[カスタムチェックポイントのデプロイ](/docs/ja/sambastack/service-administration/model-deployment/deploying-models-and-bundles/deploy-custom-checkpoints)のページをご参照ください。
</Note>

## 前提条件

### システム要件

| 要件 | 仕様 |
| - | - |
| **メモリ** | チェックポイントの 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 時間 |

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

### 必要なソフトウェア

* **Python** 3.11 以降 (`pip` を含む)
* **Google Cloud CLI** - [インストールガイド](https://cloud.google.com/sdk/docs/install)

### 必要なアクセス権

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

<Note>
  SambaNova がホストするレジストリおよびチェックポイントストレージへのアクセスは読み取り専用です。変換パッケージはレジストリから取得し、変換後のチェックポイントはご自身で管理するストレージに書き込みます。詳細は[カスタムチェックポイントのデプロイ](/docs/ja/sambastack/service-administration/model-deployment/deploying-models-and-bundles/deploy-custom-checkpoints)をご参照ください。
</Note>

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

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

カスタムチェックポイントは、decoder-only のテキスト生成モデルでサポートされています。対象のモデルファミリーがサポートされているかどうかと現時点の例外については、[対応モデル](/docs/ja/sambastack/service-administration/model-deployment/supported-models-and-bundles)のページをご確認ください。

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

チェックポイントは HuggingFace 形式で受け付けられます。テンソルは safetensors 形式であり、チェックポイントディレクトリには、カスタムチェックポイントのベースモデルと同じ関連設定ファイルが含まれている必要があります。

例えば、カスタムチェックポイントが [meta-llama/Llama-3.3-70B-Instruct](https://huggingface.co/meta-llama/Llama-3.3-70B-Instruct/tree/main) のファインチューニング済み派生モデルである場合、チェックポイントディレクトリには以下のようなファイルが含まれている必要があります。

| ファイル | 説明 |
| - | - |
| `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` など)

**変更可能な要素:**

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

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

### 互換性の具体例

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

* [deepseek-ai/DeepSeek-R1-Distill-Llama-70B](https://huggingface.co/deepseek-ai/DeepSeek-R1-Distill-Llama-70B)
* [tokyotech-llm/Llama-3.3-Swallow-70B-Instruct-v0.4](https://huggingface.co/tokyotech-llm/Llama-3.3-Swallow-70B-Instruct-v0.4)

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

## 変換パッケージの選択

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

| ベースモデル | パッケージ | コマンド |
| - | - | - |
| 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` |

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

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

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

<Steps>
  <Step stepNumber={1} titleSize="h3" title="Google Cloud CLI のインストールと認証">
    変換を実行する環境に、公式の [Google Cloud CLI インストール](https://cloud.google.com/sdk/docs/install)ガイドに従って Google Cloud CLI をインストールし、認証を行います。

    ```bash theme={} theme={}
    gcloud auth login
    ```

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

  <Step stepNumber={2} titleSize="h3" title="パッケージのインストール">
    `pip` がレジストリから読み取れるようにする認証バックエンドをインストールし、続いてお使いのモデルファミリー用のパッケージをインストールします。

    ```bash theme={} theme={}
    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` コマンドを使用しています。

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

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

  <Step stepNumber={3} titleSize="h3" title="インストールの確認">
    ```bash theme={} theme={}
    sn-convert-llama --help
    ```

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

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

### コマンド

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

```bash theme={} theme={}
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` | 指定した操作に効果がなかった場合に失敗させます。[変換結果の検証](#変換結果の検証)をご参照ください。 |

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

### 変換設定

各パッケージは独自の設定を宣言しており、ベースモデルに一致するチェックポイントに対してはデフォルト値のままで正しく動作します。`--print-plan` を使うと、実行時に解決された設定を確認できます。

設定のオーバーライドには `--set` を使用します。ブール値の設定は `+` または `-` のプレフィックスを付け、それ以外は `key=value` 形式で指定します。

```bash theme={} theme={}
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` | 変更のないシャードをコピーする代わりにシンボリックリンクにします。デフォルトでは無効です。下記の警告をご参照ください。 |

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

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

## 変換結果の検証

### 出力の確認

変換が成功すると、変換後の safetensors シャード、更新された `model.safetensors.index.json`、および `sn_checkpoint_conversion_metadata.json` がターゲットディレクトリに書き込まれ、終了コード 0 で終了します。

`sn_checkpoint_conversion_metadata.json` には、各操作の実行内容が記録されます。変換は成功したのに出力に問題がありそうな場合は、このファイルを確認してください。

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

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

```bash theme={} theme={}
sn-convert-llama -s /path/to/checkpoint -t /path/to/converted --strict-ops
```

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

### PEF との照合

各 PEF には `<pef_stem>_coe_meta.json` というマニフェストが同梱されており、コンパイル済みモデルが期待するすべてのテンソルが、その形状と dtype とともに記載されています。

マニフェストを取得するには、[PEF リソース](/docs/ja/sambastack/service-administration/model-deployment/custom-resources/pef)で PEF のストレージパス (`spec.versions.<version>.source`) を確認します。マニフェストは同じフォルダーにあり、PEF ファイル名から `.pef` 拡張子を除いた名前が付けられています。

```bash theme={} theme={}
kubectl get pef <pef-name> -o yaml
gcloud storage cp gs://<path>/<pef_stem>_coe_meta.json .
```

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

```bash theme={} theme={}
python -m sn_checkpoint_surgery.coe_meta_validation \
    /path/to/<pef_stem>_coe_meta.json \
    /path/to/converted
```

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

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

### 変換後の注意点

変換は 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` を使用してください。

## 次のステップ

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

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

完全なワークフローについては、[カスタムチェックポイントのデプロイ](/docs/ja/sambastack/service-administration/model-deployment/deploying-models-and-bundles/deploy-custom-checkpoints)をご参照ください。