> ## 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 v2.0.2 では、`BundleTemplate`、`Bundle`、`BundleDeployment` の各リソースが、次の 4 つの新しいリソースに置き換えられます。

* `Model` と `ModelProfile` は、何を提供し、どのように実行するかを記述します。
* `ModelDeployment` はそれを提供します。モデルとプロファイルを直接参照できます。
* `ModelBundle` は、必要な場合に複数のモデルを 1 つの単位にまとめます。

`ModelDeployment` がモデルとプロファイルを直接参照するため、バンドルは必須ではなくなりました。1 つのモデルの提供に必要なリソースは、3 つではなく 1 つになります。

本ページは移行ガイドです。新しいリソースモデルによる変更点、旧形式からのフィールドの対応関係、提供終了までのスケジュールを解説します。

<Warning>
  **旧リソースモデル形式の提供終了予定。** 旧リソースモデル形式は提供終了予定 (deprecated) となっていますが、**2026年9月30日までは引き続き動作します**。それまでは、両方の形式の設定を同じクラスター内で併存させることができます。新規の設定には新形式を使用し、既存のバンドルは期日までに移行してください。
</Warning>

<Note>
  新しいリソースの相互関係については、[モデルとバンドルのデプロイ](/docs/ja/sambastack/service-administration/model-deployment/deploying-models-and-bundles/overview) をご参照ください。各リソースのフィールドリファレンスは、**カスタムリソース**配下の各ページをご参照ください。作成とデプロイの手順については、[単一モデルのデプロイ](/docs/ja/sambastack/service-administration/model-deployment/deploying-models-and-bundles/deploy-a-single-model)、[カスタムバンドルの作成](/docs/ja/sambastack/service-administration/model-deployment/deploying-models-and-bundles/create-a-custom-bundle)、[バンドルのデプロイ](/docs/ja/sambastack/service-administration/model-deployment/deploying-models-and-bundles/deploy-a-bundle) をご参照ください。本ページでは、旧形式からの変更点のみを解説します。
</Note>

## 新形式の変更点

作成するリソースの数が減り、SambaStack のインストールに既に付属しているリソースを組み合わせて利用する形になります。

* **モデルの直接デプロイ。**

  * 従来: 1 つのモデルを提供するには、`BundleTemplate`、`Bundle`、`BundleDeployment` が必要でした。
  * 現在: `ModelDeployment` の `spec.models` 配下にモデルとプロファイルをインラインで宣言します。3 つのリソースが 1 つで済みます。

  詳細は [単一モデルのデプロイ](/docs/ja/sambastack/service-administration/model-deployment/deploying-models-and-bundles/deploy-a-single-model) をご参照ください。

* **再利用可能なモデルプロファイル。** `ModelProfile` は、モデルアーキテクチャの実行方法 (機能フラグ、PEF、ティアごとのバッチング) を定義します。チェックポイントではなく、アーキテクチャに紐付けられます。

  * 従来: 同等の設定をすべての `BundleTemplate` にインラインで宣言し、利用者自身で保守する必要がありました。
  * 現在: 対応アーキテクチャのプロファイルは SambaStack に同梱されるため、名前で参照するだけで済みます。

  詳細は [ModelProfile の構造](/docs/ja/sambastack/service-administration/model-deployment/custom-resources/model-profile) をご参照ください。

* **バンドルの任意化。**

  * 従来: すべてのデプロイメントでバンドルが必須でした。
  * 現在: `ModelBundle` を作成するのは、その機能が必要な場合のみです。具体的には、複数のモデルを 1 つの単位として提供する場合、DDR とホストメモリのレポートを含む Legalizer 検証を行う場合、バッチング設定をオーバーライドする場合、名前付きの設定を共有する場合です。

  詳細は [ModelBundle の構造](/docs/ja/sambastack/service-administration/model-deployment/custom-resources/model-bundle) をご参照ください。

* **チェックポイントは `Model` リソースへ。**

  * 従来: バンドルの `spec.checkpoints` ブロックでチェックポイントのソースを宣言していました。
  * 現在: チェックポイントは `Model` リソースで管理します。`ModelBundle` または `ModelDeployment` でモデルとプロファイルを名前で組み合わせ、`<model-name>:<checkpoint-version>` または `modelSettings.checkpointOverrides` でチェックポイントを選択します。

  詳細は [Model の構造](/docs/ja/sambastack/service-administration/model-deployment/custom-resources/model) をご参照ください。

  <Warning>
    チェックポイントとプロファイルの互換性は `model_arch` によって決まりますが、オペレーターはこれを自動では検証しません。使用するプロファイルと互換性のあるアーキテクチャのチェックポイントを選択してください。
  </Warning>

