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

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

モデルとエキスパート (Expert)、バンドル (Bundle) とバンドルテンプレート (Bundle Template)、モデルマニフェスト (Model Manifest)、モデルのデプロイに馴染みがない場合は、モデルバンドルのデプロイページをご覧ください。

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

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

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

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

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

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

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

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

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

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

ワークフローの概要

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

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

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

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

カスタムドラフトチェックポイントをデプロイするには、まず、デプロイしたいバンドル内のモデルエキスパートが投機的デコーディング用に構成されていることを確認します。この情報は、バンドルテンプレート (Bundle Template) の定義に記載されています。以下の例では、Meta-Llama-3.3-70B-Instruct モデルが投機的デコーディングを使用しており、投機的デコーディングを使用しない gpt-oss-120b と同じバンドルにまとめられています。

apiVersion: sambanova.ai/v1alpha1
kind: BundleTemplate
metadata:
  name: bt-gpt120-llama70sd8-llama8
spec:
  models:
    gpt-oss-120b:
      experts:
        8k:
          configs:
          - pef: gpt-oss-fp8-ss8192-bs2:1
        32k:
          configs:
          - pef: gpt-oss-fp8-ss32768-bs2:1
    Meta-Llama-3.3-70B-Instruct:
      experts:
        4k:
          configs:
          - pef: llama-3p1-70b-ss4096-bs4-sd5:3
            spec_decoding:
              draft_model: Meta-Llama-3.1-8B-Instruct
          - pef: llama-3p1-70b-ss4096-bs32-sd5:2
        8k:
          configs:
          - pef: llama-3p1-70b-ss8192-bs1-sd5:1
          - pef: llama-3p1-70b-ss8192-bs8-sd5:2
          default_config_values:
            spec_decoding:
              draft_model: Meta-Llama-3.1-8B-Instruct
        128k:
          configs:
          - pef: llama-3p1-70b-ss131072-bs1-sd5:2
    Meta-Llama-3.1-8B-Instruct:
      experts:
        4k:
          configs:
          - pef: llama-3p1-8b-ss4096-bs4:1
        8k:
          configs:
          - pef: llama-3p1-8b-ss8192-bs1:1
          - pef: llama-3p1-8b-ss8192-bs8:1
  owner: no-reply@sambanova.ai
  secretNames:
  - sambanova-artifact-reader
  usePefCRs: true

上記の例では、

Meta-Llama-3.3-70B-Instruct がターゲットモデルです。
Meta-Llama-3.1-8B-Instruct が投機的デコーディングに使用されるドラフトモデルです。
以下のとおり、ターゲットモデル Meta-Llama-3.3-70B-Instruct に対して投機的デコーディングを構成する方法は 3 通りあります。
- エキスパート内の個別の config に対するドラフトモデル: 4k エキスパートでは、バッチサイズ 4 の config に対して draft_model: Meta-Llama-3.1-8B-Instruct を指定した spec_decoding が構成されています。同じエキスパート内のバッチサイズ 32 の config には、投機的デコーディングは構成されていません。
- エキスパート内のすべての config に対するドラフトモデル: 8k エキスパートでは、default_config_values の下に spec_decoding が構成されています。これにより、8k エキスパート内のすべての config に draft_model: Meta-Llama-3.1-8B-Instruct が適用されます。
- ドラフトモデルなし: 128k エキスパートには投機的デコーディングが構成されていません。そのため、このエキスパートの実行を必要とするリクエストが送信された場合、投機的デコーディングは使用されません。バッチサイズ 32 の config を持つ 4k エキスパートについても同様です。

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

ターゲットモデルとドラフトモデルの両方が、バンドルテンプレートの YAML ファイルに記載されている必要があります。
ターゲットモデルとドラフトモデルの両方のテンプレート名が、バンドルの YAML ファイルで参照されている必要があります。
投機的デコーディングはバンドルテンプレートの YAML ファイルで指定します。バンドルの YAML ファイルでは指定しません。
カスタムチェックポイントはバンドルの YAML ファイルで指定します。バンドルテンプレートの YAML ファイルでは指定しません。

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

