> ## 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]
>
> モデルとエキスパート (Expert)、バンドル (Bundle) とバンドルテンプレート (Bundle Template)、モデルマニフェスト (Model Manifest)、モデルのデプロイに馴染みがない場合は、[モデルバンドルのデプロイ](https://docs.sambanova.ai/docs/ja/v1.2.0/sambastack/service-administration/model-deployment/deploying-model-bundles.md) ページをご覧ください。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

カスタムドラフトチェックポイントをデプロイするには、まず、デプロイしたいバンドル内のモデルエキスパートが投機的デコーディング用に構成されていることを確認します。この情報は、**バンドルテンプレート (Bundle Template)** の定義に記載されています。

以下の例では、`Meta-Llama-3.3-70B-Instruct` モデルが投機的デコーディングを使用しており、投機的デコーディングを使用しない `gpt-oss-120b` と同じバンドルにまとめられています。

```yaml theme={}
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 ファイルでは指定しません。

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

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

1. ツールをまだセットアップしていない場合は、チェックポイント変換ツールのドキュメントページにある [**ダウンロードとセットアップ**](https://docs.sambanova.ai/docs/ja/v1.2.0/sambastack/service-administration/model-deployment/checkpoint-conversion-tool.md#ダウンロードとセットアップ) の手順に従ってください。
2. 次に、[**チェックポイントの変換と検証**](https://docs.sambanova.ai/docs/ja/v1.2.0/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 の権限設定の詳細については、[**カスタムチェックポイントのデプロイ → 変換済みチェックポイントのアップロード**](https://docs.sambanova.ai/docs/ja/v1.2.0/sambastack/service-administration/model-deployment/deploy-custom-checkpoints.md#変換済みチェックポイントのアップロード) をご覧ください。

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

[カスタムチェックポイントをデプロイする](https://docs.sambanova.ai/docs/ja/v1.2.0/sambastack/service-administration/model-deployment/deploy-custom-checkpoints.md)ワークフローのステップ 3 と同様に、モデルマニフェストを作成してチェックポイントを登録します。

モデルマニフェストには、チェックポイントに関する以下のような情報が保存されます。

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

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

```yaml theme={}
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` からファインチューニングされたものである場合、トークナイザーのパスは次のように設定できます。

```yaml theme={}
tokenizer:
  endpointUrl: ''
  path: ./Meta-Llama-3.1-70B-Instruct_tokenizer
```

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

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

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

```bash theme={}
kubectl apply -f your_model_manifest_filename.yaml
```

### 6. バンドル構成の更新

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

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

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

```yaml theme={}
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` セクションの両方を編集して、カスタムドラフトチェックポイントを使用するようにバンドルを更新します。

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

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

### バンドルの適用

```bash theme={}
kubectl apply -f your_bundle_filename.yaml
```

### 重要な注意点

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

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

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

```bash theme={}
# 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 を使用した推論リクエストの送信例については、開発者向けの[クイックスタートガイド](https://docs.sambanova.ai/docs/ja/get-started/quickstart.md) をご覧ください。

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

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

## 関連ページ

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