NVIDIA Dynamo 与 LMCache 多进程(MP)模式集成部署指南:本地与 Kubernetes 双路径实战

原创2026-10-10 19:33:471,374 阅读
文章标签:人工智能大模型缓存

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 配合)值得展开:

  1. 先 docker compose up -d 拉起 NATS 与 etcd;
  2. 再 docker run 启动 GPU 版 Dynamo 容器,并把示例目录只读挂载进容器;
  3. 容器内 serve.sh 先通过健康检查等待 NATS(http://localhost:8222/healthz)与 etcd(http://localhost:2379/health)就绪;
  4. 启动 lmcache server 并等待 http://localhost:8080/healthcheck;
  5. 按模式启动 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);
  6. 所有 worker 就绪后启动 frontend;
  7. 任一服务进程退出即整体停止,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——声明一个 LMCacheEngine CR 后,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-mp Service:将 worker 路由到其自身节点上的 server(节点本地发现);
  • lmcache-mp-connection ConfigMap:其中的 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-connection ConfigMap 挂载到 /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/shm tmpfs,否则 cudaIpcOpenMemHandle 等调用会失败。
  • ConfigMap 挂载 404:LMCacheEngine 必须与 worker 处于同一命名空间(示例为 default),否则生成的 <name>-connection ConfigMap 不在 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 中继续深入查阅。

登录后查看全文
LMCache