KV Cache 事件

KV Cache 事件是在推理过程中管理 KV Cache 时发生的操作或生命周期事件。这些事件可用于 KV Cache 感知路由。

LMCache 支持以下 KV 缓存事件：

• 生成存储 KV Cache 事件

• 事件格式根据 vLLM 中的 BlockStored class 定义。

• LMCache 将事件传递给 SGLang 或 vLLM，以通过它们的消息系统发布这些事件。

先决条件

以下先决条件是必需的：

vLLM

• vLLM v0.13.0+

• LMCache v0.3.11+

SGLang

• SGLang vx.y.z+

• LMCache vx.y.z+

如何生成 KV Cache 事件

vLLM

在开始生成 KV 事件之前，您需要了解以下内容：

• 您需要为 LMCache 启用 enable_kv_events，因为默认情况下不会生成事件。

• 如果在 vLLM 中运行多个工作进程，则需要使用非默认的哈希算法（在 LMCache 中设置 pre_caching_hash_algorithm），以确保每个工作进程生成的哈希相同。如果不这样做，则会为相同操作生成重复事件，因为事件是按工作进程生成的。

• LMCache 将事件发送到 vLLM 进行发布。要启用事件发布，您需要设置 vLLM 配置选项 --kv-events-config。有关更多详细信息，请参见 vLLM KV Events configuration。

接下来的步骤给出了如何生成、发布和消费 KV 事件的示例：

1. 以如下方式启动 vLLM，使用 LMCache 和模型 Qwen/Qwen3-0.6B：

LMCACHE_CONFIG_FILE=lmcache_config.yaml \
    vllm serve Qwen/Qwen3-0.6B --kv-transfer-config '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}' \
    --disable-log-requests --no-enable-prefix-caching --kv-events-config '{"enable_kv_cache_events": "True", "publisher": "zmq", "topic": "kv-events"}'

LMCache 配置示例如下：

chunk_size: 8  # demo only; use 256 for production
local_cpu: true
enable_kv_events: true
pre_caching_hash_algorithm: sha256_cbor_64bit

2. 要处理 vLLM 发布的事件，您需要一个订阅发布者消息通道并能够消费事件的客户端。vLLM 提供了这样的客户端示例 KV Events Subscriber。在单独的终端中运行此 Python 脚本。

3. 提示模型：

  curl http://localhost:8000/v1/completions \
-H "Content-Type: application/json" \
-d '{
  "model": "Qwen/Qwen3-0.6B",
  "prompt": "<|begin_of_text|><|system|>\nYou are a helpful AI assistant.\n<|user|>\nWhat is the capital of France?\n<|assistant|>",
  "max_tokens": 100,
  "temperature": 0.7
}'

4. 您应该在客户端（您在第 2 步中启动的客户端）窗口中收到一条消息，类似于以下内容：

  Received event batch at 1765529395.2132685:
- BlockStored(block_hashes=[b'\x96\x95[h6\x1dE$v\x03\xe8\xf0\xc20\xcd\xe8\xa7#\x9cS\xe0\x16\xba\xab7\xf7z\x10P]\xfaT'], parent_block_hash=None, token_ids=[27, 91, 7265, 3575, 4326, 91, 1784, 91, 8948, 91, 397, 2610, 525, 264, 10950, 15235, 17847, 624, 27, 91, 872, 91, 397, 3838, 374, 279, 16158, 1685, 1370, 276, 5267, 27, 91, 77091, 91, 29], block_size=36, lora_id=None, medium='cpu')

这是在缓存存储操作后生成的事件。

SGLang

在开始生成 KV 事件之前，您需要了解以下内容：

• 您需要为 LMCache 启用 enable_kv_events，因为默认情况下不会生成事件。

• LMCache 将事件发送到 SGLang 进行发布。要启用事件发布，您需要设置 SGLang 配置选项 --kv-events-config。

接下来的步骤给出了如何生成、发布和消费 KV 事件的示例：

1. 使用 LMCache 和模型 Qwen/Qwen3-0.6B 启动 SGLang，如下所示：

export LMCACHE_CONFIG_FILE=lmcache_config.yaml

python -m sglang.launch_server \
--model-path Qwen/Qwen3-0.6B \
--enable-lmcache \
--kv-events-config '{"publisher": "zmq", "topic": "kv-events"}'

LMCache 配置示例如下：

chunk_size: 8  # demo only; use 256 for production
local_cpu: true
use_layerwise: true
max_local_cpu_size: 10  # GB
enable_kv_events: true

