> ## 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.
# ModelBundle
ModelBundle は、1 つ以上のモデルとプロファイルのペアを、名前を持つ 1 つのデプロイ可能な単位にまとめます。`spec.modelConfigs` の各エントリは [Model](/docs/ja/sambastack/service-administration/model-deployment/custom-resources/model) と [ModelProfile](/docs/ja/sambastack/service-administration/model-deployment/custom-resources/model-profile) を名前で参照し、モデルごとのバッチングとモデル構成を指定できます。
`ModelBundle` リソースは `apiVersion: sambanova.ai/v1alpha1` を使用します。
バンドルの作成は任意です。単一のモデルをサービングする場合は、プロファイルとペアにして直接デプロイできます。複数のモデルを 1 つの単位としてサービングする場合、投機的デコーディングを設定する場合、または名前付きの構成を検証して共有する場合に、バンドルを作成してください。
## 構造
以下は複数モデルを含むバンドルの例です。
```yaml theme={}
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` 参照。モデルのアーキテクチャが 1 つだけの場合はアーキテクチャ部分を省略でき、バージョンを省略すると最新バージョンが使用されます。 |
| `profile` | 条件付き | このモデルが使用する `ModelProfile` の名前。`profile` と `profileDefinition` のいずれか一方のみを設定します (同時には指定できません)。 |
| `profileDefinition` | 条件付き | インラインのプロファイル仕様。モデルの PEF が複数の標準プロファイルにまたがる場合に使用します。`profile` と `profileDefinition` のいずれか一方のみを設定します (同時には指定できません)。 |
| `batchingConfig` | いいえ | プロファイルのバッチングをバンドル単位でオーバーライドします。プロファイルの `batchingConfigs` のエントリ名を示す文字列 (`all` や `recommended` など) か、インラインのティアマップのいずれかを指定します。ティアマップでは、ティアに `"*"` を設定すると、そのティアに対してプロファイルが提供するすべてのバッチサイズが選択されます。[バッチング設定のオーバーライド](/docs/ja/sambastack/service-administration/model-deployment/custom-resources/model-profile#バッチング設定のオーバーライド) をご参照ください。 |
| `modelSettings.swappable` | いいえ | モデルをスワップ可能にするかどうか。[スワップ可能なモデル](#スワップ可能なモデル) をご参照ください。 |
| `modelSettings.routable` | いいえ | クライアントがこのモデルに直接ルーティングできるかどうか。省略するとデフォルト (ルーティング可能) を継承します。**投機的デコーディングのドラフトモデルでは `false` に設定してください。** |
| `modelSettings.checkpointOverrides` | いいえ | `model` 参照の代わりに適用するチェックポイントの選択。モデルレベルのチェックポイントには `checkpoint` を、エキスパートごとのチェックポイントには `expertOverrides` を使用します。 |
| `modelSettings.adapters` | いいえ | サービング名から LoRA アダプターのバインディングへのマッピング。`spec.adapters` で定義したアダプターを参照します。 |
| `modelSettings.properties` | いいえ | モデルのすべてのエキスパートにわたって適用される追加の設定フィールド。 |
バッチングは次の優先順位で解決されます: まずモデル構成の `batchingConfig`、次にプロファイルの `recommended` 設定、次に `all` 設定、最後に PEF のグルーピングから生成された設定の順です。[解決順序](/docs/ja/sambastack/service-administration/model-deployment/custom-resources/model-profile#解決順序) をご参照ください。
## スワップ可能なモデル
`swappable` 設定は、同じエンドポイント上の別のモデルを優先して、モデルを HBM から退避できるかどうかを制御します。`swappable` を `true` に設定すると、そのエンドポイントで別のモデルを実行する必要が生じた場合に、モデル全体が HBM から削除されます。これには、モデルのチェックポイントの重み、プロファイルのメタデータ、PEF が含まれます。
別のモデルのために容量を解放する目的で退避してよいモデルではこのフィールドを `true` に設定し、常駐させ続ける必要があるモデルでは未設定のままにするか `false` に設定してください。
## 投機的デコーディング
投機的デコーディングでは、小規模なドラフトモデルがトークンを提案し、大規模なターゲットモデルがそれを検証します。ペアはバンドルレベルの `spec.specDecodingPairs` で宣言し、ドラフトモデルは `spec.modelConfigs` にルーティング不可な独立したエントリとして含めます。
## Legalizer の結果
Legalizer は、デプロイ前に構成のリソース要件を検証します。ModelBundle を適用すると自動的に実行され、その結果は `status.legalizerInfo` の下に公開されます。バンドルのステータスには、各モデルに対して解決された有効なバッチング設定も報告されます。
```bash theme={}
kubectl describe modelbundle
```
```bash theme={}
kubectl -n describe modelbundle.sambanova.ai
```
以下は、警告付きで検証を通過したバンドルのステータスの例です。
```text theme={}
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` | 検証警告のリスト。各警告は `: ` 形式です。警告はデプロイをブロックしません。 |
| `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` フィールドが存在しないことがあります。
## 参考情報
独自のバンドルを作成し、適用して検証します
クラスター上でバンドルをサービングします