> ## 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.

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

> SambaStack で ModelProfile・ModelBundle・ModelDeployment リソースを使用してモデルとバンドルをデプロイする方法を、カスタムモデル・カスタムチェックポイントを含むカスタムバンドルとあわせて解説します。

本ガイドでは、カスタムリソースを作成して、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 が提供するバンドルについては、[対応モデルとバンドル](/docs/ja/v2.0.2/sambastack/service-administration/model-deployment/supported-models-and-bundles.md) をご覧ください。

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

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

> [!NOTE]
>
> 本ガイドでは、SambaNova が提供するバンドルのデプロイと、独自のバンドルの作成の両方を扱います。提供されているバンドルのカタログについては、[対応モデルとバンドル](/docs/ja/v2.0.2/sambastack/service-administration/model-deployment/supported-models-and-bundles.md) をご覧ください。

## 前提条件

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

> **[クイックスタート - ホステッド](/docs/ja/v2.0.2/sambastack/getting-started/hosted.md)**
>
> ホステッド版 SambaStack のシステムセットアップ

> **[クイックスタート - オンプレミス](/docs/ja/v2.0.2/sambastack/getting-started/on-prem.md)**
>
> オンプレミス版 SambaStack のシステムセットアップ

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

* [対応モデルとバンドル](/docs/ja/v2.0.2/sambastack/service-administration/model-deployment/supported-models-and-bundles.md) - 利用可能なモデルチェックポイント
* [投機的デコーディングのデプロイガイドライン](/docs/ja/v2.0.2/sambastack/service-administration/performance/deploy-with-speculative-decoding.md) - 投機的デコーディングのペアを設定する場合に必要

### 用語

| 用語 | 定義 |
| - | - |
| **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` を使用します。

```mermaid theme={}
graph TD
    PEF["PEF<br/><small>references to versioned executables</small>"]
    MP["ModelProfile<br/><small>set&nbsp;of&nbsp;feature‑compatible&nbsp;PEFs&nbsp;for&nbsp;a&nbsp;model&nbsp;arch<br/>+&nbsp;default&nbsp;batching&nbsp;configuration</small>"]
    M["Model<br/><small>checkpoints per architecture</small>"]
    MB["ModelBundle<br/><small>reusable,&nbsp;shareable&nbsp;set&nbsp;of<br/>models&nbsp;+&nbsp;profiles</small>"]
    MD["ModelDeployment<br/><small>routable inference endpoint, replicas &amp; QoS, backed by serving pods</small>"]
    JP("<i>ModelProfile & Model Pair</i><br/><small>implicit pairing, not a CR<br/>model_arch must be compatible</small>")

    PEF -->|"referenced by"| MP
    MP --- JP
    M --- JP
    JP -->|"referenced by"| MB
    MB ==>|"bundle deploy"| MD
    JP -.->|"direct deploy"| MD

    classDef cluster fill:#eef2f7,stroke:#8aa0bd,color:#1a2b45;
    classDef authored fill:#cfe2f3,stroke:#2f6fb0,color:#0d2c4d,stroke-width:2px;
    classDef config fill:#fbe7c6,stroke:#c9871f,color:#5c3d00;
    class PEF,MP,M cluster;
    class MB,MD authored;
    class JP config;
```

薄い色のボックスは SambaStack のインストールと共に提供され、名前で参照するリソースです。濃い色のボックスは、ユーザーが作成するリソースです。琥珀色のボックスはカスタムリソースではなく、`Model` と `ModelProfile` の 1 つのペアリングを表しており、`spec.modelConfigs` の 1 エントリに対応します。

各リソースは、次のように責務を分担します。

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

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

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

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

### ModelProfile の構造

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

```yaml theme={}
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` 形式のコード長キーを使用します。

```yaml theme={}
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 つです。 |

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

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

`ModelProfile` は各ティアで利用可能なバッチサイズを確立するものであるため、`defaultBatchingConfig` では常にバッチサイズを明示的に列挙します。`"*"` は使用しません。

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

