SambaStack 投機的デコーディングのデプロイ

SambaStack では、ユーザーが用意したチェックポイントと SambaNova 提供のチェックポイントのいずれについても、カスタムドラフトモデルを使用して、特定のデプロイシナリオにおける推論パフォーマンスを向上させることができます。これらのドラフトモデルによって投機的デコーディング (speculative decoding) が可能になり、適切に構成することでレイテンシの削減とスループットの向上が期待できます。本ページでは、投機的デコーディングを使用してモデルをデプロイする方法を説明します。投機的デコーディングが適しているケース、ドラフトモデルとターゲットモデルの互換性を検証する方法、カスタムドラフトチェックポイントの構成方法を扱います。

モデル、モデルプロファイル、モデルバンドル、モデルのデプロイに馴染みがない場合は、モデルとバンドルのデプロイページをご覧ください。

投機的デコーディングとは

投機的デコーディングは、高速かつ軽量な 「ドラフト」モデル (draft model) と、より大規模で高品質な 「ターゲット」モデル (target model) を組み合わせる推論高速化手法です。

ドラフトモデルが複数の次トークンの候補を提案します
ターゲットモデルがそれらを並列に高速で検証し、採用または棄却します
このアプローチにより、推論のデコード時間が大幅に短縮されます。特にドラフトモデルがターゲットモデルと密接に「整合」している場合に効果的です

主なメリット: 投機的デコーディングは、ターゲットモデルの出力分布 (ひいては精度) に影響を与えることなく推論を高速化します。

投機的デコーディングを使用すべきでないケース

投機的デコーディングは、ターゲットモデルの次トークンのかなりの部分をドラフトモデルが予測できる場合に最も効果を発揮します。ただし、状況によってはほとんど効果が得られず、かえって全体のパフォーマンスを低下させることもあります。

シナリオ	パフォーマンスが低下する理由
入力が長く出力が短い場合	ドラフトモデルとターゲットモデルの両方が、生成を開始する前に入力全体を処理する必要があります。ドラフトモデルの実行によるオーバーヘッドが、高速化の効果を上回る可能性があります。
モデルサイズの差が非常に大きい場合	ドラフトモデルがターゲットモデルに比べて極端に小さい (または整合性が低い) 場合、アクセプト率が低下する傾向があります。アクセプト率が低いと、棄却されるトークンが増え、ターゲットモデルでの修正のためのフォワードパスが増加し、結果としてパフォーマンスが低下します。

投機的デコーディングでのカスタムドラフトチェックポイントの使用

SambaStack の一部のモデルプロファイルは、投機的デコーディングに対応しています。ターゲットモデルが投機的デコーディングを使用する場合、ドラフトモデルとターゲットモデルの両方を一緒にデプロイする必要があり、どちらのモデルのチェックポイントもカスタマイズできます。このセクションでは、カスタムドラフトチェックポイントをデプロイする一連のワークフローを説明します。内容は以下のとおりです。

投機的デコーディングを使用するプロファイルとバンドルを特定する方法
ドラフトモデルとターゲットモデルの互換性を検証する方法
ModelBundle を更新する方法

ワークフローの概要

カスタムドラフトチェックポイントを投機的デコーディング用にデプロイする大まかな手順は以下のとおりです。

ステップ	操作
1	モデルプロファイルとバンドルの `specDecodingPairs` を確認し、デプロイメントが投機的デコーディングを使用していることを確認する
2	カスタムドラフトチェックポイントを SambaNova 互換フォーマットに変換する
3	ドラフトチェックポイントとターゲットチェックポイントの互換性を検証する (推奨)
4	変換したドラフトチェックポイントを GCS バケットにアップロードするか、クラスターからアクセスして読み取れる NFS 上に配置する
5	既存のドラフトモデルのチェックポイントをオーバーライドするか、新しい `Model` を登録して、ドラフトチェックポイントを参照する
6	カスタムドラフトチェックポイントを参照するように `ModelBundle` を更新する

