翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

# KV キャッシュとインテリジェントルーティング
<a name="sagemaker-hyperpod-model-deployment-caching-routing"></a>

Amazon SageMaker HyperPod Inference は、マネージド階層型キーバリュー (KV) キャッシュとインテリジェントルーティングを提供し、大規模言語モデル (LLM) ワークロードの推論パフォーマンスを最適化します。KV キャッシュは、以前のトークンを処理した後に事前計算されたキーと値のベクトルを保存し、冗長な再計算を排除します。2 層キャッシュアーキテクチャを使用すると、低レイテンシーのローカル再利用に CPU メモリを使用する L1 キャッシュと、Redis またはマネージド階層型ストレージを活用してスケーラブルなノードレベルのキャッシュ共有を可能にする L2 キャッシュを設定できます。

インテリジェントルーティングは受信リクエストを分析し、関連するキャッシュされたキーと値のペアを持つ可能性が最も高い推論インスタンスに転送します。システムはリクエストを調べ、次のいずれかのルーティング戦略に基づいてルーティングします。
+ `prefixaware` — 同じプロンプトプレフィックスを持つ後続のリクエストは、同じインスタンスにルーティングされます。
+ `kvaware` — 受信リクエストは、KV キャッシュヒット率が最も高いインスタンスにルーティングされます。
+ `session` — 同じユーザーセッションからのリクエストは、同じインスタンスにルーティングされます。
+ `roundrobin` — KV キャッシュの状態を考慮せずに、リクエストを均等に分散します。