* **カスタムチェックポイントに新しいバンドルやプロファイルは不要。** 独自のチェックポイントを参照し、`model_arch` が一致するプロファイルを再利用します。詳細は [カスタムチェックポイントのデプロイ](/docs/ja/sambastack/service-administration/model-deployment/deploying-models-and-bundles/deploy-custom-checkpoints) をご参照ください。

## 旧形式からの対応関係

### リソース

| 旧リソース | 新リソース | 備考 |
| - | - | - |
| `BundleTemplate` | `ModelProfile` | モデルのセットではなく、単一のモデルアーキテクチャを対象とします。対応アーキテクチャのプロファイルは SambaStack のインストールに付属します。 |
| `Bundle` | `ModelBundle` | 任意。複数モデルのデプロイメント、投機的デコーディング、Legalizer 検証、名前付き設定の共有が必要な場合にのみ作成します。 |
| `BundleDeployment` | `ModelDeployment` | `spec.bundle` で `ModelBundle` を参照するか、`spec.models` でモデルとプロファイルをインラインで宣言できます。 |
| `Bundle.spec.checkpoints` にインラインで宣言されたチェックポイント | `Model` | チェックポイントは独立したリソースになり、`ModelBundle` または `ModelDeployment` から名前で参照します。プロファイルとの互換性は `model_arch` によって決まりますが、オペレーターによる検証は行われません。 |
| `Pef` | `Pef` | 変更なし。PEF の参照動作は従来と同じで、参照を記述する場所のみバンドルテンプレートから `ModelProfile.spec.pefs` に変わります。 |

### フィールド

| 旧フィールド | 新フィールド |
| - | - |
| `BundleTemplate.spec.models.<model>.experts` および `configs[]` | `ModelProfile.spec.batchingConfigs` (構成名、次にティアをキーとします) |
| モデルのマップである `spec.models` | モデル構成のリストである `spec.modelConfigs[]` |
| 名前によるモデル参照 | `<model-name>[:<arch>][:<version>]` 形式によるモデル参照 |
| インラインの `pefs` マップと `usePefCRs` | `ModelProfile.spec.pefs`。`<pef-name>[:<version>]` の参照形式は変更ありません。 |
| `expertSet` | `batchingConfig` に含まれるティアキー |
| `default_expert_values.swappable` およびエキスパート構成ごとの `swappable` | `modelConfigs[].modelSettings.swappable` (モデルごとに 1 回定義します) |
| `private` | `modelSettings.routable` (意味が逆のフラグです) |
| `Bundle.spec.checkpoints.<alias>.source` | `Model.spec.checkpoints.<arch>.versions.<version>.source` |
| `Bundle.spec.checkpoints.<alias>.toolSupport` | `Model.spec.checkpoints.<arch>.versions.<version>.tool_support` |
| `Bundle.spec.models.<model>.template` | `modelConfigs[].profile` |
| 設定ごとの `spec_decoding.draft_model` | バンドルレベルで宣言する `spec.specDecodingPairs[]` |
| `resubmit`、`resubmit_to`、`enableResubmit` | 削除されました。 |
| バンドルで宣言していた `continuous_batching` | `Pef.spec.metadata.continuous_batching` (`ModelProfile.spec.features` に反映されます) |
| バンドルで宣言していた `constrained_decoding` | `Pef.spec.metadata.constrained_decoding` (`ModelProfile.spec.features` に反映されます) |
| `output_processor`、`enable_reasoning_effort`、`postprocess_parser` | `Model.spec.expertFields` |

<Warning>
  **削除・移設されたフィールド。**

  * `resubmit_to`、`resubmit_tool`、`enableResubmit` からなる `resubmit` 機構は削除され、代替はありません。
  * `continuous_batching` や `constrained_decoding` などの機能設定は、コンパイル済み PEF のプロパティです。バンドル内ではなく、`Pef.spec.metadata` 配下で宣言してください。
</Warning>

## バンドルの移行

