特性：精确前缀缓存感知路由

概览

本指南演示了如何配置推理调度器，以使用基于 vLLM KV-Events 数据的新型精确前缀缓存感知路由。精确前缀缓存感知路由从推理实例中提取最新的前缀缓存状态，从而消除了对额外索引服务的需求，并在高吞吐量下提高了缓存命中率。

先决条件

请在本地系统中安装适当的客户端工具以使用本指南。
配置并部署您的 Gateway 控制平面。
在系统中安装监控栈。

为安装创建一个命名空间。

export NAMESPACE=llm-d-precise # or any other namespace (shorter names recommended)
kubectl create namespace ${NAMESPACE}

在目标命名空间中创建名为 `llm-d-hf-token` 的 Secret，其键为 `HF_TOKEN`，并匹配有效的 HuggingFace 令牌以拉取模型。
选择一个 llm-d 版本

安装

使用 helmfile 来组合并安装组件栈。部署该组件栈的命名空间（Namespace）将派生自 ${NAMESPACE} 环境变量。如果您尚未设置此变量，在本示例中它将默认设为 llm-d-precise。

部署

cd guides/precise-prefix-cache-aware
helmfile apply -n ${NAMESPACE}

注意：您可以设置 $RELEASE_NAME_POSTFIX 环境变量来更改发布名称（release names）。这是我们支持并发安装的方式。例如：RELEASE_NAME_POSTFIX=kv-events-2 helmfile apply -n ${NAMESPACE}

注意：本示例默认使用 Istio 作为提供商，请参阅网关选项以了解如何安装特定提供商。

Gateway 选项

要指定您的网关选择，可以使用 -e <gateway option> 标志，例如：

helmfile apply -e kgateway -n ${NAMESPACE}

要查看支持哪些 Gateway 选项，请参考我们的 Gateway 提供商先决条件文档。每个提供商的 Gateway 配置都在 gateway-configurations 目录中进行跟踪。

您还可以自定义 Gateway，更多信息请参阅我们的 Gateway 自定义文档。

安装 HTTPRoute

请遵循特定提供商的说明来安装 HTTPRoute。

为 "kgateway" 或 "istio" 安装

kubectl apply -f httproute.yaml -n ${NAMESPACE}

为 "gke" 安装

kubectl apply -f httproute.gke.yaml -n ${NAMESPACE}

验证安装

首先，您应该能够列出所有 helm release，以查看已安装到所选命名空间中的 3 个 chart。

helm list -n ${NAMESPACE}
NAME            NAMESPACE       REVISION        UPDATED                                 STATUS          CHART                           APP VERSION
gaie-kv-events  llm-d-precise   1               2025-09-25 21:36:52.452999581 +0000 UTC deployed        inferencepool-v1.2.0            v1.2.0
infra-kv-events llm-d-precise   1               2025-09-25 21:36:50.848300265 +0000 UTC deployed        llm-d-infra-v1.3.6              v0.3.0     
ms-kv-events    llm-d-precise   1               2025-09-25 21:36:55.955958022 +0000 UTC deployed        llm-d-modelservice-v0.3.17      v0.3.0 

通过此示例，您开箱即用应拥有以下资源

kubectl get all -n ${NAMESPACE}
NAME                                                          READY   STATUS    RESTARTS   AGE
pod/gaie-kv-events-epp-687b78968b-wvswh                       1/1     Running   0          80s
pod/infra-kv-events-inference-gateway-istio-949d87f84-zvsp2   1/1     Running   0          85s
pod/ms-kv-events-llm-d-modelservice-decode-b874d48d9-bgm5r    1/1     Running   0          75s
pod/ms-kv-events-llm-d-modelservice-decode-b874d48d9-ph64c    1/1     Running   0          75s

NAME                                              TYPE           CLUSTER-IP   EXTERNAL-IP   PORT(S)                        AGE
service/gaie-kv-events-epp                        ClusterIP      10.16.2.44   <none>        9002/TCP,9090/TCP,5557/TCP     81s
service/gaie-kv-events-ip-805c964d                ClusterIP      None         <none>        54321/TCP                      75s
service/infra-kv-events-inference-gateway-istio   LoadBalancer   10.16.1.30   10.16.4.2     15021:32033/TCP,80:39332/TCP   86s

NAME                                                      READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/gaie-kv-events-epp                        1/1     1            1           81s
deployment.apps/infra-kv-events-inference-gateway-istio   1/1     1            1           86s
deployment.apps/ms-kv-events-llm-d-modelservice-decode    2/2     2            2           76s

NAME                                                                DESIRED   CURRENT   READY   AGE
replicaset.apps/gaie-kv-events-epp-687b78968b                       1         1         1       81s
replicaset.apps/infra-kv-events-inference-gateway-istio-949d87f84   1         1         1       86s
replicaset.apps/ms-kv-events-llm-d-modelservice-decode-b874d48d9    2         2         2       76s

注意： 这假设您的 ${NAMESPACE} 中没有其他指南部署，并且您没有通过 ${RELEASE_NAME} 环境变量更改默认 Release 名称。

测试此“常用路径”

关于如何开始发送推理请求，我们有适用于所有示例的通用文档，可在此处获取。不过，本示例有独特的交互指令，将在下文中提供

