NVIDIA Dynamo 与 LMCache 多进程(MP)模式集成部署指南:本地与 Kubernetes 双路径实战
NVIDIA Dynamo 与 LMCache 多进程(MP)模式集成部署指南:本地与 Kubernetes 双路径实战
本篇技术指南以 docs/source/production/dynamo_coordination.rst 为骨架,系统讲解如何在 NVIDIA Dynamo 数据中心级推理栈中接入 LMCache 的 KV 缓存层:先以单机 Docker Compose 方式跑通 NATS/etcd、Dynamo 容器、LMCache server 与 vLLM worker 的手动/脚本化启动流程,再进入 Kubernetes 集群,借助 LMCache Operator 的 LMCacheEngine 自定义资源与 Dynamo 的 DynamoGraphDeployment 完成聚合式(Aggregated)与分离式(Disaggregated)部署。读完本文,你将掌握 LMCacheMPConnector 的连接参数语义、两种部署模式的完整 YAML/命令清单,以及排查 CUDA IPC 与连接失败问题的基本方法。
背景:Dynamo 编排推理引擎,LMCache 跨请求复用 KV
NVIDIA Dynamo 是一个开源的、数据中心规模的推理栈,负责在多个节点上编排 vLLM、SGLang、TensorRT-LLM 等推理引擎。LMCache 则在其下方提供一层 KV 缓存层,将超出 GPU 显存范围的缓存存放到 CPU 内存、本地磁盘或远端存储中,供后续请求复用,从而缩短首个令牌延迟(TTFT)并提高吞吐。
本文涉及的集成采用 LMCache 的多进程(mp)模式:LMCache 以独立进程(lmcache server)运行,vLLM worker 通过 LMCacheMPConnector 连接该进程,双方通过 CUDA IPC 共享 KV 张量,无需经过 GPU 显存拷贝。仓库中的完整示例位于 examples/dynamo_integration,其 README(examples/dynamo_integration/README.md)对目录布局与两种模式做了总览:
| 路径 | 作用 |
|---|---|
| local/docker-compose.yml | 定义 NATS 与 etcd 两个基础服务 |
| local/nats-server.conf | NATS 配置(挂载进容器) |
| local/launch_lmcache_mp.sh | 单机一键脚本:aggregated(1 GPU)或 disaggregated(2 GPU) |
| local/serve.sh | 容器入口,等待依赖就绪后启动 LMCache 与 Dynamo |
| kubernetes/lmcache_engine.yaml | LMCacheEngine 自定义资源,须先于 worker 应用 |
| kubernetes/agg_lmcache_mp.yaml | 聚合式 DynamoGraphDeployment(单 worker) |
| kubernetes/disagg_lmcache_mp.yaml | 分离式 DynamoGraphDeployment(prefill + decode 双 worker) |
本地部署(Local)
本地演示以 Qwen/Qwen3-0.6B 为示例模型,单 GPU 运行,并为 LMCache 分配 16 GiB 的 CPU 内存。使用 nvcr.io/nvidia/ai-dynamo/vllm-runtime:1.4.2 镜像,该镜像内置 LMCache 0.5.2;更新版本的镜像标签可在 NVIDIA NGC 的 vllm-runtime 容器页面查询。
前置条件
- Linux 主机,具备 NVIDIA GPU 与 NVIDIA Container Toolkit;
- Docker 与 Docker Compose;
- 能够拉取
nvcr.io/nvidia/ai-dynamo/vllm-runtime:1.4.2与 NATS/etcd 镜像的网络环境。
第一步:启动 NATS 与 etcd
Dynamo 平台依赖 NATS(消息总线)与 etcd(元数据存储)。在 LMCache 仓库根目录执行:
docker compose -f examples/dynamo_integration/local/docker-compose.yml up -d
Compose 文件(examples/dynamo_integration/local/docker-compose.yml)定义了两个服务:
nats-server:nats:2.11.4,挂载 nats-server.conf,暴露 4222(客户端)、6222(集群路由)、8222(监控,含/varz、/healthz等端点);etcd-server:bitnamilegacy/etcd:3.6.1,暴露 2379(客户端,也提供/metrics)与 2380(peer)。
NATS 配置中有两个值得注意的细节:max_payload: 15728640(15 MB)是为容纳约 10 MB 的解码后 embedding 的 Base64 编码(10 MB → 约 13.3 MB,15 MB 留出约 1.7 MB 元数据余量);同时开启了 JetStream 与 8222 监控端口。
第二步:启动 Dynamo 容器
在仓库根目录执行:
docker run --rm -it --name dynamo-lmcache \
--gpus all --network host --ipc host \
nvcr.io/nvidia/ai-dynamo/vllm-runtime:1.4.2 bash
参数要点:
--network host:让容器直接使用主机网络,便于各进程通过 localhost 端口互连;--ipc host:共享主机的 IPC 命名空间,是 LMCache 与 vLLM 之间 CUDA IPC //dev/shm协作的前提;- 该镜像已预装 LMCache,进入容器后即可直接使用
lmcache命令。
随后在主机上再打开两个终端,分别执行以下命令进入同一个容器:
docker exec -it dynamo-lmcache bash
这样你就拥有三个容器 shell(终端 1/2/3)。
第三步:在三个终端中分别启动 LMCache、frontend 与 vLLM worker
终端 1:启动 LMCache server,分配 16 GiB CPU 缓存。
lmcache server --l1-size-gb 16 --eviction-policy LRU \
--port 5555 --http-port 8080
参数说明:
--l1-size-gb 16:L1(CPU RAM)缓存容量为 16 GiB;--eviction-policy LRU:缓存淘汰策略为最近最少使用;--port 5555:ZMQ 消息端口,供 worker 连接;--http-port 8080:HTTP 健康检查/监控端口(serve.sh 中通过http://localhost:8080/healthcheck探活)。
lmcache server 子命令由 lmcache/cli/commands/server.py 实现,其参数由 multiprocess、storage manager、HTTP frontend、Prometheus 与 telemetry 等多个配置模块组合注册。
终端 2:启动推理前端(frontend)。
python3 -m dynamo.frontend
前端默认在 8000 端口接受外部请求。
终端 3:待 LMCache 就绪后,启动 vLLM worker 并接入 LMCache。
DYN_SYSTEM_PORT=8081 python3 -m dynamo.vllm \
--model Qwen/Qwen3-0.6B \
--enforce-eager \
--max-model-len 4096 \
--max-num-seqs 2 \
--disable-hybrid-kv-cache-manager \
--kv-transfer-config '{
"kv_connector": "LMCacheMPConnector",
"kv_role": "kv_both",
"kv_connector_extra_config": {"lmcache.mp.port": 5555}
}'
关键参数解读:
DYN_SYSTEM_PORT=8081:Dynamo 系统端口,vLLM worker 通过它向 Dynamo 注册/通信;--enforce-eager:关闭 CUDA graph 以降低内存占用,适合演示场景;--disable-hybrid-kv-cache-manager:禁用 vLLM 的混合 KV 缓存管理器,将 KV 管理完全交给 KV transfer 链路;--kv-transfer-config:JSON 字符串,是 vLLM 接入外部 KV 层的统一入口:"kv_connector": "LMCacheMPConnector":指定连接器为 LMCache 多进程连接器,对应源码 lmcache/integration/vllm/lmcache_mp_connector.py 中的LMCacheMPConnector类(继承 vLLM 的KVConnectorBase_V1);"kv_role": "kv_both":该 worker 同时承担 KV 的生产(存)与消费(取),聚合式场景下 prefill 与 decode 在同一进程;"kv_connector_extra_config": {"lmcache.mp.port": 5555}:指定 LMCache server 端口。
从源码看,连接器的 extra_config 还支持以下字段(单服务器部署):lmcache.mp.host(默认 tcp://localhost)、lmcache.mp.mq_timeout(消息队列请求超时秒数)、lmcache.mp.heartbeat_interval(对 server 的心跳间隔秒数)、lmcache.mp.eager_prefetch(请求进入 vLLM 等待队列时即提交 lookup,默认关闭)、lmcache.mp.save_decode_cache(是否也存储含生成 token 的 chunk,默认 False,只存完整 prompt chunk);多服务器部署可用 lmcache.mp.server_urls 传入逗号分隔的 URL 列表。
至此,整条链路已经就绪:外部请求打到 frontend 的 8000 端口 → Dynamo 调度 vLLM worker → worker 通过 LMCacheMPConnector 在 5555 端口存取 KV 缓存。
第四步:用脚本一键启动(可选)
手动三终端流程可以全部交给仓库提供的启动脚本(examples/dynamo_integration/local/launch_lmcache_mp.sh),在仓库根目录执行其一:
# 聚合式:1 张 GPU
./examples/dynamo_integration/local/launch_lmcache_mp.sh aggregated
# 分离式:同节点 2 张 GPU
./examples/dynamo_integration/local/launch_lmcache_mp.sh disaggregated
脚本的执行逻辑(与 serve.sh 配合)值得展开:
- 先
docker compose up -d拉起 NATS 与 etcd; - 再
docker run启动 GPU 版 Dynamo 容器,并把示例目录只读挂载进容器; - 容器内
serve.sh先通过健康检查等待 NATS(http://localhost:8222/healthz)与 etcd(http://localhost:2379/health)就绪; - 启动
lmcache server并等待http://localhost:8080/healthcheck; - 按模式启动 worker:聚合式只启动一个
DYN_SYSTEM_PORT=8081、CUDA_VISIBLE_DEVICES=0的 vLLM worker;分离式则先启动 GPU 0 上的 decode worker(--disaggregation-mode decode),等其模型下载加载完成后再启动 GPU 1 上的 prefill worker(--disaggregation-mode prefill); - 所有 worker 就绪后启动 frontend;
- 任一服务进程退出即整体停止,
Ctrl+C会连带停止 NATS 与 etcd(脚本通过trap实现清理)。
分离式模式下先等 decode worker 就绪再启动 prefill,是为了让 decode 先完成模型下载与加载,prefill 得以复用已缓存模型文件。
Kubernetes 部署
Kubernetes 路径的架构分工如下:LMCache Operator 负责部署与管理 LMCache server(LMCacheEngine CR),Dynamo 的 Kubernetes operator 负责管理 DynamoGraphDeployment 资源中的 frontend 与推理 worker。
前置条件
- 安装 LMCache Operator:它负责部署和管理 LMCache server,并生成 worker 使用的连接配置。Operator 的机制与 CR 详解见 docs/source/mp/operator.rst——声明一个
LMCacheEngineCR 后,Operator 会自动调和出 DaemonSet、Service、ConfigMap(以及可选的 ServiceMonitor),并自动注入 CUDA IPC 相关 pod 设置(如--host 0.0.0.0、/dev/shm挂载等); - 安装 Dynamo 平台:其 Kubernetes operator 管理
DynamoGraphDeployment资源中定义的 frontend 与推理 worker; - 一个具备 GPU 节点的 Kubernetes 1.20+ 集群,
kubectl已配置。
部署 LMCache server(先于 worker)
examples/dynamo_integration/kubernetes/lmcache_engine.yaml 定义了一个名为 lmcache-mp 的 LMCacheEngine 自定义资源,为每个 server 分配 16 GiB CPU 缓存:
apiVersion: lmcache.lmcache.ai/v1alpha1
kind: LMCacheEngine
metadata:
name: lmcache-mp # 生成 worker 挂载的 "lmcache-mp-connection" ConfigMap
namespace: default # 必须与 worker 部署的命名空间一致
spec:
image:
repository: lmcache/standalone
tag: v0.5.2
pullPolicy: IfNotPresent
# LMCache 使用共享的 /dev/shm 进行 CUDA IPC。
isolatedIPC: false
# L1(CPU RAM)缓存大小——生产负载请调大。
l1:
sizeGB: 16
字段要点:
metadata.name: lmcache-mp:名称会派生出一系列资源名(见下文);metadata.namespace: default:必须与 worker 所在命名空间一致,否则连接 ConfigMap 无法被 worker 挂载;spec.image:LMCache server 镜像lmcache/standalone:v0.5.2(支持linux/amd64,因此需使用 x86_64 GPU 节点),镜像内同样包含 LMCache 0.5.2;spec.isolatedIPC: false:本版本 LMCache 需要共享主机的/dev/shm与 worker 协作(CUDA IPC),故关闭隔离 IPC。有关隔离 IPC(默认)与旧式/dev/shm共享两种模式的取舍,见 docs/source/mp/operator.rst 的 “IPC Mode” 一节;spec.l1.sizeGB: 16:每个 server 的 L1 CPU 缓存为 16 GiB,生产负载建议调大。
应用该资源:
kubectl apply -n default -f examples/dynamo_integration/kubernetes/lmcache_engine.yaml
Operator 会据此自动创建以下对象:
- DaemonSet:在每个符合条件的节点上运行一个 LMCache server pod;
lmcache-mpService:将 worker 路由到其自身节点上的 server(节点本地发现);lmcache-mp-connectionConfigMap:其中的kv-transfer-config.json条目包含LMCacheMPConnector的全部设置,包括 Service 地址与 server 端口,供 vLLM worker 直接读取使用。
聚合式 Serving(Aggregated)
examples/dynamo_integration/kubernetes/agg_lmcache_mp.yaml 定义了一个 DynamoGraphDeployment,包含一个 frontend 与一个 vLLM worker。该 worker 在一张 GPU 上同时处理 prefill 与 decode,服务 Qwen/Qwen3-0.6B:
apiVersion: nvidia.com/v1beta1
kind: DynamoGraphDeployment
metadata:
name: vllm-agg-lmcache
spec:
components:
- name: Frontend
type: frontend
replicas: 1
podTemplate:
spec:
containers:
- name: main
image: nvcr.io/nvidia/ai-dynamo/vllm-runtime:1.4.2
- name: VllmDecodeWorker
type: worker
replicas: 1
sharedMemorySize: "0"
podTemplate:
spec:
# vLLM 与 LMCache 之间的 CUDA IPC 需要。
hostIPC: true
containers:
- name: main
image: nvcr.io/nvidia/ai-dynamo/vllm-runtime:1.4.2
workingDir: /workspace/examples/backends/vllm
resources:
limits:
nvidia.com/gpu: "1"
requests:
ephemeral-storage: "2Gi"
env:
- name: PYTHONHASHSEED
value: "0"
volumeMounts:
- name: kv-transfer-config
mountPath: /etc/lmcache
readOnly: true
command:
- /bin/sh
- -c
- exec python3 -m dynamo.vllm "$@" --kv-transfer-config "$(cat /etc/lmcache/kv-transfer-config.json)"
- --
args:
- --model
- Qwen/Qwen3-0.6B
- --disable-hybrid-kv-cache-manager
volumes:
- name: kv-transfer-config
configMap:
name: lmcache-mp-connection # = <LMCacheEngine.metadata.name>-connection
要点解读:
- worker 将
lmcache-mp-connectionConfigMap 挂载到/etc/lmcache,启动命令通过$(cat /etc/lmcache/kv-transfer-config.json)把文件内容直接传给--kv-transfer-config,从而连到本节点的 LMCache server; sharedMemorySize: "0":mp 模式下 LMCache 进程自己管理/dev/shm,故不申请独立 emptyDir;hostIPC: true:vLLM 与 LMCache 之间通过 CUDA IPC 共享 KV 张量所需的宿主级 IPC 权限;PYTHONHASHSEED=0:LMCache 要求确定性哈希,需固定 Python 哈希种子;ephemeral-storage: 2Gi:更大模型需上调。
应用聚合式部署:
kubectl apply -n default -f examples/dynamo_integration/kubernetes/agg_lmcache_mp.yaml
分离式 Serving(Disaggregated)
examples/dynamo_integration/kubernetes/disagg_lmcache_mp.yaml 启动一个 frontend 与分离的 prefill、decode 两个 worker,需要一个 GPU 节点且至少 2 张 GPU的集群。每个 worker 各用一张 GPU,并连接到同一个 LMCache server。
该清单与聚合式几乎相同,区别在于 args:
- decode worker:
--disaggregation-mode decode; - prefill worker:
--disaggregation-mode prefill。
两个 worker 都挂载同一份 lmcache-mp-connection ConfigMap、都以 --kv-transfer-config "$(cat /etc/lmcache/kv-transfer-config.json)" 方式连接本节点 LMCache server,并同样设置 sharedMemorySize: "0" 与 hostIPC: true。
应用分离式部署:
kubectl apply -n default -f examples/dynamo_integration/kubernetes/disagg_lmcache_mp.yaml
部署顺序提醒:先应用 lmcache_engine.yaml,再应用 worker 清单,确保连接 ConfigMap 在 worker 启动前已就位。
kv-transfer-config 与 LMCacheMPConnector 参数速查
综合原文档与 LMCacheMPConnector 实现(其类文档字符串完整列举了 extra config 语义),整理如下:
| 字段 | 说明 | 默认值 |
|---|---|---|
kv_connector |
连接器类型,Dynamo 集成场景固定为 LMCacheMPConnector |
— |
kv_role |
角色:聚合式用 kv_both(同时存取);分离式按 worker 分别承担生产/消费角色 |
— |
kv_connector_extra_config.lmcache.mp.port |
LMCache server 的 ZMQ 端口 | 5555 |
kv_connector_extra_config.lmcache.mp.host |
LMCache server 地址(可含传输协议前缀) | tcp://localhost |
kv_connector_extra_config.lmcache.mp.server_urls |
多服务器部署:URL 列表或逗号分隔字符串(优先级高于单服务器 host/port) | 无 |
kv_connector_extra_config.lmcache.mp.mq_timeout |
消息队列请求超时(秒) | 由实现决定 |
kv_connector_extra_config.lmcache.mp.heartbeat_interval |
对 server 的心跳间隔(秒) | 由实现决定 |
kv_connector_extra_config.lmcache.mp.eager_prefetch |
请求进入等待队列即提前提交 lookup | False |
kv_connector_extra_config.lmcache.mp.save_decode_cache |
同时存储含生成 token 的 chunk(默认仅存完整 prompt chunk) | False |
常见问题与排查
- worker 连不上 server:最典型的原因是
lmcache server进程未启动,或 host/port 不匹配。源码 vllm_multi_process_adapter.py 中针对不可达 server 会抛出带指引的ConnectionError,提示用lmcache server --l1-size-gb <SIZE> --eviction-policy LRU启动本地默认 5555 端口的 server,或通过kv_connector_extra_config覆盖 host/port。 - CUDA IPC 失败:mp 模式下 vLLM 与 LMCache 通过 CUDA IPC 共享 KV 张量。本地 Docker 场景必须加
--ipc host;Kubernetes 场景必须保证hostIPC: true、sharedMemorySize: "0"且isolatedIPC: false(本版本)——两进程必须能看到同一个/dev/shmtmpfs,否则cudaIpcOpenMemHandle等调用会失败。 - ConfigMap 挂载 404:
LMCacheEngine必须与 worker 处于同一命名空间(示例为default),否则生成的<name>-connectionConfigMap 不在 worker 可挂载的位置。 - 端口冲突:聚合式 worker 使用
DYN_SYSTEM_PORT=8081,分离式 decode 为 8081、prefill 为 8082;LMCache 的 ZMQ 为 5555、HTTP 为 8080,frontend 为 8000。多套环境并存时注意错开。
小结
Dynamo 与 LMCache 的集成既可以在单机上用 Docker 快速验证(手动三终端或 launch_lmcache_mp.sh 一键脚本),也可以在 Kubernetes 上由两个 Operator 分工协作完成生产化部署。无论是聚合式还是分离式,核心都是让 vLLM worker 通过 LMCacheMPConnector 连接每节点一个的 lmcache server,借助 CUDA IPC 实现 KV 缓存的跨请求复用。相关示例文件、连接器实现与 Operator 文档均可在当前仓库的 examples/dynamo_integration、lmcache/integration/vllm/lmcache_mp_connector.py 与 docs/source/mp/operator.rst 中继续深入查阅。