示例：在多个 LLM 之间共享 KV Cache#

LMCache 应该能够减少第二次及后续调用的生成时间。

我们有以下类型的跨实例 KV Cache 共享的示例：

通过集中式缓存服务器的 KV Cache 共享：centralized_sharing
通过点对点缓存传输共享 KV 缓存: p2p_sharing

前提条件#

您的服务器应至少配备 2 个 GPU。

对于集中式共享，这将使用端口 8000 和 8001（用于 vLLM）以及端口 65432（用于 LMCache）。

对于 P2P 共享：

NIXL 安装在主机上。
用于 2 个 vLLM 服务器的 8010 和 8011 端口。
端口 8200 和 8202 用于 2 个 p2p 初始化连接。
端口 8201 和 8203 用于 2 个 p2p 查找连接。
端口 8300 用于控制器拉取请求。
控制器回复请求的端口为 8400。
8500 和 8501 端口用于 2 个 LMCache 工作线程。
端口 9000 用于控制器主端口（任意且可以更改），以启动控制器。

集中式 KV Cache 共享#

本节演示如何通过集中式 LMCache 服务器在多个 vLLM 实例之间共享 KV Cache。

重要：对于集中式缓存共享（跨进程情况），确保所有进程使用相同的 PYTHONHASHSEED 以保持 KV 缓存在进程之间的一致性：export PYTHONHASHSEED=0。

设置集中式共享#

首先，创建一个名为 lmcache_config.yaml 的配置文件，内容如下：

chunk_size: 256
local_cpu: true
remote_url: "lm://localhost:65432"
remote_serde: "cachegen"

运行集中式共享示例#

启动 LMCache 中央服务器，

lmcache_server localhost 65432

在另一个终端中，

PYTHONHASHSEED=0 \
LMCACHE_CONFIG_FILE=lmcache_config.yaml \
CUDA_VISIBLE_DEVICES=0 \
vllm serve meta-llama/Meta-Llama-3.1-8B-Instruct \
    --gpu-memory-utilization 0.8 \
    --port 8000 --kv-transfer-config \
    '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}'

在另一个终端中，

PYTHONHASHSEED=0 \
LMCACHE_CONFIG_FILE=lmcache_config.yaml \
CUDA_VISIBLE_DEVICES=1 \
vllm serve meta-llama/Meta-Llama-3.1-8B-Instruct \
    --gpu-memory-utilization 0.8 \
    --port 8001 \
    --kv-transfer-config \
    '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}'

等待直到两个引擎都准备好。

向端口 8000 的引擎发送一个请求，

curl -X POST http://localhost:8000/v1/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "meta-llama/Meta-Llama-3.1-8B-Instruct",
        "prompt": "Explain the significance of KV cache in language models.",
        "max_tokens": 10
    }'

将相同的请求发送到端口 8001 的引擎。

curl -X POST http://localhost:8001/v1/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "meta-llama/Meta-Llama-3.1-8B-Instruct",
        "prompt": "Explain the significance of KV cache in language models.",
        "max_tokens": 10
    }'

第二个请求将自动从第一个实例中检索并重用 KV Cache，显著减少生成时间。

P2P KV Cache 共享#

本节演示如何通过点对点传输在多个 vLLM 实例之间共享 KV Cache。

配置 LMCache 实例#

为 P2P 共享设置创建两个配置文件。两个文件之间不同的值是 lmcache_instance_id 和 P2P/控制器端口分配。

实例 1 配置 (p2p_example1.yaml):

chunk_size: 256
local_cpu: true
max_local_cpu_size: 5
enable_async_loading: True

# P2P configurations
enable_p2p: true
p2p_host: "localhost"
p2p_init_ports: 8200
p2p_lookup_ports: 8201
transfer_channel: "nixl"

# Controller configurations
enable_controller: true
lmcache_instance_id: "lmcache_instance_1"
controller_pull_url: "localhost:8300"
controller_reply_url: "localhost:8400"
lmcache_worker_ports: 8500

extra_config:
  lookup_backoff_time: 0.001

实例 2 配置 (p2p_example2.yaml):

chunk_size: 256
local_cpu: true
max_local_cpu_size: 5
enable_async_loading: True

# P2P configurations
enable_p2p: true
p2p_host: "localhost"
p2p_init_ports: 8202
p2p_lookup_ports: 8203
transfer_channel: "nixl"

# Controller configurations
enable_controller: true
lmcache_instance_id: "lmcache_instance_2"
controller_pull_url: "localhost:8300"
controller_reply_url: "localhost:8400"
lmcache_worker_ports: 8501

extra_config:
  lookup_backoff_time: 0.001

