# 推論コンテナの機能
Amazon Nova SageMaker 推論コンテナには、推論中にモデルの動作をカスタマイズするために有効にできる一連の機能が含まれています。各機能は特定のコンテナのバージョンで導入されており、アクティブ化するには環境変数、リクエストパラメータ、またはその両方が必要になる場合があります。
このページでは、推論コンテナで使用できる機能を一覧表示し、それぞれを有効にする方法について説明します。また、この機能が導入されたコンテナのバージョンを特定します。このリファレンスを使用して、デプロイで使用できる機能とその設定方法を決定します。
環境変数を通じて有効になる機能は、SageMaker モデルまたはエンドポイント設定を作成するときに設定されます。[CreateModel](https://docs.aws.amazon.com//sagemaker/latest/APIReference/API_CreateModel.html) API コールの `Environment` パラメータにそれらを含めます。リクエストパラメータを通じて有効になる機能は、リクエスト本文の呼び出しごとに設定されます。
**注記**
利用可能なすべての機能へのアクセス権を得るには、常に最新のコンテナイメージを使用してください。`SM-Inference-latest` タグは現在 `v1.4` を指しています。
## 特徴の概要
次の表は、Amazon Nova SageMaker 推論コンテナでサポートされているすべての機能のクイックリファレンスを示しています。
**推論コンテナ機能の概要**
| 機能 | 有効化する方法 | デフォルト | サポートされているモデル | ご紹介 |
| --- | --- | --- | --- | --- |
| [デフォルトの温度](#nova-sagemaker-inference-container-feature-default-temperature) | 環境変数 | 1.0 | すべての Amazon Nova モデル | v1.0 |
| [デフォルトの top-p](#nova-sagemaker-inference-container-feature-default-top-p) | 環境変数 | 1.0 | すべての Amazon Nova モデル | v1.0 |
| [デフォルトの top-k](#nova-sagemaker-inference-container-feature-default-top-k) | 環境変数 | -1 (無効) | すべての Amazon Nova モデル | v1.0 |
| [デフォルトの新しいトークンの最大数](#nova-sagemaker-inference-container-feature-default-max-new-tokens) | 環境変数 | モデルの最大コンテキスト長 | すべての Amazon Nova モデル | v1.0 |
| [デフォルトの logprobs](#nova-sagemaker-inference-container-feature-default-logprobs) | 環境変数 | Disabled | すべての Amazon Nova モデル | v1.0 |
| [Eagle3 投機的デコーディング](#nova-sagemaker-inference-container-feature-speculative-decoding) | デフォルトで有効 | 有効 | すべての Amazon Nova モデル | v1.0 |
| [KV キャッシュデータ型](#nova-sagemaker-inference-container-feature-kv-cache-dtype) | 環境変数 | モデルのデータ型と同じ | すべての Amazon Nova モデル | v1.3 |
| [量子化](#nova-sagemaker-inference-container-feature-quantization) | 環境変数 | Disabled\* | すべての Amazon Nova モデル | v1.3 |
| [投機トークンの数](#nova-sagemaker-inference-container-feature-num-speculative-tokens) | 環境変数 | 3 | すべての Amazon Nova モデル | v1.4 |
| [サフィックスデコーディング](#nova-sagemaker-inference-container-feature-suffix-decoding) | 環境変数 | Disabled | すべての Amazon Nova モデル | v1.4 |
**重要**
\* FP8 量子化は自動的に有効になり、次のモデルとインスタンスタイプの組み合わせでは無効にできません。
`ml.g6.12xlarge` または `ml.g6.24xlarge` 上の Amazon Nova Lite
`ml.g6.48xlarge` 上の Nova Lite 2
これらの設定では、`QUANTIZATION_DTYPE` を設定する必要はありません。詳細については、「[量子化](#nova-sagemaker-inference-container-feature-quantization)」を参照してください。
## デフォルトの温度
エンドポイントに送信されるすべての推論リクエストのデフォルトのサンプリング温度を設定します。温度は、モデルの出力のランダム性または予測可能性を制御します。`0` の値を指定すると、モデルは常に最も可能性の高い次の単語を選択し、一貫性のある反復可能な出力を生成します。値を大きくすると (最大 `2`)、モデルは可能性の低い単語をより積極的に選択し、よりクリエイティブで多様性のあるレスポンスを生成します。
**使用するタイミング:** 分類やデータ抽出などの事実に基づいた一貫した回答を必要とするタスクでは、温度を下げます (`0.1`～`0.3` など)。ストーリーの記述やブレインストーミングなどのクリエイティブなタスクでは、温度を上げます (`0.7`～`1.0` など)。温度は top-p および top-k と連動します。3 つすべてによって、モデルがトークンを選択する方法が制御されるので、それらを結合して出力動作をファインチューニングできます。
ご紹介
`v1.0`
サポートされているモデル
すべての Amazon Nova モデル
有効化する方法
SageMaker モデルを作成するときに `DEFAULT_TEMPERATURE` 環境変数を設定します。
デフォルト値
`1.0`
有効値
`0`～`2` (包括的) の浮動小数点
**環境変数**
```
"Environment": {
"DEFAULT_TEMPERATURE": "0.7"
}
```
**注記**
リクエスト本文に `temperature` パラメータを含めることで、リクエストごとにこのデフォルトを上書きできます。
## デフォルトの top-p
すべての推論リクエストのデフォルトの top-p 値を設定します。top-p は、モデルの選択を最も可能性の高い単語のサブセットに制限することで、出力の多様性を制御します。具体的には、モデルはすべての可能な次の単語を確率でソートし、組み合わせた確率が top-p 値に達した最小グループのみを考慮します。例えば、`0.9` の top-p は、モデルが確率が 90% の割合をともに占める単語のみを考慮し、残りの可能性の低いオプションを無視することを意味します。
**使用するタイミング:** 低い top-p 値 (例: `0.5`) を使用して、モデルを信頼性の高い単語に維持し、より焦点を絞った出力を生成します。より高い値 (例: `0.95`) を使用して、より大きな多様性を許可します。top-p は温度の代わりによく使用されます。どちらも出力の多様性を制御しますが、top-p は各ステップにおけるモデルの信頼度に基づいて動的に適応します。両方を一緒に使用できます。その場合、モデルは各ステップでより制限の厳しい制約を適用します。
ご紹介
`v1.0`
サポートされているモデル
すべての Amazon Nova モデル
有効化する方法
SageMaker モデルを作成するときに `DEFAULT_TOP_P` 環境変数を設定します。
デフォルト値
`1.0`
有効値
`1e-10`～`1` (包括的) の浮動小数点
**環境変数**
```
"Environment": {
"DEFAULT_TOP_P": "0.9"
}
```
**注記**
リクエスト本文に `top_p` パラメータを含めることで、リクエストごとにこのデフォルトを上書きできます。
## デフォルトの top-k
すべての推論リクエストのデフォルトの top-k 値を設定します。top-k は、モデルの選択を最も可能性の高い次の単語の固定数に制限します。例えば、`50` の top-k は、モデルが個々の確率に関係なく、各ステップで最も可能性の高い 50 個の単語のみを考慮することを意味します。`-1` の値を指定すると、この制限が無効になり、モデルはすべての可能な単語を考慮できます。
**使用するタイミング:** モデルが考慮する単語の選択数をハードキャップする場合は、top-k を使用します。値 (`10` など) を小さくすると、より予測可能な出力が生成されますが、値を大きくすると、より大きな多様性が可能になります。top-k は温度と top-p と組み合わせることができます。複数のサンプリングコントロールがアクティブな場合、モデルは各ステップで最も制限の厳しいものを使用してそれらをすべて適用します。
ご紹介
`v1.0`
サポートされているモデル
すべての Amazon Nova モデル
有効化する方法
SageMaker モデルを作成するときに `DEFAULT_TOP_K` 環境変数を設定します。
デフォルトの値
`-1` (無効)
有効値
`-1` 以上の整数。`-1` を使用してすべてのトークンを考慮します。
**環境変数**
```
"Environment": {
"DEFAULT_TOP_K": "50"
}
```
**注記**
リクエスト本文に `top_k` パラメータを含めることで、リクエストごとにこのデフォルトを上書きできます。
## デフォルトの新しいトークンの最大数
モデルがレスポンスで生成するトークン (単語または単語部分) のデフォルトの最大数を設定します。この値は、上書きされない限り、すべてのリクエストに適用されます。これを使用して、レスポンスの長さを制御し、エンドポイント全体のコストを管理します。
**使用するタイミング:** すべてのリクエストに一貫した最大レスポンス長を適用する場合に設定します。例えば、短い回答タスクの場合は `256` に設定し、長いコンテンツ生成の場合は `2048` に設定します。入力トークンと出力トークンはコンテキスト長を超えることができないため、許可される最大値はエンドポイントに設定された `CONTEXT_LENGTH` によって異なります。
ご紹介
`v1.0`
サポートされているモデル
すべての Amazon Nova モデル
有効化する方法
SageMaker モデルを作成するときに `DEFAULT_MAX_NEW_TOKENS` 環境変数を設定します。
デフォルトの値
モデルの最大コンテキスト長
有効値
`1` 以上の整数
**環境変数**
```
"Environment": {
"DEFAULT_MAX_NEW_TOKENS": "512"
}
```
**注記**
リクエスト本文に `max_tokens` または `max_completion_tokens` パラメータを含めることで、リクエストごとにこのデフォルトを上書きできます。許可される最大値は、エンドポイントに設定された `CONTEXT_LENGTH` によって異なります。
## デフォルトの logprobs
生成されたトークンごとに返されるログ確率のデフォルト数を設定します。ログ確率は、モデルが各単語の選択にどの程度自信があったかを示す数値スコアです。有効にすると、レスポンスには各出力トークンのこれらのスコアが含まれ、これは、モデルの信頼度の評価、代替単語の選択の比較、生成動作のデバッグに役立ちます。
**使用するタイミング:** モデルが出力にどの程度自信があるかを評価する必要がある場合に logprobs を有効にします。例えば、人間によるレビューのために信頼度の低いレスポンスにフラグを付けたり、さまざまな生成結果の可能性を比較したりします。logprobs を有効にすると、レスポンスのレイテンシーとレスポンスのペイロードサイズがわずかに増加する可能性があります。
ご紹介
`v1.0`
サポートされているモデル
すべての Amazon Nova モデル
有効化する方法
SageMaker モデルを作成するときに `DEFAULT_LOGPROBS` 環境変数を設定します。
デフォルトの値
Disabled
有効値
`1`～`20` (包括的) の整数
**環境変数**
```
"Environment": {
"DEFAULT_LOGPROBS": "5"
}
```
**注記**
リクエスト本文に `logprobs` および `top_logprobs` パラメータを含めることで、リクエストごとにこのデフォルトを上書きできます。logprobs を有効にすると、レスポンスのレイテンシーがわずかに増加する可能性があります。
## Eagle3 投機的デコーディング
Eagle3 投機的デコーディングは、テキスト生成を高速化する最適化手法です。より小さくて高速なドラフトモデルを使用して複数のトークンを事前に予測し、それらの予測を 1 つのステップでプライマリモデルに対して照合することで機能します。予測が正しい場合、モデルは、生成に通常かかる時間内に複数のトークンを効果的に生成します。プライマリモデルは常にドラフトトークンを検証するため、最終出力はプライマリモデルが独自に生成するものと同一です。品質ではなく速度のみが変わります。
**使用するタイミング:** Eagle3 投機的デコーディングはデフォルトで有効になっており、ほとんどのワークロードにメリットがあります。予期しない動作が観測されるか、デバッグ中にパフォーマンス特性を分離する必要がある場合にのみ、無効にすることを検討してください。
ご紹介
`v1.0`。Eagle3 投機的デコーディングによる FP8 量子化のサポートが `v1.4` に追加されました。
サポートされているモデル
すべての Amazon Nova モデル
有効化する方法
Eagle3 投機的デコーディングはデフォルトで有効になっており、設定の必要はありません。無効にするには、`DISABLE_SPECULATIVE_DECODING` を使用します。
デフォルトの値
`false` (Eagle3 投機的デコーディングが有効)
有効値
`true`, `false`
**環境変数**
次の例では、Eagle3 投機的デコーディングを無効にします。
```
"Environment": {
"DISABLE_SPECULATIVE_DECODING": "true"
}
```
## KV キャッシュデータ型
推論中に使用されるキー‐値 (KV) キャッシュのデータ型を設定します。KV キャッシュは、以前のトークンのモデルのメモリを会話に保存するため、入力全体を再処理することなく新しいトークンを生成できます。長いシーケンスの場合、このキャッシュは大量の GPU メモリを消費する可能性があります。KV キャッシュを FP8 などの低精度データ型に設定すると、メモリ使用量が削減され、スループットが向上する可能性があります。ただし、出力にわずかな数値差が生じるという犠牲を伴います。
**使用するタイミング:** インスタンスで長いコンテキスト長またはより高い同時実行をサポートする必要がある場合は、FP8 KV キャッシュを有効にします。これは、メモリが限られている GPU インスタンスで特に役立ちます。ユースケースをテストして、出力品質が要件を満たしていることを確認します。精度が低いと、わずかに異なる結果が得られる可能性があるためです。
ご紹介
`v1.3`
サポートされているモデル
すべての Amazon Nova モデル
有効化する方法
SageMaker モデルを作成するときに `KV_CACHE_DTYPE` 環境変数を設定します。
デフォルトの値
モデルのデータ型と同じ
有効値
`fp8`
**環境変数**
```
"Environment": {
"KV_CACHE_DTYPE": "fp8"
}
```
**注記**
KV キャッシュデータ型を変更すると、デフォルトの精度と比較して出力がわずかに異なる場合があります。ユースケースをテストして、出力品質が要件を満たしていることを確認します。
## 量子化
モデル重みの量子化データ型を設定します。量子化は、モデルの重みを低精度形式 (デフォルトの高精度ではなく FP8) に圧縮し、モデルに必要な GPU メモリの量を減らします。これにより、推論スループットが向上し、より大きなモデルをより小さなインスタンスタイプに適合させ、出力品質への影響を最小限に抑えることができます。
**使用するタイミング:** メモリ使用量を減らしてより多数の同時実行をサポートしたり、より小さなインスタンスタイプにモデルを適合させたりする場合は、FP8 量子化を使用します。一部のモデルとインスタンスタイプの組み合わせでは、FP8 量子化が自動的に必要になることに注意してください。以下の警告を参照してください。
ご紹介
`v1.3`
サポートされているモデル
すべての Amazon Nova モデル
有効化する方法
SageMaker モデルを作成するときに `QUANTIZATION_DTYPE` 環境変数を設定します。
デフォルトの値
Disabled。ただし、FP8 量子化は、特定のモデルとインスタンスタイプの組み合わせで自動的に有効になります。以下の注記を参照してください。
有効値
`fp8`
**環境変数**
```
"Environment": {
"QUANTIZATION_DTYPE": "fp8"
}
```
**重要**
次のモデルとインスタンスタイプの組み合わせには、FP8 量子化が必要です。これらの設定では、量子化は自動的に有効になり、無効にしたり上書きしたりすることはできません。
`ml.g6.12xlarge` または `ml.g6.24xlarge` 上の Amazon Nova Lite
`ml.g6.48xlarge` 上の Nova Lite 2
その他すべての設定については、「[サポートされているモデルとインスタンス](nova-model-sagemaker-inference.md#nova-sagemaker-inference-supported)」を参照してください。
## 投機トークンの数
各 Eagle3 投機的デコーディングステップ中にドラフトモデルが事前に予測するトークンの数を制御します。値が大きいほど、ドラフトモデルはより多くのトークンを一度に予測しようとし、これにより、予測が正確である場合のスループットを向上させることができます。ドラフトモデルの予測がプライマリモデルと頻繁に異なる場合、低い値の方が効率的である場合があります。
**使用するタイミング:** ワークロードが予測可能な出力パターン (構造化データやテンプレートテキストなど) を生成し、ドラフトモデルが正しく推測する可能性が高い場合は、この値を増加させます。予測の信頼性が低いクリエイティブな出力や多様性が高い出力には減少させます。
ご紹介
`v1.4`
サポートされているモデル
すべての Amazon Nova モデル
有効化する方法
SageMaker モデルを作成するときに `NUM_SPECULATIVE_TOKENS` 環境変数を設定します。
デフォルト値
`3`
有効値
`1`～`10` (包括的) の整数
**環境変数**
```
"Environment": {
"NUM_SPECULATIVE_TOKENS": "5"
}
```
**注記**
この設定は、Eagle3 投機的デコーディングが有効になっている (`DISABLE_SPECULATIVE_DECODING` が `false` である) 場合にのみ適用されます。投機的デコーディングが無効になっている場合やサフィックスデコーディングを使用している場合は効果がありません。
## サフィックスデコーディング
サフィックスデコーディングは、テキスト生成を高速化するための代替方法です。(Eagle3 のように) 別のドラフトモデルを使用する代わりに、サフィックスデコーディングは、既に生成されたテキストまたは入力プロンプトで繰り返しパターンを探し、それらのパターンを再利用して将来のトークンを予測します。このアプローチは、出力に繰り返しフレーズ、構造化形式、または入力を非常によく反映したコンテンツが含まれている可能性が高い場合に適しています。
**使用するタイミング:** 構造化データの生成、テンプレートの入力、ソースからフレーズを再利用するコンテンツの要約など、出力に反復パターンが含まれているタスクではサフィックスデコードを使用します。出力の多様性が高い汎用の生成の場合、デフォルトの Eagle3 メソッドは通常、より高いスループットを提供します。
ご紹介
`v1.4`
サポートされているモデル
すべての Amazon Nova モデル
有効化する方法
SageMaker モデルを作成するときに、`SPECULATIVE_DECODING_METHOD` 環境変数を `suffix` に設定します。
デフォルト値
`eagle3`
有効値
`eagle3`, `suffix`
**環境変数**
```
"Environment": {
"SPECULATIVE_DECODING_METHOD": "suffix"
}
```
**注記**
サフィックスデコードを使用するには、`DISABLE_SPECULATIVE_DECODING` を `false` (デフォルト) に設定する必要があります。`DISABLE_SPECULATIVE_DECODING` を `true` に設定すると、サフィックスデコーディングを含むすべての投機的デコーディングメソッドが無効になります。