> ## 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.

# カスタムチェックポイントのデプロイ

SambaStack では、独自のカスタムチェックポイントやファインチューニング済みのチェックポイントを、[標準提供モデルのデプロイ](/docs/ja/v2.1.1/sambastack/service-administration/model-deployment/deploying-models-and-bundles/deploy-a-bundle.md)と同じ方法で推論用にデプロイできます。必要なのは、チェックポイントをプラットフォームで使用できるように準備するためのいくつかの追加ステップだけです。準備とデプロイが完了すれば、カスタムチェックポイントは SambaStack にデプロイする他のチェックポイントとまったく同じように動作します。

本ページで作成するリソースのフィールドリファレンスについては、**カスタムリソース**配下の [Model](/docs/ja/v2.1.1/sambastack/service-administration/model-deployment/custom-resources/model.md) と [PEF](/docs/ja/v2.1.1/sambastack/service-administration/model-deployment/custom-resources/pef.md) をご覧ください。

## 概要

カスタムチェックポイントのデプロイは、大きく分けて次の 4 つの作業で構成されます。

1. [チェックポイント変換ツール](/docs/ja/v2.1.1/sambastack/service-administration/model-deployment/checkpoint-conversion-tool.md)を使用して、**チェックポイントを SambaNova 互換形式に変換**する。
2. SambaNova から提供されたサービスアカウントに読み取り権限を付与したプライベートな Google Cloud Storage バケットに**変換済みチェックポイントをアップロード**する。または、クラスターから読み取り可能な NFS 上に配置する。
3. 既存モデルが使用するチェックポイントをオーバーライドするか、新しい `Model` リソースを登録して、**チェックポイントを参照**する。
4. `ModelDeployment` または `ModelBundle` で、モデルを互換性のある `ModelProfile` と組み合わせて**デプロイ**する。

> [!NOTE]
>
> このワークフローを開始する前に、チェックポイントの変換プロセスを完了しておいてください。手順は[チェックポイント変換ツール](/docs/ja/v2.1.1/sambastack/service-administration/model-deployment/checkpoint-conversion-tool.md)のページをご参照ください。

## 前提条件

カスタムチェックポイントをデプロイする前に、以下を準備してください。

* SambaNova 互換形式に変換済みのチェックポイント ([チェックポイント変換ツール](/docs/ja/v2.1.1/sambastack/service-administration/model-deployment/checkpoint-conversion-tool.md)を参照)
* NFS マウント済みのストレージ、または Google Cloud Storage (GCS) バケットへのアクセス
* SambaNova から提供されたサービスアカウントの JSON ファイル
* SambaStack クラスターにアクセスできるように構成された `kubectl`
* モデルプロファイルとモデルバンドルを含む、[モデルデプロイメントの各リソース](/docs/ja/v2.1.1/sambastack/service-administration/model-deployment/deploying-models-and-bundles/overview)の理解

## カスタムチェックポイントの対応モデル

カスタムチェックポイントのデプロイは、SambaStack の拡大を続けるベースモデル群でサポートされています。カスタムチェックポイントに対応するモデルは、[対応モデルとバンドル](/docs/ja/v2.1.1/sambastack/service-administration/model-deployment/supported-models-and-bundles.md)の表でご確認ください。

## カスタムチェックポイントのデプロイ手順

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

カスタムチェックポイントやファインチューニング済みのチェックポイントは、デプロイする前に、SambaNova の SN40L ハードウェアに最適化された形式に変換する必要があります。SambaNova は、ローカルで実行できる Docker コンテナとして**チェックポイント変換ツール**を提供しています。このツールは変換済みチェックポイントのアーティファクトを生成し、それを SambaStack にアップロードして推論用にデプロイできます。