インテリジェントルーティングは、Amazon SageMaker JumpStart デプロイ (コンソールと kubectl の両方）、NVMe ローカルストレージデプロイ、Amazon S3、Amazon FSx、Hugging Face Hub からのデプロイなど、すべての Amazon SageMaker HyperPod Inference デプロイ方法で機能します。 Amazon S3 FSx モデルの配信に使用するデプロイ方法に関係なく、キャッシュとルーティングを有効にできます。

**注記**  
KV キャッシュとインテリジェントルーティングは現在、vLLM ベースの推論コンテナのみをサポートしています。

## KV キャッシュとインテリジェントルーティングを設定する
<a name="sagemaker-hyperpod-model-deployment-deploy-ftm-cache-route"></a>

1. `enableL1Cache` と `enableL2Cache`を に設定して KV キャッシュを有効にします`true`。次に、 `l2CacheBackend`を `redis`または に設定`l2CacheSpec`して を設定します`tieredstorage`。を選択した場合は`redis`、Redis クラスター URL `l2CacheLocalUrl`で を更新します。

   ```
     kvCacheSpec:
       enableL1Cache: true
       enableL2Cache: true
       l2CacheSpec:
         l2CacheBackend: <redis | tieredstorage>
         l2CacheLocalUrl: <Redis cluster URL if l2CacheBackend is redis >
   ```
**注記**  
Redis クラスターが HyperPod クラスターと同じ Amazon VPC 内にない場合、転送中のデータの暗号化は保証されません。
**注記**  
`l2CacheLocalUrl` `tieredstorage` を選択した場合、 は必要ありません。

1. `true` で `enabled` を に設定して、インテリジェントルーティングを有効にします`intelligentRoutingSpec`。で使用するルーティング戦略を で指定できます`routingStrategy`。ルーティング戦略が指定されていない場合、デフォルトで になります`prefixaware`。

   ```
   intelligentRoutingSpec:
       enabled: true
       routingStrategy: <routing strategy to use>
   ```

1. `true` で `enabled`を に設定して、ルーターメトリクスとキャッシュメトリクスを有効にします`metrics`。`port` 値は、 `containerPort`の値と同じである必要があります`modelInvocationPort`。

   ```
   metrics:
       enabled: true
       modelMetrics:
         port: <port value>
       ...
       modelInvocationPort:
         containerPort: <port value>
   ```

## KV 対応ルーティングの互換性
<a name="sagemaker-hyperpod-model-deployment-kv-routing-compatibility"></a>

このセクションの互換性マトリックスとバージョンの制約は、`kvaware`ルーティング戦略*にのみ適用されます*。この`kvaware`戦略は、着信リクエストを KV キャッシュヒット率の高い推論インスタンスに送信し、現在、呼び出しエンドポイントとして `/completions` API を使用する vLLM ベースのイメージのみをサポートしています。

**注記**  
`kvaware` ルーティングを使用する場合は、デプロイマニフェスト`/completions`で `invocationEndpoint`を に設定する必要があります。`/v1/chat/completions` エンドポイントは`kvaware`ルーティングではサポートされていません。他のルーティング戦略 (`prefixaware`、`session`、`roundrobin`) は、任意の呼び出しエンドポイントで機能します。

**サポートされているイメージ:**
+ vLLM イメージ: [hub.docker.com/r/vllm/vllm-openai](https://hub.docker.com/r/vllm/vllm-openai)
+ LMCache イメージ: [hub.docker.com/r/lmcache/vllm-openai](https://hub.docker.com/r/lmcache/vllm-openai/tags)
+ AWS 深層学習コンテナ: [gallery.ecr.aws/deep-learning-containers/vllm](https://gallery.ecr.aws/deep-learning-containers/vllm)


| 推論演算子のバージョン | Amazon EKS アドオンバージョン | LMCache イメージバージョン | vLLM イメージバージョン | 
| --- | --- | --- | --- | 
| >= v3.1.3 | >= v1.2.1-eksbuild.1 | >= v0.4.3 | >= v0.19.1 | 
| < v3.1.3 | < v1.2.1-eksbuild.1 | v0.3.9post2 | v0.11.1 | 

**注記**  
サポートマトリックスに示されている対応する LMCache および vLLM バージョンでは、推論演算子バージョン v3.1.3 以降を使用することをお勧めします。新しい LMCache バージョンでは、テンソル並列処理、障害処理の改善、キャッシュワーカー登録がサポートされるため、KV 対応ルーティングの堅牢性が向上します。

### KV キャッシュ対応ルーティングの検証
<a name="sagemaker-hyperpod-model-deployment-kv-routing-validation"></a>

KV 対応ルーティングを有効にしてモデルをデプロイしたら、次の手順を使用してルーティングが正しく動作していることを確認します。

#### ワーカー登録を確認する
<a name="sagemaker-hyperpod-model-deployment-kv-routing-validation-registration"></a>

ルーターログを確認して、ワーカーがルーターに登録されていることを確認します。

```
kubectl logs -n hyperpod-inference-system <router-pod> | grep -i "register"
```

正常な登録は以下を示します。

```
INFO: Worker registered: lmcacheengineconfig_<hash>
```

#### ルーターログのキャッシュヒットを確認する
<a name="sagemaker-hyperpod-model-deployment-kv-routing-validation-cache-hits"></a>

ルーターが KV 対応ルーティングを使用してリクエストを送信していることを確認します。

```
kubectl logs -n hyperpod-inference-system <router-pod> | grep -i "kvaware\|Matched instance\|Lookup"
```

KV 対応ルーティングが正しく動作している場合:

```
INFO: Routing request to lmcacheengineconfig_<hash> found by kvaware router
```

KV 対応ルーティングが機能しない場合 (ラウンドロビンに戻る):

```
DEBUG: Matched instance url None
```

#### ワーカーログの LMCache 初期化を確認する
<a name="sagemaker-hyperpod-model-deployment-kv-routing-validation-lmcache"></a>

LMCache がワーカーポッドで正常に初期化されたことを確認します。

```
kubectl logs -n <namespace> <worker-pod> | grep -i "LMCache"
```

正常な初期化は以下を示します。

```
LMCache INFO: LMCacheManager initialized successfully
```

LMCache の初期化に失敗すると、以下が表示されます。

```
LMCache ERROR: Failed to initialize LMCacheManager components: . System will operate in degraded mode (recompute).
```

#### Grafana メトリクスで検証する
<a name="sagemaker-hyperpod-model-deployment-kv-routing-validation-metrics"></a>

メトリクス (`metrics.enabled: true`) を有効にすると、vLLM ワーカー`/metrics`エンドポイントの次のメトリクスがキャッシュヒットを確認します。KV 対応ルーティングが正しく動作している場合、これらのメトリクスには高い値が表示されます。


| メトリクス | 説明 | 
| --- | --- | 
| vllm:prefix\_cache\_hits\_total / vllm:prefix\_cache\_queries\_total | GPU プレフィックスキャッシュヒット率 (比率として計算) | 
| lmcache:num\_vllm\_hit\_tokens\_total | LMCache から提供されるトークンの数 | 
| lmcache:num\_lookup\_hits\_total / lmcache:num\_lookup\_tokens\_total | LMCache ルックアップヒット率 (比率として計算) | 
| lmcache:request\_cache\_hit\_rate | リクエストごとのキャッシュヒット率 (ヒストグラム) |