ドラフトモデルのチェックポイントを、独自にファインチューニングしたバージョンやカスタムバージョンに置き換える場合は、チェックポイント変換ツール (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 の権限設定の詳細については、カスタムチェックポイントのデプロイ → 変換済みチェックポイントのアップロード をご覧ください。

ドラフトチェックポイントの登録

カスタムチェックポイントをデプロイするワークフローのステップ 3 と同様に、モデルマニフェストを作成してチェックポイントを登録します。モデルマニフェストには、チェックポイントに関する以下のような情報が保存されます。

API リクエストや他の YAML で使用する名前
対応言語
チェックポイントの説明

モデルマニフェストの例

apiVersion: sambanova.ai/v1
kind: Model

metadata:
  name: my-custom-llama3.1-8b # kubernetes resource name

spec:
  name: my-custom-llama3.1-8b # serving name used in the inference API
  owner: jane@doe.ai
  public: true

  aliases:
    - my-custom-llama3.1-8b # other aliases for the serving name used in the inference API
    - My-Custom-Llama3.1-8B

  metadata:
    name: "[optional]" # kubernetes name
    overview: "[optional description of the model]"
    architecture: "[optional]"
    category: "[optional]"
    status: active

    github_link: "[optional]"
    hf_link: "[optional]"

    languages:
      - "[optional]"

    license: "[optional]"
    vocabulary_size: "[optional]"

  price:
    input_tokens: "[optional]"
    output_tokens: "[optional]"

  tokenizer:
    endpointUrl: ""   # optional remote tokenizer endpoint
    path: ./Meta-Llama-3.1-8B-Instruct_tokenizer

name フィールド (上記の例では my-custom-llama3.1-8b) は、以降のステップで参照する重要なフィールドになります。

トークナイザーフィールドの選択

モデルマニフェストの tokenizer フィールドには、カスタムチェックポイントのベースとなったモデルを設定できます。たとえば、カスタムチェックポイントが Meta-Llama-3.1-70B-Instruct からファインチューニングされたものである場合、トークナイザーのパスは次のように設定できます。

tokenizer:
  endpointUrl: ''
  path: ./Meta-Llama-3.1-70B-Instruct_tokenizer

モデルマニフェストの tokenizer フィールドは、生成前にシーケンス長の要件を計算するための入力チェックにのみ使用されます。

モデルマニフェストの適用

モデルマニフェストを作成したら、次のコマンドで適用します。

kubectl apply -f your_model_manifest_filename.yaml

バンドル構成の更新

ドラフトチェックポイントのアップロードと登録が完了したら、他のカスタムチェックポイントと同じ方法でバンドル構成を更新します。

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

以下は、カスタムドラフトチェックポイントを導入する前のバンドルです。ターゲットチェックポイントのみがカスタマイズされています。

apiVersion: sambanova.ai/v1alpha1
kind: Bundle
metadata:
  name: 70b-3dot3-ss-4-8-64-128k
spec:
  checkpoints:
    LLAMA3_8B_3_1_CKPT:
      source: gs://service-account-gcs-bucket/.../ckpts/meta-llama3-8b-instruct
      toolSupport: true
    CUSTOM_70B_TARGET_CKPT:
      source: gs://your-gcs-bucket/path/to/custom/ckpt/dir
      toolSupport: false
  models:
    Meta-Llama-3.1-8B-Instruct:
      checkpoint: LLAMA3_8B_3_1_CKPT
      template: Meta-Llama-3.1-8B-Instruct
    Custom-Target-Llama-3.3-70B:
      checkpoint: CUSTOM_70B_TARGET_CKPT
      template: Meta-Llama-3.3-70B-Instruct
...

変更後: カスタムドラフトを使用

ドラフトモデルのチェックポイントを置き換えるには、ターゲットモデルの場合と同様に、checkpoints セクションと models セクションの両方を編集して、カスタムドラフトチェックポイントを使用するようにバンドルを更新します。

apiVersion: sambanova.ai/v1alpha1
kind: Bundle
metadata:
  name: 70b-3dot3-ss-4-8-64-128k
spec:
  checkpoints:
    CUSTOM_8B_DRAFT_CKPT:
      source: gs://your-gcs-bucket/path/to/custom/draft/ckpt/dir
      toolSupport: true
    CUSTOM_70B_TARGET_CKPT:
      source: nfs://your-nfs-server/path/to/custom/ckpt/dir
      toolSupport: false
  models:
    Custom-Draft-Llama-3.1-8B:
      checkpoint: CUSTOM_8B_DRAFT_CKPT
      template: Meta-Llama-3.1-8B-Instruct
    Custom-Target-Llama-3.3-70B:
      checkpoint: CUSTOM_70B_TARGET_CKPT
      template: Meta-Llama-3.3-70B-Instruct
...

spec.checkpoints.source には、Google Cloud Storage のパス (gs://) または NFS のパス (nfs://) を指定できます。

バンドルの適用

kubectl apply -f your_bundle_filename.yaml

重要な注意点

推論 API リクエストでドラフトモデルを直接呼び出す必要はありません
ターゲットモデル (例: Custom-Target-Llama-3.3-70B) にリクエストを送信すると、SambaStack が対応するドラフトチェックポイントを使用して投機的デコーディングを自動的に実行します
投機的デコーディングが機能するには、両方のチェックポイントがバンドルに含まれている必要があります
カスタムドラフトチェックポイントを参照するようにデプロイメントを変更する手順は、カスタムチェックポイントの手順と同様です。詳細については、カスタムチェックポイントのデプロイページのデプロイ用 Bundle でのチェックポイントの参照をご覧ください。

デプロイメントの確認

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

# Check Bundle status
kubectl get bundles

# Check Bundle details
kubectl describe bundle <your-bundle-name>

# Verify models are registered
kubectl get models

ターゲットモデルに推論リクエストを送信してテストします。SambaStack は、リクエストの処理時に自動的にドラフトモデルを使用して投機的デコーディングを実行します。 SambaNova SDK、OpenAI 互換ライブラリ、または CURL を使用した推論リクエストの送信例については、開発者向けのクイックスタートガイドをご覧ください。

トラブルシューティング

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

はじめに

サービス管理

ハードウェア管理

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

リソース

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

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

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

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

ワークフローの概要

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

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

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

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

コマンドテンプレート

パラメータ

ホスト側の変数

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

ドラフトチェックポイントの登録

モデルマニフェストの例

トークナイザーフィールドの選択

モデルマニフェストの適用

バンドル構成の更新

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

変更後: カスタムドラフトを使用

バンドルの適用

重要な注意点

デプロイメントの確認

トラブルシューティング

関連ページ

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

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

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

​ワークフローの概要

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

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

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

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

​コマンドテンプレート

​パラメータ

​ホスト側の変数

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

ドラフトチェックポイントの登録

​モデルマニフェストの例

​トークナイザーフィールドの選択

​モデルマニフェストの適用

バンドル構成の更新

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

​変更後: カスタムドラフトを使用

​バンドルの適用

​重要な注意点

​デプロイメントの確認

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

​関連ページ

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

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

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

ワークフローの概要

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

コマンドテンプレート

パラメータ

ホスト側の変数

モデルマニフェストの例

トークナイザーフィールドの選択

モデルマニフェストの適用

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

変更後: カスタムドラフトを使用

バンドルの適用

重要な注意点

デプロイメントの確認

トラブルシューティング

関連ページ