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

本ガイドでは、カスタムリソースを作成して、SambaStack 上で特定の構成を持つモデルをデプロイする方法を説明します。単一のモデルをサービングするには ModelDeployment を、複数のモデルをまとめてサービングするには ModelBundle を使用します。 SambaStack のデプロイメントは、1 つのノード上で 1 つ以上のモデルを、バッチサイズやシーケンス長を含む構成と共にサービングします。このアプローチでは、SambaNova の Reconfigurable Dataflow Unit (RDU) を利用して、1 つのデプロイメントで複数のモデルと構成をサポートします。デプロイメント内のすべてのモデルはすでにメモリに常駐しているため、モデル間の切り替えに重みの再ロードは不要であり、単一の静的なモデルをロードするデプロイメントと比較してスループットが向上します。例えば、1 つのバンドルで Llama-3.3-70B-Instruct と Llama-3.1-8B-Instruct の両方をサービングすることで、両者をほぼ瞬時に切り替えられます。各構成はノード上の容量を消費するため、バンドルごとに含まれる構成のセットは異なります。バッチサイズ 4、シーケンス長 16k の Llama-3.3-70B-Instruct は 1 つの構成に相当します。SambaNova が提供するバンドルについては、対応モデルとバンドルをご覧ください。

SambaStack v2.0.2 では、バンドルのデプロイ方法を管理する新しい Kubernetes カスタムリソース (CR) 群が導入されました。旧バージョンの SambaStack の CR は非推奨となりましたが、2026 年 9 月 30 日までは引き続き機能します。非推奨の CR で構築したモデルバンドルは、新しいリソースモデルへの移行が必要になります。

バンドルは必須ではありません。単一のモデルをサービングする場合は、モデルプロファイルと組み合わせて直接デプロイします。複数のモデルを 1 つの単位としてサービングする場合、投機的デコーディングを設定する場合、または名前付きの構成を検証して共有する場合に、バンドルを作成します。

本ガイドでは、SambaNova が提供するバンドルのデプロイと、独自のバンドルの作成の両方を扱います。提供されているバンドルのカタログについては、対応モデルとバンドルをご覧ください。

前提条件

カスタムのデプロイメントやバンドルを作成する前に、お使いの環境に応じて以下を完了してください。

クイックスタート - ホステッド

ホステッド版 SambaStack のシステムセットアップ

クイックスタート - オンプレミス

オンプレミス版 SambaStack のシステムセットアップ

あわせて、以下のドキュメントも確認してください。

対応モデルとバンドル - 利用可能なモデルチェックポイント
投機的デコーディングのデプロイガイドライン - 投機的デコーディングのペアを設定する場合に必要

用語

用語	定義
RDU	Reconfigurable Dataflow Unit - SambaNova 独自のプロセッサアーキテクチャ
PEF	Processor Executable Format - RDU 上で実行されるコンパイル済みのモデルバイナリ
バンドル (Bundle)	モデル、そのプロファイル、およびその構成を組み合わせたデプロイ可能なパッケージ
構成 (Configuration)	バッチサイズやシーケンス長を含む、モデルのランタイム設定。1 つのデプロイメントに複数の構成を含めることができ、構成間を即座に切り替えられます
モデルアーキテクチャ	PEF のセットが共有する `model_arch` の値。それらの PEF と互換性のあるチェックポイントを決定します
エキスパート (Expert)	モデル内のシーケンス長プロファイル構成 (例: 8k、16k、32k)
ティア (Tier)	バッチング設定内のシーケンス長キー (例: `8k` や `128k`)。そのシーケンス長でサービングされるバッチサイズにマッピングされます
投機的デコーディング	より小さいドラフトモデルを使用して、より大きいターゲットモデルの推論を高速化する最適化手法
Legalizer	構成が RDU のメモリ制約に収まるかを検証する検証プロセス
CR (カスタムリソース)	`Pef`、`Model`、`ModelProfile`、`ModelDeployment`、`ModelBundle` などのカスタムリソースタイプを定義する Kubernetes の拡張機構

概念

リソースアーキテクチャ

このセクションでは、カスタムのデプロイメントを作成する際に使用するリソース構造を説明します。これらのリソースはすべて apiVersion: sambanova.ai/v1alpha1 を使用します。薄い色のボックスは SambaStack のインストールと共に提供され、名前で参照するリソースです。濃い色のボックスは、ユーザーが作成するリソースです。琥珀色のボックスはカスタムリソースではなく、Model と ModelProfile の 1 つのペアリングを表しており、spec.modelConfigs の 1 エントリに対応します。各リソースは、次のように責務を分担します。

