> ## 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 上で特定の構成を持つモデルをデプロイするために、カスタムの **BundleTemplate** と **Bundle** を作成する方法を解説します。

SambaStack では、バンドルがデプロイの基本単位です。個別のモデルをデプロイするのではなく、1 つ以上のモデルを、バッチサイズやシーケンス長を含むデプロイ構成と共にまとめたバンドルをデプロイします。このアプローチは、SambaNova の Reconfigurable Dataflow Unit (RDU) を活用して 1 つのデプロイメント内で複数のモデルと構成をサポートし、構成間の即時切り替えによって効率性と柔軟性を向上させます。

> [!NOTE]
>
> 本ガイドはカスタムバンドルの作成を対象としています。SambaNova が提供する事前構成済みバンドルのデプロイについては、[バンドルのデプロイ](https://docs.sambanova.ai/docs/ja/v1.2.0/sambastack/service-administration/model-deployment/deploying-model-bundles.md)をご参照ください。

## 前提条件

カスタムバンドルを作成する前に、お使いの環境に該当する以下のセットアップを完了してください。

> **[クイックスタート - ホステッド](https://docs.sambanova.ai/docs/ja/v1.2.0/sambastack/getting-started/hosted.md)**
>
> ホステッド SambaStack のシステムセットアップ

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

加えて、以下のドキュメントもご確認ください。

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

### 用語

| 用語 | 定義 |
| - | - |
| **RDU** | Reconfigurable Dataflow Unit - SambaNova 独自のプロセッサアーキテクチャ |
| **PEF** | Processor Executable Format - RDU 上で実行される、コンパイル済みのモデルバイナリ |
| **エキスパート (Expert)** | モデル内のシーケンス長プロファイル構成 (例: 8k、16k、32k) |
| **投機的デコーディング (Speculative Decoding)** | より小さいドラフトモデルを使用して、より大きいターゲットモデルの推論を高速化する最適化手法 |
| **Legalizer** | バンドルが RDU のメモリ制約内に収まることを検証する検証プロセス |
| **CR (カスタムリソース)** | `Pef`、`Bundle`、`BundleTemplate` などのカスタムリソースタイプを定義する Kubernetes の拡張機構 |

## 概念

### バンドルアーキテクチャ

バンドルおよびバンドルテンプレートとは何かを含む、バンドルの基本概念の概要については、[モデルバンドルのデプロイ](https://docs.sambanova.ai/docs/ja/v1.2.0/sambastack/service-administration/model-deployment/deploying-model-bundles.md)をご参照ください。このセクションでは、**カスタム**バンドルを作成する際に使用する 3 層構造を解説します。

1. **BundleTemplate** - モデルを「どのように」実行できるかを定義します。利用可能なシーケンス長プロファイル、バッチサイズ、PEF のマッピングを指定します。また、投機的デコーディングのペアにおけるターゲットモデルとドラフトモデルの関係も定義します。
2. **Bundle** - テンプレートをストレージ上の「特定のチェックポイント」に紐づけ、デプロイ可能な状態にします。
3. **BundleDeployment** - バンドルの 1 つ以上のレプリカをクラスター上にインスタンス化します。

この分離により、以下が可能になります。

* ファインチューニング済みモデルのカスタムチェックポイントを含め、複数のチェックポイント間でテンプレートを再利用する
* 同じテンプレートを共有しながら、同一の基盤モデルの異なるチェックポイントをバンドルする
* 同じバンドル構成を異なるレプリカ数でデプロイする
* デプロイ構成を変更せずにチェックポイントを更新する

### BundleTemplate の構造

BundleTemplate は、1 つ以上のモデルのデプロイ能力を定義します。以下は、投機的デコーディング構成を含むマルチモデルテンプレートの例です。

```yaml theme={}
apiVersion: sambanova.ai/v1alpha1
kind: BundleTemplate
metadata:
  name: bt-gpt120-llama70sd8-llama8
spec:
  models:
    gpt-oss-120b:
      experts:
        8k:
          configs:
          - pef: gpt-oss-fp8-ss8192-bs2:1
        32k:
          configs:
          - pef: gpt-oss-fp8-ss32768-bs2:1
    Meta-Llama-3.3-70B-Instruct:
      experts:
        4k:
          configs:
          - pef: llama-3p1-70b-ss4096-bs4-sd5:3
            spec_decoding:
              draft_model: Meta-Llama-3.1-8B-Instruct
          - pef: llama-3p1-70b-ss4096-bs32-sd5:2
        8k:
          configs:
          - pef: llama-3p1-70b-ss8192-bs1-sd5:1
          - pef: llama-3p1-70b-ss8192-bs8-sd5:2
          default_config_values:
            spec_decoding:
              draft_model: Meta-Llama-3.1-8B-Instruct
        128k:
          configs:
          - pef: llama-3p1-70b-ss131072-bs1-sd5:2
    Meta-Llama-3.1-8B-Instruct:
      experts:
        4k:
          configs:
          - pef: llama-3p1-8b-ss4096-bs4:1
        8k:
          configs:
          - pef: llama-3p1-8b-ss8192-bs1:1
          - pef: llama-3p1-8b-ss8192-bs8:1
  owner: no-reply@sambanova.ai
  secretNames:
  - sambanova-artifact-reader
  usePefCRs: true
```

上記の例には、3 つのモデルの構成が含まれています。

* **gpt-oss-120b**: 2 個の構成
* **Meta-Llama-3.3-70B-Instruct**: 5 個の構成。うち 3 個は、Meta-Llama-3.1-8B-Instruct をドラフトモデルとする投機的デコーディングを使用
* **Meta-Llama-3.1-8B-Instruct**: 3 個の構成

投機的デコーディング関連のフィールドの詳細については、[投機的デコーディングのデプロイガイドライン](https://docs.sambanova.ai/docs/ja/v1.2.0/sambastack/service-administration/performance/deploy-with-speculative-decoding.md)をご参照ください。

**BundleTemplate のトップレベルフィールド**

| フィールド | 必須 | 説明 |
| - | - | - |
| `spec.models` | 必須 | モデルとそのエキスパート構成を定義します。[モデルとエキスパート](#モデルとエキスパート)をご参照ください。 |
| `spec.owner` | 必須 | 追跡と通知に使用する、バンドルテンプレート所有者のメールアドレス。 |
| `spec.secretNames` | 必須 | アーティファクトへのアクセスに使用する Kubernetes Secret のリスト。お使いの環境で構成されている Secret と一致している必要があります。 |
| `spec.usePefCRs` | 必須 | デプロイに PEF カスタムリソースを使用する場合は `true` に設定します。 |

#### モデルとエキスパート

BundleTemplate 内の各モデルには 1 つ以上の**エキスパート**が含まれ、それぞれがシーケンス長プロファイルを表します。一般的なプロファイルは以下のとおりです。

* `8k`、`16k`、`32k`、`64k`、`128k` - 固定シーケンス長の構成
* `default` - 特定の長さを必要としない場合の標準構成

```yaml theme={}
spec:
  models:
    Meta-Llama-3.1-8B-Instruct:
      experts:
        128k:
          configs:
            - <config>
        64k:
          configs:
            - <config>
        32k:
          configs:
            - <config>
        16k:
          configs:
            - <config>
        8k:
          configs:
            - <config>
        default:
          configs:
            - <config>
```

**エキスパート構成のパラメータ**

各エキスパートには、以下のパラメータを持つ構成が 1 つ以上含まれます。

| パラメータ | 必須 | 説明 |
| - | - | - |
| `pef` | 必須 | `<pef-name>:<version>` 形式の PEF カスタムリソースへの参照。`kubectl describe pef` でより新しいバージョンが確認できる場合を除き、バージョン `1` を使用してください。`<pef-name>` の `bs` の後の文字はバッチサイズを表します。 |
| `spec_decoding` | 任意 | 投機的デコーディングの構成。**ターゲットモデルにのみ指定します。ドラフトモデルには指定しないでください。** |

> **投機的デコーディングのパラメータ**
>
> `spec_decoding` 内のパラメータ (ターゲットモデルのみ):
>
> | パラメータ | 説明 |
> | - | - |
> | `draft_model` | 同じ BundleTemplate 内のドラフトモデルの名前 |
> | `draft_expert` | 使用するドラフトモデルのエキスパートプロファイル。ターゲットモデルのエキスパートのシーケンス長と一致させてください (例: 16k のターゲットエキスパートには 16k のドラフトエキスパートを使用)。 |
>
> 詳細なガイダンスについては、[投機的デコーディングのデプロイガイドライン](https://docs.sambanova.ai/docs/ja/v1.2.0/sambastack/service-administration/performance/deploy-with-speculative-decoding.md)をご参照ください。

### Bundle の構造

Bundle は、BundleTemplate を特定のチェックポイントに紐づけます。以下のセクションでは、Bundle マニフェストの各パートを説明します。

**リソースの識別情報**

Bundle 名とリソースタイプを定義します。

```yaml theme={}
apiVersion: sambanova.ai/v1alpha1
kind: Bundle
metadata:
  name: b-70b-3dot3-ss-16-32k-bs-4
```

* `metadata.name` - デプロイでこのバンドルを参照する際に使用する **Bundle 名**
* `apiVersion` と `kind` - すべてのバンドルで同じ値を使用します

**チェックポイント**

使用するモデルチェックポイントを定義します。

```yaml theme={}
spec:
  checkpoints:
    GPT_OSS_120B_CKPT:
      source: gs://<SAMBASTACK_ARTIFACTS_BUCKET>/path/to/checkpoint
      toolSupport: true
    META_LLAMA_3_3_70B_INSTRUCT_CKPT:
      source: gs://<SAMBASTACK_ARTIFACTS_BUCKET>/path/to/checkpoint
      toolSupport: true
    META_LLAMA_3_1_8B_INSTRUCT_CKPT:
      source: gs://<SAMBASTACK_ARTIFACTS_BUCKET>/path/to/checkpoint
      toolSupport: true
```

| フィールド | 説明 |
| - | - |
| `source` | モデルチェックポイントを指す GCS パス。利用可能なチェックポイントは[対応モデルとバンドル](https://docs.sambanova.ai/docs/ja/v1.2.0/sambastack/service-administration/model-deployment/supported-models-and-bundles.md)で確認できます。 |
| `toolSupport` | このチェックポイントがツールおよび Function calling (製品でサポートされている場合) に対応しているかどうかを示すブール値フラグ。 |

**モデル**

モデル名をチェックポイントとテンプレートにマッピングします。

```yaml theme={}
spec:
  models:
    gpt-oss-120b:
      checkpoint: GPT_OSS_120B_CKPT
      template: gpt-oss-120b
    Meta-Llama-3.3-70B-Instruct:
      checkpoint: META_LLAMA_3_3_70B_INSTRUCT_CKPT
      template: Meta-Llama-3.3-70B-Instruct
    Meta-Llama-3.1-8B-Instruct:
      checkpoint: META_LLAMA_3_1_8B_INSTRUCT_CKPT
      template: Meta-Llama-3.1-8B-Instruct
```

| フィールド | 説明 |
| - | - |
| `<model-key>` (例: `Meta-Llama-3.3-70B-Instruct`) | ユーザーが推論リクエストの送信先として指定する **API モデル名**。BundleTemplate の `spec.models` セクション内の名前と一致している必要があります。 |
| `checkpoint` | このモデルが使用するチェックポイントのエイリアス (`spec.checkpoints` で定義したもの)。 |
| `template` | 使用する、BundleTemplate の `spec.models` 内のモデルテンプレート。この値は、BundleTemplate の `spec.models` 配下で定義されたモデル名と**完全に一致**している必要があります。 |

**テンプレートと Secret**

Bundle を BundleTemplate および認証情報に関連付けます。

```yaml theme={}
spec:
  template: bt-gpt120-llama70sd8-llama8
  secretNames:
  - sambanova-artifact-reader
```

| フィールド | 説明 |
| - | - |
| `template` | BundleTemplate をその `metadata.name` で参照します。これにより、Bundle がそのテンプレートで定義されたデプロイ構成に関連付けられます。 |
| `secretNames` | GCS からチェックポイントを読み取るために使用する認証情報。お使いの環境で構成されている Secret と一致している必要があります。 |

#### Bundle の完全な例

以下は、マルチモデル Bundle の完全な例です。

```yaml theme={}
apiVersion: sambanova.ai/v1alpha1
kind: Bundle
metadata:
  name: b-gpt120-llama70sd8-llama8
spec:
  checkpoints:
    GPT_OSS_120B_CKPT:
      source: gs://<SAMBASTACK_ARTIFACTS_BUCKET>/path/to/checkpoint
      toolSupport: true
    META_LLAMA_3_3_70B_INSTRUCT_CKPT:
      source: gs://<SAMBASTACK_ARTIFACTS_BUCKET>/path/to/checkpoint
      toolSupport: true
    META_LLAMA_3_1_8B_INSTRUCT_CKPT:
      source: gs://<SAMBASTACK_ARTIFACTS_BUCKET>/path/to/checkpoint
      toolSupport: true
  models:
    gpt-oss-120b:
      checkpoint: GPT_OSS_120B_CKPT
      template: gpt-oss-120b
    Meta-Llama-3.3-70B-Instruct:
      checkpoint: META_LLAMA_3_3_70B_INSTRUCT_CKPT
      template: Meta-Llama-3.3-70B-Instruct
    Meta-Llama-3.1-8B-Instruct:
      checkpoint: META_LLAMA_3_1_8B_INSTRUCT_CKPT
      template: Meta-Llama-3.1-8B-Instruct
  secretNames:
  - sambanova-artifact-reader
  template: bt-gpt120-llama70sd8-llama8
```

SambaNova がホストするチェックポイントのパスは、SambaNova の担当者から提供されます。ご自身でチェックポイントをホストしている場合は、そのパスを上記の `source` フィールドに指定できます。

### BundleDeployment の構造

BundleDeployment は、バンドルをクラスター上にインスタンス化します。デプロイの詳細については、[クイックスタート - ホステッド](https://docs.sambanova.ai/docs/ja/v1.2.0/sambastack/getting-started/hosted.md)または[クイックスタート - オンプレミス](https://docs.sambanova.ai/docs/ja/v1.2.0/sambastack/getting-started/on-prem.md)をご参照ください。

```yaml theme={}
apiVersion: sambanova.ai/v1alpha1
kind: BundleDeployment
metadata:
  name: bd-gpt120-llama70sd8-llama8
spec:
  bundle: b-gpt120-llama70sd8-llama8
  groups:
  - minReplicas: 1
    name: default
    qosList:
    - free
  owner: no-reply@sambanova.ai
  secretNames:
  - sambanova-artifact-reader
```

| フィールド | 説明 |
| - | - |
| `spec.bundle` | デプロイする Bundle の名前 |
| `spec.groups[].name` | デプロイメントグループの識別名 |
| `spec.groups[].minReplicas` | 維持するバンドルレプリカの最小数 |
| `spec.groups[].qosList` | リクエストの優先度付けに使用する QoS クラス |
| `spec.owner` | 追跡と通知に使用する、デプロイメント所有者のメールアドレス |
| `spec.secretNames` | アーティファクトへのアクセスに使用する認証情報。お使いの環境で構成されている Secret と一致している必要があります。 |

### PEF とチェックポイントのライフサイクルステータス

SambaStack は、サポートライフサイクルを示すために、PEF CR のバージョンに `pef_status` フィールドを、モデル CR のチェックポイントバージョンに `checkpoint_status` フィールドを割り当てます。これらのステータスを理解することで、カスタムバンドルに使用する PEF やチェックポイントのバージョンを適切に選択できます。

**PEF およびチェックポイントバージョンのステータス値**

PEF CR の各バージョンエントリには `pef_status` フィールドが含まれます。チェックポイント CR のバージョンでは `checkpoint_status` が使用されます。両者は同じ値のセットを共有します。

| ステータス | 説明 |
| - | - |
| `preview` | 十分なテストやサポートが行われていません。信頼性やパフォーマンスに未知の問題がある可能性や、機能が限定されている可能性があります (例: Function calling の部分的なサポート)。本番ワークロードには推奨されません。 |
| `stable` | 完全にサポートされ、テスト済みです。 |
| `deprecated` | 信頼性またはパフォーマンスに既知の問題があります。安定版への移行を可能にするため、限られた移行期間 (提供終了の告知から最大 3 か月) の間は引き続き利用できます。 |
| `removed` | 使用できません。バージョンエントリは、トレーサビリティと監査可能性のために PEF CR またはモデル CR 内に保持されますが、パスはすでに存在しない可能性があり、参照するとデプロイが失敗します。 |

**ステータス付きの PEF CR バージョンの例**

```yaml theme={}
versions:
  '1':
    source: gs://ext-sambastack-artifacts-prod-0/path/to/pef_v1.pef
    pef_status: deprecated
  '2':
    source: gs://ext-sambastack-artifacts-prod-0/path/to/pef_v2.pef
    pef_status: stable
```

バージョンのステータスを確認するには、`kubectl describe pef <pef-name>` または `kubectl describe model <model-name>` を実行し、`Versions` セクションの `pef_status` または `checkpoint_status` フィールドを確認します。

> [!TIP]
>
> 以下の手順では、ここまでに説明した概念と構造を使用してカスタムバンドルを作成・デプロイするワークフローをステップごとに解説します。

## 手順

### 利用可能な PEF の確認

BundleTemplate を作成する前に、対象のモデルで利用可能な PEF リソースを確認します。

**1. 利用可能な PEF の一覧表示**

モデルとシーケンス長の要件に一致する PEF を一覧表示します。

**ホステッド**

```bash theme={}
kubectl get pefs | grep <model-pattern>
```

例:

```bash theme={}
kubectl get pefs | grep llama-3p1-70b-ss4096
```

**オンプレミス**

```bash theme={}
kubectl -n <namespace> get pefs.sambanova.ai | grep <model-pattern>
```

例:

```bash theme={}
kubectl -n <namespace> get pefs.sambanova.ai | grep llama-3p1-70b-ss4096
```

出力:

```text theme={}
llama-3p1-70b-ss4096-bs1-sd9     17h
llama-3p1-70b-ss4096-bs16-sd5    17h
llama-3p1-70b-ss4096-bs2-sd5     17h
llama-3p1-70b-ss4096-bs32-sd5    17h
llama-3p1-70b-ss4096-bs4-sd5     17h
llama-3p1-70b-ss4096-bs8-sd5     17h
```

**2. PEF の詳細確認**

PEF の詳細を表示し、サポートされている構成の把握と、より新しいバージョンの有無の確認を行います。

**ホステッド**

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

出力例:

```text theme={}
$ kubectl describe pef deepseek-ss131072-bs1
Name:         deepseek-ss131072-bs1
...
Spec:
  copy_pef:                gs://<SAMBASTACK_ARTIFACTS_BUCKET>/path/to/copy_pef
  copy_pef_name_override:  COPY_PEF_DEEPSEEK_R1_128K_PEF_BS1
  Metadata:
    batch_size:             1
    is_prompt_caching:      false
    job_type:               infer
    max_completion_tokens:  131072
    max_seq_length:         131072
    num_rdus:               16
    rdu_arch:               SN40L-16
    seq_lengths:
      65536
      131072
  model_arch:         deepseek
  pef_name_override:  DEEPSEEK_R1_128K_PEF_BS1
  Versions:
    1:
      cached_path:  gs://<SAMBASTACK_ARTIFACTS_BUCKET>/path/to/pef_v1.pef
      pef_status:   deprecated
      Source:       gs://<SAMBASTACK_ARTIFACTS_BUCKET>/path/to/pef_v1.pef
    2:
      cached_path:  gs://<SAMBASTACK_ARTIFACTS_BUCKET>/path/to/pef_v2.pef
      pef_status:   stable
      Source:       gs://<SAMBASTACK_ARTIFACTS_BUCKET>/path/to/pef_v2.pef
```

**オンプレミス**

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

出力例:

```text theme={}
$ kubectl -n <namespace> describe pef.sambanova.ai deepseek-ss131072-bs1
Name:         deepseek-ss131072-bs1
...
Spec:
  copy_pef:                gs://<SAMBASTACK_ARTIFACTS_BUCKET>/path/to/copy_pef
  copy_pef_name_override:  COPY_PEF_DEEPSEEK_R1_128K_PEF_BS1
  Metadata:
    batch_size:             1
    is_prompt_caching:      false
    job_type:               infer
    max_completion_tokens:  131072
    max_seq_length:         131072
    num_rdus:               16
    rdu_arch:               SN40L-16
    seq_lengths:
      65536
      131072
  model_arch:         deepseek
  pef_name_override:  DEEPSEEK_R1_128K_PEF_BS1
  Versions:
    1:
      cached_path:  gs://<SAMBASTACK_ARTIFACTS_BUCKET>/path/to/pef_v1.pef
      pef_status:   deprecated
      Source:       gs://<SAMBASTACK_ARTIFACTS_BUCKET>/path/to/pef_v1.pef
    2:
      cached_path:  gs://<SAMBASTACK_ARTIFACTS_BUCKET>/path/to/pef_v2.pef
      pef_status:   stable
      Source:       gs://<SAMBASTACK_ARTIFACTS_BUCKET>/path/to/pef_v2.pef
```

`Spec.Metadata` セクションで以下を確認します。

* `batch_size` - サポートされるバッチサイズ
* `max_seq_length` - 最大シーケンス長
* `num_rdus` - 必要な RDU 数
* `rdu_arch` - 必要な RDU アーキテクチャ
* `seq_lengths` - サポートされるシーケンス長

BundleTemplate で参照する前に、`Versions` セクションを確認して、より新しい PEF バージョンが利用可能かどうかと、各バージョンの `pef_status` を確認してください。

> [!TIP]
>
> `kubectl describe pef` でより新しいバージョンが利用可能であることが確認できる場合を除き、PEF の参照にはバージョン `1` を使用してください (例: `llama-3p1-70b-ss16384-bs4-sd5:1`)。

### BundleTemplate の作成

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

BundleTemplate 用の YAML ファイルを作成します。単一モデルのテンプレートの場合:

```yaml theme={}
apiVersion: sambanova.ai/v1alpha1
kind: BundleTemplate
metadata:
  name: bt-gpt120
spec:
  models:
    gpt-oss-120b:
      experts:
        8k:
          configs:
          - pef: gpt-oss-fp8-ss8192-bs2:1
        32k:
          configs:
          - pef: gpt-oss-fp8-ss32768-bs2:1
        64k:
          configs:
          - pef: gpt-oss-fp8-ss65536-bs2:1
        128k:
          configs:
          - pef: gpt-oss-fp8-ss131072-bs2:1
  owner: no-reply@sambanova.ai
  secretNames:
  - sambanova-artifact-reader
  usePefCRs: true
```

投機的デコーディングを含むマルチモデルテンプレートについては、[BundleTemplate の構造](#bundletemplate-の構造)の例をご参照ください。

**2. BundleTemplate の適用**

**ホステッド**

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

**オンプレミス**

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

**3. 作成の確認**

**ホステッド**

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

**オンプレミス**

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

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

### バンドルの作成

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

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

```yaml theme={}
apiVersion: sambanova.ai/v1alpha1
kind: Bundle
metadata:
  name: b-gpt120
spec:
  checkpoints:
    GPT_OSS_120B_CKPT:
      source: gs://<SAMBASTACK_ARTIFACTS_BUCKET>/path/to/checkpoint
      toolSupport: true
  models:
    gpt-oss-120b:
      checkpoint: GPT_OSS_120B_CKPT
      template: gpt-oss-120b
  secretNames:
  - sambanova-artifact-reader
  template: bt-gpt120
```

マルチモデルバンドルについては、[Bundle の完全な例](#bundle-の完全な例)をご参照ください。

**2. Bundle の適用**

**ホステッド**

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

**オンプレミス**

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

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

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

**ホステッド**

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

**オンプレミス**

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

**検証成功**

```text theme={}
Status:
  Conditions:
    Last Transition Time:  2025-12-22T21:11:05.689262+00:00
    Message:               Bundle is Valid
    Observed Generation:   1
    Reason:                ValidationSucceeded
    Status:                True
    Type:                  Valid
```

**検証失敗**

```text theme={}
Status:
  Conditions:
    Last Transition Time:  2025-12-22T21:11:54.975311+00:00
    Message:               <error-details>
    Reason:                ValidationFailed
    Status:                False
    Type:                  Valid
```

`Message` フィールドには、Legalizer のエラーを含むエラーの詳細が記録されます。

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

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

**1. BundleDeployment の作成**

```yaml theme={}
apiVersion: sambanova.ai/v1alpha1
kind: BundleDeployment
metadata:
  name: bd-gpt120
spec:
  bundle: b-gpt120
  groups:
  - minReplicas: 1
    name: default
    qosList:
    - free
  owner: no-reply@sambanova.ai
  secretNames:
  - sambanova-artifact-reader
```

**2. BundleDeployment の適用**

**ホステッド**

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

**オンプレミス**

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

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

**ホステッド**

```bash theme={}
kubectl get bundledeployments
kubectl describe bundledeployment <deployment-name>
```

**オンプレミス**

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

### バンドル/BundleTemplate の更新・削除

**バンドルの更新**

**1. YAML ファイルの修正**

Bundle または BundleTemplate の YAML ファイルに変更を加えます。

**2. 設定の再適用**

**ホステッド**

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

**オンプレミス**

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

Legalizer が変更内容を自動的に再検証します。

**バンドルの削除**

**1. BundleDeployment の削除**

**ホステッド**

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

**オンプレミス**

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

**2. Bundle の削除**

**ホステッド**

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

**オンプレミス**

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

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

**ホステッド**

```bash theme={}
kubectl delete bundletemplate <template-name>
```

**オンプレミス**

```bash theme={}
kubectl -n <namespace> delete bundletemplate <template-name>
```

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

### Legalizer 検証の失敗

| エラーパターン | 原因 | 対処方法 |
| - | - | - |
| `PEF pef1 and pef2 are not checkpoint compatible (checkpoint #0)` | 同じ `ckpt_sharing_uuid` を持つ PEF はチェックポイントメモリを共有できません | 互換性のない PEF に異なる `ckpt_sharing_uuid` の値を割り当ててください |
| `Bundle exceeds memory constraints` | PEF とチェックポイントの合計サイズが RDU メモリを超過しています | テンプレート内のエキスパート数またはバッチサイズを減らしてください |
| `PEF not found: <pef-name>` | 参照された PEF が存在しません | `kubectl get pefs` で PEF 名を確認してください |

### デプロイの失敗

| 症状 | 考えられる原因 | 対処方法 |
| - | - | - |
| デプロイが pending のまま進まない | RDU リソースの不足 | クラスターの容量を確認し、`minReplicas` を減らしてください |
| チェックポイントのダウンロードが失敗する | GCS パスが無効、または認証情報の不足 | `source` パスを確認し、`sambanova-artifact-reader` Secret が存在することを確認してください |
| API 経由でモデルにアクセスできない | モデル名の不一致 | `spec.models.<name>` が想定される API エンドポイントと一致していることを確認してください |

## 参考情報

> **[モデルのデプロイ](https://docs.sambanova.ai/docs/ja/v1.2.0/sambastack/service-administration/model-deployment/deploying-model-bundles.md)**
>
> バンドルデプロイの概念とワークフロー

> **[対応モデルとバンドル](https://docs.sambanova.ai/docs/ja/v1.2.0/sambastack/service-administration/model-deployment/supported-models-and-bundles.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/model-deployment/checkpoint-conversion-tool.md)**
>
> チェックポイントの互換形式への変換