企业官网建设流程全解析

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 等不同硬件平台上的全部安装路径：Python（pip / uv）Stable 与 Nightly 渠道、源码编译、Docker 镜像拉取与自建，以及安装后的验证方法。读完本文，你将能根据自身运行环境（PyTorch 版本、GPU 型号、vLLM 版本）准确选择安装渠道，理解--no-build-isolation、--find-links、LMCACHE_CUDA_MAJOR等关键参数的作用，并正确完成一次可验证的 LMCache 安装。

安装前置条件与选型总览

官方文档给出的基础前置条件如下：

• 操作系统：Linux
• Python：3.9–3.13
• 硬件：NVIDIA GPU（compute 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 版本」的单一矩阵，而是三个相互独立的层次：

这一选型逻辑贯穿下文所有安装命令，请先对照自身环境再选择安装路径。

通过 Python（pip / uv）安装 LMCache

Stable 渠道

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 构建的默认目标版本是 13（LMCACHE_CUDA_MAJOR未设置时取"13"），这正对应 PyPI 默认 wheel 的构建基线；而nixlextra 在 setup.py 中通过 profile 的extras_requirements()注入，对应 requirements/nixl.txt。

CUDA 12.9

CUDA 12.9 的 wheel 并不发布到 PyPI，而是发布在专用的 GitHub Releases 资产页。安装时需要同时指定 CUDA 12.9 的 PyTorch wheel 索引与--find-links地址：

uv venv --python 3.12 source .venv/bin/activate VERSION=0.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 变体不匹配的版本，导致运行时符号错误。

ROCm（AMD Instinct，torch 2.11）

ROCm wheel 面向 AMD Instinctgfx942（MI300X / MI325X）与gfx950（MI350X / 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 seccomp=unconfined \ --entrypoint bash vllm/vllm-openai-rocm:v0.25.0 VERSION=0.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 XPU

Intel XPU wheel 与上游vllm/vllm-openai-xpu:v0.26.0镜像（torch 2.12.0+xpu 与 oneAPI/SYCL）做 ABI 匹配，同样发布在 GitHub Releases。安装方式同样是进入匹配的 vLLM XPU 容器，用--no-deps保留容器内的 torch 与 oneAPI/SYCL runtime 栈：

docker run -it --device /dev/dri --shm-size=4g \ --entrypoint bash vllm/vllm-openai-xpu:v0.26.0 VERSION=0.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 version，pip show lmcache可以区分构建来源。

Moore Threads MUSA

MUSA wheel 在发布流程使用的、已验证的 TorchMUSA/MUSA SDK 镜像中构建，发布到 GitHub Releases。由于 TorchMUSA 由摩尔线程自行分发、不在公共 PyPI 索引上，因此该 wheel 不上传 PyPI。

先启动匹配的 MUSA runtime 镜像。镜像必须提供torch_musa、MUSA SDK 库，以及（若要使用 native transfer 快速路径）musa_aiter：

docker run -it --privileged --network=host \ -e MTHREADS_VISIBLE_DEVICES=all \ --entrypoint bash \ sh-harbor.mthreads.com/ai-kv/kuae-lmcache-vllm-ci@sha256:75c8c1012cf49caf6dd99dbbfd33931ef100d035647083b999eaf0092d94edba VERSION=0.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 version，pip 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.0+rocm7.2.4.lw.git3d3aa833-cp312-cp312-linux_x86_64.whl
• torch runtime 版本：2.10.0+rocm7.2.4.git3d3aa833
• ROCm7.2.4，HIP runtime7.2.53211
• Python/platform tag：cp312-cp312-manylinux_2_39_x86_64
• C++ ABI：_GLIBCXX_USE_CXX11_ABI=1

在该固定镜像内安装匹配的 wheel：

docker run -it --device /dev/kfd --device /dev/dri \ --group-add video --security-opt seccomp=unconfined \ --entrypoint bash \ rocm/pytorch:rocm7.2.4_ubuntu24.04_py3.12_pytorch_release_2.10.0@sha256:4449f856653602317e4101a76fce599c7fcd58ccec2e539951fce5f73083179e VERSION=0.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-torch210

wheel 在运行时链接容器内的 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-match