Pef - コンパイル済み実行ファイルと、そのモデルアーキテクチャ、バッチサイズ、最大シーケンス長を含む、サポート内容を記述するメタデータを登録します。
ModelProfile - モデルアーキテクチャを「どのように」実行できるかを定義します。使用する PEF、サポートする機能、各シーケンス長ティアで利用可能なバッチサイズを含みます。
Model - 各アーキテクチャに対して「どのチェックポイント」が利用可能かを、使用するトークナイザーとあわせて定義します。
ModelBundle - 1 つ以上のモデルとプロファイルのペアを、名前付きの単一のデプロイ可能な単位にまとめます。任意です。
ModelDeployment - バンドル、またはインラインのモデルとプロファイルのペアから、クラスター上に 1 つ以上のレプリカをインスタンス化します。

この分離により、次のことが可能になります。

バンドルを作成せずに、モデルをプロファイルと組み合わせて単一モデルをデプロイする
ファインチューニングしたモデルのカスタムチェックポイントを含め、同じアーキテクチャを共有するすべてのモデルとチェックポイントで 1 つのプロファイルを再利用する
プロファイルには手を加えず、Model リソースを追加するだけでカスタムチェックポイントをサービングする
複数のモデルをまとめてサービングする必要がある場合に、検証済みで共有可能な 1 つの単位にグループ化する
プロファイルやデプロイメント構成を変更せずにチェックポイントを更新する
同じ構成を異なるレプリカ数でデプロイする

チェックポイントのパスをバンドルやデプロイメントで宣言することはありません。オペレーターは、参照した Model からパスを解決します。解決には、<model-name>[:<arch>][:<version>] 形式の参照、または modelSettings.checkpointOverrides が使用されます。チェックポイントとプロファイルの互換性は model_arch によって定義されますが、オペレーターはこれを検証しません。参照するプロファイルと互換性のあるアーキテクチャを持つチェックポイントを選択してください。

ModelProfile の構造

ModelProfile は、単一のモデルアーキテクチャのランタイム形状を定義します。プロファイルは再利用可能であり、対応アーキテクチャのプロファイルは SambaStack のインストールと共に提供されるため、多くの場合、プロファイルを自作するのではなく既存のプロファイルを名前で参照します。

apiVersion: sambanova.ai/v1alpha1
kind: ModelProfile
metadata:
  name: gpt-oss-fp8-dyt
spec:
  model_arch: gpt-oss-fp8
  features: []
  defaultBatchingConfig:
    8k:
      batch_sizes: [2, 4, 6, 8]
    32k:
      batch_sizes: [2, 4, 6, 8]
    64k:
      batch_sizes: [2, 4]
    128k:
      batch_sizes: [2]
  pefs:
    - gpt-oss-fp8-ss131072-bs8-dyt-1:1
  secretNames:
    - sambanova-artifact-reader

ModelProfile のトップレベルフィールド

フィールド	必須	説明
`spec.pefs`	はい	PEF カスタムリソース参照の順序付きリスト。各要素は `<pef-name>[:<version>]` 形式です。リストは空にできず、重複した PEF 名を含めることはできません。バージョンのサフィックスを省略した場合は、最新バージョンが使用されます。
`spec.model_arch`	はい	このプロファイルが対象とするモデルアーキテクチャ。プロファイル内のすべての PEF は同じ `model_arch` を共有しており、このフィールドにより個々の `Pef` リソースを確認しなくてもその値を参照できます。
`spec.features`	はい	このプロファイルがサポートする機能。プロファイルの PEF から導出されます。既知の値は `continuous_batching`、`prompt_caching`、`speculative_decoding`、`speculative_prefill`、`constrained_decoding` です。空のリストはオプション機能なしを意味します。
`spec.defaultBatchingConfig`	はい	シーケンス長ティアをキーとする、デフォルトのバッチングサポート。バッチング設定をご覧ください。省略した場合、オペレーターが PEF のグルーピングから設定を生成します。
`spec.secretNames`	はい	PEF のダウンロードに必要な Kubernetes Secret のリスト。お使いの環境で設定されている Secret と一致している必要があります。
`spec.skip_legalizer`	いいえ	このプロファイルの Legalizer による検証をスキップします。
`status.batchingConfig`	N/A	読み取り専用。spec から取得された、またはオペレーターによって生成された、解決済みのデフォルトバッチング設定。

バッチング設定

バッチング設定は、各シーケンス長ティアを、そのシーケンス長でサービングされるバッチサイズにマッピングします。一般的なティアのキーは 8k、16k、32k、64k、128k です。1k 未満の PEF は 448 のような整数のみのキーを使用し、Vocoder の PEF は 10t のような <n>t 形式のコード長キーを使用します。

