> ## 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 は、**バンドル**をデプロイすることでモデルを提供します。バンドルとは、1 つ以上のモデルを、バッチサイズやシーケンス長を含むデプロイ構成と共にまとめたパッケージです。これにより、多数のモデルを同時に提供でき、重みを再ロードすることなくモデル間を即座に切り替えられます。このアプローチは、単一の静的なモデルをロードする従来の GPU デプロイと比較して、効率性、柔軟性、スループットを向上させます。

例えば、1 つのバンドルに `Llama-3.3-70B-Instruct` と `Llama-3.1-8B-Instruct` を含めることで、両者をほぼ瞬時に切り替えられます。バンドル内のモデルの各構成はそれぞれ容量を消費するため、バンドルごとに含まれる構成のセットは異なります。例えば、バッチサイズ 4、シーケンス長 16K の `Llama-3.3-70B-Instruct` は 1 つの構成に相当します。ユースケースに基づいて、最適なバンドルを選択できます。現在の一覧は[対応モデルとバンドル](https://docs.sambanova.ai/docs/ja/v1.2.0/sambastack/service-administration/model-deployment/supported-models-and-bundles.md)のページをご参照ください。

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

## 概念

### バンドルテンプレート

**バンドルテンプレート**は、1 つのノード上でどのモデルと構成を一緒にデプロイできるかを定義します。各バンドルテンプレートには 1 つ以上の**モデルテンプレート**が含まれ、それぞれがサポートされるシーケンス長とバッチサイズを指定します。

BundleTemplate 内でモデルテンプレートがどのように定義されるかの詳細な例は、[カスタムバンドルのデプロイ → BundleTemplate の構造](https://docs.sambanova.ai/docs/ja/v1.2.0/sambastack/service-administration/model-deployment/custom-bundle-deployment.md#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 の構造](https://docs.sambanova.ai/docs/ja/v1.2.0/sambastack/service-administration/model-deployment/custom-bundle-deployment.md#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 レベルを含め、クラスター全体でバンドルをどのようにデプロイするかを定義します。 |

カスタムバンドルについては、[カスタムバンドルのデプロイ](https://docs.sambanova.ai/docs/ja/v1.2.0/sambastack/service-administration/model-deployment/custom-bundle-deployment.md)をご参照ください。

**設定例:**

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

> [!NOTE]
>
> 完全な例は [SambaStack.yaml リファレンス](https://docs.sambanova.ai/docs/ja/v1.2.0/sambastack/resources/sambastack-yaml.md)をご参照ください。

## バンドルの切り替え

別のバンドルに切り替えるには、`bundleSpecs` と `bundleDeploymentSpecs` の両方を新しいバンドル名で更新します。

利用可能なバンドルは[対応モデルとバンドル](https://docs.sambanova.ai/docs/ja/v1.2.0/sambastack/service-administration/model-deployment/supported-models-and-bundles.md)をご参照ください。新しいバンドルテンプレートをリクエストする場合は、SambaNova のサポート窓口までお問い合わせください。

**例:**

```yaml theme={}
bundles:
  bundleSpecs:
    - name: qwen3-32b-whisper

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

> [!NOTE]
>
> 完全な例は [SambaStack.yaml リファレンス](https://docs.sambanova.ai/docs/ja/v1.2.0/sambastack/resources/sambastack-yaml.md)をご参照ください。

変更を適用します。

```bash theme={}
kubectl apply -f sambastack.yaml
```

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

```text theme={}
configmap/sambastack configured
```

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

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

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

> [!NOTE]
>
> 完全な例は [SambaStack.yaml リファレンス](https://docs.sambanova.ai/docs/ja/v1.2.0/sambastack/resources/sambastack-yaml.md)をご参照ください。

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

### デプロイ状態の確認

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

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

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

```bash theme={}
kubectl get bundle <bundle-name> -o yaml
```

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

```yaml theme={}
# Legalizer passed
status:
  legalizerInfo:
    errors: []
    status: Legalizer passed
    utilization:
      ddr: '0.75'
      hbm_resident: '0.65'
      host: '0.30'
    warnings: []
```

```yaml theme={}
# 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: []
```

```yaml theme={}
# 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% を表します) |

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

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

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

**前提条件:**

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

変換手順については、[カスタムチェックポイントのデプロイガイド](https://docs.sambanova.ai/docs/ja/v1.2.0/sambastack/service-administration/model-deployment/deploy-custom-checkpoints.md)をご参照ください。

### バンドル構成の作成

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

```yaml theme={}
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 の構造](https://docs.sambanova.ai/docs/ja/v1.2.0/sambastack/service-administration/model-deployment/custom-bundle-deployment.md#bundletemplate-の構造)をご参照ください。

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

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

### 要件

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

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

### 互換性の検証

デプロイ前に、SN Conversion Library を使用してドラフトチェックポイントとターゲットチェックポイントの互換性を検証してください。詳細は[投機的デコーディングガイド](https://docs.sambanova.ai/docs/ja/v1.2.0/sambastack/service-administration/performance/deploy-with-speculative-decoding.md)をご参照ください。

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

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

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

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

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

## 参考情報

* [カスタムバンドルのデプロイ](https://docs.sambanova.ai/docs/ja/v1.2.0/sambastack/service-administration/model-deployment/custom-bundle-deployment.md)
* [カスタムチェックポイントのデプロイ](https://docs.sambanova.ai/docs/ja/v1.2.0/sambastack/service-administration/model-deployment/deploy-custom-checkpoints.md)
* [投機的デコーディング](https://docs.sambanova.ai/docs/ja/v1.2.0/sambastack/service-administration/performance/deploy-with-speculative-decoding.md)
* [対応モデルとバンドル](https://docs.sambanova.ai/docs/ja/v1.2.0/sambastack/service-administration/model-deployment/supported-models-and-bundles.md)