快速开始

本页介绍了快速启动 LMCache 多进程模式的几种方法——本地、在 Docker 中以及使用 HTTP 服务器变体。

本地快速开始

步骤 1：启动 LMCache 服务器

lmcache server \
    --l1-size-gb 100 --eviction-policy LRU

预期的日志输出：

LMCache INFO: LMCache cache server is running...

备注

默认的 ZMQ 端口是 **5555**（使用 --port 来更改）。HTTP 前端默认监听 **8080**（使用 --http-port 来更改）。

步骤 2：使用 LMCache 连接器启动 vLLM

在新的终端中：

vllm serve Qwen/Qwen3-14B \
    --kv-transfer-config \
    '{"kv_connector":"LMCacheMPConnector", "kv_role":"kv_both"}'

备注

这将连接到本地主机上的默认 LMCache 端口 (5555)。如果您使用 --port 更改了服务器端口，请通过 kv_connector_extra_config 在 vLLM 端传递它：

vllm serve Qwen/Qwen3-14B \
    --kv-transfer-config \
    '{"kv_connector":"LMCacheMPConnector", "kv_role":"kv_both", "kv_connector_extra_config": {"lmcache.mp.port": 6555}}'

要连接到远程主机，还需设置 lmcache.mp.host：

--kv-transfer-config \
'{"kv_connector":"LMCacheMPConnector", "kv_role":"kv_both", "kv_connector_extra_config": {"lmcache.mp.host": "10.0.0.1", "lmcache.mp.port": 6555}}'

您应该在 vLLM 端看到：

LMCache INFO: Registering kv caches!

在 LMCache 端：

LMCache INFO: Registered KV cache for GPU ID <pid> with 40 layers

步骤 3：发送请求

curl -X POST http://localhost:8000/v1/completions \
    -H "Content-Type: application/json" \
    -d "{
        \"model\": \"Qwen/Qwen3-14B\",
        \"prompt\": \"$(printf 'Explain the significance of KV cache in language models.%.0s' {1..100})\",
        \"max_tokens\": 10
    }"

第一次请求 -- 令牌被 存储：

LMCache INFO: Stored 768 tokens in 0.001 seconds

第二个相同的请求 -- 令牌从缓存中 检索：

LMCache INFO: Retrieved 768 tokens in 0.001 seconds

Docker 快速入门

步骤 1：启动 LMCache 容器

docker run --runtime nvidia --gpus all \
    --network host \
    --ipc host \
    lmcache/standalone:nightly \
    /opt/venv/bin/lmcache server \
    --l1-size-gb 60 --eviction-policy LRU --max-workers 4 --port 6555

备注

--network host 允许 vLLM 容器访问本地主机上的 LMCache 服务器。 --ipc host 是 CUDA IPC 共享内存所必需的。

步骤 2：启动 vLLM 容器

docker run --runtime nvidia --gpus all \
    --network host \
    --ipc host \
    lmcache/vllm-openai:latest-nightly \
    Qwen/Qwen3-14B \
    --kv-transfer-config \
    '{"kv_connector":"LMCacheMPConnector", "kv_role":"kv_both", "kv_connector_extra_config": {"lmcache.mp.port": 6555}}'

备注

使用夜间构建镜像（lmcache/standalone:nightly 和 lmcache/vllm-openai:latest-nightly），因为 MP 模式接口正在积极演进。

步骤 3：发送请求 与本地快速入门相同。

HTTP 服务器快速入门

HTTP 服务器使用 FastAPI 前端封装了 ZMQ 服务器，添加了用于健康检查和缓存管理的 HTTP 管理端点。

lmcache server \
    --l1-size-gb 100 --eviction-policy LRU

HTTP 服务器默认监听 0.0.0.0:8080``（可通过 ``--http-host 和 --http-port 进行配置）。

端点：

方法	路径	描述
获取	/healthcheck	当引擎初始化并且内存检查通过时，返回 {"status": "healthy"}。适用于 Kubernetes 的存活/就绪探针。
POST	/clear-cache	强制清除存储在 L1 (CPU) 内存中的所有 KV Cache 数据，包括具有活动读/写锁的对象。成功时返回 {\"status\": \"ok\"}。
获取	/status	返回所有 MP 组件的详细内部状态，包括 L1 缓存、L2 适配器、控制器、注册的 GPU 和活动会话。

示例：

# Health check
curl http://localhost:8080/healthcheck
# {"status": "healthy"}

# Clear all KV cache data in L1 (CPU) memory
curl -X POST http://localhost:8080/clear-cache
# {"status": "ok"}

# Inspect detailed internal state
curl http://localhost:8080/status

ZMQ 服务器在相同的默认端口（5555）上运行，并接受 vLLM 连接，正如本地快速入门中所示。

CPU-Only Quick Start

LMCache MP mode works on hosts without a GPU. The server runs with a StubCPUDevice and vLLM uses its CPU backend. KV tensors are shared between vLLM and the LMCache server via POSIX shared memory (zero-copy, no GPU required).

Step 1: Start the LMCache server (no GPU needed)

lmcache server \
    --l1-size-gb 2 --eviction-policy LRU --port 5555

预期的日志输出：

LMCache INFO: torch_dev=StubCPUDevice(device_type=cpu), ...
LMCache INFO: LMCache cache server is running...

Step 2: Start vLLM with the engine-driven transfer mode

Pass lmcache.mp.mp_transfer_mode=engine_driven in kv_connector_extra_config to enable the POSIX-SHM zero-copy path. At startup the vLLM worker migrates each KV cache tensor to a shared memory segment (/lmcache_kv_<pid>_<idx>) so the LMCache server can map the same physical pages directly.

vllm serve <model> --dtype bfloat16 \
    --disable-hybrid-kv-cache-manager \
    --no-enable-prefix-caching \
    --kv-transfer-config \
    '{"kv_connector": "LMCacheMPConnector",
      "kv_role": "kv_both",
      "kv_connector_module_path":
        "lmcache.integration.vllm.lmcache_mp_connector",
      "kv_connector_extra_config": {
        "lmcache.mp.host": "tcp://localhost",
        "lmcache.mp.port": 5555,
        "lmcache.mp.mp_transfer_mode": "engine_driven"
      }}'

Expected log output on the vLLM side:

LMCache INFO: lmcache.mp.mp_transfer_mode = engine_driven (overridden, ...)
LMCache INFO: Creating transfer context (device_type=cpu, mode=engine_driven)
LMCache INFO: Migrated CPU KV cache tensor (nbytes=...) to SHM /lmcache_kv_...

步骤 3：发送请求 与本地快速入门相同。

备注

The default auto transfer mode routes CPU tensors to the lmcache_driven path (worker-side gather/scatter). Use mp_transfer_mode=engine_driven explicitly to get the zero-copy SHM path described above.