カスタムドラフトチェックポイントのデプロイ手順

デプロイメントが投機的デコーディングを使用していることを確認

投機的デコーディングには、ModelProfile が投機的デコーディングに対応したターゲットモデルと、それと一緒にデプロイされるドラフトモデルが必要です。プロファイルが投機的デコーディングに対応しているかどうかは、spec.features に speculative_decoding が含まれているかで判断できます。

kubectl -n <namespace> get modelprofiles -o json

ペアリング自体は、ModelBundle の spec.specDecodingPairs で宣言します。以下の例では、meta-llama-3-3-70b-instruct がターゲット、meta-llama-3-2-1b-instruct がドラフトです。3 つ目のモデル gemma-4-31b-it は、これらと同じバンドルに含まれていますが、投機的デコーディングは使用しません。

apiVersion: sambanova.ai/v1alpha1
kind: ModelBundle
metadata:
  name: gemma4-31-llama70-sd-1b
spec:
  modelConfigs:
    - model: gemma-4-31b-it:1
      profile: gemma4-31b-dyt
    - model: meta-llama-3-3-70b-instruct:1
      profile: llama-3p1-70b-sd
    - model: meta-llama-3-2-1b-instruct:1
      profile: llama-3p1-1b
      modelSettings:
        routable: false
  specDecodingPairs:
    - draft: meta-llama-3-2-1b-instruct
      target: meta-llama-3-3-70b-instruct

上記の例では:

meta-llama-3-3-70b-instruct がターゲットモデルです。投機的デコーディング用にコンパイルされた PEF を持つ llama-3p1-70b-sd プロファイルを使用しています。
meta-llama-3-2-1b-instruct がドラフトモデルです。routable: false が指定されているため、クライアントから直接アクセスすることはできません。
spec.specDecodingPairs が両者のペアリングを宣言しています。
gemma-4-31b-it はこのペアリングとは無関係で、通常どおりサービングされます。

以下の点に注意してください。

ターゲットモデルとドラフトモデルの両方が、spec.modelConfigs のエントリとして記載されている必要があります。
リクエストはターゲットモデルに送信されるため、ドラフトモデルはルーティング不可 (non-routable) にすることを推奨します。
specDecodingPairs のエントリでは、アーキテクチャやバージョンのサフィックスを付けずに、Model リソース名のみでモデルを参照します。

投機的デコーディングのフィールド

フィールド	必須	説明
`target`	はい	ターゲットモデルのリソース名。アーキテクチャやバージョンのサフィックスは付けずに指定します。
`draft`	はい	ドラフトモデルのリソース名。アーキテクチャやバージョンのサフィックスは付けずに指定します。
`experts`	いいえ	ペアリングを特定のエキスパートに限定します。このフィールドを省略すると、ペアリングはターゲットモデルのすべてのエキスパートに適用されます。

カスタムドラフトチェックポイントの変換

ドラフトモデルのチェックポイントを、独自にファインチューニングしたバージョンやカスタムバージョンに置き換える場合は、チェックポイント変換ツール (Checkpoint Conversion Tool) を使用して SambaNova 互換フォーマットに変換します。

ツールをまだセットアップしていない場合は、チェックポイント変換ツールのドキュメントページにある ダウンロードとセットアップ の手順に従ってください。
次に、チェックポイントの変換と検証 の手順に従ってドラフトチェックポイントを変換します。

SambaStack 提供のチェックポイントは、すでに正しいフォーマットになっています。SambaStack 提供のドラフトチェックポイントを使用する場合は、このステップをスキップしてください。

ドラフトとターゲットのチェックポイント互換性の検証

投機的デコーディングでカスタムチェックポイントをデプロイする際は、ドラフトチェックポイントがターゲットチェックポイントと互換であることを検証してください。これにより、推論時の予期しないエラーを防止できます。チェックポイント変換ツールには、ドラフトとターゲットの互換性をチェックする組み込みユーティリティが用意されています。この検証ユーティリティを使用して、以下を確認します。

