SambaStack でのモデルバンドルのデプロイ

本ページでは、ModelDeployment からバンドルを参照してサービングする方法を説明します。この手順は、SambaNova が提供するバンドルと、自作したバンドルの両方に適用されます。先に独自のバンドルを作成する場合は、カスタムバンドルの作成をご覧ください。バンドルを使わずに単一のモデルをサービングする場合は、単一モデルのデプロイをご覧ください。

前提条件

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

クイックスタート - ホステッド

ホステッド版 SambaStack のシステムセットアップ

クイックスタート - オンプレミス

オンプレミス版 SambaStack のシステムセットアップ

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

ModelDeployment のフィールドリファレンスをご確認ください。
デプロイするバンドルが検証に合格していることを確認してください。Legalizer の結果をご覧ください。
SambaNova が提供するバンドルについては、対応モデルとバンドルをご確認ください。

バンドルのデプロイ

利用可能なバンドルの確認

クラスターに存在するバンドルを一覧表示し、デプロイしたいバンドルの名前を確認します。

Hosted
On Premise

kubectl get modelbundles

kubectl -n <namespace> get modelbundles.sambanova.ai

出力:

mb-gpt120                      17h
mb-gpt120-llama70sd8-llama8    17h
ds-v32-gemma-4-31b             3h

デプロイする前に、Legalizer の結果に記載されたとおり、バンドルが検証に合格していることを確認してください。

ModelDeployment の作成

spec.bundle にバンドル名を指定します。

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

ModelDeployment の適用

Hosted
On Premise

kubectl apply -f <modeldeployment-file>.yaml

kubectl -n <namespace> apply -f <modeldeployment-file>.yaml

デプロイ状態の監視

Hosted
On Premise

kubectl get modeldeployments
kubectl describe modeldeployment <deployment-name>

kubectl -n <namespace> get modeldeployments.sambanova.ai
kubectl -n <namespace> describe modeldeployment.sambanova.ai <deployment-name>

デプロイの確認

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

サービング名の解決

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

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

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

Hosted
On Premise

kubectl get model <model-resource-name> -o jsonpath='{.spec.name}{"\n"}'

kubectl -n <namespace> get model.sambanova.ai <model-resource-name> -o jsonpath='{.spec.name}{"\n"}'

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

curl https://<your-api-domain>/v1/models \
  -H "Authorization: Bearer $SAMBANOVA_API_KEY"

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

リクエストの送信

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

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 に生成内容を返します。

{
  "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 ドメインについては、クイックスタート - ホステッドまたはクイックスタート - オンプレミスをご覧ください。

Pod が稼働しているのに model not found エラーが発生する場合、通常はリクエストで spec.name ではなく metadata.name を使用したことが原因です。ロードされて一覧にも表示されるモデルで推論エラーが発生する場合、通常はチェックポイントとプロファイルの model_arch が一致していないことが原因です。デプロイの失敗をご覧ください。

バンドルの切り替え

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

既存の ModelDeployment の削除

Hosted
On Premise

kubectl delete modeldeployment <deployment-name>

kubectl -n <namespace> delete modeldeployment <deployment-name>

新しいバンドル用の ModelDeployment の適用

サービングしたいバンドルを spec.bundle に指定した新しい ModelDeployment を作成し、バンドルのデプロイの説明に従って適用します。

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

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

複数バンドルのデプロイ

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

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

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

Hosted
On Premise

kubectl get pods

kubectl -n <namespace> get pods

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

構成の更新
構成の削除

YAML ファイルの変更

ModelBundle、ModelProfile、または ModelDeployment の YAML ファイルを編集して変更を加えます。

構成の再適用

Hosted
On Premise

kubectl apply -f <modified-file>.yaml

kubectl -n <namespace> apply -f <modified-file>.yaml

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

ModelDeployment の削除

Hosted
On Premise

kubectl delete modeldeployment <deployment-name>

kubectl -n <namespace> delete modeldeployment <deployment-name>

ModelBundle の削除 (バンドルを使用していた場合)

Hosted
On Premise

kubectl delete modelbundle <bundle-name>

kubectl -n <namespace> delete modelbundle <bundle-name>

ModelProfile の削除 (任意)

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

Hosted
On Premise

kubectl delete modelprofile <profile-name>

kubectl -n <namespace> delete modelprofile <profile-name>

トラブルシューティング

オペレーターがサービング Pod の作成開始後に報告する失敗と、その前に Legalizer が報告する失敗については、デプロイメントのトラブルシューティングをご覧ください。

対応モデルとバンドル

デプロイ可能なモデルとバンドルのカタログ

ModelDeployment

デプロイメントリソースの全フィールドのリファレンス

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

独自のカスタムチェックポイントやファインチューニング済みチェックポイントのデプロイ

バンドル設定の移行

非推奨のカスタムリソースで構築したバンドルの移行

はじめに

サービス管理

ハードウェア管理

リファレンスアーキテクチャ

リソース

バンドルのデプロイ

前提条件

クイックスタート - ホステッド

クイックスタート - オンプレミス

バンドルのデプロイ

デプロイの確認

サービング名の解決

リクエストの送信

バンドルの切り替え

複数バンドルのデプロイ

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

トラブルシューティング

関連ドキュメント

対応モデルとバンドル

ModelDeployment

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

バンドル設定の移行

​前提条件

クイックスタート - ホステッド

クイックスタート - オンプレミス

​バンドルのデプロイ

​デプロイの確認

​サービング名の解決

​リクエストの送信

​バンドルの切り替え

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

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

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

​関連ドキュメント

対応モデルとバンドル

ModelDeployment

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

バンドル設定の移行

前提条件

バンドルのデプロイ

デプロイの確認

サービング名の解決

リクエストの送信

バンドルの切り替え

複数バンドルのデプロイ

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

トラブルシューティング

関連ドキュメント