LMCache 为 LLM 推理引擎设计的 KV 缓存管理中间层，加速推理并降低延迟（TTFT）

LMCache 是一个为 LLM 推理引擎设计的 KV 缓存管理中间层，它的核心作用是加速推理并降低延迟（TTFT）。部署 LMCache 的关键在于让它和推理引擎（如 vLLM）正确通信。

目前官方主推的是多进程（MP）模式，下面这份指南会围绕它的 Docker 和 Kubernetes 部署展开。

核心概念：多进程（MP）模式

在这种模式下，LMCache 不再作为推理引擎的附属进程，而是独立的守护进程运行。这样做有几个好处：

进程隔离：推理引擎崩溃不会导致缓存丢失。
资源独立：可以为 LMCache 单独分配 CPU 和内存资源。
易于扩展：在 Kubernetes 中，它可以作为 DaemonSet 部署，供同一节点上的所有推理 Pod 共享。

方案一：Docker 部署（快速验证）

如果你想先在本机快速测试，Docker 是最直接的方式。核心是启动两个容器，并让它们通过 --ipc host 共享内存。

1. 启动 LMCache 服务器
这条命令会启动一个独立的 LMCache 进程，管理 60GB 的缓存空间。

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

2. 启动 vLLM 并连接 LMCache
这里需要添加 --kv-transfer-config 参数，通过 LMCacheMPConnector 让 vLLM 把 KV 缓存交给 LMCache 管理。

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}}'

关键参数说明：

--network host：让 vLLM 能通过 localhost 访问到 LMCache 服务。
--ipc host：这是必须的，用于容器间通过 CUDA IPC 进行共享内存传输。

方案二：Kubernetes 部署（生产推荐）

在生产环境（如 Kubernetes 集群）中，官方推荐 DaemonSet + Deployment 的架构：

DaemonSet：在每个节点上运行一个 LMCache 实例，作为该节点的缓存服务。
Deployment：部署 vLLM 推理服务，每个 Pod 会自动连接到其所在节点的 LMCache。

1. 前提条件

一个支持 GPU 的 Kubernetes 集群。
已安装 NVIDIA GPU Operator。
节点上建议至少有 4 块 GPU。

2. 快速部署步骤
你可以直接使用项目 examples/multi_process/ 目录下的 YAML 文件进行部署。

# 1. 创建命名空间
kubectl create namespace multi-process

# 2. 部署 LMCache DaemonSet
kubectl apply -f examples/multi_process/lmcache-daemonset.yaml

# 3. 部署 vLLM Deployment
kubectl apply -f examples/multi_process/vllm-deployment.yaml

3. 监控与验证
部署后，你需要确认服务是否正常连接。

# 查看 Pod 状态，确保 Running
kubectl get pods -n multi-process

# 转发端口，发送测试请求
kubectl port-forward -n multi-process deployment/vllm-deployment 8000:8000

curl -X POST http://localhost:8000/v1/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "Qwen/Qwen3-14B",
        "prompt": "Explain the significance of KV cache in language models.",
        "max_tokens": 50
    }'

如何确认缓存生效？
连续发送两次完全相同的长提示词（prompt），然后查看 LMCache 的日志。如果看到缓存命中的相关记录，说明配置成功。

部署要点与排错

无论选择哪种方式，以下几点都值得留意：

共享内存是核心：--ipc host 和挂载 /dev/shm 是保证 GPU 显存间高效传输的关键，不能省略。
端口配置：默认的 --port 6555 如果被占用，可以在启动 LMCache 时修改，并同步更新 vLLM 的 kv_transfer_config 中的端口号。
模型兼容性：对于 DeepSeek-V4-Flash 这类特殊模型，需要遵循特定的 vLLM 安装和启动指南（例如，锁定 vLLM 正式版本，使用 --kv-cache-dtype fp8_ds_mla 参数）。
Kubernetes 部署的常见问题：LMCache DaemonSet 在不含 GPU 的节点上启动会报 CUDA 错误，这是正常现象，因为它只需要运行在 GPU 节点上。另外，确保 vLLM Pod 与 LMCache DaemonSet 在同一节点，它们通过 hostNetwork 自动发现。