ドラフトモデルとターゲットモデルが構造的に整合していること
両者のトークナイザーに互換性があること
このペアで投機的デコーディングを安全に実行できること

コマンドテンプレート

docker run -v $HOST_WORKING_DIR:$DOCKER_WORKING_DIR --rm -it \
    --platform linux/amd64 \
    $IMAGE_NAME \
    validate-sd \
    --target_model $TARGET_MODEL \
    --target_checkpoint_path "$DOCKER_WORKING_DIR/$TARGET_CHECKPOINT_DIR" \
    --draft_model $DRAFT_MODEL \
    --draft_checkpoint_path "$DOCKER_WORKING_DIR/$DRAFT_CHECKPOINT_DIR" \
    --server $SERVER \
    --cache_location $CACHE_LOCATION

パラメータ

以下は、validate-sd コマンドの主な入力フラグです。

フラグ / 変数	型	説明
`--target_model` / `TARGET_MODEL`	`str`	検証対象となるターゲットモデルのファミリー (例: `"llama3-70b"`)。ターゲットのデプロイメントで使用するモデルファミリーと一致させる必要があります。
`--target_checkpoint_path`	`str`	変換済みのターゲットチェックポイントを含むディレクトリへのコンテナ内パス。通常は、`HOST_WORKING_DIR` からマウントされた `$DOCKER_WORKING_DIR/<subdir>` です。
`--draft_model` / `DRAFT_MODEL`	`str`	検証するドラフトモデルのファミリー (例: `"llama3-8b"`)。投機的デコーディング構成でドラフトモデルとして使用するモデルファミリーと一致させる必要があります。
`--draft_checkpoint_path`	`str`	変換済みのドラフトチェックポイントを含むディレクトリへのコンテナ内パス。通常は、`HOST_WORKING_DIR` からマウントされた `$DOCKER_WORKING_DIR/<subdir>` です。
`--server` / `SERVER`	`str`	サービングメタデータの取得元。`embedded`、ローカルパス、または `https://api.sambanova.ai/` のようなリモート URL を指定できます。通常は、お使いの SambaStack インスタンスのベースエンドポイント URL です。
`--cache_location` / `CACHE_LOCATION`	`str`	サービングメタデータや設定が保存される場所 (コンテナ内)。通常は `$DOCKER_WORKING_DIR` のサブディレクトリで、ホスト側では `$HOST_WORKING_DIR/$CACHE_LOCATION` から参照できます。

ホスト側の変数

上記のフラグに加えて、通常は Docker コマンド用に以下の環境変数を設定します。

変数	説明
`HOST_WORKING_DIR`	変換済みのターゲットおよびドラフトチェックポイントを含むホスト上のディレクトリ。書き込み可能である必要があります。
`DOCKER_WORKING_DIR`	`HOST_WORKING_DIR` がマウントされるコンテナ内のディレクトリ (`-v` の右側と一致)。
`IMAGE_NAME`	チェックポイント変換ツールのコンテナの完全なイメージ名。
`TARGET_CHECKPOINT_DIR`	ターゲットチェックポイントのディレクトリを含む `HOST_WORKING_DIR` 配下のサブディレクトリ (`DOCKER_WORKING_DIR` 配下にミラーされます)。
`DRAFT_CHECKPOINT_DIR`	ドラフトチェックポイントのディレクトリを含む `HOST_WORKING_DIR` 配下のサブディレクトリ (`DOCKER_WORKING_DIR` 配下にミラーされます)。

重要: 検証の前に、ドラフトおよびターゲットの両方のチェックポイントを変換しておく必要があります。SambaStack 提供のターゲットチェックポイントを使用する場合、変換は不要です。SambaStack 提供のチェックポイントは、すべてすでに正しいフォーマットになっています。

