SambaStack での単一モデルのデプロイ

1 つのモデルをサービングするには、プロファイルと組み合わせて ModelDeployment で直接デプロイします。バンドルは作成されません。複数のモデルを 1 つの単位としてサービングする場合、投機的デコーディングを設定する場合、または名前付きの構成を検証して共有する場合は、代わりにバンドルを作成します。カスタムバンドルの作成をご覧ください。

前提条件

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

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

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

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

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

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

モデル、プロファイル、デプロイメントの関係については、デプロイの概要をご確認ください。
組み合わせるモデルとプロファイルを特定し、互換性があることを確認してください。利用可能なモデルとプロファイルの特定をご覧ください。
利用可能なモデルチェックポイントについては、対応モデルとバンドルをご確認ください。

モデルのデプロイ

YAML ファイルの作成

spec.models の下にモデルとプロファイルをインラインで宣言する YAML ファイルを作成します。

apiVersion: sambanova.ai/v1alpha1
kind: ModelDeployment
metadata:
  name: md-gpt120
spec:
  models:
    modelConfigs:
    - model: gpt-oss-120b:1
      profile: gpt-oss-fp8-dyt
  groups:
  - minReplicas: 1
    name: default
    qosList:
    - free
  owner: no-reply@sambanova.ai
  secretNames:
  - sambanova-artifact-reader
  engineConfig:
    startupTimeout: 7200

チェックポイントのパスは不要です。チェックポイントは、参照した Model から解決されます。startupTimeout の単位は秒です。ここでの 7200 は、起動プローブが失敗するまでにエンジンがモデルをダウンロードしてロードするための時間として 2 時間を与えるもので、デフォルトの 45 分を大きく上回ります。起動タイムアウトをご覧ください。

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 ステータスを報告すれば、デプロイは完了です。

デプロイの確認

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 が一致していないことが原因です。デプロイの失敗をご覧ください。

デプロイメントの更新・削除

デプロイメントの構成を変更するには、その YAML ファイルを編集して再適用します。Legalizer が自動的に変更を再検証します。

Hosted
On Premise

kubectl apply -f <modified-file>.yaml

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

デプロイメントを削除するには、次を実行します。

Hosted
On Premise

kubectl delete modeldeployment <deployment-name>

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

トラブルシューティング

インラインの spec.models 仕様から作成されたデプロイメントは、その場で Legalizer による検証を受けるため、2 種類の失敗の両方が発生し得ます。Legalizer の検証失敗とデプロイの失敗については、デプロイメントのトラブルシューティングをご覧ください。

ModelDeployment

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

バンドルのデプロイ

複数のモデルを 1 つの単位としてまとめてサービング

Get started

Models

Features

Build

Resources

単一モデルのデプロイ

前提条件

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

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

モデルのデプロイ

デプロイの確認

サービング名の解決

リクエストの送信

デプロイメントの更新・削除

トラブルシューティング

関連ドキュメント

ModelDeployment

バンドルのデプロイ

​前提条件

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

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

​モデルのデプロイ

​デプロイの確認

​サービング名の解決

​リクエストの送信

​デプロイメントの更新・削除

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

​関連ドキュメント

ModelDeployment

バンドルのデプロイ

前提条件

モデルのデプロイ

デプロイの確認

サービング名の解決

リクエストの送信

デプロイメントの更新・削除

トラブルシューティング

関連ドキュメント