将两个文件保存在您将挂载到容器中的目录中（稍后称为 $YAML_FILES）。

运行 P2P 共享工作流#

在主机上配置环境并在容器内打开一个 shell：

docker pull vllm/vllm-openai:latest
export WEIGHT_DIR="/models"          # model weights directory
export CONTAINER_NAME="lmcache_vllm" # container name
export YAML_FILES="/path/to/yaml"    # directory containing the YAML files
docker run --name "$CONTAINER_NAME" \
        --detach \
        --ipc=host \
        --network host \
        --gpus all \
        --volume "$WEIGHT_DIR:$WEIGHT_DIR" \
        --volume "$YAML_FILES:$YAML_FILES" \
        --entrypoint "/bin/bash" \
        vllm/vllm-openai:latest -c "time sleep 452d"
docker exec -it "$CONTAINER_NAME" /bin/bash
pip install -U lmcache # update lmcache to the latest version

启动 LMCache 控制器和监控端点：

PYTHONHASHSEED=123 lmcache_controller --host localhost --port 9000 --monitor-ports '{"pull": 8300, "reply": 8400}'

启动两个 vLLM 引擎，每个引擎都有自己的 LMCache 工作配置。

在 GPU 0 上启动 vLLM 引擎 1：

PYTHONHASHSEED=123 UCX_TLS=rc CUDA_VISIBLE_DEVICES=0 LMCACHE_CONFIG_FILE=p2p_example1.yaml \
vllm serve meta-llama/Meta-Llama-3.1-8B-Instruct \
    --gpu-memory-utilization 0.8 \
    --port 8010 \
    --kv-transfer-config '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}'

在 GPU 1 上启动 vLLM 引擎 2：

PYTHONHASHSEED=123 UCX_TLS=rc CUDA_VISIBLE_DEVICES=1 LMCACHE_CONFIG_FILE=p2p_example2.yaml \
vllm serve meta-llama/Meta-Llama-3.1-8B-Instruct \
    --gpu-memory-utilization 0.8 \
    --port 8011 \
    --kv-transfer-config '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}'

通过向第一个引擎发送请求来填充 KV Cache：

curl -X POST http://localhost:8010/v1/completions \
    -H "Content-Type: application/json" \
    -d "{
        \"model\": \"meta-llama/Meta-Llama-3.1-8B-Instruct\",
        \"prompt\": \"$(printf 'Explain the significance of KV cache in language models.%.0s' {1..100})\",
        \"max_tokens\": 10
    }"

将相同的请求发送到第二个引擎以演示缓存检索：

curl -X POST http://localhost:8011/v1/completions \
    -H "Content-Type: application/json" \
    -d "{
        \"model\": \"meta-llama/Meta-Llama-3.1-8B-Instruct\",
        \"prompt\": \"$(printf 'Explain the significance of KV cache in language models.%.0s' {1..100})\",
        \"max_tokens\": 10
    }"

预期输出#

当第二个请求成功从第一个实例检索到缓存时，日志应包含类似于以下内容的条目：

(EngineCore_DP0 pid=305) [2025-11-16 07:24:11,522] LMCache INFO: Got layout info from controller: ('lmcache_instance_2', 'LocalCPUBackend', 3, 'localhost:8202') (p2p_backend.py:196:lmcache.v1.storage_backend.p2p_backend)
(EngineCore_DP0 pid=305) [2025-11-16 07:24:11,607] LMCache INFO: Established connection to peer_init_url localhost:8202. The peer_lookup_url: localhost:8203 (p2p_backend.py:349:lmcache.v1.storage_backend.p2p_backend)
(EngineCore_DP0 pid=305) [2025-11-16 07:24:11,706] LMCache INFO: Responding to scheduler for lookup id cmpl-e9ec2875bf954bd298ca26d14e083b80-0 with retrieved length 768 (storage_manager.py:531:lmcache.v1.storage_backend.storage_manager)
(EngineCore_DP0 pid=305) [2025-11-16 07:24:11,708] LMCache INFO: Reqid: cmpl-e9ec2875bf954bd298ca26d14e083b80-0, Total tokens 1002, LMCache hit tokens: 768, need to load: 768 (vllm_v1_adapter.py:1330:lmcache.integration.vllm.vllm_v1_adapter)
(EngineCore_DP0 pid=305) [2025-11-16 07:24:11,724] LMCache INFO: Retrieved 768 out of 768 required tokens (from 768 total tokens). size: 0.0938 gb, cost 7.9816 ms, throughput: 11.7458 GB/s; (cache_engine.py:531:lmcache.v1.cache_engine)

这些日志表明对等连接已建立，并且缓存已成功传输。