SambaStack モデルバンドルのデプロイ

SambaStack は、バンドルをデプロイすることでモデルを提供します。バンドルとは、1 つ以上のモデルを、バッチサイズやシーケンス長を含むデプロイ構成と共にまとめたパッケージです。これにより、多数のモデルを同時に提供でき、重みを再ロードすることなくモデル間を即座に切り替えられます。このアプローチは、単一の静的なモデルをロードする従来の GPU デプロイと比較して、効率性、柔軟性、スループットを向上させます。例えば、1 つのバンドルに Llama-3.3-70B-Instruct と Llama-3.1-8B-Instruct を含めることで、両者をほぼ瞬時に切り替えられます。バンドル内のモデルの各構成はそれぞれ容量を消費するため、バンドルごとに含まれる構成のセットは異なります。例えば、バッチサイズ 4、シーケンス長 16K の Llama-3.3-70B-Instruct は 1 つの構成に相当します。ユースケースに基づいて、最適なバンドルを選択できます。現在の一覧は対応モデルとバンドルのページをご参照ください。

構成 (configuration) とは、バッチサイズやシーケンス長を含む、モデルデプロイのランタイム設定を定義するものです。1 つのデプロイメントに複数の構成を含めることができ、構成間の即時切り替えによって最適化されたパフォーマンスを実現します。

概念

バンドルテンプレート

バンドルテンプレートは、1 つのノード上でどのモデルと構成を一緒にデプロイできるかを定義します。各バンドルテンプレートには 1 つ以上のモデルテンプレートが含まれ、それぞれがサポートされるシーケンス長とバッチサイズを指定します。 BundleTemplate 内でモデルテンプレートがどのように定義されるかの詳細な例は、カスタムバンドルのデプロイ → BundleTemplate の構造をご参照ください。 モデルテンプレートの例:

モデルテンプレート	サポートされるシーケンス長	サポートされるバッチサイズ
`DeepSeek-R1-0528-Template`	4k, 8k	1, 2, 4, 8
`DeepSeek-V3-0324-Template`	4k, 8k	1, 2, 4, 8

バンドルテンプレートの例: deepseek-r1-v3-fp8-32k-Template は、DeepSeek-R1-0528-Template と DeepSeek-V3-0324-Template の両方を 1 つのデプロイ可能なパッケージにまとめます。 BundleTemplate 定義の完全な YAML の例は、カスタムバンドルのデプロイ → BundleTemplate の構造セクションをご参照ください。

バンドル

バンドルは、学習済みのチェックポイント (モデルの重み) を、バンドルテンプレートで定義されたモデルテンプレートに関連付けたものです。例えば、バンドル deepseek-r1-v3-fp8-32k は、R1-0528 チェックポイントと V3-0324 チェックポイントを、deepseek-r1-v3-fp8-32k-Template 内の対応するモデルテンプレートにリンクします。

主要用語

用語	定義
バンドル (Bundle)	モデル、チェックポイント、構成を組み合わせたデプロイ可能なパッケージ
エキスパート (Expert)	特定のシーケンス長に紐づいたモデルインスタンス (例: `DeepSeek-R1-Distill-Llama-70B-4K`)
エキスパート構成 (Expert config)	特定のバッチサイズを持つエキスパート (例: `DeepSeek-R1-Distill-Llama-70B-4k-BS2`)

バンドルの設定

sambastack.yaml 設定ファイルの bundles セクションには、2 つのサブセクションがあります。

サブセクション	目的
`bundleSpecs`	どのバンドルをデプロイ可能にするかを宣言します。これによりバンドルがシステムに登録されますが、この時点ではまだデプロイされません。
`bundleDeploymentSpecs`	レプリカ数や QoS レベルを含め、クラスター全体でバンドルをどのようにデプロイするかを定義します。

カスタムバンドルについては、カスタムバンドルのデプロイをご参照ください。 設定例:

bundles:
  bundleSpecs:
    - name: gpt-oss-120b-8-32-64-128k

  bundleDeploymentSpecs:
    - name: gpt-oss-120b-8-32-64-128k
      groups:
        - name: "default"
          minReplicas: 1
          qosList:
            - "web"
            - "free"

完全な例は SambaStack.yaml リファレンスをご参照ください。