このステップは任意ですが、実行時エラーを避けるために強く推奨します。

カスタムドラフトチェックポイントのアップロード

クラスターが NFS マウントストレージを使用している場合は、カスタムチェックポイントを、クラスターから読み取れる NFS 上に配置してください。クラスターで Google Cloud Storage を使用している場合は、変換済みのドラフトチェックポイントのディレクトリを GCS バケットにアップロードし、SambaStack のサービスアカウントから読み取れることを確認してください。

gcloud storage cp -r <LOCAL_DRAFT_CHECKPOINT_DIR> gs://<BUCKET_NAME>/<PATH>/

アップロード手順と GCS の権限設定の詳細については、カスタムチェックポイントのデプロイ → 変換済みチェックポイントのアップロード をご覧ください。

ドラフトチェックポイントの参照

カスタムチェックポイントのデプロイで説明されている 2 つの方法のいずれかを使用して、変換したドラフトチェックポイントをサービング可能にします。

既存のドラフトモデルのチェックポイントをオーバーライドする。 spec.modelConfigs 内のドラフトモデルのエントリに checkpointOverrides を設定します。ドラフトモデルの名前は変わらないため、specDecodingPairs の変更は不要です。こちらの方が簡単な方法で、次のステップで示します。
新しい Model リソースを登録する。 ドラフトチェックポイントを独自の名前でサービングする場合に使用します。この場合、specDecodingPairs の draft の値を、新しいリソース名を参照するように更新する必要があります。

ドラフトモデルがクライアントから直接アクセスされることはないため、新しいサービング名が必要になるケースはまれです。ドラフトを独自の名前でアクセス可能にしたい場合を除き、チェックポイントのオーバーライドを推奨します。

ModelBundle の更新

ドラフトチェックポイントのアップロードが完了したら、ドラフトモデルのエントリがそのチェックポイントを参照するようにします。

変更前: SambaNova 提供のドラフトを使用

spec:
  modelConfigs:
    - model: meta-llama-3-3-70b-instruct:1
      profile: llama-3p1-70b-sd
    - model: meta-llama-3-2-1b-instruct:1
      profile: llama-3p1-1b
      modelSettings:
        routable: false
  specDecodingPairs:
    - draft: meta-llama-3-2-1b-instruct
      target: meta-llama-3-3-70b-instruct

変更後: カスタムドラフトチェックポイントを使用

ドラフトモデルの modelSettings に checkpointOverrides を追加します。specDecodingPairs を含め、それ以外は何も変わりません。

spec:
  modelConfigs:
    - model: meta-llama-3-3-70b-instruct:1
      profile: llama-3p1-70b-sd
    - model: meta-llama-3-2-1b-instruct:1
      profile: llama-3p1-1b
      modelSettings:
        routable: false
        checkpointOverrides:
          checkpoint:
            source: gs://<BUCKET_NAME>/path/to/custom/draft/checkpoint
            checkpoint_status: stable
  specDecodingPairs:
    - draft: meta-llama-3-2-1b-instruct
      target: meta-llama-3-3-70b-instruct

