LMCache 多进程模式部署指南:Docker 与 Kubernetes 实战、Isolated IPC 与生产调优

原创2026-09-15 19:17:062,315 阅读
文章标签:人工智能大模型缓存

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 真正提供的东西):

  1. KV 缓存内存共享:默认注册路径使用 PyTorch storage IPC,它会在 /dev/shm 中维护一个引用计数文件;
  2. 事件排序(每个 STORE/RETRIEVE 的设备事件):CUDA 跨进程 event 句柄只有在两个容器共享同一 /dev/shm tmpfs 时才能解析。

因此默认模式下,两个容器必须共享 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

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;limits 120Gi 内存、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 模式能稳定工作的前提。

登录后查看全文
LMCache