2. 要处理 SGLang 发布的事件，您需要一个订阅发布者消息通道并能够消费事件的客户端。vLLM 提供了这样一个客户端示例 KV Events Subscriber。要将此客户端用于 SGLang，您需要从 BlockStored 类定义中删除属性 medium 和 lora_name，并从 BlockRemoved 类定义中删除 medium。保存更改并在单独的终端中运行此更新的 Python 脚本。

3. 提示模型：

curl http://localhost:30000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
  "model": "Qwen/Qwen3-0.6B",
  "messages": [{"role": "user", "content": "Qwen3 is the latest generation of large language models in Qwen series, offering a comprehensive suite of dense and mixture-of-experts"}],
  "max_tokens": 100,
  "temperature": 0.7
}'

4. 您应该在客户端（您在第 2 步中启动的客户端）窗口中收到一条消息，类似于以下内容：

Received event batch at 1769014811.9058058:
  - BlockStored(block_hashes=[-7651984371600085018], parent_block_hash=None, token_ids=[151644, 872, 198, 48, 16948, 18, 374, 279, 5535], block_size=8, lora_id=None)
  - BlockStored(block_hashes=[1717827842932260036], parent_block_hash=-7651984371600085018, token_ids=[5535, 9471, 315, 3460, 4128, 4119, 304, 1207, 16948], block_size=8, lora_id=None)
  - BlockStored(block_hashes=[-6563676647234339623], parent_block_hash=1717827842932260036, token_ids=[16948, 4013, 11, 10004, 264, 15817, 16182, 315, 27950], block_size=8, lora_id=None)
  - BlockStored(block_hashes=[-5164197595219155465], parent_block_hash=-6563676647234339623, token_ids=[27950, 323, 20980, 8668, 18376, 15546, 151645, 198, 151644], block_size=8, lora_id=None)
  - BlockStored(block_hashes=[8690007828157426740], parent_block_hash=-5164197595219155465, token_ids=[151644, 77091, 198, 151667, 198, 32313, 11, 279, 1196], block_size=8, lora_id=None)
  - BlockStored(block_hashes=[5720773965762948853], parent_block_hash=8690007828157426740, token_ids=[1196, 9733, 1207, 16948, 18, 438, 279, 5535, 9471], block_size=8, lora_id=None)
  - BlockStored(block_hashes=[-4465594513801548703], parent_block_hash=5720773965762948853, token_ids=[9471, 315, 3460, 4128, 4119, 304, 279, 1207, 16948], block_size=8, lora_id=None)
  - BlockStored(block_hashes=[4010782427232237897], parent_block_hash=-4465594513801548703, token_ids=[16948, 4013, 323, 429, 432, 5707, 264, 15817, 16182], block_size=8, lora_id=None)
  - BlockStored(block_hashes=[8472258105533326837], parent_block_hash=4010782427232237897, token_ids=[16182, 315, 27950, 323, 20980, 8668, 18376, 15546, 4119], block_size=8, lora_id=None)
  - BlockStored(block_hashes=[-3602322156693524155], parent_block_hash=8472258105533326837, token_ids=[4119, 13, 6771, 752, 1191, 553, 48996, 279, 1207], block_size=8, lora_id=None)
  - BlockStored(block_hashes=[-6413316389463734553], parent_block_hash=-3602322156693524155, token_ids=[1207, 16948, 4013, 13, 1207, 16948, 374, 264, 4013], block_size=8, lora_id=None)
  - BlockStored(block_hashes=[-4080340760183068020], parent_block_hash=-6413316389463734553, token_ids=[4013, 315, 15235, 4119, 7881, 553, 54364, 13, 576], block_size=8, lora_id=None)
  - BlockStored(block_hashes=[1557368444906237766], parent_block_hash=-4080340760183068020, token_ids=[576, 5535, 825, 11, 1207, 16948, 18, 11, 374], block_size=8, lora_id=None)
  - BlockStored(block_hashes=[-2282733302929094006], parent_block_hash=1557368444906237766, token_ids=[374, 12824, 279, 5535, 11, 773, 429, 594, 4396], block_size=8, lora_id=None)
  - BlockStored(block_hashes=[8695562889830890067], parent_block_hash=-2282733302929094006, token_ids=[4396, 382, 7039, 11, 279, 1196, 6801, 311, 1414], block_size=8, lora_id=None)
  - BlockStored(block_hashes=[-6034740625096789744], parent_block_hash=8695562889830890067, token_ids=[1414, 911, 279, 15817, 16182, 315, 27950, 323, 20980], block_size=8, lora_id=None)

这是在缓存存储操作后生成的事件。