```yaml theme={}
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` リソースのリファレンスは、[カスタムチェックポイントのデプロイ](/docs/ja/v2.0.2/sambastack/service-administration/model-deployment/deploy-custom-checkpoints.md#pef-の構造) をご覧ください。

### ModelBundle の構造

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

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

```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-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` にルーティング不可の独立したエントリとして含めます。

フィールドリファレンス、要件、カスタムドラフトチェックポイントを含む完全なワークフローについては、[投機的デコーディングによるデプロイ](/docs/ja/v2.0.2/sambastack/service-administration/performance/deploy-with-speculative-decoding.md) をご覧ください。

### ModelDeployment の構造

ModelDeployment は、クラスター上でモデルをインスタンス化し、ルーティング可能な推論エンドポイントを支えるサービング Pod を作成します。デプロイの詳細については、[クイックスタート - ホステッド](/docs/ja/v2.0.2/sambastack/getting-started/hosted.md) または [クイックスタート - オンプレミス](/docs/ja/v2.0.2/sambastack/getting-started/on-prem.md) をご覧ください。

モデルソースは、**必ずいずれか一方のみ**を設定します。

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

```yaml theme={}
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**

```bash theme={}
kubectl describe modelbundle <bundle-name>
```

**On Premise**

```bash theme={}
kubectl -n <namespace> describe modelbundle.sambanova.ai <bundle-name>
```

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

```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` | 検証警告のリスト。各項目は `<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% を表します) |

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

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

## 手順

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

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

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

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

**Hosted**

```bash theme={}
kubectl get models
```

例:

```bash theme={}
kubectl describe model gpt-oss-120b
```

**On Premise**

```bash theme={}
kubectl -n <namespace> get models.sambanova.ai
```

例:

```bash theme={}
kubectl -n <namespace> describe model.sambanova.ai gpt-oss-120b
```