首先，您需要向网关发送一个基础推理请求。有关如何执行此操作的深入文档，请参阅上面的链接，但此处会提供一个可在默认设置下开箱即用的命令

kubectl port-forward -n ${NAMESPACE} service/infra-kv-events-inference-gateway-istio 8000:80
export LONG_TEXT_200_WORDS="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum."

curl -s https://:8000/v1/completions \
  -H "Content-Type: application/json" \
  -d ``{
    "model": "Qwen/Qwen3-0.6B",
    "prompt": "'"$LONG_TEXT_200_WORDS"'",
    "max_tokens": 50
  }`` | jq

使用以下命令检查推理调度器（inference-scheduler）的前缀缓存打分器（prefix-cache-scorer）的得分

kubectl logs -l inferencepool=gaie-kv-events-epp -n ${NAMESPACE} --tail 100 | grep "Calculated score" | grep "precise-prefix-cache-scorer/precise-prefix-cache-scorer"

您应该看到类似于以下的输出

`{"level":"Level(-4)","ts":"2025-10-07T16:07:36Z","caller":"framework/scheduler_profile.go:165","msg":"Calculated score","x-request-id":"77790804-deb4-441a-9a03-d771d8e20778","objectiveKey":"","incomingModelName":"Qwen/Qwen3-0.6B","targetModelName":"Qwen/Qwen3-0.6B","priority":0,"plugin":"precise-prefix-cache-scorer/precise-prefix-cache-scorer","endpoint":{"name":"ms-kv-events-llm-d-modelservice-decode-75499f8dc5-pbp84","namespace":"llm-d-precise"}`,"score":0}
`{"level":"Level(-4)","ts":"2025-10-07T16:07:36Z","caller":"framework/scheduler_profile.go:165","msg":"Calculated score","x-request-id":"77790804-deb4-441a-9a03-d771d8e20778","objectiveKey":"","incomingModelName":"Qwen/Qwen3-0.6B","targetModelName":"Qwen/Qwen3-0.6B","priority":0,"plugin":"precise-prefix-cache-scorer/precise-prefix-cache-scorer","endpoint":{"name":"ms-kv-events-llm-d-modelservice-decode-75499f8dc5-kgnqh","namespace":"llm-d-precise"}`,"score":0}

重复上述步骤以查看前缀缓存打分器的实际运行情况

您应该看到类似于以下的输出

`{"level":"Level(-4)","ts":"2025-10-07T16:09:21Z","caller":"framework/scheduler_profile.go:165","msg":"Calculated score","x-request-id":"f4c967aa-ad15-4be2-8640-55164da18dfa","objectiveKey":"","incomingModelName":"Qwen/Qwen3-0.6B","targetModelName":"Qwen/Qwen3-0.6B","priority":0,"plugin":"precise-prefix-cache-scorer/precise-prefix-cache-scorer","endpoint":{"name":"ms-kv-events-llm-d-modelservice-decode-75499f8dc5-pbp84","namespace":"llm-d-precise"}`,"score":0}
`{"level":"Level(-4)","ts":"2025-10-07T16:09:21Z","caller":"framework/scheduler_profile.go:165","msg":"Calculated score","x-request-id":"f4c967aa-ad15-4be2-8640-55164da18dfa","objectiveKey":"","incomingModelName":"Qwen/Qwen3-0.6B","targetModelName":"Qwen/Qwen3-0.6B","priority":0,"plugin":"precise-prefix-cache-scorer/precise-prefix-cache-scorer","endpoint":{"name":"ms-kv-events-llm-d-modelservice-decode-75499f8dc5-kgnqh","namespace":"llm-d-precise"}`,"score":1}

注意：这些日志仅针对唯一的请求出现，因此如果您没有看到重复出现的日志实例，请确保以唯一的方式重新执行请求。

请注意，当我们第二次调用 /v1/completions 端点时，前缀缓存打分器能够为 pod 返回一个得分，这表明它已缓存了来自第一次调用的 KV 块。

清理

移除部署

# Remove the model services
# From examples/precise-prefix-cache-aware
helmfile destroy -n ${NAMESPACE}

# Or uninstall manually
helm uninstall infra-kv-events -n ${NAMESPACE}
helm uninstall gaie-kv-events -n ${NAMESPACE}
helm uninstall ms-kv-events -n ${NAMESPACE}

注意：如果您设置了 $RELEASE_NAME_POSTFIX 环境变量，您的发布名称将与上述命令不同：infra-$RELEASE_NAME_POSTFIX、gaie-$RELEASE_NAME_POSTFIX 和 ms-$RELEASE_NAME_POSTFIX。

自定义

有关自定义指南的信息以及构建自己的指南的技巧，请参阅我们的文档

内容来源

此内容自动从 llm-d/llm-d 仓库 main 分支的 guides/precise-prefix-cache-aware/README.md 同步。

📝 如需建议更改，请编辑源文件或创建 issue。

概览​

先决条件​

安装​

部署​

Gateway 选项​

安装 HTTPRoute​

为 "kgateway" 或 "istio" 安装​

为 "gke" 安装​

验证安装​

测试此“常用路径”​

清理​

自定义​

概览