ROCm nightly 需要在上游 vLLM ROCm 容器内用--no-deps安装：

docker run -it --device /dev/kfd --device /dev/dri \ --group-add video --security-opt seccomp=unconfined \ --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-rocm

Nightly ROCm wheel 的版本号与 CUDA nightly 一致并追加 ROCm local segment，例如0.5.4.dev15+rocm7.2。这里--no-index是必需的：--find-links只是新增一个来源，没有它 pip 还会考虑 PyPI——在 PEP 440 规则下，预发布版本0.5.4rc4的排序高于0.5.4.dev15+rocm7.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.txt

requirements/build.txt 的内容包含ninja、packaging>=24.2、setuptools>=77.0.3,<81.0.0、setuptools_scm>=8、grpcio==1.78.0、grpcio-tools==1.78.0与wheel。该文件头部注释明确指出：torch 不在这里，因为 vLLM 的安装会隐式带入 torch，而用户应当有意识地选择自己的 torch 版本（或让 serving 引擎代为选择）——这也解释了各平台从源码构建时为何都要先手动装 torch。

CUDA 13.0

git 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-isolation

CUDA 12.9

git 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_MAJOR=12 makes setup.py pick cupy-cuda12x # for install_requires instead of the cu13 default. LMCACHE_CUDA_MAJOR=12 \ uv pip install -e . --no-build-isolation

LMCACHE_CUDA_MAJOR环境变量的作用可以从 setup_extensions/build_profiles/cuda.py 得到验证：_cuda_major()读取该变量（默认"13"），只接受"12"或"13"，并据此选择requirements/cuda12_core.txt或requirements/cuda13_core.txt作为核心依赖文件，从而决定install_requires中引入哪个 cupy 变体。

ROCm

git 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_HIP=1 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_ARCH="gfx942,gfx950" \ TORCH_DONT_CHECK_COMPILER_ABI=1 \ CXX=hipcc \ BUILD_WITH_HIP=1 \ uv pip install -e . --no-build-isolation

Intel XPU

git 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_SYCL=1 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_SYCL=1即对应 setup_extensions/build_profiles/ 中的 sycl profile 触发条件。

MetaX MACA

MACA 与 CUDA 兼容：启用 MACA 的 torch 构建会报告device.type == "cuda"，因此 LMCache 现有的 CUDA 兼容 connector 路径无需单独的设备后端即可工作。没有预构建的 MACA wheel 或 CI 构建——这是仅支持自编译的路径，需要先通过 MetaX 自己的工具链（而非 PyPI）安装启用 MACA 的 torch：

# Puts the MACA SDK's 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.txt's 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 (MetaX's cupy equivalent), published on MetaX's # 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 # torch's own ROCm wheels are named e.g. torch-2.11.0+rocm7.2-...). # Derives the base version from this checkout's own git tag (so # it never needs manual updates across releases) and appends a # +maca<build> 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_MACA=1 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_VERSION=13.0 DOCKERFILE_NAME='Dockerfile' VLLM_VERSION="${VLLM_VERSION:-nightly}" # 例如 VLLM_VERSION=0.9.1 ./example_build.sh UBUNTU_VERSION=24.04 BUILD_TARGET=image-build # 或 image-release IMAGE_TAG='lmcache/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

主 Dockerfile（docker/Dockerfile）定义了三个构建目标，对应三种发布策略：

• image-build：集成 vLLM nightly 与从源码构建的最新 LMCache；
• image-release：使用 vLLM stable release 与来自 PyPI 的 LMCache（cu13 默认 wheel）；
• image-release-cu129：使用 cu12.9 vLLM 与来自 GitHub Releases cu129 资产的 LMCache。

该 Dockerfile 还支持以下构建参数（详见 docker/README.md 的 CUDA Build Arguments 表格）：

nvcc_threads的auto语义在 setup_extensions/build_profiles/cuda.py 中有源码级实现：resolve_build_parallelism()会根据宿主机 CPU 数与内存预算（读取 cgroup v2 的memory.max）计算并发编译槽位——单次 nvcc 编译峰值内存约 2.7–3.0 GiB（CUDA 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_ops"

lmcache.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.rst）：

• vLLM external MP connector：vLLM>= 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 events：vLLM0.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