SambaStack ModelBundle カスタムリソース

ModelBundle は、1 つ以上のモデルとプロファイルのペアを、名前を持つ 1 つのデプロイ可能な単位にまとめます。spec.modelConfigs の各エントリは Model と ModelProfile を名前で参照し、モデルごとのバッチングとモデル構成を指定できます。 ModelBundle リソースは apiVersion: sambanova.ai/v1alpha1 を使用します。

バンドルの作成は任意です。単一のモデルをサービングする場合は、プロファイルとペアにして直接デプロイできます。複数のモデルを 1 つの単位としてサービングする場合、投機的デコーディングを設定する場合、または名前付きの構成を検証して共有する場合に、バンドルを作成してください。

構造

以下は複数モデルを含むバンドルの例です。

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` 参照。モデルのアーキテクチャが 1 つだけの場合はアーキテクチャ部分を省略でき、バージョンを省略すると最新バージョンが使用されます。
`profile`	条件付き	このモデルが使用する `ModelProfile` の名前。`profile` と `profileDefinition` のいずれか一方のみを設定します (同時には指定できません)。
`profileDefinition`	条件付き	インラインのプロファイル仕様。モデルの PEF が複数の標準プロファイルにまたがる場合に使用します。`profile` と `profileDefinition` のいずれか一方のみを設定します (同時には指定できません)。
`batchingConfig`	いいえ	プロファイルのバッチングをバンドル単位でオーバーライドします。プロファイルの `batchingConfigs` のエントリ名を示す文字列 (`all` や `recommended` など) か、インラインのティアマップのいずれかを指定します。ティアマップでは、ティアに `"*"` を設定すると、そのティアに対してプロファイルが提供するすべてのバッチサイズが選択されます。バッチング設定のオーバーライドをご参照ください。
`modelSettings.swappable`	いいえ	モデルをスワップ可能にするかどうか。スワップ可能なモデルをご参照ください。
`modelSettings.routable`	いいえ	クライアントがこのモデルに直接ルーティングできるかどうか。省略するとデフォルト (ルーティング可能) を継承します。投機的デコーディングのドラフトモデルでは `false` に設定してください。
`modelSettings.checkpointOverrides`	いいえ	`model` 参照の代わりに適用するチェックポイントの選択。モデルレベルのチェックポイントには `checkpoint` を、エキスパートごとのチェックポイントには `expertOverrides` を使用します。
`modelSettings.adapters`	いいえ	サービング名から LoRA アダプターのバインディングへのマッピング。`spec.adapters` で定義したアダプターを参照します。
`modelSettings.properties`	いいえ	モデルのすべてのエキスパートにわたって適用される追加の設定フィールド。

バッチングは次の優先順位で解決されます: まずモデル構成の batchingConfig、次にプロファイルの recommended 設定、次に all 設定、最後に PEF のグルーピングから生成された設定の順です。解決順序をご参照ください。

スワップ可能なモデル

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

投機的デコーディング

投機的デコーディングでは、小規模なドラフトモデルがトークンを提案し、大規模なターゲットモデルがそれを検証します。ペアはバンドルレベルの spec.specDecodingPairs で宣言し、ドラフトモデルは spec.modelConfigs にルーティング不可な独立したエントリとして含めます。

Legalizer の結果

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

ホステッド
オンプレミス

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 が設定されていた場合など、バンドルが一度も Legalizer による検証を受けていない場合は、legalizerInfo 自体が存在しません。また、Legalizer の出力を解析できなかった場合も utilization フィールドが存在しないことがあります。

はじめに

サービス管理

ハードウェア管理

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

リソース

ModelBundle

構造

モデル構成

スワップ可能なモデル

投機的デコーディング

Legalizer の結果

参考情報

カスタムバンドルの作成

ModelDeployment

​構造

​モデル構成

​スワップ可能なモデル

​投機的デコーディング

​Legalizer の結果

​参考情報

カスタムバンドルの作成

ModelDeployment

構造

モデル構成

スワップ可能なモデル

投機的デコーディング

Legalizer の結果

参考情報