spec:
  defaultBatchingConfig:
    128k:
      batch_sizes: [1]
    32k:
      batch_sizes: [1, 2, 4]
    8k:
      batch_sizes: [1, 2, 4, 8]
    4k:
      batch_sizes: [1, 2, 4, 8]
      is_default: true

パラメータ	必須	説明
`batch_sizes`	はい	`defaultBatchingConfig` では、整数の明示的なリスト (例: `[1, 2, 4]`)。オーバーライドでは、文字列 `"*"` も指定できます。バッチング設定のオーバーライドをご覧ください。
`is_default`	いいえ	`true` の場合、このティアは `default` エキスパートとしてサービングされます。1 つのバッチング設定内でこれを設定できるティアは最大 1 つです。

各ティアに複数のバッチサイズを含めておくと、推論エンジンが現在のワークロードに基づいて、最小かつ最速の構成を選択できます。

バッチング設定のオーバーライド

ModelProfile は各ティアで利用可能なバッチサイズを確立するものであるため、defaultBatchingConfig では常にバッチサイズを明示的に列挙します。"*" は使用しません。ティアと batch_sizes の構造は、あるモデルについてプロファイルのデフォルトをオーバーライドする際にも再利用されます。オーバーライドは、ModelBundle の modelConfigs[].batchingConfig、または ModelDeployment のインラインの spec.models で行います。オーバーライドの場合に限り、batch_sizes に文字列 "*" を設定でき、これはプロファイルの defaultBatchingConfig がそのティアに提供するすべてのバッチサイズを選択します。

spec:
  modelConfigs:
  - model: gpt-oss-120b:1
    profile: gpt-oss-fp8-dyt
    batchingConfig:
      128k:
        batch_sizes: "*"    # every batch size the profile defines for 128k
      32k:
        batch_sizes: [2, 4] # a subset of what the profile defines for 32k

オーバーライドでは、プロファイルがすでに提供している内容を絞り込むか、再記述することしかできません。プロファイルの defaultBatchingConfig に含まれないバッチサイズを新たに導入することはできません。

PEF

PEF は、1 つのモデル構成に対するコンパイル済みアーティファクトです。どの PEF・シーケンスサイズ・バッチサイズが使用されるかはプロファイルによって決まるため、PEF ではなくプロファイルを参照します。Pef リソースのリファレンスは、カスタムチェックポイントのデプロイをご覧ください。

ModelBundle の構造

ModelBundle は、1 つ以上のモデルとプロファイルのペアを、名前付きの単一のデプロイ可能な単位にまとめます。spec.modelConfigs の各エントリはモデルとプロファイルを名前で参照し、モデルごとのバッチング設定やモデル構成を指定できます。以下は、複数モデルのバンドルの例です。

apiVersion: sambanova.ai/v1alpha1
kind: ModelBundle
metadata:
  name: mb-gpt120-llama70sd8-llama8
spec:
  modelConfigs:
    - model: gpt-oss-120b:1
      profile: gpt-oss-fp8-dyt
      batchingConfig:
        8k:
          batch_sizes: [2]
        32k:
          batch_sizes: [2]
    - model: meta-llama-3-3-70b-instruct:1
      profile: llama-3p1-70b-sd
      modelSettings:
        swappable: true
    - model: meta-llama-3-1-8b-instruct:1
      profile: llama-3p1-8b
      modelSettings:
        routable: false
  specDecodingPairs:
    - draft: meta-llama-3-1-8b-instruct
      target: meta-llama-3-3-70b-instruct

上記の例には 3 つのモデルが含まれており、Meta-Llama-3.1-8B-Instruct は Meta-Llama-3.3-70B-Instruct に対するルーティング不可のドラフトモデルとして機能します。 ModelBundle のトップレベルフィールド

フィールド	必須	説明
`spec.modelConfigs`	はい	バンドル内のモデル構成のリスト。モデルごとに 1 エントリです。モデル構成をご覧ください。
`spec.specDecodingPairs`	いいえ	投機的デコーディングのペア。後述の投機的デコーディングのパラメータをご覧ください。
`spec.adapters`	いいえ	モデル構成で使用される LoRA アダプタの定義。アダプタ名をキーとします。
`spec.skip_legalizer`	いいえ	バンドルの Legalizer による検証をスキップします。

モデル構成

spec.modelConfigs の各エントリは、1 つのモデルを 1 つのプロファイルと組み合わせます。

