本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 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 缓存状态的情况下均匀分配请求。

智能路由适用于所有亚马逊 SageMaker HyperPod 推断部署方法，包括亚马逊部 SageMaker JumpStart 署（控制台和 kubectl）、NVMe 本地存储部署以及来自亚马逊 S3、亚马逊 FSx 或 Hugging Face Hub 的部署。无论使用哪种部署方法为模型提供服务，都可以启用缓存和路由。

**注意**  
KV 缓存和智能路由目前仅支持 v LLM-based 推理容器。

## 配置 KV 缓存和智能路由
<a name="sagemaker-hyperpod-model-deployment-deploy-ftm-cache-route"></a>

1. 通过设置`enableL1Cache`和`enableL2Cache`来启用 KV 缓存`true`。然后，`l2CacheSpec`通过设置`l2CacheBackend`为`redis`或进行配置`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. 通过`enabled`将`true`设置为 under 来启用智能路由`intelligentRoutingSpec`。您可以在下方指定要使用的路由策略`routingStrategy`。如果未指定路由策略，则默认为`prefixaware`。

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

1. 通过设置`enabled`为小`true`于，启用路由器指标和缓存指标`metrics`。该`port`值必须与下的`containerPort`值相同`modelInvocationPort`。

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

## KV-aware 路由兼容性
<a name="sagemaker-hyperpod-model-deployment-kv-routing-compatibility"></a>

本节中的兼容性矩阵和版本限制*仅*适用于`kvaware`路由策略。该`kvaware`策略将传入的请求定向到具有最高 KV 缓存命中率的推理实例，并且目前仅支持以 `/completions` API 作为调用端点的 v LLM-based 图像。

**注意**  
如果您使用`kvaware`路由，则必须在部署清单`/completions`中`invocationEndpoint`将设置为。`kvaware`路由不支持`/v1/chat/completions`终端节点。其他路由策略 (`prefixaware`,`session`,`roundrobin`) 适用于任何调用端点。

**支持的图片：**
+ [vllM 图片：hub.docker。 com/r/vllm/vllm-](https://hub.docker.com/r/vllm/vllm-openai) openai
+ [lmCache 图片：hub.docker。 com/r/lmcache/vllm-](https://hub.docker.com/r/lmcache/vllm-openai/tags) openai
+ AWS 深度学习容器：[gallery.ecr. aws/deep-学习-containers/vllm](https://gallery.ecr.aws/deep-learning-containers/vllm)


| 推理运算符版本 | 亚马逊 EKS Add-on 版本 | 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 | 

**注意**  
我们建议使用推理运算符 v3.1.3 或更高版本，以及支持矩阵中显示的相应的 lmCache 和 vlLM 版本。较新的 LmCache 版本支持张量并行性、改进的故障处理和缓存工作器注册，这为路由提供了更好的稳健性。 KV-aware

### 验证 KV 缓存感知路由
<a name="sagemaker-hyperpod-model-deployment-kv-routing-validation"></a>

部署启用 KV-aware 路由的模型后，使用以下步骤验证路由是否正常工作。

#### 查看工作人员登记
<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-aware 路由来定向请求：

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

当 KV-aware 路由正常工作时：

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

当 KV-aware 路由不起作用时（回退到循环模式）：

```
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-aware 路由正常运行时，这些指标应显示较高的值：


| 指标 | 说明 | 
| --- | --- | 
| 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 | Per-request 缓存命中率（直方图） |