バンドルの切り替え

別のバンドルに切り替えるには、bundleSpecs と bundleDeploymentSpecs の両方を新しいバンドル名で更新します。利用可能なバンドルは対応モデルとバンドルをご参照ください。新しいバンドルテンプレートをリクエストする場合は、SambaNova のサポート窓口までお問い合わせください。例:

bundles:
  bundleSpecs:
    - name: qwen3-32b-whisper

  bundleDeploymentSpecs:
    - name: qwen3-32b-whisper
      groups:
        - name: "default"
          minReplicas: 1
          qosList:
            - "web"
            - "free"

完全な例は SambaStack.yaml リファレンスをご参照ください。

変更を適用します。

kubectl apply -f sambastack.yaml

更新が成功すると、次のように表示されます。

configmap/sambastack configured

複数バンドルのデプロイ

複数のバンドルを同時にデプロイするには、各バンドルを bundleSpecs と bundleDeploymentSpecs の両方に列挙します。

bundles:
  bundleSpecs:
    - name: gpt-oss-120b-8-32-64-128k
    - name: qwen3-32b-whisper

  bundleDeploymentSpecs:
    - name: gpt-oss-120b-8-32-64-128k
      groups:
        - name: "default"
          minReplicas: 1
          qosList:
            - "web"
            - "free"

    - name: qwen3-32b-whisper
      groups:
        - name: "default"
          minReplicas: 1
          qosList:
            - "web"
            - "free"

完全な例は SambaStack.yaml リファレンスをご参照ください。

SambaStack は、1 ノードあたり 1 つのバンドルのみをサポートします。複数のバンドルをデプロイする場合は、リソースの競合を避けるため、各バンドルを別々のノードに割り当ててください。

デプロイ状態の確認

Pod が更新後のバンドル構成を反映していることを確認します。

kubectl get pods

Legalizer は、デプロイ前にバンドルのリソース要件を検証します。リソース使用率を含む検証結果を確認するには、次を実行します。

kubectl get bundle <bundle-name> -o yaml

status.legalizerInfo セクションに、リソース使用率を含む Legalizer の結果が表示されます。

# Legalizer passed
status:
  legalizerInfo:
    errors: []
    status: Legalizer passed
    utilization:
      ddr: '0.75'
      hbm_resident: '0.65'
      host: '0.30'
    warnings: []

# Legalizer failed
status:
  legalizerInfo:
    errors:
    - 'PEF pef1 and pef2 are not checkpoint compatible (checkpoint #0)'
    status: Legalizer failed
    utilization:
      ddr: '0.75'
      hbm_resident: '0.65'
      host: '0.30'
    warnings: []

# Legalizer skipped (skip_legalizer: true set on a previously-legalized bundle)
status:
  legalizerInfo:
    errors: []
    status: Legalizer was skipped
    utilization:
      ddr: N/A
      hbm_resident: N/A
      host: N/A
    warnings: []

フィールド	説明
`status.legalizerInfo.status`	人間が読める形式の Legalizer の結果: `Legalizer passed`、`Legalizer failed`、`Legalizer was skipped` のいずれか。Legalizer の出力を処理できなかった場合は存在しません
`status.legalizerInfo.errors`	Legalizer による検証エラーのリスト
`status.legalizerInfo.warnings`	Legalizer による検証警告のリスト
`status.legalizerInfo.utilization.ddr`	DDR メモリ使用率 (引用符付き文字列。例: `'0.75'` は 75% を表します)
`status.legalizerInfo.utilization.hbm_resident`	HBM 常駐メモリ使用率 (引用符付き文字列。例: `'0.65'` は 65% を表します。`'1.0'` を超える値は過剰割り当てを示します)
`status.legalizerInfo.utilization.host`	ホストメモリ使用率 (引用符付き文字列。例: `'0.30'` は 30% を表します)

一度でも Legalizer による検証が行われたバンドルに skip_legalizer: true が設定されている場合、utilization フィールドは N/A になります。バンドルが一度も検証されていない場合 (例えば、初回デプロイ時から skip_legalizer: true が設定されていた場合)、legalizerInfo 自体が存在しません。Legalizer の出力を解析できなかった場合も、utilization フィールドが存在しないことがあります。

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