フィールド	必須	説明
`model`	はい	`<model-name>[:<arch>][:<version>]` 形式の `Model` 参照。モデルが単一のアーキテクチャしか持たない場合はアーキテクチャのセグメントを省略でき、バージョンを省略すると最新バージョンが使用されます。
`profile`	条件付き	このモデルが使用する `ModelProfile` の名前。`profile` と `profileDefinition` は、いずれか一方のみを設定します。
`profileDefinition`	条件付き	インラインのプロファイル定義。モデルの PEF が複数の標準プロファイルにまたがる場合に使用します。`profile` と `profileDefinition` は、いずれか一方のみを設定します。
`batchingConfig`	いいえ	プロファイルの `defaultBatchingConfig` をバンドル単位でオーバーライドします。同じティア構造を使用します。ティアに `"*"` を設定すると、プロファイルがそのティアに提供するすべてのバッチサイズを選択します。バッチング設定のオーバーライドをご覧ください。
`modelSettings.swappable`	いいえ	モデルをスワップ可能にするかどうか。スワップ可能なモデルをご覧ください。
`modelSettings.routable`	いいえ	クライアントがモデルを直接ルーティングできるかどうか。省略するとデフォルト (ルーティング可能) を継承します。投機的デコーディングのドラフトモデルでは `false` に設定してください。
`modelSettings.checkpointOverrides`	いいえ	`model` 参照の代わりに適用されるチェックポイントの選択。モデルレベルのチェックポイントには `checkpoint` を、エキスパートごとのチェックポイントには `expertOverrides` を使用します。
`modelSettings.adapters`	いいえ	サービング名から LoRA アダプタのバインディングへのマッピング。`spec.adapters` で定義されたアダプタを参照します。
`modelSettings.properties`	いいえ	モデルのすべてのエキスパートに適用される追加の設定フィールド。

バッチングは、次の優先順位で解決されます: モデル構成の batchingConfig、次にプロファイルの defaultBatchingConfig、最後に PEF のグルーピングから生成された設定。

スワップ可能なモデル

swappable 設定は、同じエンドポイント上の別のモデルを優先して、モデルを HBM から退避できるかどうかを制御します。swappable を true に設定すると、別のモデルがそのエンドポイントで実行する必要がある場合に、モデル全体が HBM から削除されます。これには、モデルのチェックポイントの重み、プロファイルのメタデータ、PEF が含まれます。別のモデルのために容量を解放する目的で退避してよいモデルにはこのフィールドを true に設定し、常駐が必須のモデルでは未設定のままにするか false に設定してください。

投機的デコーディング

投機的デコーディングでは、より小さいドラフトモデルがトークンを提案し、より大きいターゲットモデルがそれを検証します。ペアリングはバンドルレベルの spec.specDecodingPairs で宣言し、ドラフトモデルは spec.modelConfigs にルーティング不可の独立したエントリとして含めます。フィールドリファレンス、要件、カスタムドラフトチェックポイントを含む完全なワークフローについては、投機的デコーディングによるデプロイをご覧ください。

ModelDeployment の構造

ModelDeployment は、クラスター上でモデルをインスタンス化し、ルーティング可能な推論エンドポイントを支えるサービング Pod を作成します。デプロイの詳細については、クイックスタート - ホステッドまたはクイックスタート - オンプレミスをご覧ください。モデルソースは、必ずいずれか一方のみを設定します。

デプロイ方式	フィールド	説明
直接デプロイ	`spec.models`	モデルとプロファイルをインラインで宣言します。仕様はその場で検証・Legalizer チェックされ、バンドルは使用されません。
バンドルデプロイ	`spec.bundle`	既存の `ModelBundle` を名前で参照します。バンドルは、一度検証されれば信頼された状態になります。

apiVersion: sambanova.ai/v1alpha1
kind: ModelDeployment
metadata:
  name: md-gpt120-llama70sd8-llama8
spec:
  bundle: mb-gpt120-llama70sd8-llama8
  groups:
  - minReplicas: 1
    name: default
    qosList:
    - free
  owner: no-reply@sambanova.ai
  secretNames:
  - sambanova-artifact-reader
  engineConfig:
    startupTimeout: 7200

