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

# バンドルのデプロイ

本ページでは、`ModelDeployment` からバンドルを参照してサービングする方法を説明します。この手順は、SambaNova が提供するバンドルと、自作したバンドルの両方に適用されます。

先に独自のバンドルを作成する場合は、[カスタムバンドルの作成](/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-single-model) をご覧ください。

## 前提条件

デプロイの前に、お使いの環境に応じたクイックスタートを完了してください。

<CardGroup cols={2}>
  <Card icon="list-check" href="/docs/ja/sambastack/getting-started/hosted" title="クイックスタート - ホステッド">
    ホステッド版 SambaStack のシステムセットアップ
  </Card>

  <Card icon="list-check" href="/docs/ja/sambastack/getting-started/on-prem" title="クイックスタート - オンプレミス">
    オンプレミス版 SambaStack のシステムセットアップ
  </Card>
</CardGroup>

あわせて、以下を確認してください。

* [ModelDeployment](/docs/ja/sambastack/service-administration/model-deployment/custom-resources/model-deployment) のフィールドリファレンスをご確認ください。
* デプロイするバンドルが検証に合格していることを確認してください。[Legalizer の結果](/docs/ja/sambastack/service-administration/model-deployment/custom-resources/model-bundle#legalizer-の結果) をご覧ください。
* SambaNova が提供するバンドルについては、[対応モデルとバンドル](/docs/ja/sambastack/service-administration/model-deployment/supported-models-and-bundles) をご確認ください。

## バンドルのデプロイ

<Steps>
  <Step title="利用可能なバンドルの確認">
    クラスターに存在するバンドルを一覧表示し、デプロイしたいバンドルの名前を確認します。

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

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

    出力:

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

    デプロイする前に、[Legalizer の結果](/docs/ja/sambastack/service-administration/model-deployment/custom-resources/model-bundle#legalizer-の結果) に記載されたとおり、バンドルが検証に合格していることを確認してください。
  </Step>

  <Step title="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
    ```
  </Step>

  <Step title="ModelDeployment の適用">
    <Tabs>
      <Tab title="Hosted">
        ```bash theme={}
        kubectl apply -f <modeldeployment-file>.yaml
        ```
      </Tab>

      <Tab title="On Premise">
        ```bash theme={}
        kubectl -n <namespace> apply -f <modeldeployment-file>.yaml
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="デプロイ状態の監視">
    <Tabs>
      <Tab title="Hosted">
        ```bash theme={}
        kubectl get modeldeployments
        kubectl describe modeldeployment <deployment-name>
        ```
      </Tab>

      <Tab title="On Premise">
        ```bash theme={}
        kubectl -n <namespace> get modeldeployments.sambanova.ai
        kubectl -n <namespace> describe modeldeployment.sambanova.ai <deployment-name>
        ```
      </Tab>
    </Tabs>
  </Step>
</Steps>

## デプロイの確認

Pod が ready を報告するのはサービングコンテナが起動したことを意味するだけで、モデルがリクエストに応答することの確認にはなりません。サービング名を確認したうえで、推論リクエストを 1 件送信してください。

### サービング名の解決

API に送信する名前は、Kubernetes のリソース名ではありません。関係する名前は 3 つあります。

| 名前 | 定義場所 | 用途 |
| - | - | - |
| Model の `metadata.name` | `Model` リソース | `kubectl` コマンド、およびバンドルとデプロイメント内の `modelConfigs[].model` 参照 |
| Model の `spec.name` | `Model` リソース | 推論リクエストの `model` フィールド |
| Model の `spec.aliases` | `Model` リソース | 同じモデルにルーティングされる追加の名前 |

デプロイした Model からサービング名を読み取ります。

<Tabs>
  <Tab title="Hosted">
    ```bash theme={}
    kubectl get model <model-resource-name> -o jsonpath='{.spec.name}{"\n"}'
    ```
  </Tab>

  <Tab title="On Premise">
    ```bash theme={}
    kubectl -n <namespace> get model.sambanova.ai <model-resource-name> -o jsonpath='{.spec.name}{"\n"}'
    ```
  </Tab>
</Tabs>

次に、ゲートウェイがそのモデルをサービングしていることを確認します。レスポンス内の各 `id` が、サービング可能な名前です。

```bash theme={}
curl https://<your-api-domain>/v1/models \
  -H "Authorization: Bearer $SAMBANOVA_API_KEY"
```

<Note>
  投機的デコーディングのドラフトモデルなど、`modelSettings.routable: false` が設定されたモデルは、意図的にこの一覧から除外されており、直接アクセスすることはできません。
</Note>

### リクエストの送信

`model` フィールドにサービング名を使用します。

```bash theme={}
curl https://<your-api-domain>/v1/chat/completions \
  -H "Authorization: Bearer $SAMBANOVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-oss-120b",
    "messages": [
      {"role": "system", "content": "You are a concise assistant."},
      {"role": "user", "content": "Say hi in one sentence."}
    ],
    "max_tokens": 128,
    "stream": false
  }'
```

成功した場合のレスポンスは、`model` にサービング名を、`choices[0].message` に生成内容を返します。

```json theme={}
{
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "message": {
        "content": "Hi there, it's a sunny day today!",
        "role": "assistant"
      }
    }
  ],
  "created": 1770927918,
  "id": "c754b468-05e1-4fe4-8a28-f51ecc74f4f2",
  "model": "gpt-oss-120b",
  "object": "chat.completion",
  "system_fingerprint": "fastcoe",
  "usage": {
    "completion_tokens": 121,
    "prompt_tokens": 91,
    "total_tokens": 212,
    "stop_reason": "stop",
    "time_to_first_token": 0.05286884307861328,
    "total_latency": 0.29257988929748535
  }
}
```

`usage` オブジェクトには、スループットとレイテンシに関する追加のフィールドが含まれます。レスポンスボディの全体像と、各環境で使用する API ドメインについては、[クイックスタート - ホステッド](/docs/ja/sambastack/getting-started/hosted) または [クイックスタート - オンプレミス](/docs/ja/sambastack/getting-started/on-prem) をご覧ください。

<Warning>
  Pod が稼働しているのに `model not found` エラーが発生する場合、通常はリクエストで `spec.name` ではなく `metadata.name` を使用したことが原因です。ロードされて一覧にも表示されるモデルで推論エラーが発生する場合、通常はチェックポイントとプロファイルの `model_arch` が一致していないことが原因です。[デプロイの失敗](/docs/ja/sambastack/service-administration/model-deployment/deploying-models-and-bundles/troubleshooting#デプロイの失敗) をご覧ください。
</Warning>

## バンドルの切り替え

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

<Steps>
  <Step title="既存の ModelDeployment の削除">
    <Tabs>
      <Tab title="Hosted">
        ```bash theme={}
        kubectl delete modeldeployment <deployment-name>
        ```
      </Tab>

      <Tab title="On Premise">
        ```bash theme={}
        kubectl -n <namespace> delete modeldeployment <deployment-name>
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="新しいバンドル用の 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
    ```
  </Step>
</Steps>

新しいバンドルをリクエストする場合は、SambaNova のサポート窓口までお問い合わせください。

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

複数のバンドルを同時にサービングするには、バンドルごとに個別の ModelDeployment を適用します。

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

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

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

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

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

<Tabs>
  <Tab title="構成の更新">
    <Steps>
      <Step title="YAML ファイルの変更">
        ModelBundle、ModelProfile、または ModelDeployment の YAML ファイルを編集して変更を加えます。
      </Step>

      <Step title="構成の再適用">
        <Tabs>
          <Tab title="Hosted">
            ```bash theme={}
            kubectl apply -f <modified-file>.yaml
            ```
          </Tab>

          <Tab title="On Premise">
            ```bash theme={}
            kubectl -n <namespace> apply -f <modified-file>.yaml
            ```
          </Tab>
        </Tabs>

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

  <Tab title="構成の削除">
    <Steps>
      <Step title="ModelDeployment の削除">
        <Tabs>
          <Tab title="Hosted">
            ```bash theme={}
            kubectl delete modeldeployment <deployment-name>
            ```
          </Tab>

          <Tab title="On Premise">
            ```bash theme={}
            kubectl -n <namespace> delete modeldeployment <deployment-name>
            ```
          </Tab>
        </Tabs>
      </Step>

      <Step title="ModelBundle の削除 (バンドルを使用していた場合)">
        <Tabs>
          <Tab title="Hosted">
            ```bash theme={}
            kubectl delete modelbundle <bundle-name>
            ```
          </Tab>

          <Tab title="On Premise">
            ```bash theme={}
            kubectl -n <namespace> delete modelbundle <bundle-name>
            ```
          </Tab>
        </Tabs>
      </Step>

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

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

          <Tab title="On Premise">
            ```bash theme={}
            kubectl -n <namespace> delete modelprofile <profile-name>
            ```
          </Tab>
        </Tabs>
      </Step>
    </Steps>
  </Tab>
</Tabs>

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

オペレーターがサービング Pod の作成開始後に報告する失敗と、その前に Legalizer が報告する失敗については、[デプロイメントのトラブルシューティング](/docs/ja/sambastack/service-administration/model-deployment/deploying-models-and-bundles/troubleshooting) をご覧ください。

## 関連ドキュメント

<CardGroup cols={2}>
  <Card icon="cube" href="/docs/ja/sambastack/service-administration/model-deployment/supported-models-and-bundles" title="対応モデルとバンドル">
    デプロイ可能なモデルとバンドルのカタログ
  </Card>

  <Card icon="server" href="/docs/ja/sambastack/service-administration/model-deployment/custom-resources/model-deployment" title="ModelDeployment">
    デプロイメントリソースの全フィールドのリファレンス
  </Card>

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

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