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

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

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

本ページでは、投機的デコーディングを使用してモデルをデプロイする方法を説明します。投機的デコーディングが適しているケース、ドラフトモデルとターゲットモデルの互換性を検証する方法、カスタムドラフトチェックポイントの構成方法を扱います。

> [!NOTE]
>
> モデル、モデルプロファイル、モデルバンドル、モデルのデプロイに馴染みがない場合は、[モデルとバンドルのデプロイ](/docs/ja/v2.1.1/sambastack/service-administration/model-deployment/deploying-models-and-bundles/overview) をご覧ください。

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

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

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

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

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

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

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

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

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

このセクションでは、**カスタムドラフトチェックポイント**をデプロイする一連のワークフローを説明します。内容は以下のとおりです。

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

### ワークフローの概要

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

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

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

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

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

```bash theme={}
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` は、これらと同じバンドルに含まれていますが、投機的デコーディングは使用しません。

```yaml theme={}
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` | いいえ | ペアリングを特定のエキスパートに限定します。このフィールドを省略すると、ペアリングはターゲットモデルのすべてのエキスパートに適用されます。 |

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

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

1. ツールをまだセットアップしていない場合は、チェックポイント変換ツールのドキュメントページにある [**ダウンロードとセットアップ**](/docs/ja/v2.1.1/sambastack/service-administration/model-deployment/checkpoint-conversion-tool.md#ダウンロードとセットアップ) の手順に従ってください。
2. 次に、[**チェックポイントの変換と検証**](/docs/ja/v2.1.1/sambastack/service-administration/model-deployment/checkpoint-conversion-tool.md#チェックポイントの変換と検証) の手順に従ってドラフトチェックポイントを変換します。

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

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

投機的デコーディングでカスタムチェックポイントをデプロイする際は、ドラフトチェックポイントがターゲットチェックポイントと互換であることを検証してください。これにより、推論時の予期しないエラーを防止できます。

**チェックポイント変換ツール**には、ドラフトとターゲットの互換性をチェックする組み込みユーティリティが用意されています。この検証ユーティリティを使用して、以下を確認します。

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

### コマンドテンプレート

```bash theme={}
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` 配下にミラーされます)。 |

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

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

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

**クラスターが NFS マウントストレージを使用している場合は**、カスタムチェックポイントを、クラスターから読み取れる NFS 上に配置してください。

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

```bash theme={}
gcloud storage cp -r <LOCAL_DRAFT_CHECKPOINT_DIR> gs://<BUCKET_NAME>/<PATH>/
```

アップロード手順と GCS の権限設定の詳細については、[**カスタムチェックポイントのデプロイ → 変換済みチェックポイントのアップロード**](/docs/ja/v2.1.1/sambastack/service-administration/model-deployment/deploying-models-and-bundles/deploy-custom-checkpoints.md#変換済みチェックポイントのアップロード) をご覧ください。

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

[カスタムチェックポイントのデプロイ](/docs/ja/v2.1.1/sambastack/service-administration/model-deployment/deploying-models-and-bundles/deploy-custom-checkpoints.md#チェックポイントの参照) で説明されている 2 つの方法のいずれかを使用して、変換したドラフトチェックポイントをサービング可能にします。

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

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

### 6. ModelBundle の更新

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

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

```yaml theme={}
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` を含め、それ以外は何も変わりません。

```yaml theme={}
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
```

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

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

### バンドルの適用

```bash theme={}
kubectl apply -f <modelbundle-file>.yaml
```

### 重要な注意点

* 推論 API リクエストでドラフトモデルを直接呼び出す必要は**ありません**。
* ターゲットモデルにリクエストを送信すると、SambaStack がペアリングされたドラフトモデルを使用して投機的デコーディングを自動的に実行します。
* 投機的デコーディングが機能するには、両方のモデルが `spec.modelConfigs` に含まれている必要があります。
* カスタムチェックポイントの完全なワークフローについては、[カスタムチェックポイントのデプロイ](/docs/ja/v2.1.1/sambastack/service-administration/model-deployment/deploying-models-and-bundles/deploy-custom-checkpoints.md) をご覧ください。

## デプロイメントの確認

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

```bash theme={}
# 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 は、リクエストの処理時に自動的にドラフトモデルを使用して投機的デコーディングを実行します。

> [!NOTE]
>
> `kubectl get models` が一覧表示するのは Kubernetes のリソース名 (`metadata.name`) です。ターゲットモデルへのアクセスには、サービング名 (`spec.name`) を使用してください。両者は異なることがよくあります。[対応モデルとバンドル](/docs/ja/v2.1.1/sambastack/service-administration/model-deployment/supported-models-and-bundles.md#対応モデルの一覧) をご覧ください。

SambaNova SDK、OpenAI 互換ライブラリ、または CURL を使用した推論リクエストの送信例については、開発者向けの[クイックスタートガイド](/docs/ja/get-started/quickstart.md) をご覧ください。

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

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

## 関連ページ

* [チェックポイント変換ツール](/docs/ja/v2.1.1/sambastack/service-administration/model-deployment/checkpoint-conversion-tool.md): チェックポイントを SambaNova フォーマットに変換
* [カスタムチェックポイントのデプロイ](/docs/ja/v2.1.1/sambastack/service-administration/model-deployment/deploying-models-and-bundles/deploy-custom-checkpoints.md): カスタムターゲットチェックポイントのデプロイ
* [モデルとバンドルのデプロイ](/docs/ja/v2.1.1/sambastack/service-administration/model-deployment/deploying-models-and-bundles/overview): モデル、プロファイル、バンドル、デプロイメントの概念