カスタムチェックポイントは、SambaNova が提供するチェックポイントと同じデプロイプロセスを使用しますが、事前に変換が必要です。 前提条件:

変換済みのチェックポイント (適切なアクセス権を持つチームメンバーであれば誰でも変換を実行できます)
変換済みチェックポイントの Google Cloud Storage パス

変換手順については、カスタムチェックポイントのデプロイガイドをご参照ください。

バンドル構成の作成

カスタムチェックポイントの保存場所を参照するバンドル構成を作成します。

apiVersion: sambanova.ai/v1alpha1
kind: Bundle
metadata:
  name: 70b-3dot3-ss-4-8-64-128k
spec:
  checkpoints:
    LLAMA3D2_1B_CKPT:
      source: gs://your-bucket/path/to/converted/checkpoint

LLAMA3D2_1B_CKPT をバンドルテンプレートが要求するチェックポイントキーに置き換え、source パスをチェックポイントの場所に更新してください。この構成で使用するチェックポイントキーは、対応する BundleTemplate で定義されたキーと一致している必要があります。これらのキーの定義例は、カスタムバンドルのデプロイ → BundleTemplate の構造をご参照ください。

投機的デコーディングによるデプロイ

投機的デコーディング (speculative decoding) は、より小さいドラフトモデルでトークンを予測し、それをより大きいターゲットモデルが検証することで、スループットの向上が期待できる手法です。

要件

ドラフトチェックポイントがターゲットチェックポイントと互換であること
カスタムモデルの場合は、ターゲットモデルのドメインに合わせてファインチューニングされたドラフトチェックポイントを使用すること

適切にチューニングされたドラフトチェックポイントなしで投機的デコーディングを使用すると、パフォーマンスが低下する可能性があります。互換性のあるドラフトチェックポイントがない場合は、投機的デコーディングを含まないバンドルテンプレートを使用してください。

互換性の検証

デプロイ前に、SN Conversion Library を使用してドラフトチェックポイントとターゲットチェックポイントの互換性を検証してください。詳細は投機的デコーディングガイドをご参照ください。

ドラフトチェックポイントとターゲットチェックポイントの設定

バンドル構成に両方のチェックポイントを指定します。

apiVersion: sambanova.ai/v1alpha1
kind: Bundle
metadata:
  name: 70b-3dot3-ss-4-8-64-128k
spec:
  checkpoints:
    LLAMA3D2_1B_CKPT:
      source: gs://your-bucket/path/to/draft/checkpoint
    LLAMA3_70B_3_3_CKPT:
      source: gs://your-bucket/path/to/target/checkpoint

パフォーマンスに関する考慮事項

投機的デコーディングは出力精度には影響しません。最終的なトークンの決定は常にターゲットモデルが行います。ただし、パフォーマンスの向上度合いはアクセプト率 (ターゲットモデルがドラフトモデルの予測を受け入れる頻度) に依存します。ターゲットに適合したドラフトチェックポイントを使用すると、一般的にアクセプト率が高くなり、スループットが向上します。

はじめに

サービス管理

ハードウェア管理

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

リソース

モデルバンドルのデプロイ

概念

バンドルテンプレート

バンドル

主要用語

バンドルの設定

バンドルの切り替え

複数バンドルのデプロイ

デプロイ状態の確認

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

バンドル構成の作成

投機的デコーディングによるデプロイ

要件

互換性の検証

ドラフトチェックポイントとターゲットチェックポイントの設定

パフォーマンスに関する考慮事項

参考情報

​概念

​バンドルテンプレート

​バンドル

​主要用語

​バンドルの設定

​バンドルの切り替え

​複数バンドルのデプロイ

​デプロイ状態の確認

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

​バンドル構成の作成

​投機的デコーディングによるデプロイ

​要件

​互換性の検証

​ドラフトチェックポイントとターゲットチェックポイントの設定

​パフォーマンスに関する考慮事項

​参考情報

概念

バンドルテンプレート

バンドル

主要用語

バンドルの設定

バンドルの切り替え

複数バンドルのデプロイ

デプロイ状態の確認

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

バンドル構成の作成

投機的デコーディングによるデプロイ

要件

互換性の検証

ドラフトチェックポイントとターゲットチェックポイントの設定

パフォーマンスに関する考慮事項

参考情報