フィールド	必須	説明
`spec.bundle`	条件付き	デプロイする `ModelBundle` の名前。`spec.bundle` と `spec.models` は、いずれか一方のみを設定します。
`spec.models`	条件付き	デプロイするモデルとプロファイルのインライン定義。`ModelBundle` と同じ `modelConfigs` 構造を使用します。`spec.bundle` と `spec.models` は、いずれか一方のみを設定します。
`spec.groups[].name`	はい	デプロイメントグループの名前識別子。デフォルトは `default` です。
`spec.groups[].minReplicas`	はい	維持するレプリカの最小数。
`spec.groups[].qosList`	はい	リクエストの優先順位付けに使用する QoS クラス。
`spec.owner`	はい	追跡と通知のためのデプロイメント所有者のメールアドレス。
`spec.secretNames`	はい	アーティファクトへのアクセスに使用する認証情報。お使いの環境で設定されている Secret と一致している必要があります。
`spec.engineConfig`	いいえ	`startupTimeout` などの設定を含む、推論エンジンイメージの設定。
`spec.cacheConfig`	いいえ	アーティファクトキャッシュコンテナの設定。
`spec.tokenizerConfig`	いいえ	トークナイザーイメージの設定。
`spec.storage`、`spec.storageClass`	いいえ	デプロイメントのストレージ設定。
`spec.nodeSelector`、`spec.tolerations`	いいえ	デプロイメントのデフォルトのスケジューリング制御。
`spec.skip_legalizer`	いいえ	インラインの `spec.models` 仕様をデプロイする際に Legalizer をスキップします。

Legalizer の結果

Legalizer は、デプロイ前に構成のリソース要件を検証します。ModelBundle を適用すると自動的に実行され、その結果は status.legalizerInfo に公開されます。バンドルのステータスには、各モデルに対して解決された実効バッチング設定も報告されます。

Hosted
On Premise

kubectl describe modelbundle <bundle-name>

kubectl -n <namespace> describe modelbundle.sambanova.ai <bundle-name>

警告付きで検証に合格したバンドルのステータス例:

Status:
  Batching Configs:
    gemma-4-31b-it:1:
      128k:
        batch_sizes:
          2
      32k:
        batch_sizes:
          2
          4
          6
          8
    minimax-m2-7:1:
      192k:
        batch_sizes:
          2
      8k:
        batch_sizes:
          2
          4
          6
          8
  Conditions:
    Last Transition Time:  2026-07-28T22:15:18.967900+00:00
    Message:               ModelBundle is Valid
    Observed Generation:   2
    Reason:                ValidationSucceeded
    Status:                True
    Type:                  Valid
  Legalizer Info:
    Errors:
    Status:  Legalizer passed
    Utilization:
      Ddr:           0.0614
      hbm_resident:  0.0
      Host:          0.0304
    Warnings:
      gemma-4-31b-it-vision-ckpt: checkpoint sharing not enabled for gemma-4-31B-it-128k-vision-emb and gemma-4-31B-it-32k-vision-emb
  Observed Generation:  2

フィールド	説明
`status.conditions[].reason`	`ValidationSucceeded` または `ValidationFailed`。付随する `message` は、成功時は `ModelBundle is Valid`、失敗時はエラーの詳細を含みます。
`status.batchingConfigs`	モデルごとの実効バッチング設定。モデル参照、次にシーケンス長ティアをキーとします。モデル構成、プロファイルのデフォルト、または PEF のグルーピングから実際に解決された設定を反映します。
`status.legalizerInfo.status`	人間が読める形式の Legalizer の結果: `Legalizer passed`、`Legalizer failed`、`Legalizer was skipped` のいずれか。Legalizer の出力を処理できなかった場合は存在しません。
`status.legalizerInfo.errors`	Legalizer による検証エラーのリスト。Legalizer が合格した場合は空です。
`status.legalizerInfo.warnings`	検証警告のリスト。各項目は `<checkpoint-name>: <message>` 形式です。警告はデプロイを妨げません。
`status.legalizerInfo.utilization.ddr`	小数で表した DDR メモリ使用率 (例: `0.0614` は約 6% を表します)
`status.legalizerInfo.utilization.hbm_resident`	小数で表した HBM 常駐メモリ使用率。`1.0` を超える値は過剰割り当てを示します。
`status.legalizerInfo.utilization.host`	小数で表したホストメモリ使用率 (例: `0.0304` は約 3% を表します)

上記の例のように、警告が存在してもバンドルは Legalizer に合格し、ValidationSucceeded を報告することがあります。デプロイ前に警告を確認してください。ただし、警告はデプロイを妨げません。

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

手順

利用可能なモデルとプロファイルの特定

デプロイメントを作成する前に、クラスターで利用可能なモデルとプロファイルを特定し、どの組み合わせが可能かを確認します。

利用可能なモデルの一覧表示

モデルを一覧表示し、各モデルの spec.checkpoints 配下のアーキテクチャキーを確認します。

Hosted
On Premise

kubectl get models

例:

kubectl describe model gpt-oss-120b

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

例:

kubectl -n <namespace> describe model.sambanova.ai gpt-oss-120b

これらのコマンドが一覧表示するのは Kubernetes のリソース名 (metadata.name) であり、推論 API に送信する名前ではありません。リクエストには spec.name のサービング名を使用してください。対応モデルとバンドルをご覧ください。

利用可能なプロファイルの一覧表示

