本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# KV 快取和智慧型路由
<a name="sagemaker-hyperpod-model-deployment-caching-routing"></a>

Amazon SageMaker HyperPod Inference 提供受管分層金鑰值 (KV) 快取和智慧型路由，以最佳化大型語言模型 (LLM) 工作負載的推論效能。KV 快取會在處理先前的權杖後儲存預先計算的鍵/值向量，消除多餘的重新計算。透過雙層快取架構，您可以設定使用 CPU 記憶體進行低延遲本機重複使用的 L1 快取，以及利用 Redis 或受管分層儲存來啟用可擴展節點層級快取共用的 L2 快取。

智慧型路由會分析傳入的請求，並將其導向至最有可能具有相關快取金鑰/值對的推論執行個體。系統會檢查請求，並根據下列其中一個路由策略進行路由：
+ `prefixaware` — 具有相同提示字首的後續請求會路由至相同的執行個體。
+ `kvaware` — 傳入的請求會路由至 KV 快取命中率最高的執行個體。
+ `session` — 來自相同使用者工作階段的請求會路由至相同的執行個體。
+ `roundrobin` — 平均分佈請求，而不考慮 KV 快取的狀態。

智慧路由適用於所有 Amazon SageMaker HyperPod 推論部署方法，包括 Amazon SageMaker JumpStart 部署 （主控台和 kubectl)、NVMe 本機儲存部署，以及來自 Amazon S3、Amazon FSx 或 Hugging Face Hub 的部署。無論您使用哪種部署方法為模型提供服務，都可以啟用快取和路由。

**注意**  
KV 快取和智慧型路由目前僅支援 vLLM 型推論容器。

## 設定 KV 快取和智慧型路由
<a name="sagemaker-hyperpod-model-deployment-deploy-ftm-cache-route"></a>

1. 透過將 `enableL1Cache`和 設定為 `enableL2Cache`來啟用 KV 快取`true`。然後，`l2CacheSpec`將 設定為 `redis`或 `l2CacheBackend`來設定 `tieredstorage`。如果您選擇 `redis`，`l2CacheLocalUrl`請使用 Redis 叢集 URL 更新 。

   ```
     kvCacheSpec:
       enableL1Cache: true
       enableL2Cache: true
       l2CacheSpec:
         l2CacheBackend: <redis | tieredstorage>
         l2CacheLocalUrl: <Redis cluster URL if l2CacheBackend is redis >
   ```
**注意**  
如果 Redis 叢集不在與 HyperPod 叢集相同的 Amazon VPC 內，則不保證傳輸中資料的加密。
**注意**  
如果`tieredstorage`已選取 `l2CacheLocalUrl` ，則不需要。

1. 透過將 `enabled`設定為 `true`下的 來啟用智慧型路由`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`將 設定為 。`kvaware` 路由不支援`/v1/chat/completions`端點。其他路由策略 (`prefixaware`、`session`、`roundrobin`) 可與任何調用端點搭配使用。

**支援的影像：**
+ vLLM 影像：https：//[hub.docker.com/r/vllm/vllm-openai](https://hub.docker.com/r/vllm/vllm-openai)
+ LMCache 映像：https：//[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 | >= 0.4.3 版 | >= v0.19.1 | 
| < 3.1.3 版 | < 1.2.1-eksbuild.1 版 | v0.3.9post2 | v0.11.1 | 

**注意**  
我們建議將推論運算子版本 v3.1.3 或更新版本與支援矩陣中顯示的對應 LMCache 和 vLLM 版本搭配使用。較新的 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 在工作者 Pod 上初始化成功：

```
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 | 每個請求快取命中率 （長條圖） |