> [!NOTE]
>
> これらのコマンドが一覧表示するのは Kubernetes のリソース名 (`metadata.name`) であり、推論 API に送信する名前ではありません。リクエストには `spec.name` のサービング名を使用してください。[対応モデルとバンドル](/docs/ja/v2.0.2/sambastack/service-administration/model-deployment/supported-models-and-bundles.md#対応モデルの一覧) をご覧ください。

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

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

**Hosted**

```bash theme={}
kubectl get modelprofiles
```

**On Premise**

```bash theme={}
kubectl -n <namespace> get modelprofiles.sambanova.ai
```

出力:

```text theme={}
deepseek              17h
gpt-oss-fp8-dyt       17h
llama-3p1-70b-sd      17h
llama-3p1-8b          17h
```

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

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

**Hosted**

```bash theme={}
kubectl describe modelprofile <profile-name>
```

**On Premise**

```bash theme={}
kubectl -n <namespace> describe modelprofile.sambanova.ai <profile-name>
```

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

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

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

### 単一モデルのデプロイ

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

**1. YAML ファイルの作成**

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

```yaml theme={}
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` から解決されます。

**2. ModelDeployment の適用**

**Hosted**

```bash theme={}
kubectl apply -f <modeldeployment-file>.yaml
```

**On Premise**

```bash theme={}
kubectl -n <namespace> apply -f <modeldeployment-file>.yaml
```

**3. デプロイ状態の監視**

**Hosted**

```bash theme={}
kubectl get modeldeployments
kubectl describe modeldeployment <deployment-name>
```

**On Premise**

```bash theme={}
kubectl -n <namespace> get modeldeployments.sambanova.ai
kubectl -n <namespace> describe modeldeployment.sambanova.ai <deployment-name>
```

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

### ModelBundle の作成

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

**1. YAML ファイルの作成**

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

```yaml theme={}
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-の構造) の例をご覧ください。

**2. ModelBundle の適用**

**Hosted**

```bash theme={}
kubectl apply -f <modelbundle-file>.yaml
```

**On Premise**

```bash theme={}
kubectl -n <namespace> apply -f <modelbundle-file>.yaml
```

**3. Legalizer による検証の確認**

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

**Hosted**

```bash theme={}
kubectl describe modelbundle <bundle-name>
```

**On Premise**

```bash theme={}
kubectl -n <namespace> describe modelbundle.sambanova.ai <bundle-name>
```

**検証成功**

```text theme={}
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
```

**検証失敗**

```text theme={}
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 の結果を直接確認するには、次を実行します。

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

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

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

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

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

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

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

**Hosted**

```bash theme={}
kubectl get modelbundles
```

**On Premise**

```bash theme={}
kubectl -n <namespace> get modelbundles.sambanova.ai
```

出力:

```text theme={}
mb-gpt120                      17h
mb-gpt120-llama70sd8-llama8    17h
ds-v32-gemma-4-31b             3h
```

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

**2. ModelDeployment の作成**

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

```yaml theme={}
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
```

**3. ModelDeployment の適用**

**Hosted**

```bash theme={}
kubectl apply -f <modeldeployment-file>.yaml
```

**On Premise**

```bash theme={}
kubectl -n <namespace> apply -f <modeldeployment-file>.yaml
```

**4. デプロイ状態の監視**

**Hosted**

```bash theme={}
kubectl get modeldeployments
kubectl describe modeldeployment <deployment-name>
```

**On Premise**

```bash theme={}
kubectl -n <namespace> get modeldeployments.sambanova.ai
kubectl -n <namespace> describe modeldeployment.sambanova.ai <deployment-name>
```

### バンドルの切り替え

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

**1. 既存の ModelDeployment の削除**

**Hosted**

```bash theme={}
kubectl delete modeldeployment <deployment-name>
```

**On Premise**

```bash theme={}
kubectl -n <namespace> delete modeldeployment <deployment-name>
```

**2. 新しいバンドル用の ModelDeployment の適用**

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

```yaml theme={}
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 を適用します。

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

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

**Hosted**

```bash theme={}
kubectl get pods
```

**On Premise**

```bash theme={}
kubectl -n <namespace> get pods
```

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

独自に変換またはファインチューニングしたチェックポイントをサービングするには、既存モデルが使用するチェックポイントをオーバーライドするか、そのチェックポイント用に新しいモデルを登録します。[カスタムチェックポイントのデプロイ](/docs/ja/v2.0.2/sambastack/service-administration/model-deployment/deploy-custom-checkpoints.md) をご覧ください。

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

SambaStack がまだサポートしていないモデルアーキテクチャをサービングするには、PEF のコンパイルと、`Pef`、`ModelProfile`、`Model` リソースの作成が必要です。[カスタムチェックポイントのデプロイ](/docs/ja/v2.0.2/sambastack/service-administration/model-deployment/deploy-custom-checkpoints.md#カスタムモデルアーキテクチャの追加) をご覧ください。

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

**構成の更新**

**1. YAML ファイルの変更**

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

**2. 構成の再適用**

**Hosted**

```bash theme={}
kubectl apply -f <modified-file>.yaml
```

**On Premise**

```bash theme={}
kubectl -n <namespace> apply -f <modified-file>.yaml
```

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

**構成の削除**

**1. ModelDeployment の削除**

**Hosted**

```bash theme={}
kubectl delete modeldeployment <deployment-name>
```

**On Premise**

```bash theme={}
kubectl -n <namespace> delete modeldeployment <deployment-name>
```

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

**Hosted**

```bash theme={}
kubectl delete modelbundle <bundle-name>
```

**On Premise**

```bash theme={}
kubectl -n <namespace> delete modelbundle <bundle-name>
```

**3. ModelProfile の削除 (任意)**

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

**Hosted**

```bash theme={}
kubectl delete modelprofile <profile-name>
```

**On Premise**

```bash theme={}
kubectl -n <namespace> delete modelprofile <profile-name>
```

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

### Legalizer の検証失敗

エラーは `status.legalizerInfo.errors` に表示され、`ValidationFailed` の原因になります。警告は `status.legalizerInfo.warnings` に表示され、デプロイを妨げません。[Legalizer の結果](#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` に設定してください |

## 関連ドキュメント

> **[バンドル設定の移行](/docs/ja/v2.0.2/sambastack/service-administration/model-deployment/sambastack-v2-bundle-migration.md)**
>
> 非推奨のカスタムリソースで構築したバンドルの移行

> **[対応モデルとバンドル](/docs/ja/v2.0.2/sambastack/service-administration/model-deployment/supported-models-and-bundles.md)**
>
> デプロイ可能なモデルとバンドルのカタログ

> **[カスタムチェックポイントのデプロイ](/docs/ja/v2.0.2/sambastack/service-administration/model-deployment/deploy-custom-checkpoints.md)**
>
> 独自のカスタムチェックポイントやファインチューニング済みチェックポイントのデプロイ

> **[チェックポイント変換ツール](/docs/ja/v2.0.2/sambastack/service-administration/model-deployment/checkpoint-conversion-tool.md)**
>
> チェックポイントを互換形式に変換