プロファイルを一覧表示し、それぞれの model_arch の値を確認します。

Hosted
On Premise

kubectl get modelprofiles

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

出力:

deepseek              17h
gpt-oss-fp8-dyt       17h
llama-3p1-70b-sd      17h
llama-3p1-8b          17h

プロファイルとモデルのマッチング

プロファイルの内容を表示して、そのアーキテクチャ、機能、バッチングサポートを確認します。

Hosted
On Premise

kubectl describe modelprofile <profile-name>

kubectl -n <namespace> describe modelprofile.sambanova.ai <profile-name>

プロファイルの model_arch の値が、モデルの spec.checkpoints 配下のアーキテクチャキーのいずれかと一致する場合、そのプロファイルをモデルと組み合わせて使用できます。オペレーターはこのペアリングを検証しないため、デプロイ前にご自身で確認してください。プロファイルでは、以下を確認します。

model_arch - プロファイルが対象とするアーキテクチャ
features - プロファイルの PEF がサポートするオプション機能
defaultBatchingConfig - シーケンス長ティアとそのバッチサイズ
pefs - プロファイルが参照する PEF のバージョン

features リストに speculative_decoding を含むプロファイルには、ドラフトモデルが必要です。バンドルの spec.specDecodingPairs を使用してペアリングしてください。

単一モデルのデプロイ

1 つのモデルをサービングするには、プロファイルと組み合わせて直接デプロイします。バンドルは作成されません。

YAML ファイルの作成

spec.models の下にモデルとプロファイルをインラインで宣言する YAML ファイルを作成します。

apiVersion: sambanova.ai/v1alpha1
kind: ModelDeployment
metadata:
  name: md-gpt120
spec:
  models:
    modelConfigs:
    - model: gpt-oss-120b:1
      profile: gpt-oss-fp8-dyt
  groups:
  - minReplicas: 1
    name: default
    qosList:
    - free
  owner: no-reply@sambanova.ai
  secretNames:
  - sambanova-artifact-reader
  engineConfig:
    startupTimeout: 7200

チェックポイントのパスは不要です。チェックポイントは、参照した Model から解決されます。

ModelDeployment の適用

Hosted
On Premise

kubectl apply -f <modeldeployment-file>.yaml

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

デプロイ状態の監視

Hosted
On Premise

kubectl get modeldeployments
kubectl describe modeldeployment <deployment-name>

kubectl -n <namespace> get modeldeployments.sambanova.ai
kubectl -n <namespace> describe modeldeployment.sambanova.ai <deployment-name>

すべてのサービング Pod が ready ステータスを報告すれば、デプロイは完了です。

ModelBundle の作成

複数のモデルを 1 つの単位としてサービングする場合、投機的デコーディングを設定する場合、または名前付きの構成を検証して共有する場合に、バンドルを作成します。

YAML ファイルの作成

ModelBundle の YAML ファイルを作成します。

apiVersion: sambanova.ai/v1alpha1
kind: ModelBundle
metadata:
  name: mb-gpt120
spec:
  modelConfigs:
  - model: gpt-oss-120b:1
    profile: gpt-oss-fp8-dyt
    batchingConfig:
      8k:
        batch_sizes: [2]
      32k:
        batch_sizes: [2]
      64k:
        batch_sizes: [2]
      128k:
        batch_sizes: [2]

投機的デコーディングを含む複数モデルのバンドルについては、ModelBundle の構造の例をご覧ください。

ModelBundle の適用

Hosted
On Premise

kubectl apply -f <modelbundle-file>.yaml

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

Legalizer による検証の確認

バンドルを適用すると Legalizer が自動的に実行され、構成が RDU のメモリに収まるかどうかを検証します。

Hosted
On Premise

kubectl describe modelbundle <bundle-name>

kubectl -n <namespace> describe modelbundle.sambanova.ai <bundle-name>

検証成功
検証失敗

Status:
  Conditions:
    Last Transition Time:  2026-06-22T21:11:05.689262+00:00
    Message:               ModelBundle is Valid
    Observed Generation:   1
    Reason:                ValidationSucceeded
    Status:                True
    Type:                  Valid

Status:
  Conditions:
    Last Transition Time:  2026-06-22T21:11:54.975311+00:00
    Message:               <error-details>
    Reason:                ValidationFailed
    Status:                False
    Type:                  Valid

Message フィールドには、Legalizer のエラーがある場合はそれを含む、エラーの詳細が含まれます。

メモリ使用率や警告を含む Legalizer の結果を直接確認するには、次を実行します。

kubectl get modelbundle <bundle-name> -o jsonpath='{.status.legalizerInfo}'

