LMCache 多进程模式部署指南Docker 与 Kubernetes 实战、Isolated IPC 与生产调优【免费下载链接】LMCacheLMCache: Supercharge Your LLM with the Fastest KV Cache Layer项目地址: https://gitcode.com/GitHub_Trending/lm/LMCache本文围绕 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 后端读写、驱逐与查询和若干引擎 workervLLM 等推理引擎的进程。部署的核心工作就是让这两类进程在容器或 Pod 中互相连通并让 GPU 上的 KV 张量能够跨进程共享。Docker 场景LMCache server 与 vLLM 各起一个容器通过--network host让 vLLM 在 localhost 上访问 LMCache。Kubernetes 场景官方推荐DaemonSet Deployment模式——每节点一个 LMCache serverDaemonSet同节点多个 vLLM PodDeployment共享这一个缓存实例示例清单位于 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 60L1 层CPU 侧缓存容量60 GB--eviction-policy LRUL1 驱逐策略使用 LRU其他可选IsolatedLRU、noop--max-workers 4worker 线程数同时设定 GPU 亲和池与 CPU 普通池的大小默认 1--port 6555ZMQ 服务监听端口默认 5555vLLM 侧需与之对齐。从源码看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-configkv_connector固定为LMCacheMPConnectorkv_role取kv_both同时承担 KV 写入与读取kv_connector_extra_config中以lmcache.mp.前缀传递连接参数。此处只写了lmcache.mp.port由于容器使用--network hostLMCache 默认监听 localhost因此可以省略lmcache.mp.host。三个必需的 Docker 标志标志作用--network host让 vLLM 容器通过 localhost 直接访问 LMCache 服务--ipc host默认legacy模式下CUDA IPC 共享内存传输依赖共享的/dev/shmtmpfs该标志正是提供这一共享命名空间的前提--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/shmCUDA IPC 在 MP 模式下有两条“腿”默认情况下都依赖共享的/dev/shmtmpfs这正是--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/shmDocker 中可去掉--ipc hostKubernetes 中可去掉hostIPC: true与共享/dev/shm挂载两个容器只需能访问同一批 GPU 且拥有不同的 PID值任何常规容器配置都满足。Kubernetes Operator 在 NVIDIA 平台上默认就接线 Isolated IPCspec.isolatedIPC详见 operator.rst。当前限制部署前必须评估限制说明仅 vLLM MP connector 支持SGLang、TensorRT-LLM、CacheBlend、qstore 仍创建 raw CUDA 跨进程事件要求保持 Isolated IPC 关闭默认值KV 张量必须在cudaMalloc风格内存中CUDA VMM 分配没有 IPC 内存句柄因此PYTORCH_CUDA_ALLOC_CONFexpandable_segments:True和 vLLM 的 sleep 模式CuMemAllocator与 Isolated IPC 不兼容注册时会报出带说明的错误两侧都需要cuda-python包该依赖已包含在 CUDA 需求文件中见 requirements/cuda.txtKubernetesDaemonSet Deployment 模式LMCache 针对 Kubernetes 设计为每节点一个 serverDaemonSet 每节点多个 vLLM PodDeployment的模式所有同节点 vLLM Pod 自动连接同一个 LMCache DaemonSet 实例。示例 YAML 位于 examples/multi_process/。前置条件带 GPU 支持的 Kubernetes 集群已安装 NVIDIA GPU Operator每节点至少 4 张 GPU对应示例中tensor-parallel-size 4kubectl已正确配置可访问集群。Step 1创建命名空间kubectl create namespace multi-processStep 2部署 LMCache DaemonSetkubectl apply -f examples/multi_process/lmcache-daemonset.yamllmcache-daemonset.yaml 的要点hostNetwork: truevLLM 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资源规划参考requests65Gi内存60 GB L1 约 5 GB Python 运行时与 server 操作开销、4 CPUlimits120Gi内存、8 CPU注意DaemonSet 不请求 GPU——这是有意为之让 GPU 被 vLLM Pod 独占NVIDIA container runtime 会为 IPC 内存传输自动提供 GPU 访问能力示例将LMCACHE_LOG_LEVEL设为DEBUG便于排查生产可改回INFO。Step 3部署 vLLMkubectl apply -f examples/multi_process/vllm-deployment.yamlvllm-deployment.yaml 的关键设计默认模型Qwen/Qwen3-14Btensor-parallel-size 4对应每节点 4 张 GPU通过 Downward API 把status.hostIP注入环境变量HOST_IP再以lmcache.mp.host: tcp://${HOST_IP}传给 connector挂载宿主机/dev/shm以支持默认模式下的 CUDA IPC设置PYTHONHASHSEED0保证跨进程哈希可复现对应--hash-algorithm builtin场景设置PROMETHEUS_MULTIPROC_DIR/tmp支持多进程 Prometheus 指标聚合自带startupProbe/health端口 8000。若使用 Llama 等 gated 模型先创建包含 Hugging Face token 的 Secret再把HF_TOKEN环境变量加入 vLLM 容器 speckubectl create secret generic vllm-secrets \ --from-literalhf_tokenyour_hf_token_here \ -n multi-processStep 4监控部署状态# DaemonSet 状态 kubectl get daemonset -n multi-process kubectl get pods -n multi-process -l applmcache-server # vLLM 状态 kubectl get pods -n multi-process -l appvllm-deployment -w # 定位 vLLM Pod 所在节点并查看该节点上 LMCache 的日志 VLLM_NODE$(kubectl get pod -n multi-process -l appvllm-deployment \ -o jsonpath{.items[0].spec.nodeName}) LMCACHE_POD$(kubectl get pod -n multi-process -l applmcache-server \ --field-selector spec.nodeName$VLLM_NODE \ -o jsonpath{.items[0].metadata.name}) kubectl logs -n multi-process $LMCACHE_POD -fStep 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: truevLLM 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 ServerKubernetes 探针请使用 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、internalTrafficPolicyLocal的节点本地服务发现、基于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_LEVELDEBUG验证 L2 store/load 活动与预取结果生产环境切回默认INFO降低日志量。传输模式与 SHM--supported-transfer-mode/--shm-nameLMCache 支持两条 worker → server 的 KV 传输路径路径驱动方适用lmcache-drivenserver 通过 CUDA IPC 或 CPU SHM 主动拉/推STORE/RETRIEVE覆盖 CUDA 设备IPC与 CPU 设备SHMengine-driven引擎 worker 侧 gather/scatter 拷贝PREPARE/COMMIT用于 CPU-only 或非 CUDA 加速器 workerserver 通过--supported-transfer-mode决定加载哪些路径lmcache_driven默认只加载 server 驱动路径支持 CUDAIPC与 CPUSHM设备并跳过 engine-driven 的 prepare/commit 资源pickle codec分配engine_driven只加载 engine 驱动路径用于服务 CPU-only 或非 CUDA 加速器 workerauto两条路径都加载任意设备类型的 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.rstDaemonSet 资源规划示例中 60 GB L1 对应 requests65Gi内存这一“L1 运行开销”的估算方式可直接迁移到其他容量规划中。最后提醒一点LMCache Pod 在无 GPU 节点上崩溃是预期行为多进程模式依赖 CUDA 环境所有 LMCache server 都应只调度到承载 vLLM 的 GPU 节点上这是 DaemonSet Deployment 模式能稳定工作的前提。【免费下载链接】LMCacheLMCache: Supercharge Your LLM with the Fastest KV Cache Layer项目地址: https://gitcode.com/GitHub_Trending/lm/LMCache创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 LMCache 多进程模式部署指南：Docker 与 Kubernetes 实战、Isolated IPC 与生产调优
LMCache 多进程模式部署指南Docker 与 Kubernetes 实战、Isolated IPC 与生产调优【免费下载链接】LMCacheLMCache: Supercharge Your LLM with the Fastest KV Cache Layer项目地址: https://gitcode.com/GitHub_Trending/lm/LMCache本文围绕 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 后端读写、驱逐与查询和若干引擎 workervLLM 等推理引擎的进程。部署的核心工作就是让这两类进程在容器或 Pod 中互相连通并让 GPU 上的 KV 张量能够跨进程共享。Docker 场景LMCache server 与 vLLM 各起一个容器通过--network host让 vLLM 在 localhost 上访问 LMCache。Kubernetes 场景官方推荐DaemonSet Deployment模式——每节点一个 LMCache serverDaemonSet同节点多个 vLLM PodDeployment共享这一个缓存实例示例清单位于 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 60L1 层CPU 侧缓存容量60 GB--eviction-policy LRUL1 驱逐策略使用 LRU其他可选IsolatedLRU、noop--max-workers 4worker 线程数同时设定 GPU 亲和池与 CPU 普通池的大小默认 1--port 6555ZMQ 服务监听端口默认 5555vLLM 侧需与之对齐。从源码看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-configkv_connector固定为LMCacheMPConnectorkv_role取kv_both同时承担 KV 写入与读取kv_connector_extra_config中以lmcache.mp.前缀传递连接参数。此处只写了lmcache.mp.port由于容器使用--network hostLMCache 默认监听 localhost因此可以省略lmcache.mp.host。三个必需的 Docker 标志标志作用--network host让 vLLM 容器通过 localhost 直接访问 LMCache 服务--ipc host默认legacy模式下CUDA IPC 共享内存传输依赖共享的/dev/shmtmpfs该标志正是提供这一共享命名空间的前提--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/shmCUDA IPC 在 MP 模式下有两条“腿”默认情况下都依赖共享的/dev/shmtmpfs这正是--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/shmDocker 中可去掉--ipc hostKubernetes 中可去掉hostIPC: true与共享/dev/shm挂载两个容器只需能访问同一批 GPU 且拥有不同的 PID值任何常规容器配置都满足。Kubernetes Operator 在 NVIDIA 平台上默认就接线 Isolated IPCspec.isolatedIPC详见 operator.rst。当前限制部署前必须评估限制说明仅 vLLM MP connector 支持SGLang、TensorRT-LLM、CacheBlend、qstore 仍创建 raw CUDA 跨进程事件要求保持 Isolated IPC 关闭默认值KV 张量必须在cudaMalloc风格内存中CUDA VMM 分配没有 IPC 内存句柄因此PYTORCH_CUDA_ALLOC_CONFexpandable_segments:True和 vLLM 的 sleep 模式CuMemAllocator与 Isolated IPC 不兼容注册时会报出带说明的错误两侧都需要cuda-python包该依赖已包含在 CUDA 需求文件中见 requirements/cuda.txtKubernetesDaemonSet Deployment 模式LMCache 针对 Kubernetes 设计为每节点一个 serverDaemonSet 每节点多个 vLLM PodDeployment的模式所有同节点 vLLM Pod 自动连接同一个 LMCache DaemonSet 实例。示例 YAML 位于 examples/multi_process/。前置条件带 GPU 支持的 Kubernetes 集群已安装 NVIDIA GPU Operator每节点至少 4 张 GPU对应示例中tensor-parallel-size 4kubectl已正确配置可访问集群。Step 1创建命名空间kubectl create namespace multi-processStep 2部署 LMCache DaemonSetkubectl apply -f examples/multi_process/lmcache-daemonset.yamllmcache-daemonset.yaml 的要点hostNetwork: truevLLM 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资源规划参考requests65Gi内存60 GB L1 约 5 GB Python 运行时与 server 操作开销、4 CPUlimits120Gi内存、8 CPU注意DaemonSet 不请求 GPU——这是有意为之让 GPU 被 vLLM Pod 独占NVIDIA container runtime 会为 IPC 内存传输自动提供 GPU 访问能力示例将LMCACHE_LOG_LEVEL设为DEBUG便于排查生产可改回INFO。Step 3部署 vLLMkubectl apply -f examples/multi_process/vllm-deployment.yamlvllm-deployment.yaml 的关键设计默认模型Qwen/Qwen3-14Btensor-parallel-size 4对应每节点 4 张 GPU通过 Downward API 把status.hostIP注入环境变量HOST_IP再以lmcache.mp.host: tcp://${HOST_IP}传给 connector挂载宿主机/dev/shm以支持默认模式下的 CUDA IPC设置PYTHONHASHSEED0保证跨进程哈希可复现对应--hash-algorithm builtin场景设置PROMETHEUS_MULTIPROC_DIR/tmp支持多进程 Prometheus 指标聚合自带startupProbe/health端口 8000。若使用 Llama 等 gated 模型先创建包含 Hugging Face token 的 Secret再把HF_TOKEN环境变量加入 vLLM 容器 speckubectl create secret generic vllm-secrets \ --from-literalhf_tokenyour_hf_token_here \ -n multi-processStep 4监控部署状态# DaemonSet 状态 kubectl get daemonset -n multi-process kubectl get pods -n multi-process -l applmcache-server # vLLM 状态 kubectl get pods -n multi-process -l appvllm-deployment -w # 定位 vLLM Pod 所在节点并查看该节点上 LMCache 的日志 VLLM_NODE$(kubectl get pod -n multi-process -l appvllm-deployment \ -o jsonpath{.items[0].spec.nodeName}) LMCACHE_POD$(kubectl get pod -n multi-process -l applmcache-server \ --field-selector spec.nodeName$VLLM_NODE \ -o jsonpath{.items[0].metadata.name}) kubectl logs -n multi-process $LMCACHE_POD -fStep 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: truevLLM 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 ServerKubernetes 探针请使用 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、internalTrafficPolicyLocal的节点本地服务发现、基于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_LEVELDEBUG验证 L2 store/load 活动与预取结果生产环境切回默认INFO降低日志量。传输模式与 SHM--supported-transfer-mode/--shm-nameLMCache 支持两条 worker → server 的 KV 传输路径路径驱动方适用lmcache-drivenserver 通过 CUDA IPC 或 CPU SHM 主动拉/推STORE/RETRIEVE覆盖 CUDA 设备IPC与 CPU 设备SHMengine-driven引擎 worker 侧 gather/scatter 拷贝PREPARE/COMMIT用于 CPU-only 或非 CUDA 加速器 workerserver 通过--supported-transfer-mode决定加载哪些路径lmcache_driven默认只加载 server 驱动路径支持 CUDAIPC与 CPUSHM设备并跳过 engine-driven 的 prepare/commit 资源pickle codec分配engine_driven只加载 engine 驱动路径用于服务 CPU-only 或非 CUDA 加速器 workerauto两条路径都加载任意设备类型的 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.rstDaemonSet 资源规划示例中 60 GB L1 对应 requests65Gi内存这一“L1 运行开销”的估算方式可直接迁移到其他容量规划中。最后提醒一点LMCache Pod 在无 GPU 节点上崩溃是预期行为多进程模式依赖 CUDA 环境所有 LMCache server 都应只调度到承载 vLLM 的 GPU 节点上这是 DaemonSet Deployment 模式能稳定工作的前提。【免费下载链接】LMCacheLMCache: Supercharge Your LLM with the Fastest KV Cache Layer项目地址: https://gitcode.com/GitHub_Trending/lm/LMCache创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考