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

SambaStack では、独自のカスタムチェックポイントやファインチューニング済みのチェックポイントを、標準提供モデルのデプロイと同じ方法で推論用にデプロイできます。必要なのは、チェックポイントをプラットフォームで使用できるように準備するためのいくつかの追加ステップだけです。準備とデプロイが完了すれば、カスタムチェックポイントは SambaStack にデプロイする他のチェックポイントとまったく同じように動作します。本ページで作成するリソースのフィールドリファレンスについては、カスタムリソース配下の Model と PEF をご覧ください。

概要

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

お使いのモデルファミリーに対応するチェックポイント変換パッケージを使用して、チェックポイントを SambaNova 互換形式に変換する。
SambaNova から提供されたサービスアカウントに読み取り権限を付与したプライベートな Google Cloud Storage バケットに変換済みチェックポイントをアップロードする。または、クラスターから読み取り可能な NFS 上に配置する。
既存モデルが使用するチェックポイントをオーバーライドするか、新しい Model リソースを登録して、チェックポイントを参照する。
ModelDeployment または ModelBundle で、モデルを互換性のある ModelProfile と組み合わせてデプロイする。

このワークフローを開始する前に、チェックポイントの変換プロセスを完了しておいてください。手順はチェックポイント変換ツールのページをご参照ください。

前提条件

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

SambaNova 互換形式に変換済みのチェックポイント (チェックポイント変換ツールを参照)
NFS マウント済みのストレージ、または Google Cloud Storage (GCS) バケットへのアクセス
SambaNova から提供されたサービスアカウントの JSON ファイル
SambaStack クラスターにアクセスできるように構成された kubectl
モデルプロファイルとモデルバンドルを含む、モデルデプロイメントの各リソースの理解

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

カスタムチェックポイントのデプロイは、一部の例外を除き、SambaStack のすべての decoder-only のテキスト生成モデルでサポートされています。例外の一覧と、各モデルファミリーに対応する変換パッケージについては、対応モデルとバンドルをご確認ください。

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

チェックポイントの変換

カスタムチェックポイントやファインチューニング済みのチェックポイントは、デプロイする前に、SambaNova の SN40L ハードウェアに最適化された形式に変換する必要があります。SambaNova は対応モデルファミリーごとに変換パッケージを提供しており、お使いの SambaStack アーティファクトレジストリからインストールしてローカルで実行します。変換パッケージのインストールの手順でお使いのモデルファミリー用のパッケージをインストールし、続いてチェックポイントの変換の手順で変換済みアーティファクトを生成します。アップロードする前に、変換結果の検証の手順で変換が成功したことを確認してください。

GCS バケットの権限設定

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

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

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

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

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

{
  "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 を使用する場合:

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

gcloud CLI を使用する場合:以下のコマンドを実行する前に、次の値を確認してください。

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

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

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

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

gcloud storage buckets get-iam-policy gs://<BUCKET_NAME> \
    --project=<PROJECT_ID>

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

bindings:
- members:
  - serviceAccount:<SERVICE_ACCOUNT_EMAIL>
  role: roles/storage.objectViewer

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

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

NFS

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

Google Cloud Storage

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

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

Google Cloud Console を使用する場合:

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

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

gcloud storage cp -r <LOCAL_CONVERTED_CHECKPOINT_DIR> gs://<BUCKET_NAME>/<DESTINATION_PREFIX>/

チェックポイントの参照

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

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

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

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 にチェックポイントの派生元であるベースモデルのトークナイザーを設定します。

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 をご覧ください。

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

リソースを適用します。

Hosted
On Premise

kubectl apply -f <model-file>.yaml

kubectl -n <namespace> apply -f <model-file>.yaml

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

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

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

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

Hosted
On Premise

kubectl get modelprofiles

kubectl -n <namespace> get modelprofiles.sambanova.ai

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

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
On Premise

kubectl apply -f <modeldeployment-file>.yaml

kubectl -n <namespace> apply -f <modeldeployment-file>.yaml

複数のモデルをバンドルにまとめる方法を含む、デプロイオプションの全体像は、バンドルのデプロイをご覧ください。

デプロイの稼働後は、定義したサービング名 (例: 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
On Premise

kubectl get pef <pef-name> -o yaml
kubectl get modelprofile <profile-name> -o yaml
kubectl get model <model-name> -o yaml

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

デプロイの確認

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

デプロイ状態の確認:

kubectl get modeldeployments
kubectl describe modeldeployment <your-deployment-name>

モデルが利用可能であることの確認:
kubectl get models
このコマンドが一覧表示するのは Kubernetes のリソース名 (metadata.name) です。リクエストで使用する必要があるのは spec.name に設定したサービング名であり、両者は異なることがよくあります。
spec.name のサービング名を使用して、サンプルの推論リクエストでテストします。 SambaNova SDK、OpenAI 互換ライブラリ、CURL を使用した推論リクエストの例については、開発者向けクイックスタートガイドをご参照ください。

トラブルシューティング

よくある問題

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

GCS アクセスの確認

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

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

次のステップ

本ページで作成するリソースについては、Model、PEF、およびデプロイの概要をご参照ください。
監視とモニタリングについては、SambaStack の監視をご参照ください。
カスタムチェックポイントがベースモデルと異なるチャットテンプレートやツール呼び出しの出力形式を使用する場合は、クライアント側でのプロンプト整形と出力解析の方法について、開発者ガイドのカスタムチャットテンプレートと出力解析をご参照ください。

Get started

Models

Features

Build

Resources

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

概要

前提条件

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

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

チェックポイントの変換

GCS バケットの権限設定

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

Storage Object Viewer ロールの付与

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

NFS

Google Cloud Storage

チェックポイントの参照

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

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

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

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

デプロイの確認

トラブルシューティング

よくある問題

GCS アクセスの確認

次のステップ

​概要

​前提条件

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

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

チェックポイントの変換

GCS バケットの権限設定

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

​Storage Object Viewer ロールの付与

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

​NFS

​Google Cloud Storage

チェックポイントの参照

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

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

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

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

​デプロイの確認

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

​よくある問題

​GCS アクセスの確認

​次のステップ

概要

前提条件

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

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

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

Storage Object Viewer ロールの付与

NFS

Google Cloud Storage

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

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

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

デプロイの確認

トラブルシューティング

よくある問題

GCS アクセスの確認

次のステップ