ステータスの完全な構造とフィールドの説明については、Legalizer の結果をご覧ください。

バンドルが ValidationSucceeded を示すまで、デプロイに進まないでください。

バンドルのデプロイ

この手順は、SambaNova が提供するバンドルと、自作したバンドルの両方に適用されます。

利用可能なバンドルの確認

クラスターに存在するバンドルを一覧表示し、デプロイしたいバンドルの名前を確認します。

Hosted
On Premise

kubectl get modelbundles

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

出力:

mb-gpt120                      17h
mb-gpt120-llama70sd8-llama8    17h
ds-v32-gemma-4-31b             3h

デプロイする前に、Legalizer の結果に記載されたとおり、バンドルが検証に合格していることを確認してください。

ModelDeployment の作成

spec.bundle にバンドル名を指定します。

apiVersion: sambanova.ai/v1alpha1
kind: ModelDeployment
metadata:
  name: md-gpt120
spec:
  bundle: mb-gpt120
  groups:
  - minReplicas: 1
    name: default
    qosList:
    - free
  owner: no-reply@sambanova.ai
  secretNames:
  - sambanova-artifact-reader

ModelDeployment の適用

Hosted
On Premise

kubectl apply -f <modeldeployment-file>.yaml

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

デプロイ状態の監視

Hosted
On Premise

kubectl get modeldeployments
kubectl describe modeldeployment <deployment-name>

kubectl -n <namespace> get modeldeployments.sambanova.ai
kubectl -n <namespace> describe modeldeployment.sambanova.ai <deployment-name>

バンドルの切り替え

ModelDeployment のバンドル参照をその場で変更することはできません。別のバンドルをサービングするには、既存のデプロイメントを削除し、新しいバンドルを参照する新しいデプロイメントを適用します。

既存の ModelDeployment の削除

Hosted
On Premise

kubectl delete modeldeployment <deployment-name>

kubectl -n <namespace> delete modeldeployment <deployment-name>

新しいバンドル用の ModelDeployment の適用

サービングしたいバンドルを spec.bundle に指定した新しい ModelDeployment を作成し、バンドルのデプロイの説明に従って適用します。

apiVersion: sambanova.ai/v1alpha1
kind: ModelDeployment
metadata:
  name: md-qwen3-32b-whisper
spec:
  bundle: mb-qwen3-32b-whisper
  groups:
  - minReplicas: 1
    name: default
    qosList:
    - free
  owner: no-reply@sambanova.ai
  secretNames:
  - sambanova-artifact-reader

新しいバンドルをリクエストする場合は、SambaNova のサポート窓口までお問い合わせください。

複数バンドルのデプロイ

複数のバンドルを同時にサービングするには、バンドルごとに個別の ModelDeployment を適用します。

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

Pod がデプロイされたバンドルを反映していることを確認します。

Hosted
On Premise

kubectl get pods

kubectl -n <namespace> get pods

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

独自に変換またはファインチューニングしたチェックポイントをサービングするには、既存モデルが使用するチェックポイントをオーバーライドするか、そのチェックポイント用に新しいモデルを登録します。カスタムチェックポイントのデプロイをご覧ください。

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

SambaStack がまだサポートしていないモデルアーキテクチャをサービングするには、PEF のコンパイルと、Pef、ModelProfile、Model リソースの作成が必要です。カスタムチェックポイントのデプロイをご覧ください。

デプロイメントまたはバンドルの更新・削除

構成の更新
構成の削除

YAML ファイルの変更

ModelBundle、ModelProfile、または ModelDeployment の YAML ファイルを編集して変更を加えます。

構成の再適用

Hosted
On Premise

kubectl apply -f <modified-file>.yaml

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

Legalizer が自動的に変更を再検証します。プロファイルやモデルを変更すると、それを参照するすべてのバンドルとデプロイメントの調整 (reconcile) がトリガーされます。

ModelDeployment の削除

Hosted
On Premise

kubectl delete modeldeployment <deployment-name>

kubectl -n <namespace> delete modeldeployment <deployment-name>

ModelBundle の削除 (バンドルを使用していた場合)

Hosted
On Premise

kubectl delete modelbundle <bundle-name>

kubectl -n <namespace> delete modelbundle <bundle-name>

ModelProfile の削除 (任意)

プロファイルを削除するのは、カスタムアーキテクチャのために自作した場合のみにしてください。SambaStack のインストールと共に提供されるプロファイルはモデル間で共有されているため、そのまま残しておく必要があります。

Hosted
On Premise

kubectl delete modelprofile <profile-name>

kubectl -n <namespace> delete modelprofile <profile-name>

トラブルシューティング

Legalizer の検証失敗