まず、チェックポイント変換ツールのドキュメントの[**ダウンロードとセットアップ**](/docs/ja/v2.1.1/sambastack/service-administration/model-deployment/checkpoint-conversion-tool.md#ダウンロードとセットアップ)セクションの手順に従ってください。変換ツールのコンテナをダウンロードし、お使いの SambaStack インスタンスとモデルメタデータを同期すればセットアップは完了です。

セットアップ後、チェックポイント変換ツールのドキュメントの[**チェックポイントの変換と検証**](/docs/ja/v2.1.1/sambastack/service-administration/model-deployment/checkpoint-conversion-tool.md#チェックポイントの変換と検証)セクションに記載された手順で、カスタムチェックポイントを SambaNova 互換形式に変換します。

### 2. GCS バケットの権限設定

> [!NOTE]
>
> **クラスターに NFS がマウントされている場合、このセクションはスキップできます。**

SambaStack は、チェックポイントやその他の SambaStack アーティファクトの保存に Google Cloud Storage (GCS) を使用します。カスタムチェックポイントの場合、変換済みチェックポイントのアーティファクトは**ご自身の** GCS バケットに保存します。デプロイ時に SambaStack がこれらのアーティファクトを利用できるようにするには、SambaNova から提供されたサービスアカウントにバケットへの読み取りアクセス権が必要です。

> [!NOTE]
>
> これは一度だけ行うセットアップ手順です。権限を設定した後は、任意の数のカスタムチェックポイントをバケットにアップロードし、デプロイで直接使用できます。

### サービスアカウントの確認

サービスアカウントの情報は JSON ファイルとして提供されます。`client_email` フィールドを確認してください。これが、バケットへの読み取りアクセス権を必要とする ID です。例:

```json theme={}
{
  "type": "service_account",
  "project_id": "example-project-id",
  "private_key_id": "example-private-key-id",
  "private_key": "-----BEGIN PRIVATE KEY-----\n<private key contents>\n-----END PRIVATE KEY-----\n",
  "client_email": "ss-artifacts-reader@example-project-id.iam.gserviceaccount.com",
  "client_id": "12345678901234567890",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/ss-artifacts-reader%40example-project-id.iam.gserviceaccount.com",
  "universe_domain": "googleapis.com"
}
```

### Storage Object Viewer ロールの付与

SambaStack がカスタムチェックポイントにアクセスできるようにするには、サービスアカウントに対して、バケットの **Storage Object Viewer** ロールを付与します。これにより、書き込みや変更を許可せず、オブジェクトへの読み取り専用アクセスのみが可能になります。

**Google Cloud Console を使用する場合:**

1. **Google Cloud Console** を開きます。
2. **Storage → Buckets** に移動し、使用するバケットを選択します。
3. **Permissions** タブに移動します。
4. **+ Add principal** をクリックします。
5. 「New principals」フィールドに、サービスアカウントの `client_email` を入力します。
6. 「Role」ドロップダウンで **Cloud Storage → Storage Object Viewer** を選択します。
7. **Save** をクリックします。

**gcloud CLI を使用する場合:**

以下のコマンドを実行する前に、次の値を確認してください。

* `<BUCKET_NAME>` – GCS バケットの名前
* `<SERVICE_ACCOUNT_EMAIL>` – サービスアカウントの JSON に記載された `client_email` の値
* `<PROJECT_ID>` – バケットを所有する Google Cloud プロジェクト

バケットレベルで **Storage Object Viewer** ロールを付与するには:

```bash theme={}
gcloud storage buckets add-iam-policy-binding gs://<BUCKET_NAME> \
    --member="serviceAccount:<SERVICE_ACCOUNT_EMAIL>" \
    --role="roles/storage.objectViewer" \
    --project=<PROJECT_ID>
```

ロールが正常に適用されたことを確認するには:

```bash theme={}
gcloud storage buckets get-iam-policy gs://<BUCKET_NAME> \
    --project=<PROJECT_ID>
```

次のようなエントリが表示されるはずです。

```yaml theme={}
bindings:
- members:
  - serviceAccount:<SERVICE_ACCOUNT_EMAIL>
  role: roles/storage.objectViewer
```

詳細については、Google の IAM ドキュメントをご参照ください。

* [Google Cloud: リソースへのアクセス権の付与、変更、取り消し](https://cloud.google.com/iam/docs/granting-changing-revoking-access)
* [Google Cloud Storage の IAM ロール](https://cloud.google.com/storage/docs/access-control/iam-roles)

### 3. 変換済みチェックポイントのアップロード

### NFS

クラスターに NFS がマウントされている場合は、変換済みチェックポイントが NFS に移動され、クラスターからアクセスできることを確認してください。

### Google Cloud Storage

Google Cloud Storage (GCS) を使用している場合は、チェックポイントの変換後、変換済みチェックポイントのファイルを含むディレクトリを GCS バケットにアップロードします。

> [!NOTE]
>
> このステップは、チェックポイントのサイズによっては時間がかかることがあります。

**Google Cloud Console を使用する場合:**

1. **Google Cloud Console** を開きます。
2. **Storage → Buckets** に移動し、カスタムチェックポイント用に設定したバケットを選択します。
3. **Upload folder** (または、構成によっては **Upload files**) をクリックします。
4. 変換済みチェックポイントのアーティファクトを含むディレクトリを選択します。
5. アップロードの完了を待ちます。ディレクトリ構造はそのまま維持される必要があります。

**gcloud CLI を使用する場合:**

変換済みチェックポイントのディレクトリ全体を再帰的にアップロードするには、次を実行します。

```bash theme={}
gcloud storage cp -r <LOCAL_CONVERTED_CHECKPOINT_DIR> gs://<BUCKET_NAME>/<DESTINATION_PREFIX>/
```

### 4. チェックポイントの参照

チェックポイントをサービング可能にする方法は 2 つあり、既存のモデル名を維持するか、新しい名前でチェックポイントをサービングするかによって使い分けます。

### 方法 1: 既存モデルのチェックポイントをオーバーライドする

既存モデルの名前を再利用し、そのモデルが通常使用するチェックポイントの代わりにカスタムチェックポイントをサービングする場合に使用します。新しい `Model` リソースは不要です。`ModelBundle` または `ModelDeployment` のモデル構成に `checkpointOverrides` を設定します。

```yaml theme={}
spec:
  modelConfigs:
  - model: meta-llama-3-1-8b-instruct:1
    profile: llama-3p1-8b
    modelSettings:
      checkpointOverrides:
        checkpoint:
          source: gs://<BUCKET_NAME>/path/to/converted/checkpoint
          checkpoint_status: stable
          tool_support: false
```

リクエストでは、引き続き既存モデルのサービング名を使用します。対応モデルのファインチューニング版をサービングする場合は、この方法を推奨します。

### 方法 2: 新しい Model リソースを登録する

チェックポイントを**独自の**モデル名でサービングする場合に使用します。例えば、別のモデルからファインチューニングしたチェックポイントを、推論 API で個別の名前でアクセスできるようにしたい場合です。この方法では、新しい `Model` リソースの作成が必要です。

組み合わせる予定のプロファイルと互換性のあるアーキテクチャキーを使用して `spec.checkpoints.<arch>` を設定し、`source` に変換済みチェックポイントの場所を、`spec.tokenizer.path` にチェックポイントの派生元であるベースモデルのトークナイザーを設定します。

```yaml theme={}
apiVersion: sambanova.ai/v1alpha1
kind: Model
metadata:
  name: my-custom-llama-3-1-8b   # must be a valid Kubernetes resource name
spec:
  name: my-custom-llama-3-1-8b   # serving name used in the inference API
  owner: jane@doe.ai
  public: true
  aliases:
  - My-Custom-Llama3.1-8B
  checkpoints:
    llama3:
      versions:
        "1":
          source: gs://<BUCKET_NAME>/path/to/converted/checkpoint
          checkpoint_status: stable
          tool_support: false
  tokenizer:
    path: ./Meta-Llama-3.1-8B-Instruct_tokenizer
  metadata:
    capabilities:
    - text
```

この例のアーキテクチャキー `llama3` は説明用の例です。使用する予定のプロファイルの `model_arch` と一致するキーを使用してください。全フィールドのリファレンスは、[Model](/docs/ja/v2.1.1/sambastack/service-administration/model-deployment/custom-resources/model.md) をご覧ください。

> [!NOTE]
>
> `tokenizer` フィールドは、生成の前に入力のチェックを実行してシーケンス長の要件を計算するためにのみ使用されます。チェックポイントのファインチューニング元であるベースモデルのトークナイザーを設定してください。

リソースを適用します。

**Hosted**

```bash theme={}
kubectl apply -f <model-file>.yaml
```

**On Premise**

```bash theme={}
kubectl -n <namespace> apply -f <model-file>.yaml
```

### 5. チェックポイントのデプロイ

チェックポイントのアーキテクチャと互換性のある `model_arch` を持つ `ModelProfile` とモデルを組み合わせたうえで、直接またはバンドル経由でデプロイします。

> [!WARNING]
>
> チェックポイントとプロファイルの互換性は `model_arch` によって決まりますが、オペレーターはこれを検証しません。サービングするチェックポイントとアーキテクチャが一致するプロファイルを選択してください。不一致があると推論エラーが発生します。

互換性のあるプロファイルを見つけるには、クラスター内のプロファイルを一覧表示し、それぞれの `model_arch` を確認します。

**Hosted**

```bash theme={}
kubectl get modelprofiles
```

**On Premise**

```bash theme={}
kubectl -n <namespace> get modelprofiles.sambanova.ai
```

その後、デプロイします。単一モデルの場合は、`ModelDeployment` にインラインで記述します。

```yaml theme={}
apiVersion: sambanova.ai/v1alpha1
kind: ModelDeployment
metadata:
  name: md-my-custom-llama-3-1-8b
spec:
  models:
    modelConfigs:
    - model: my-custom-llama-3-1-8b:1
      profile: llama-3p1-8b
  groups:
  - minReplicas: 1
    name: default
    qosList:
    - free
  owner: jane@doe.ai
  secretNames:
  - sambanova-artifact-reader
```

適用します。

**Hosted**

```bash theme={}
kubectl apply -f <modeldeployment-file>.yaml
```

**On Premise**

```bash theme={}
kubectl -n <namespace> apply -f <modeldeployment-file>.yaml
```

複数のモデルをバンドルにまとめる方法を含む、デプロイオプションの全体像は、[バンドルのデプロイ](/docs/ja/v2.1.1/sambastack/service-administration/model-deployment/deploying-models-and-bundles/deploy-a-bundle.md) をご覧ください。

> [!TIP]
>
> デプロイの稼働後は、定義したサービング名 (例: `my-custom-llama-3-1-8b`) を推論 API リクエストで使用してください。

## カスタムモデルアーキテクチャの追加

モデルアーキテクチャがまだサポートされていない場合、そのアーキテクチャ用のコンパイル済み実行ファイルもプロファイルも存在しないため、以下の順序で一連のリソースをすべて作成する必要があります。

| 順序 | リソース | 目的 |
| - | - | - |
| 1 | `Pef` | 新しいアーキテクチャ用にコンパイルされた PEF を登録します。`spec.metadata.model_arch`、バッチサイズ、最大シーケンス長、機能サポートのフラグを含みます。 |
| 2 | `ModelProfile` | 新しい PEF を `spec.pefs` に列挙し、新しい `model_arch` の値を公開し、アーキテクチャのデフォルトのバッチングサポートを定義します。 |
| 3 | `Model` | PEF と同じアーキテクチャキーの下にチェックポイントのソースを保持し、トークナイザーのパスもあわせて保持します。 |
| 4 | `ModelDeployment` | モデルを直接、または `ModelBundle` 経由でデプロイします。 |

新しいアーキテクチャ用に PEF をコンパイルし、それを登録する `Pef` リソースを作成する必要があります。PEF のコンパイル方法は本ページでは扱いません。

各リソースの値を決める際は、最も近い対応モデルのリソースを参考にしてください。

**Hosted**

```bash theme={}
kubectl get pef <pef-name> -o yaml
kubectl get modelprofile <profile-name> -o yaml
kubectl get model <model-name> -o yaml
```

**On Premise**

```bash theme={}
kubectl -n <namespace> get pef.sambanova.ai <pef-name> -o yaml
kubectl -n <namespace> get modelprofile.sambanova.ai <profile-name> -o yaml
kubectl -n <namespace> get model.sambanova.ai <model-name> -o yaml
```

## デプロイの確認

デプロイメントを適用したら、カスタムチェックポイントのデプロイが成功したことを確認します。

1. **デプロイ状態の確認:**

   ```bash theme={}
   kubectl get modeldeployments
   kubectl describe modeldeployment <your-deployment-name>
   ```
2. **モデルが利用可能であることの確認:**

   ```bash theme={}
   kubectl get models
   ```

   > [!NOTE]
   >
   > このコマンドが一覧表示するのは Kubernetes のリソース名 (`metadata.name`) です。リクエストで使用する必要があるのは `spec.name` に設定したサービング名であり、両者は異なることがよくあります。
3. `spec.name` のサービング名を使用して、**サンプルの推論リクエストでテスト**します。
   SambaNova SDK、OpenAI 互換ライブラリ、CURL を使用した推論リクエストの例については、[開発者向けクイックスタートガイド](/docs/ja/get-started/quickstart.md)をご参照ください。

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

### よくある問題

| 問題 | 考えられる原因 | 解決方法 |
| - | - | - |
| 権限エラーでデプロイが失敗する | サービスアカウントに GCS バケットへの読み取りアクセス権がない | Storage Object Viewer ロールが付与されていることを確認してください (ステップ 2 を参照) |
| API リクエストでモデルが見つからない | モデル名の不一致、またはモデルがルーティング不可 | リクエストで `Model` リソースの `spec.name` を使用していること、および `modelSettings.routable` が `false` に設定されていないことを確認してください |
| チェックポイントファイルが見つからない | チェックポイントのパスが誤っている | `source` パスが、アップロードしたチェックポイントの場所と一致していることを確認してください |
| 推論エラー | チェックポイントがプロファイルと互換でない | プロファイルの `model_arch` が、カスタムチェックポイントのアーキテクチャと互換であることを確認してください |

### GCS アクセスの確認

権限の問題が疑われる場合は、サービスアカウントがチェックポイントにアクセスできることを確認してください。

```bash theme={}
gcloud auth activate-service-account --key-file=<path-to-service-account-json>
gsutil ls gs://<BUCKET_NAME>/<CHECKPOINT_PATH>/
```

## 次のステップ

* 本ページで作成するリソースについては、[Model](/docs/ja/v2.1.1/sambastack/service-administration/model-deployment/custom-resources/model.md)、[PEF](/docs/ja/v2.1.1/sambastack/service-administration/model-deployment/custom-resources/pef.md)、および[デプロイの概要](/docs/ja/v2.1.1/sambastack/service-administration/model-deployment/deploying-models-and-bundles/overview)をご参照ください。
* 投機的デコーディングを使用してカスタムチェックポイントをデプロイするには、[投機的デコーディングによるデプロイ](/docs/ja/v2.1.1/sambastack/service-administration/performance/deploy-with-speculative-decoding.md)をご参照ください。
* 監視とモニタリングについては、[SambaStack の監視](/docs/ja/v2.1.1/sambastack/reference-architecture/observability/overview.md)をご参照ください。
* カスタムチェックポイントがベースモデルと異なるチャットテンプレートやツール呼び出しの出力形式を使用する場合は、クライアント側でのプロンプト整形と出力解析の方法について、開発者ガイドの[カスタムチャットテンプレートと出力解析](/docs/ja/build/chat-templates.md)をご参照ください。