チェックポイントの source には、Google Cloud Storage のパス (gs://) または NFS のパス (nfs://) を指定できます。

ターゲットのチェックポイントもカスタマイズする場合は、同じ方法でターゲットモデルのエントリに checkpointOverrides を追加します。

バンドルの適用

kubectl apply -f <modelbundle-file>.yaml

重要な注意点

推論 API リクエストでドラフトモデルを直接呼び出す必要はありません。
ターゲットモデルにリクエストを送信すると、SambaStack がペアリングされたドラフトモデルを使用して投機的デコーディングを自動的に実行します。
投機的デコーディングが機能するには、両方のモデルが spec.modelConfigs に含まれている必要があります。
カスタムチェックポイントの完全なワークフローについては、カスタムチェックポイントのデプロイをご覧ください。

デプロイメントの確認

バンドルを適用してデプロイしたら、デプロイメントを確認します。

# Check bundle status
kubectl get modelbundles

# Check bundle details, including the legalizer result
kubectl describe modelbundle <your-bundle-name>

# Check the deployment
kubectl get modeldeployments

# Verify models are registered
kubectl get models

ターゲットモデルに推論リクエストを送信してテストします。SambaStack は、リクエストの処理時に自動的にドラフトモデルを使用して投機的デコーディングを実行します。

kubectl get models が一覧表示するのは Kubernetes のリソース名 (metadata.name) です。ターゲットモデルへのアクセスには、サービング名 (spec.name) を使用してください。両者は異なることがよくあります。対応モデルとバンドルをご覧ください。

SambaNova SDK、OpenAI 互換ライブラリ、または CURL を使用した推論リクエストの送信例については、開発者向けのクイックスタートガイドをご覧ください。

トラブルシューティング

問題	考えられる原因	解決策
検証に失敗する	語彙サイズの不一致	ドラフトとターゲットが互換性のあるトークナイザーを使用していることを確認してください
アクセプト率が低い	ドラフトとターゲットの整合性が低い	ターゲットとより密接に整合したドラフトモデルを使用してください
パフォーマンスの低下	入力が長く出力が短い	このワークロードでは投機的デコーディングの無効化を検討してください
デプロイに失敗する	バンドルにドラフトモデルがない	ターゲットモデルとドラフトモデルの両方が `spec.modelConfigs` に記載されていることを確認してください
モデルが見つからない	モデル名の不一致	`modelConfigs[].model` が `Model` リソース名と一致していることを確認してください

はじめに

サービス管理

ハードウェア管理

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

リソース

投機的デコーディングによるデプロイ

投機的デコーディングとは

投機的デコーディングを使用すべきでないケース

投機的デコーディングでのカスタムドラフトチェックポイントの使用

ワークフローの概要

カスタムドラフトチェックポイントのデプロイ手順

デプロイメントが投機的デコーディングを使用していることを確認

投機的デコーディングのフィールド

カスタムドラフトチェックポイントの変換

ドラフトとターゲットのチェックポイント互換性の検証

コマンドテンプレート

パラメータ

ホスト側の変数

カスタムドラフトチェックポイントのアップロード

ドラフトチェックポイントの参照

ModelBundle の更新

変更前: SambaNova 提供のドラフトを使用

変更後: カスタムドラフトチェックポイントを使用

バンドルの適用

重要な注意点

デプロイメントの確認

トラブルシューティング

関連ページ

​投機的デコーディングとは

​投機的デコーディングを使用すべきでないケース

​投機的デコーディングでのカスタムドラフトチェックポイントの使用

​ワークフローの概要

​カスタムドラフトチェックポイントのデプロイ手順

デプロイメントが投機的デコーディングを使用していることを確認

​投機的デコーディングのフィールド

カスタムドラフトチェックポイントの変換

ドラフトとターゲットのチェックポイント互換性の検証

​コマンドテンプレート

​パラメータ

​ホスト側の変数

カスタムドラフトチェックポイントのアップロード

ドラフトチェックポイントの参照

ModelBundle の更新

​変更前: SambaNova 提供のドラフトを使用

​変更後: カスタムドラフトチェックポイントを使用

​バンドルの適用

​重要な注意点

​デプロイメントの確認

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

​関連ページ

投機的デコーディングとは

投機的デコーディングを使用すべきでないケース

投機的デコーディングでのカスタムドラフトチェックポイントの使用

ワークフローの概要

カスタムドラフトチェックポイントのデプロイ手順

投機的デコーディングのフィールド

コマンドテンプレート

パラメータ

ホスト側の変数

変更前: SambaNova 提供のドラフトを使用

変更後: カスタムドラフトチェックポイントを使用

バンドルの適用

重要な注意点

デプロイメントの確認

トラブルシューティング

関連ページ