LMCache 安装完全指南：多平台 Wheel、Nightly 与源码构建实战

LMCache 安装完全指南多平台 Wheel、Nightly 与源码构建实战【免费下载链接】LMCacheLMCache: Supercharge Your LLM with the Fastest KV Cache Layer项目地址: https://gitcode.com/GitHub_Trending/lm/LMCache本篇技术指南以 LMCache 官方安装文档 docs/source/getting_started/installation.rst 为主体完整讲解在 CUDA、ROCm、Intel XPU、Moore Threads MUSA、MetaX MACA 等不同硬件平台上的全部安装路径Pythonpip / uvStable 与 Nightly 渠道、源码编译、Docker 镜像拉取与自建以及安装后的验证方法。读完本文你将能根据自身运行环境PyTorch 版本、GPU 型号、vLLM 版本准确选择安装渠道理解--no-build-isolation、--find-links、LMCACHE_CUDA_MAJOR等关键参数的作用并正确完成一次可验证的 LMCache 安装。安装前置条件与选型总览官方文档给出的基础前置条件如下操作系统LinuxPython3.9–3.13硬件NVIDIA GPUcompute capability 7.0软件CUDA 12.1包管理工具uv官方推荐的 Python 环境与依赖管理工具值得注意的是这组前置条件描述的是CUDA 路径的最低要求对于 ROCm、XPU、MUSA、MACA 等平台实际安装姿势是「进入与 vLLM 官方镜像匹配的容器内安装」无需自备全套 CUDA 工具链。在动手安装前官方强烈建议先阅读兼容性文档 docs/source/getting_started/compatibility.rst 来选定 vLLM 发行版、LMCache 发布渠道与 native runtime 的组合。该文档指出兼容性不是一张「vLLM 版本 × LMCache 版本」的单一矩阵而是三个相互独立的层次层次必须匹配的内容推荐动作Runtime 与 ABIPython 次版本、PyTorch 构建、CUDA/ROCm/oneAPI runtime、native 扩展 ABI、必要时 C ABI使用与 runtime 匹配的 LMCache wheel 或容器若环境使用了不同的 PyTorch 构建则用--no-build-isolation针对已安装的 PyTorch 从源码构建Connector 加载vLLM 发行版是否支持部署所用的 connector 加载机制对支持外部 connector 模块的 vLLM 版本显式设置kv_connector_module_path指向 LMCache connector更老版本使用 vLLM 内置的 connector 实现特性与模型KV layout、block size、hybrid/recurrent 行为、传输模式、设备与存储后端遵循对应模型或功能 recipe未列出的组合在 smoke-test 通过前视为未验证这一选型逻辑贯穿下文所有安装命令请先对照自身环境再选择安装路径。通过 Pythonpip / uv安装 LMCacheStable 渠道CUDA 13.0默认推荐路径PyPI 上发布的默认lmcachewheel 即基于 CUDA 13.0 构建因此最简单的安装方式如下uv venv --python 3.12 source .venv/bin/activate uv pip install lmcache安装完成后即可直接开始使用。NIXL 支持例如用于 disaggregated prefill 和 P2P KV 共享属于可选 extra按需安装uv pip install lmcache[nixl]从 setup_extensions/build_profiles/cuda.py 的源码可以看到CUDA 构建的默认目标版本是 13LMCACHE_CUDA_MAJOR未设置时取13这正对应 PyPI 默认 wheel 的构建基线而nixlextra 在 setup.py 中通过 profile 的extras_requirements()注入对应 requirements/nixl.txt。CUDA 12.9CUDA 12.9 的 wheel 并不发布到 PyPI而是发布在专用的 GitHub Releases 资产页。安装时需要同时指定 CUDA 12.9 的 PyTorch wheel 索引与--find-links地址uv venv --python 3.12 source .venv/bin/activate VERSION0.4.3 # replace with target release uv pip install lmcache${VERSION} \ --extra-index-url https://download.pytorch.org/whl/cu129 \ --find-links https://github.com/LMCache/LMCache/releases/expanded_assets/v${VERSION}-cu129 \ --index-strategy unsafe-best-match这里--extra-index-url https://download.pytorch.org/whl/cu129的作用是确保解析到 CUDA 12.9 构建的 PyTorch缺少它时 pip 可能选中 CUDA 变体不匹配的版本导致运行时符号错误。ROCmAMD Instincttorch 2.11ROCm wheel 面向 AMD Instinctgfx942MI300X / MI325X与gfx950MI350X / MI355X在一个 fat binary 中同时提供支持并且与上游vllm/vllm-openai-rocm镜像torch 2.11、ROCm 7.2、Python 3.12做 ABI 匹配。该 wheel 同样发布在 GitHub Releases而非 PyPI。推荐的安装方式是直接在上游 vLLM ROCm 容器内进行——torch 与 ROCm runtime 已在镜像中使用--no-deps让 wheel 在运行时绑定镜像内的这些库docker run -it --device /dev/kfd --device /dev/dri \ --group-add video --security-opt seccompunconfined \ --entrypoint bash vllm/vllm-openai-rocm:v0.25.0 VERSION0.5.3 # replace with target release pip install lmcache${VERSION}rocm7.2 --no-deps \ --find-links https://github.com/LMCache/LMCache/releases/expanded_assets/v${VERSION}-rocm两个要点wheel不打包torch 与 ROCm runtime 库运行时绑定宿主镜像因此 wheel 的 torch/ROCm 次版本必须与容器匹配其他基础镜像请使用下方「从源码构建」路径。ROCm wheel 带有rocm7.2这个 PEP 440 local version 标识因此pip show lmcache能直接报告安装的是哪个构建lmcache${VERSION}这种不带 local segment 的写法同样能解析到它忽略 local segment但显式写出可避免歧义。Intel XPUIntel XPU wheel 与上游vllm/vllm-openai-xpu:v0.26.0镜像torch 2.12.0xpu 与 oneAPI/SYCL做 ABI 匹配同样发布在 GitHub Releases。安装方式同样是进入匹配的 vLLM XPU 容器用--no-deps保留容器内的 torch 与 oneAPI/SYCL runtime 栈docker run -it --device /dev/dri --shm-size4g \ --entrypoint bash vllm/vllm-openai-xpu:v0.26.0 VERSION0.5.3 # replace with target release pip install lmcache${VERSION}xpu --no-deps \ --no-index \ --find-links https://github.com/LMCache/LMCache/releases/expanded_assets/v${VERSION}-xpu这里--no-index将 pip 限定在 GitHub Release 资产内防止它从 PyPI 选中同版本的 CUDA wheel。XPU wheel 同样携带xpuPEP 440 local versionpip show lmcache可以区分构建来源。Moore Threads MUSAMUSA wheel 在发布流程使用的、已验证的 TorchMUSA/MUSA SDK 镜像中构建发布到 GitHub Releases。由于 TorchMUSA 由摩尔线程自行分发、不在公共 PyPI 索引上因此该 wheel 不上传 PyPI。先启动匹配的 MUSA runtime 镜像。镜像必须提供torch_musa、MUSA SDK 库以及若要使用 native transfer 快速路径musa_aiterdocker run -it --privileged --networkhost \ -e MTHREADS_VISIBLE_DEVICESall \ --entrypoint bash \ sh-harbor.mthreads.com/ai-kv/kuae-lmcache-vllm-cisha256:75c8c1012cf49caf6dd99dbbfd33931ef100d035647083b999eaf0092d94edba VERSION0.5.5 # replace with target release pip install lmcache${VERSION}musa --no-deps \ --no-index \ --find-links https://github.com/LMCache/LMCache/releases/expanded_assets/v${VERSION}-musa要点--no-deps是必需的它保留镜像中厂商固定的 TorchMUSA 栈而不是从 PyPI 解析通用的torch依赖。--no-index防止 pip 选中同版本 CUDA wheel。当前 MUSA profile 随附 LMCache 的 Python MUSA 集成与常用 native 模块MUSA 特化的 fused kernel 仍由可选的musa_aiter包提供。若厂商镜像使用不同的 native 扩展需从源码构建。wheel 携带musaPEP 440 local versionpip show lmcache可识别加速器变体显式写出 local version 可避免误选 CUDA 产物。ROCm 7.2.4 / torch 2.10公共 AMD PyTorch 镜像该 wheel 同样面向 gfx942 与 gfx950在公开的 AMD PyTorch 镜像rocm/pytorch:rocm7.2.4_ubuntu24.04_py3.12_pytorch_release_2.10.0固定 digest中构建并通过 smoke-test且不依赖 ATOM 镜像。其支持的 ABI 元组是精确固定的AMD wheel 来源torch-2.10.0rocm7.2.4.lw.git3d3aa833-cp312-cp312-linux_x86_64.whltorch runtime 版本2.10.0rocm7.2.4.git3d3aa833ROCm7.2.4HIP runtime7.2.53211Python/platform tagcp312-cp312-manylinux_2_39_x86_64C ABI_GLIBCXX_USE_CXX11_ABI1在该固定镜像内安装匹配的 wheeldocker run -it --device /dev/kfd --device /dev/dri \ --group-add video --security-opt seccompunconfined \ --entrypoint bash \ rocm/pytorch:rocm7.2.4_ubuntu24.04_py3.12_pytorch_release_2.10.0sha256:4449f856653602317e4101a76fce599c7fcd58ccec2e539951fce5f73083179e VERSION0.5.4 # replace with target release pip install \ lmcache${VERSION}rocm7.2.4.torch2.10.git3d3aa833.cxx11abi1 \ --no-deps \ --find-links https://github.com/LMCache/LMCache/releases/expanded_assets/v${VERSION}-rocm-torch210wheel 在运行时链接容器内的 torch 与 ROCm 库。其他 torch 2.10、ROCm 7.2.x、Python 或 C ABI 组合不在该产物的覆盖范围内此类环境需从源码构建。Nightly 渠道Nightly wheel 每天 07:30 UTC 从最新dev分支构建并发布到 GitHub Releases。无需固定版本号——--pre会自动选择最新的 nightly# CUDA 13.0 uv venv --python 3.12 source .venv/bin/activate uv pip install lmcache --pre \ --extra-index-url https://download.pytorch.org/whl/cu130 \ --find-links https://github.com/LMCache/LMCache/releases/expanded_assets/nightly \ --index-strategy unsafe-best-match # CUDA 12.9 uv venv --python 3.12 source .venv/bin/activate uv pip install lmcache --pre \ --extra-index-url https://download.pytorch.org/whl/cu129 \ --find-links https://github.com/LMCache/LMCache/releases/expanded_assets/nightly-cu129 \ --index-strategy unsafe-best-matchROCm nightly 需要在上游 vLLM ROCm 容器内用--no-deps安装docker run -it --device /dev/kfd --device /dev/dri \ --group-add video --security-opt seccompunconfined \ --entrypoint bash vllm/vllm-openai-rocm:v0.26.0 pip install lmcache --pre --no-deps --no-index \ --find-links https://github.com/LMCache/LMCache/releases/expanded_assets/nightly-rocmNightly ROCm wheel 的版本号与 CUDA nightly 一致并追加 ROCm local segment例如0.5.4.dev15rocm7.2。这里--no-index是必需的--find-links只是新增一个来源没有它 pip 还会考虑 PyPI——在 PEP 440 规则下预发布版本0.5.4rc4的排序高于0.5.4.dev15rocm7.2因此--pre会误装 CUDA wheel。Stable 渠道不需要--no-index因为lmcache${VERSION}rocm7.2是只有 ROCm release 才能满足的精确 pin。--no-deps使得--no-index在这里是安全的torch 与 ROCm runtime 来自容器无需解析其他依赖。从源码构建从源码构建的关键在于--no-build-isolation它保证 kernel 是针对环境中已安装的同一个 torch编译的从而避免运行时出现 undefined symbol 错误。构建前需手动安装构建依赖uv pip install -r requirements/build.txtrequirements/build.txt 的内容包含ninja、packaging24.2、setuptools77.0.3,81.0.0、setuptools_scm8、grpcio1.78.0、grpcio-tools1.78.0与wheel。该文件头部注释明确指出torch 不在这里因为 vLLM 的安装会隐式带入 torch而用户应当有意识地选择自己的 torch 版本或让 serving 引擎代为选择——这也解释了各平台从源码构建时为何都要先手动装 torch。CUDA 13.0git clone https://github.com/LMCache/LMCache.git cd LMCache uv venv --python 3.12 source .venv/bin/activate uv pip install -r requirements/build.txt uv pip install vllm # pulls in required torch version (cu13) uv pip install -e . --no-build-isolationCUDA 12.9git clone https://github.com/LMCache/LMCache.git cd LMCache uv venv --python 3.12 source .venv/bin/activate uv pip install -r requirements/build.txt # Pin vLLM (and torch) to the cu12.9 wheel index so the local # CUDA 12 toolchain matches what the extensions are built against. uv pip install vllm \ --extra-index-url https://download.pytorch.org/whl/cu129 \ --index-strategy unsafe-best-match # LMCACHE_CUDA_MAJOR12 makes setup.py pick cupy-cuda12x # for install_requires instead of the cu13 default. LMCACHE_CUDA_MAJOR12 \ uv pip install -e . --no-build-isolationLMCACHE_CUDA_MAJOR环境变量的作用可以从 setup_extensions/build_profiles/cuda.py 得到验证_cuda_major()读取该变量默认13只接受12或13并据此选择requirements/cuda12_core.txt或requirements/cuda13_core.txt作为核心依赖文件从而决定install_requires中引入哪个 cupy 变体。ROCmgit clone https://github.com/LMCache/LMCache.git cd LMCache uv venv --python 3.12 source .venv/bin/activate # Need to install these packages manually to avoid build isolation uv pip install -r requirements/build.txt # Install torch from the ROCm wheel index. Use the rocm7.2 index to # match the upstream vllm/vllm-openai-rocm image (torch 2.11, ROCm 7.2). uv pip install torch torchvision --index-url https://download.pytorch.org/whl/rocm7.2 # Build LMCache. BUILD_WITH_HIP1 makes setup.py pick cupy-rocm-7-0 automatically. # PYTORCH_ROCM_ARCH selects the target GPU(s): # gfx942 - MI300X / MI325X # gfx950 - MI350X / MI355X # Comma-separate to build a fat binary for multiple archs. PYTORCH_ROCM_ARCHgfx942,gfx950 \ TORCH_DONT_CHECK_COMPILER_ABI1 \ CXXhipcc \ BUILD_WITH_HIP1 \ uv pip install -e . --no-build-isolationIntel XPUgit clone https://github.com/LMCache/LMCache.git cd LMCache uv venv --python 3.12 source .venv/bin/activate # Need to install these packages manually to avoid build isolation uv pip install -r requirements/build.txt # Build LMCache with SYCL backend. BUILD_WITH_SYCL1 uv pip install --no-build-isolation -e .从仓库结构看SYCL 后端的 kernel 实现集中在 csrc/sycl/如mem_kernels_sycl.cpp、pos_kernels_sycl.cpp、ac_enc_sycl.cpp等BUILD_WITH_SYCL1即对应 setup_extensions/build_profiles/ 中的 sycl profile 触发条件。MetaX MACAMACA 与 CUDA 兼容启用 MACA 的 torch 构建会报告device.type cuda因此 LMCache 现有的 CUDA 兼容 connector 路径无需单独的设备后端即可工作。没有预构建的 MACA wheel 或 CI 构建——这是仅支持自编译的路径需要先通过 MetaX 自己的工具链而非 PyPI安装启用 MACA 的 torch# Puts the MACA SDKs cu-bridge nvcc-compatible compiler on PATH # and its runtime libs on LD_LIBRARY_PATH -- required before the # build step below, so torch.utils.cpp_extension can locate it. # Adjust MACA_PATH to your actual MACA SDK install root. export MACA_PATH/opt/maca export CUCC_PATH${MACA_PATH}/tools/cu-bridge export PATH${CUCC_PATH}/bin:${CUCC_PATH}/tools:${MACA_PATH}/mxgpu_llvm/bin:${MACA_PATH}/bin:${PATH} export LD_LIBRARY_PATH${MACA_PATH}/lib:${MACA_PATH}/mxgpu_llvm/lib:${MACA_PATH}/ompi/lib:${LD_LIBRARY_PATH} git clone https://github.com/LMCache/LMCache.git cd LMCache # Assumes a MACA-enabled torch is already installed/active in this # environment (e.g. inside a vllm-metax container). # Need to install these packages manually to avoid build isolation pip install -r requirements/build.txt # --no-deps skips install_requires entirely, including # requirements/common.txts cufile-python/nvtx (NVIDIA-only, # not needed on MACA) and the unpinned generic torch entry # (which would otherwise risk resolving over the MACA build). # Install any other runtime deps you actually need yourself first -- # MP mode needs mcpy (MetaXs cupy equivalent), published on MetaXs # own pip index rather than PyPI: # pip install mcpy -i https://repos.metax-tech.com/r/maca-pypi/simple \ # --trusted-host repos.metax-tech.com # SETUPTOOLS_SCM_PRETEND_VERSION makes the wheel filename and # lmcache.__version__ carry the MACA build identity (mirrors how # torchs own ROCm wheels are named e.g. torch-2.11.0rocm7.2-...). # Derives the base version from this checkouts own git tag (so # it never needs manual updates across releases) and appends a # macabuild local segment -- set MACA_AI_VERSION to your MACA # SDK/build number, or leave it at the default below. BASE_VERSION$(python -m setuptools_scm) SETUPTOOLS_SCM_PRETEND_VERSION${BASE_VERSION}maca${MACA_AI_VERSION:-0.0.0.0} \ BUILD_WITH_MACA1 pip install --no-deps --no-build-isolation -e .使用 Docker 安装拉取预构建镜像LMCache 提供了与 vLLM OpenAI server 集成的一体化镜像可按发行渠道与 CUDA 版本拉取# Stable docker pull lmcache/vllm-openai # CUDA 13.0 docker pull lmcache/vllm-openai:latest-cu129 # CUDA 12.9 # Nightly docker pull lmcache/vllm-openai:latest-nightly # CUDA 13.0 docker pull lmcache/vllm-openai:latest-nightly-cu129 # CUDA 12.9 # ROCm docker pull rocm/vllm-dev:nightly_0624_rc2_0624_rc2_20250620 # Intel XPU docker pull vllm/vllm-openai-xpu:v0.26.0关于容器运行方式与 ROCm 镜像的详细说明参见 docs/source/production/docker_deployment.rst。从源码自建镜像不想拉取预构建镜像时可以从仓库根目录用提供的 Dockerfile 自行构建与 vLLM 集成的 LMCache 镜像docker build --tag IMAGE_NAME:TAG --target image-build --file docker/Dockerfile .将IMAGE_NAME与TAG替换为你想要的镜像名与标签。docker/example_build.sh 给出了所有构建参数的示例用法CUDA_VERSION13.0 DOCKERFILE_NAMEDockerfile VLLM_VERSION${VLLM_VERSION:-nightly} # 例如 VLLM_VERSION0.9.1 ./example_build.sh UBUNTU_VERSION24.04 BUILD_TARGETimage-build # 或 image-release IMAGE_TAGlmcache/vllm-openai:build-latest docker build \ --build-arg CUDA_VERSION$CUDA_VERSION \ --build-arg UBUNTU_VERSION$UBUNTU_VERSION \ --build-arg VLLM_VERSION$VLLM_VERSION \ --target $BUILD_TARGET --file $DOCKERFILE_NAME \ --tag $IMAGE_TAG $DOCKER_BUILD_PATH主 Dockerfiledocker/Dockerfile定义了三个构建目标对应三种发布策略image-build集成 vLLM nightly 与从源码构建的最新 LMCacheimage-release使用 vLLM stable release 与来自 PyPI 的 LMCachecu13 默认 wheelimage-release-cu129使用 cu12.9 vLLM 与来自 GitHub Releases cu129 资产的 LMCache。该 Dockerfile 还支持以下构建参数详见 docker/README.md 的 CUDA Build Arguments 表格参数默认值说明CUDA_VERSION13.0CUDA 版本UBUNTU_VERSION24.04Ubuntu 基础版本PYTHON_VERSION3.12Python 版本max_jobs2扩展构建的最大并行任务数nvcc_threadsautonvcc--threads数量auto会自动缩放使max_jobs × nvcc_threads适配宿主机的 CPU 与内存每次编译约需 3 GiB指定数值则强制torch_cuda_arch_list7.5 8.0 8.6 8.9 9.0 10.0 12.0PTX编译进扩展的 CUDA 架构列表nvcc_threads的auto语义在 setup_extensions/build_profiles/cuda.py 中有源码级实现resolve_build_parallelism()会根据宿主机 CPU 数与内存预算读取 cgroup v2 的memory.max计算并发编译槽位——单次 nvcc 编译峰值内存约 2.7–3.0 GiBCUDA 13.0预留 3 GiB 系统余量后MAX_JOBS × NVCC_THREADS被限制在min(cpus, (memory - headroom) / 3.0GiB)内。这也解释了 CI 中为何曾出现 16 GB runner 被2×8并发编译 SIGTERM 的记录。此外仓库还提供Dockerfile.standalone不含 vLLM 的独立 LMCache 镜像、Dockerfile.lightweight基于官方 vLLM 镜像从 PyPI 快速安装不含 NIXL/PD 支持、Dockerfile.rocm、Dockerfile.xpu与Dockerfile.payload等变体具体差异与适用场景见 docker/README.md。轻量级 CLI-only 安装如果只需要查询或压测远端 LMCache server可以安装轻量级的 CLI-only 包。它不需要 CUDA可在任何操作系统上运行pip install lmcache-cli注意lmcache-cli与lmcache安装的是同一个lmcacheCLI 命令不要在同一环境中同时安装两者。验证安装安装完成后用一行命令验证 native 扩展是否可用python -c import lmcache.cuda_opslmcache.cuda_ops是 CUDA 构建产物中承载 memory kernels、lookup kernels、Cascade-AC encode/decode、position kernels 与 event recorder 的原生扩展模块见 setup_extensions/build_profiles/cuda.py 中CUDAExtension(lmcache.cuda_ops, ...)的源码列表与 csrc/cuda/ 目录。该 import 能成功说明 wheel/源码构建的 native 扩展与当前环境 ABI 匹配若出现 undefined symbol 类错误通常意味着 wheel 与环境的 PyTorch/CUDA 变体不匹配应改用匹配渠道的 wheel 或按本文「从源码构建」一节用--no-build-isolation重编。版本兼容性速查安装前必须知道的边界最后汇总兼容性文档中记录的、直接影响安装选型的几个精确事实详见 docs/source/getting_started/compatibility.rstvLLM external MP connectorvLLM 0.20.0才支持通过kv_connector_module_path显式选择 LMCache 包自带的 connector更老版本只能使用 vLLM 内置的 connector 实现。显式配置示例{ kv_connector: LMCacheMPConnector, kv_connector_module_path: lmcache.integration.vllm.lmcache_mp_connector, kv_role: kv_both }vLLM KV eventsvLLM0.13.0是 KV-events 集成的最低文档版本事件发布仍需 vLLM 侧相应配置见 docs/source/production/kv_cache_events.rst。混合模型hybrid models模型 recipe 与 docs/source/mp/hybrid_models.rst 比包版本比较更具权威性——不同 attention/recurrent 组的物理 page 几何可能不同即使两个包都能成功 import部署也可能不兼容。评价新组合使用 recipe 中未列出的 vLLM 新版本例如 vLLM0.28.0时最新本身不代表已验证。至少应完成启动 server 并确认加载了预期 connector 模块 → 一次冷请求存储 prefix → 同 prefix 二次请求确认非零 cache hit → 重启引擎验证跨进程 retrieve → 比对输出正确性并检查 server 日志中的 layout/transfer/worker 错误。历史上 LMCache 0.3–0.4 版本的安装兼容矩阵可参考仓库中的 docs/source/getting_started/Installation_compatibility_matrix.csv但该文件已不再是当前兼容性的事实来源应以本文引用的兼容性文档与各功能 recipe 为准。按上述路径安装并验证后即可参考 docs/source/getting_started/quickstart.rst 的快速上手示例将 LMCache 接入 vLLM 开始 KV cache 加速。【免费下载链接】LMCacheLMCache: Supercharge Your LLM with the Fastest KV Cache Layer项目地址: https://gitcode.com/GitHub_Trending/lm/LMCache创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考