エラーは status.legalizerInfo.errors に表示され、ValidationFailed の原因になります。警告は status.legalizerInfo.warnings に表示され、デプロイを妨げません。Legalizer の結果をご覧ください。

エラーパターン	原因	解決方法
`PEF pef1 and pef2 are not checkpoint compatible (checkpoint #0)`	同じ `ckpt_sharing_uuid` を持つ PEF がチェックポイントメモリを共有できない	互換性のない PEF に異なる `ckpt_sharing_uuid` の値を割り当ててください
`<checkpoint>: checkpoint sharing not enabled for <expert-a> and <expert-b>`	警告のみ。2 つのエキスパートがチェックポイントメモリを共有できないため、それぞれが独自のコピーを保持します	対応は不要です。重複したメモリを回収するには、ティアの数を減らすか、チェックポイントを共有できる PEF を使用してください
`Bundle exceeds memory constraints`	PEF とチェックポイントの合計サイズが RDU のメモリを超えている	バッチング設定内のティアの数またはバッチサイズを減らしてください
`PEF not found: <pef-name>`	参照された PEF が存在しない	`kubectl get pefs` で PEF 名を確認してください
プロファイルまたはモデルの参照を解決できない	指定した名前の `ModelProfile` または `Model` が名前空間に存在しない	`kubectl get modelprofiles` と `kubectl get models` で名前を確認してください

デプロイの失敗

症状	考えられる原因	解決方法
デプロイが pending のまま進まない	RDU リソースの不足	クラスターのキャパシティを確認し、`minReplicas` を減らしてください
チェックポイントのダウンロードが失敗する	チェックポイントのパスが無効、または認証情報がない	Model の `source` パスを確認し、`sambanova-artifact-reader` Secret が存在することを確認してください
API からモデルにアクセスできない	モデル名の不一致、またはモデルがルーティング不可	Model の `spec.name` を確認し、`modelSettings.routable` が `false` に設定されていないことを確認してください
ドラフトモデルが直接サービングされる	ドラフトモデルがルーティング可能なままになっている	ドラフトモデルのエントリで `modelSettings.routable` を `false` に設定してください

バンドル設定の移行

非推奨のカスタムリソースで構築したバンドルの移行

対応モデルとバンドル

デプロイ可能なモデルとバンドルのカタログ

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

独自のカスタムチェックポイントやファインチューニング済みチェックポイントのデプロイ

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

チェックポイントを互換形式に変換

はじめに

サービス管理

ハードウェア管理

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

リソース

前提条件

クイックスタート - ホステッド

クイックスタート - オンプレミス

用語

概念

リソースアーキテクチャ

ModelProfile の構造

バッチング設定

バッチング設定のオーバーライド

PEF

ModelBundle の構造

モデル構成

スワップ可能なモデル

投機的デコーディング

ModelDeployment の構造

Legalizer の結果

手順

利用可能なモデルとプロファイルの特定

単一モデルのデプロイ

ModelBundle の作成

バンドルのデプロイ

バンドルの切り替え

複数バンドルのデプロイ

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

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

デプロイメントまたはバンドルの更新・削除

トラブルシューティング

Legalizer の検証失敗

デプロイの失敗

関連ドキュメント

バンドル設定の移行

対応モデルとバンドル

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

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

​前提条件

クイックスタート - ホステッド

クイックスタート - オンプレミス

​用語

​概念

​リソースアーキテクチャ

​ModelProfile の構造

​バッチング設定

​バッチング設定のオーバーライド

​PEF

​ModelBundle の構造

​モデル構成

​スワップ可能なモデル

​投機的デコーディング

​ModelDeployment の構造

​Legalizer の結果

​手順

​利用可能なモデルとプロファイルの特定

​単一モデルのデプロイ

​ModelBundle の作成

​バンドルのデプロイ

​バンドルの切り替え

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

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

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

​デプロイメントまたはバンドルの更新・削除

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

​Legalizer の検証失敗

​デプロイの失敗

​関連ドキュメント

バンドル設定の移行

対応モデルとバンドル

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

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

前提条件

用語

概念

リソースアーキテクチャ

ModelProfile の構造

バッチング設定

バッチング設定のオーバーライド

PEF

ModelBundle の構造

モデル構成

スワップ可能なモデル

投機的デコーディング

ModelDeployment の構造

Legalizer の結果

手順

利用可能なモデルとプロファイルの特定

単一モデルのデプロイ

ModelBundle の作成

バンドルのデプロイ

バンドルの切り替え

複数バンドルのデプロイ

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

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

デプロイメントまたはバンドルの更新・削除

トラブルシューティング

Legalizer の検証失敗

デプロイの失敗

関連ドキュメント