<Steps>
  <Step title="BundleTemplate を置き換えるプロファイルの特定">
    既存の `BundleTemplate` に含まれる各モデルについて、`model_arch` の値がそのモデルのチェックポイントアーキテクチャと一致する `ModelProfile` を見つけます。ほとんどの場合、プロファイルは既にクラスター内に存在しており、テンプレートのエキスパート構成や config の構造を再作成する必要はありません。

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

    詳細は [利用可能なモデルとプロファイルの特定](/docs/ja/sambastack/service-administration/model-deployment/deploying-models-and-bundles/overview#利用可能なモデルとプロファイルの特定) をご参照ください。
  </Step>

  <Step title="エキスパート構成からバッチング設定への変換">
    ネストされた `experts` と `configs[]` の構造を、各シーケンス長ティアをそのバッチサイズに対応付けるフラットな `batchingConfig` に置き換えます。プロファイルの名前付き `batchingConfigs` のいずれかが既存バンドルの提供内容と既に一致している場合は、オーバーライド自体を省略するか、その構成を名前で指定してください。

    詳細は [バッチング設定](/docs/ja/sambastack/service-administration/model-deployment/custom-resources/model-profile#バッチング設定) をご参照ください。
  </Step>

  <Step title="チェックポイントの Model リソースへの移動">
    `spec.checkpoints` ブロックを削除します。各チェックポイントに対応する `Model` リソースが存在することを確認するか、カスタムチェックポイントの場合は新たに作成します。チェックポイントのパスはオペレーターが解決するため、バンドルで宣言する必要はなくなりました。

    詳細は [カスタムチェックポイントのデプロイ](/docs/ja/sambastack/service-administration/model-deployment/deploying-models-and-bundles/deploy-custom-checkpoints) をご参照ください。
  </Step>

  <Step title="ModelBundle の作成または直接デプロイ">
    既存のバンドルが投機的デコーディングなしの単一モデルのみを含む場合は、バンドルを省略してモデルを直接デプロイできます。それ以外の場合は、モデルごとに 1 つの `modelConfigs` エントリを持つ `ModelBundle` を作成し、`spec_decoding.draft_model` の設定を `spec.specDecodingPairs` に移します。

    詳細は [ModelBundle の作成](/docs/ja/sambastack/service-administration/model-deployment/deploying-models-and-bundles/create-a-custom-bundle) をご参照ください。
  </Step>

  <Step title="検証とデプロイ">
    バンドルを適用し、Legalizer が `ValidationSucceeded` を報告することを確認したら、`ModelDeployment` でデプロイします。旧 `BundleDeployment` のデプロイメントレベルの設定 (`groups`、`owner`、`secretNames`、`engineConfig` を含む) は、そのまま引き継がれます。

    詳細は [バンドルのデプロイ](/docs/ja/sambastack/service-administration/model-deployment/deploying-models-and-bundles/deploy-a-bundle) をご参照ください。
  </Step>
</Steps>

## 提供終了までのスケジュール

旧リソースモデル形式は提供終了予定となっていますが、**2026年9月30日**までは引き続き動作します。既存のバンドルは、期日までに新形式へ移行してください。

それまでの間、既存のバンドルは SambaStack v2.0.2 でも引き続き動作し、両方の形式の設定を同じクラスター内で併存させることができます。内部的には、オペレーターが `ModelBundle` をメモリ上の `BundleTemplate` と `Bundle` に変換し、従来の Legalizer とレンダリングのパイプラインを再利用します。そのため、新形式の設定とそれに相当する旧形式の設定は、同じデプロイメントを生成します。SambaNova が提供する新形式のバンドルは旧定義から生成されており、新形式を段階的に導入できます。

<Note>
  同じ名前のバンドルが両方の形式で定義されている場合、重複によりインストールが失敗します。1 つのバンドルは、どちらか一方の形式でのみ定義してください。
</Note>

## 参考情報

* [モデルとバンドルのデプロイ](/docs/ja/sambastack/service-administration/model-deployment/deploying-models-and-bundles/overview): 新しいリソースの相互関係。各リソースのフィールドリファレンスは **カスタムリソース**配下にあります。
* [バンドルのデプロイ](/docs/ja/sambastack/service-administration/model-deployment/deploying-models-and-bundles/deploy-a-bundle): 作成とデプロイの手順。
* [対応モデルとバンドル](/docs/ja/sambastack/service-administration/model-deployment/supported-models-and-bundles): 利用可能なモデルと推奨バンドル。