LMCache 多进程模式部署指南:Docker 与 Kubernetes 实战、Isolated IPC 与生产调优
LMCache 多进程模式部署指南:Docker 与 Kubernetes 实战、Isolated IPC 与生产调优
本文围绕 LMCache 多进程(MP)模式在生产环境的部署展开,完整覆盖 Docker 容器编排、Kubernetes 的 DaemonSet + Deployment 部署模式、CUDA IPC 在容器间的数据共享原理(含 Isolated IPC 无共享 /dev/shm 方案)、健康检查与监控集成,以及 worker 线程池、L1 容量、驱逐策略、传输模式等生产最佳实践。读完本文,你将能够独立规划并落地一套 LMCache + vLLM 的多进程 KV Cache 服务,并在不同网络/IPC 约束下选择正确的部署形态。
部署全景:一套缓存服务,两种编排路径
LMCache 多进程模式把 KV Cache 服务拆成两个角色:一个常驻的 LMCache MP server(负责 L1 缓存、L2 后端读写、驱逐与查询)和若干 引擎 worker(vLLM 等推理引擎的进程)。部署的核心工作就是让这两类进程在容器或 Pod 中互相连通,并让 GPU 上的 KV 张量能够跨进程共享。
- Docker 场景:LMCache server 与 vLLM 各起一个容器,通过
--network host让 vLLM 在 localhost 上访问 LMCache。 - Kubernetes 场景:官方推荐 DaemonSet + Deployment 模式——每节点一个 LMCache server(DaemonSet),同节点多个 vLLM Pod(Deployment)共享这一个缓存实例,示例清单位于 examples/multi_process/。
两条路径下,容器/Pod 之间的 CUDA IPC 共享与 事件同步是决定部署形态的关键变量,也是 Isolated IPC 这一新机制要解决的问题。
Docker 部署:双容器编排
启动 LMCache 独立服务容器
使用官方 standalone 镜像启动 LMCache MP server,命令如下:
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
参数含义:
--l1-size-gb 60:L1 层(CPU 侧缓存)容量,60 GB;--eviction-policy LRU:L1 驱逐策略使用 LRU(其他可选IsolatedLRU、noop);--max-workers 4:worker 线程数(同时设定 GPU 亲和池与 CPU 普通池的大小,默认 1);--port 6555:ZMQ 服务监听端口(默认 5555),vLLM 侧需与之对齐。
从源码看,lmcache server 入口会组装一个 MPCacheServer 组合器,将 LMCacheDrivenTransferModule、EngineDrivenTransferModule、LookupModule、ManagementModule 等可插拔引擎模块装配进共享的 MPCacheServerContext,统一管理存储、会话与健康状态——这也是部署时无需再额外启动其他进程的原因。
启动 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}}'
vLLM 侧的关键是 --kv-transfer-config:
kv_connector固定为LMCacheMPConnector;kv_role取kv_both(同时承担 KV 写入与读取);kv_connector_extra_config中以lmcache.mp.前缀传递连接参数。此处只写了lmcache.mp.port,由于容器使用--network host,LMCache 默认监听 localhost,因此可以省略lmcache.mp.host。
三个必需的 Docker 标志
| 标志 | 作用 |
|---|---|
--network host |
让 vLLM 容器通过 localhost 直接访问 LMCache 服务 |
--ipc host |
默认(legacy)模式下,CUDA IPC 共享内存传输依赖共享的 /dev/shm tmpfs,该标志正是提供这一共享命名空间的前提 |
--runtime nvidia --gpus all |
通过 NVIDIA container runtime 获得 GPU 访问能力 |
其中 --ipc host 在启用 Isolated IPC 后可以去掉,详见下文。
HTTP 服务入口变体
容器编排场景(尤其是 Kubernetes 探针与缓存管理 API)建议使用 HTTP server 入口。LMCache MP server 内置 FastAPI/uvicorn 前端(默认绑定 0.0.0.0:8080),提供 /healthcheck、缓存管理、配额等 HTTP 接口,启动命令与上面相同(lmcache server ...),无需额外参数,--http-host / --http-port 可自定义绑定。
Isolated IPC:无需共享 /dev/shm 的部署
为什么默认模式依赖 /dev/shm
CUDA IPC 在 MP 模式下有两条“腿”,默认情况下都依赖共享的 /dev/shm tmpfs(这正是 --ipc host / hostIPC: true 真正提供的东西):
- KV 缓存内存共享:默认注册路径使用 PyTorch storage IPC,它会在
/dev/shm中维护一个引用计数文件; - 事件排序(每个 STORE/RETRIEVE 的设备事件):CUDA 跨进程 event 句柄只有在两个容器共享同一
/dev/shmtmpfs 时才能解析。
因此默认模式下,两个容器必须共享 host 的 IPC 命名空间,这在安全和多租户隔离要求较高的场景下并不理想。
Isolated IPC 如何工作
Isolated IPC 同时移除上述两条依赖:
- KV 缓存注册改用 raw CUDA IPC 内存句柄(设计文档:ipc_wrapper.md);
- 事件排序改用承载于 CUDA IPC 内存句柄之上的 timeline-semaphore 事件(设计文档:timeline_semaphore_event_ipc.md)。
两者的会合(rendezvous)都在内核驱动层完成,因此可以跨越“互不共享任何东西”的容器工作——无需 host IPC 命名空间、无需公共 /dev/shm、无需 --ipc host。
它必须在部署的两侧同时启用:
# LMCache server
lmcache server --isolated-ipc --l1-size-gb 60 --eviction-policy LRU
# 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.isolated_ipc": true}}'
对应关系:server 侧 CLI 标志为 --isolated-ipc(定义于 lmcache/v1/multiprocess/config.py 的 MP server 参数组),vLLM 侧为 kv_connector_extra_config 中的 lmcache.mp.isolated_ipc。
半开部署的失败模式
两种事件机制交换的是不兼容的句柄,因此只在一侧启用会“响亮地失败”(fail loudly):
- 事件导入阶段即报错:vLLM 侧立刻崩溃;
- server 侧记录错误日志,对应 worker 在
lmcache.mp.mq_timeout(默认 300 秒)超时后被判定为失效。
部署前务必核对两侧配置一致。
启用后的运维变化与当前限制
当两侧都启用 Isolated IPC 后,MP 数据路径不再依赖 /dev/shm:
- Docker 中可去掉
--ipc host; - Kubernetes 中可去掉
hostIPC: true与共享/dev/shm挂载; - 两个容器只需能访问同一批 GPU 且拥有不同的 PID 值(任何常规容器配置都满足)。
Kubernetes Operator 在 NVIDIA 平台上默认就接线 Isolated IPC(spec.isolatedIPC,详见 operator.rst)。
当前限制(部署前必须评估):
| 限制 | 说明 |
|---|---|
| 仅 vLLM MP connector 支持 | SGLang、TensorRT-LLM、CacheBlend、qstore 仍创建 raw CUDA 跨进程事件,要求保持 Isolated IPC 关闭(默认值) |
KV 张量必须在 cudaMalloc 风格内存中 |
CUDA VMM 分配没有 IPC 内存句柄,因此 PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True 和 vLLM 的 sleep 模式(CuMemAllocator)与 Isolated IPC 不兼容,注册时会报出带说明的错误 |
两侧都需要 cuda-python 包 |
该依赖已包含在 CUDA 需求文件中(见 requirements/cuda.txt) |
Kubernetes:DaemonSet + Deployment 模式
LMCache 针对 Kubernetes 设计为 每节点一个 server(DaemonSet)+ 每节点多个 vLLM Pod(Deployment) 的模式:所有同节点 vLLM Pod 自动连接同一个 LMCache DaemonSet 实例。示例 YAML 位于 examples/multi_process/。
前置条件
- 带 GPU 支持的 Kubernetes 集群(已安装 NVIDIA GPU Operator);
- 每节点至少 4 张 GPU(对应示例中
tensor-parallel-size 4); kubectl已正确配置可访问集群。
Step 1:创建命名空间
kubectl create namespace multi-process
Step 2:部署 LMCache DaemonSet
kubectl apply -f examples/multi_process/lmcache-daemonset.yaml
hostNetwork: true:vLLM Pod 通过status.hostIP发现 LMCache server;- 挂载宿主机
/dev/shm(默认 legacy 模式的 CUDA IPC 前提,启用 Isolated IPC 后可移除); - 启动命令等价于
python3 -m lmcache.v1.multiprocess.server --host 0.0.0.0 --port 6555 --l1-size-gb 60 --eviction-policy LRU --max-workers 4; - 资源规划参考:requests
65Gi内存(60 GB L1 + 约 5 GB Python 运行时与 server 操作开销)、4 CPU;limits120Gi内存、8 CPU; - 注意:DaemonSet 不请求 GPU——这是有意为之,让 GPU 被 vLLM Pod 独占,NVIDIA container runtime 会为 IPC 内存传输自动提供 GPU 访问能力;
- 示例将
LMCACHE_LOG_LEVEL设为DEBUG便于排查,生产可改回INFO。
Step 3:部署 vLLM
kubectl apply -f examples/multi_process/vllm-deployment.yaml
vllm-deployment.yaml 的关键设计:
- 默认模型
Qwen/Qwen3-14B,tensor-parallel-size 4(对应每节点 4 张 GPU); - 通过 Downward API 把
status.hostIP注入环境变量HOST_IP,再以lmcache.mp.host: tcp://${HOST_IP}传给 connector; - 挂载宿主机
/dev/shm以支持默认模式下的 CUDA IPC; - 设置
PYTHONHASHSEED=0保证跨进程哈希可复现(对应--hash-algorithm builtin场景); - 设置
PROMETHEUS_MULTIPROC_DIR=/tmp支持多进程 Prometheus 指标聚合; - 自带
startupProbe(/health,端口 8000)。
若使用 Llama 等 gated 模型,先创建包含 Hugging Face token 的 Secret,再把
HF_TOKEN环境变量加入 vLLM 容器 spec:kubectl create secret generic vllm-secrets \ --from-literal=hf_token=your_hf_token_here \ -n multi-process
Step 4:监控部署状态
# DaemonSet 状态
kubectl get daemonset -n multi-process
kubectl get pods -n multi-process -l app=lmcache-server
# vLLM 状态
kubectl get pods -n multi-process -l app=vllm-deployment -w
# 定位 vLLM Pod 所在节点,并查看该节点上 LMCache 的日志
VLLM_NODE=$(kubectl get pod -n multi-process -l app=vllm-deployment \
-o jsonpath='{.items[0].spec.nodeName}')
LMCACHE_POD=$(kubectl get pod -n multi-process -l app=lmcache-server \
--field-selector spec.nodeName=$VLLM_NODE \
-o jsonpath='{.items[0].metadata.name}')
kubectl logs -n multi-process $LMCACHE_POD -f
Step 5:发送测试请求
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\": \"$(printf 'Explain the significance of KV cache in language models.%.0s' {1..100})\",
\"max_tokens\": 10
}"
用 100 段重复长 prompt 构造前缀复用场景,可直观验证缓存命中后的加速效果。
架构要点与预期行为
- DaemonSet 使用
hostNetwork: true,vLLM Pod 通过status.hostIP发现 LMCache server; - 两个容器都挂载宿主机
/dev/shm(默认 legacy 模式所需;Isolated IPC 下可移除); - DaemonSet 不请求 GPU,让 GPU 被 vLLM Pod 独占;
- 同节点多个 vLLM Pod 自动连接同一个 LMCache DaemonSet 实例;
- 无 GPU 节点上的 LMCache Pod 会因 CUDA 初始化失败而崩溃——这是预期行为,LMCache 只需运行在 vLLM Pod 被调度到的 GPU 节点上,可用 nodeSelector 约束。
健康检查(HTTP Server)
Kubernetes 探针请使用 HTTP server 变体,调用 /healthcheck 端点:
livenessProbe:
httpGet:
path: /healthcheck
port: 8080
initialDelaySeconds: 10
periodSeconds: 30
readinessProbe:
httpGet:
path: /healthcheck
port: 8080
initialDelaySeconds: 5
periodSeconds: 10
监控集成
Prometheus 指标默认在 9090 端口启用。为 LMCache DaemonSet Pod 添加 ServiceMonitor 或 Prometheus scrape 注解即可采集指标;各指标与日志、追踪的详细说明见 observability/index.rst。
清理
kubectl delete -f examples/multi_process/vllm-deployment.yaml
kubectl delete -f examples/multi_process/lmcache-daemonset.yaml
kubectl delete namespace multi-process
进阶:Operator 替代手工清单
手工 DaemonSet 方案可行,但存在不少“锐边”:跨 Pod CUDA IPC 接线错误会引发难以排查的 cudaErrorMapBufferObjectFailed、内存资源容易配多配少、服务发现依赖 hostNetwork 与 Downward API。LMCache 的 Kubernetes Operator(见 operator.rst)把这一切声明式化:只需定义一个 LMCacheEngine 自定义资源,Operator 即自动完成 IPC 接线(NVIDIA 平台默认 Isolated IPC)、internalTrafficPolicy=Local 的节点本地服务发现、基于 l1.sizeGB 的自动资源计算、声明式 ServiceMonitor 与 CRD 校验。
生产最佳实践
Worker 线程池(--max-workers / --max-gpu-workers / --max-cpu-workers)
--max-workers同时设定 GPU 亲和池与 CPU 普通池的大小,默认 1;--max-gpu-workers独立覆盖 GPU 池:建议至少设为共享该缓存服务的 vLLM 实例数,让每个实例获得专用线程——同一 vLLM 实例的请求总是派发到同一线程,消除 GPU 传输锁竞争;--max-cpu-workers独立覆盖 CPU 池,用于 LOOKUP 等非 GPU 操作。
L1 内存容量(--l1-size-gb)
在扣除操作系统与 vLLM 占用后,把尽可能多的 CPU 内存分配给 L1。L1 越大,L2 round-trip 越少,缓存命中收益越高。注意与 vLLM 的 gpu-memory-utilization 一起规划整机内存。
驱逐调优
--eviction-trigger-watermark 0.8(默认):L1 使用率达到 80% 时触发驱逐;--eviction-ratio 0.2(默认):每次驱逐周期释放已分配内存的 20%;- 若稳定负载下频繁驱逐,可调低 watermark 或调大 ratio(例如 configuration.rst 中的全量示例使用了
0.9/0.1组合,适合内存充足、希望减少驱逐频率的场景)。
日志
- 初始搭建阶段用
LMCACHE_LOG_LEVEL=DEBUG验证 L2 store/load 活动与预取结果; - 生产环境切回默认
INFO降低日志量。
传输模式与 SHM:--supported-transfer-mode / --shm-name
LMCache 支持两条 worker → server 的 KV 传输路径:
| 路径 | 驱动方 | 适用 |
|---|---|---|
| lmcache-driven | server 通过 CUDA IPC 或 CPU SHM 主动拉/推 | STORE/RETRIEVE,覆盖 CUDA 设备(IPC)与 CPU 设备(SHM) |
| engine-driven | 引擎 worker 侧 gather/scatter 拷贝 | PREPARE/COMMIT,用于 CPU-only 或非 CUDA 加速器 worker |
server 通过 --supported-transfer-mode 决定加载哪些路径:
lmcache_driven(默认):只加载 server 驱动路径,支持 CUDA(IPC)与 CPU(SHM)设备,并跳过 engine-driven 的 prepare/commit 资源(pickle codec)分配;engine_driven:只加载 engine 驱动路径,用于服务 CPU-only 或非 CUDA 加速器 worker;auto:两条路径都加载,任意设备类型的 worker 无需手动配置即可连接——server 启动时并不预先知道来连接的 worker 是什么设备。
当 engine-driven 路径被加载(auto 或 engine_driven)时,默认使用 pickle 路径传输 KV。传入 --shm-name 可改用共享内存(SHM)池:
--shm-name 值 |
效果 |
|---|---|
""(空字符串,默认) |
不建 SHM 池,KV 传输走 pickle 路径。适用于 /dev/shm 不可用或 Docker 中不带 --ipc host 的场景 |
"my_pool"(任意非空名) |
以该精确段名创建 SHM 池并用于 KV 传输。确定性、可读的段名也便于监控与调试 |
示例:
# Engine-driven 路径 + pickle 传输(无 SHM)——默认行为:
lmcache server --l1-size-gb 60 --eviction-policy LRU \
--supported-transfer-mode engine_driven
# Engine-driven 路径 + 命名 SHM 段:
lmcache server --l1-size-gb 60 --eviction-policy LRU \
--supported-transfer-mode engine_driven --shm-name "lmcache_pool"
与此对应,vLLM 侧可通过 lmcache.mp.mp_transfer_mode 在 auto / lmcache_driven / engine_driven 间选择 worker → server 传输上下文的走法(auto 下 CUDA 走 lmcache_driven、其余走 engine_driven),并可用 LMCACHE_MP_TRANSFER_MODE 环境变量兜底。
从源码理解部署时的行为边界
- server 组合器:
lmcache server实际装配的是 MPCacheServer 及其引擎模块列表(见 server.py 的_build_modules),部署时无需关心模块细节,但了解其结构有助于阅读report_status()聚合出的健康信息(存储管理器状态、活动会话数、chunk 大小、哈希算法等); - 参数族:
--isolated-ipc、--supported-transfer-mode、--shm-name、--max-*-workers等均注册在 config.py 的 MP server 参数组,完整的参数表(含默认值与取值范围)可查阅 configuration.rst; - DaemonSet 资源规划:示例中 60 GB L1 对应 requests
65Gi内存,这一“L1 + 运行开销”的估算方式可直接迁移到其他容量规划中。
最后提醒一点:LMCache Pod 在无 GPU 节点上崩溃是预期行为;多进程模式依赖 CUDA 环境,所有 LMCache server 都应只调度到承载 vLLM 的 GPU 节点上,这是 DaemonSet + Deployment 模式能稳定工作的前提。