> ## 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 は、一連の Kubernetes カスタムリソースを通じてモデルサービングを管理します。本ページでは、これらのリソースの相互関係、クラスターに既に存在するリソースの確認方法、目的のデプロイに応じてどのワークフローに従えばよいかを解説します。このセクションの各ページでは、それぞれのワークフローを順を追って説明します。個々のリソースのフィールドリファレンスは、**カスタムリソース**配下の専用ページにあります。

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.2.3/sambastack/service-administration/model-deployment/supported-models-and-bundles) をご覧ください。

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

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

## 用語

| 用語 | 定義 |
| - | - |
| **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
    accTitle: How the SambaStack model deployment custom resources relate to one another
    accDescr: A PEF is referenced by a ModelProfile. A ModelProfile and a Model form an implicit pair, which is not a custom resource. That pair is referenced by a ModelBundle, and the bundle is served by a ModelDeployment. The pair can also be deployed directly by a ModelDeployment without a bundle. PEF, ModelProfile, and Model are provided with the SambaStack installation. ModelBundle and ModelDeployment are the resources you author.

    PEF["PEF<br/><small>provided&nbsp;·&nbsp;references to versioned executables</small>"]
    MP["ModelProfile<br/><small>provided&nbsp;·&nbsp;set&nbsp;of&nbsp;feature‑compatible&nbsp;PEFs&nbsp;for&nbsp;a&nbsp;model&nbsp;arch<br/>+&nbsp;named&nbsp;batching&nbsp;configurations</small>"]
    M["Model<br/><small>provided&nbsp;·&nbsp;checkpoints per architecture</small>"]
    MB["ModelBundle<br/><small>you&nbsp;author&nbsp;·&nbsp;reusable,&nbsp;shareable&nbsp;set&nbsp;of<br/>models&nbsp;+&nbsp;profiles</small>"]
    MD["ModelDeployment<br/><small>you author&nbsp;·&nbsp;routable inference endpoint, replicas &amp; QoS, backed by serving pods</small>"]
    JP("<i>ModelProfile & Model Pair</i><br/><small>not a CR&nbsp;·&nbsp;implicit pairing<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,stroke-dasharray:4 3;
    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;
```

各ノードには役割を示すタグが付いています。*provided* とタグ付けされたノードは破線の枠線で示され、SambaStack のインストールと共に提供されるため、名前で参照します。*you author* とタグ付けされたノードは実線の枠線で示され、ユーザーが作成するリソースです。*not a CR* とタグ付けされた角丸のノードはカスタムリソースではなく、`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` によって定義されますが、オペレーターはこれを検証しません。参照するプロファイルと互換性のあるアーキテクチャを持つチェックポイントを選択してください。
</Note>

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

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

<Steps>
  <Step title="利用可能なモデルの一覧表示">
    モデルを一覧表示し、各モデルの `spec.checkpoints` 配下のアーキテクチャキーを確認します。

    <Tabs>
      <Tab title="Hosted">
        ```bash theme={}
        kubectl get models
        ```

        例:

        ```bash theme={}
        kubectl describe model gpt-oss-120b
        ```
      </Tab>

      <Tab title="On Premise">
        ```bash theme={}
        kubectl -n <namespace> get models.sambanova.ai
        ```

        例:

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

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

  <Step title="利用可能なプロファイルの一覧表示">
    プロファイルを一覧表示し、それぞれの `model_arch` の値を確認します。

    <Tabs>
      <Tab title="Hosted">
        ```bash theme={}
        kubectl get modelprofiles
        ```
      </Tab>

      <Tab title="On Premise">
        ```bash theme={}
        kubectl -n <namespace> get modelprofiles.sambanova.ai
        ```
      </Tab>
    </Tabs>

    出力:

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

  <Step title="プロファイルとモデルのマッチング">
    プロファイルの内容を表示して、そのアーキテクチャ、機能、バッチングサポートを確認します。

    <Tabs>
      <Tab title="Hosted">
        ```bash theme={}
        kubectl describe modelprofile <profile-name>
        ```
      </Tab>

      <Tab title="On Premise">
        ```bash theme={}
        kubectl -n <namespace> describe modelprofile.sambanova.ai <profile-name>
        ```
      </Tab>
    </Tabs>

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

    * `model_arch` - プロファイルが対象とするアーキテクチャ
    * `features` - プロファイルの PEF がサポートするオプション機能
    * `batchingConfigs` - 名前付きのバッチング設定。それぞれがシーケンス長ティアをそのバッチサイズにマッピングします
    * `pefs` - プロファイルが参照する PEF のバージョン
  </Step>
</Steps>

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

## ワークフローの選択

<CardGroup cols={2}>
  <Card icon="rocket" href="/docs/ja/v2.2.3/sambastack/service-administration/model-deployment/deploying-models-and-bundles/deploy-a-single-model" title="単一モデルのデプロイ">
    バンドルを使わずに、モデルをプロファイルと組み合わせて直接デプロイ
  </Card>

  <Card icon="layer-group" href="/docs/ja/v2.2.3/sambastack/service-administration/model-deployment/deploying-models-and-bundles/deploy-a-bundle" title="バンドルのデプロイ">
    SambaNova が提供するバンドル、または自作したバンドルのサービング
  </Card>

  <Card icon="wrench" href="/docs/ja/v2.2.3/sambastack/service-administration/model-deployment/deploying-models-and-bundles/create-a-custom-bundle" title="カスタムバンドルの作成">
    複数のモデルとプロファイルを、名前付きの検証済みの 1 つの単位に統合
  </Card>

  <Card icon="compress" href="/docs/ja/v2.2.3/sambastack/service-administration/model-deployment/deploying-models-and-bundles/deploy-custom-checkpoints" title="カスタムチェックポイントのデプロイ">
    独自のカスタムチェックポイントやファインチューニング済みチェックポイントの変換・アップロード・サービング
  </Card>

  <Card icon="gauge-high" href="/docs/ja/v2.2.3/sambastack/service-administration/model-deployment/deploying-models-and-bundles/deployment-configurations" title="高スループット vs. 高インタラクティビティ">
    2 種類の専用デプロイ構成の使い分け
  </Card>

  <Card icon="arrow-right-arrow-left" href="/docs/ja/v2.2.3/sambastack/service-administration/model-deployment/deploying-models-and-bundles/sambastack-v2-bundle-migration" title="バンドル設定の移行">
    非推奨のカスタムリソースで構築したバンドルの移行
  </Card>
</CardGroup>