部署指南#

本页介绍了在 Docker 和 Kubernetes 环境中部署 LMCache 多进程模式的最佳实践。

Docker#

LMCache 容器：

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

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}}'

所需的 Docker 标志：

  • --network host -- 允许 vLLM 容器访问本地主机上的 LMCache。

  • --ipc host -- 需要用于容器之间的 CUDA IPC 共享内存传输。

  • --runtime nvidia --gpus all -- 通过 NVIDIA 容器运行时访问 GPU。

HTTP 服务器变体：

对于健康检查和缓存管理 API 支持（在容器编排器中非常有用），请使用 HTTP 服务器入口点：

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

Kubernetes#

LMCache 设计为 DaemonSet + Deployment 模式：每个节点一个 LMCache 服务器（DaemonSet），由多个 vLLM pod（Deployment）共享。

在 examples/multi_process/ 中提供了示例 YAML 文件。

前提条件#

  • 支持 GPU 的 Kubernetes 集群（安装了 NVIDIA GPU Operator）

  • 每个节点至少需要 4 个 GPU

  • kubectl 配置为访问您的集群

逐步指南#

步骤 1：创建命名空间

kubectl create namespace multi-process

步骤 2：部署 LMCache DaemonSet

kubectl apply -f examples/multi_process/lmcache-daemonset.yaml

步骤 3：部署 vLLM

kubectl apply -f examples/multi_process/vllm-deployment.yaml

备注

默认模型是 Qwen/Qwen3-14B。对于受限模型（例如 Llama），请使用您的 Hugging Face 令牌创建一个 Secret：

kubectl create secret generic vllm-secrets \
  --from-literal=hf_token=your_hf_token_here \
  -n multi-process

然后将 HF_TOKEN 环境变量添加到 vLLM 容器规格中。

步骤 4：监控部署

# DaemonSet status
kubectl get daemonset -n multi-process
kubectl get pods -n multi-process -l app=lmcache-server

# vLLM status
kubectl get pods -n multi-process -l app=vllm-deployment -w

# LMCache logs (for a specific node)
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

步骤 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
    }"

架构说明#

  • DaemonSet 使用 ``hostNetwork: true`` 以便 vLLM pod 通过 status.hostIP 发现 LMCache 服务器。

  • 两个容器从主机挂载 ``/dev/shm`` 以启用 CUDA IPC 内存共享。

  • 不在 DaemonSet 中请求 GPU -- 这允许 GPU 保持专门分配给 vLLM pod。NVIDIA 容器运行时自动提供 GPU 访问以进行基于 IPC 的内存传输。

  • 多个 vLLM pod 在同一节点上会自动连接到同一个 LMCache DaemonSet 实例。

备注

没有 GPU 的节点上的 LMCache pod 会因 CUDA 初始化错误而崩溃。这是预期的——LMCache 只需要在调度有 vLLM pod 的 GPU 节点上运行。

健康检查 (HTTP 服务器)#

对于 Kubernetes 活跃性/就绪性探针，请部署 HTTP 服务器变体。使用 /healthcheck 端点：

livenessProbe:
  httpGet:
    path: /healthcheck
    port: 8080
  initialDelaySeconds: 10
  periodSeconds: 30
readinessProbe:
  httpGet:
    path: /healthcheck
    port: 8080
  initialDelaySeconds: 5
  periodSeconds: 10

监控集成#

默认情况下，Prometheus 指标在 9090 端口启用。添加 ServiceMonitor 或 Prometheus 抓取注释以从 LMCache DaemonSet Pod 收集指标。有关指标详细信息，请参见 可观察性。

清理#

kubectl delete -f examples/multi_process/vllm-deployment.yaml
kubectl delete -f examples/multi_process/lmcache-daemonset.yaml
kubectl delete namespace multi-process

生产最佳实践#

工作进程数量 (``--max-workers``, ``--max-gpu-workers``, ``--max-cpu-workers``): --max-workers 设置 GPU 亲和力池和 CPU 正常池的大小（默认值为 1）。使用 --max-gpu-workers 独立覆盖 GPU 池——将其设置为至少与共享缓存服务器的 vLLM 实例数量相同，以便每个实例获得自己的专用线程。使用 --max-cpu-workers 来覆盖查找和其他非 GPU 操作的 CPU 池。

L1 内存大小 (``--l1-size-gb``): 在考虑操作系统和 vLLM 后，分配尽可能多的 CPU 内存。更大的 L1 缓存意味着更少的 L2 往返。

逐出调优:

  • ``--eviction-trigger-watermark 0.8``（默认值）在 L1 达到 80% 满时触发逐出。

  • ``--eviction-ratio 0.2``（默认值）在每个逐出周期释放 20% 的分配内存。

  • 如果在稳定负载下观察到频繁的逐出，请降低水位线或增加比率。

日志记录: 在初始设置期间使用 LMCACHE_LOG_LEVEL=DEBUG 来验证 L2 存储/加载活动。 在生产中切换到 ``INFO``（默认）以减少日志量。