安装#

环境要求#

硬件环境#

当前，CT-HPKV KV Cache卸载产品主要支持以下AI芯片：业界主流的英伟达Tesla和GeForce系列GPU，以及国产的昇腾910 系列NPU、沐曦集成电路曦彩系列GPU及摩尔线程数据中心系列GPU。支持的芯片型号如下：

CPU: x86_64, aarch64
MTT NPU: S4000, S5000
MetaX GPU: C500, C550, C588, C600
Ascend NPU: 910系列
NVIDIA GPU: 计算能力7.5+

软件环境#

Linux OS: CTyunOS, Ubuntu, RedHat, OpenEuler等
Python: 3.8 -- 3.13
MTT: MUSA SDK v4.0.0+
MetaX: MACA SDK 3.0.0.8+
Ascend: CANN v8.5.0+
NVIDIA: CUDA 12.0+

推理引擎#

CT-HPKV支持业界主流的开源大模型推理引擎，当前支持的推理引擎和版本信息如下, 其它推理引擎版本正在快速支持中

vLLM: v0.9.1, v0.13.0
vLLM-Ascend: v0.9.1rc2, v0.13.0
SGLang: v0.5.7

二进制安装#

CT-HPKV项目由C++和Python语言混合编写(部分算子代码由对应芯片下的runtime层API开发，如CUDA C ，Ascend C等), CT-HPKV团队预编译了适配各种环境的Python whl包。这里我们以Python 3.11的CUDA与Ascend环境为例，介绍CT-HPKV的快速安装:

NVIDIA GPU#

GPU环境下使用CT-HPKV前，需参考硬件环境准备好满足条件的CPU和GPU硬件资源，并参考软件环境要求下载和安装 GPU驱动和 CUDA程序。安装可参考英伟达官方网站或技术博客网站，按照相应的教程和步骤进行。此外，我们还需要准备好满足条件的Python环境及依赖包。vLLM安装时会自动安装依赖的PyTorch库，这里只介绍vLLM和CT-HPKV的安装:

# 创建并激活Python 3.11环境
uv venv --python 3.11
source .venv/bin/activate

# 安装vLLM v0.13.0
uv pip install vllm==0.13.0

# 如果使用SGLang
uv pip install sglang==0.5.7

# 安装CT-HPKV预编译二进制包(自动检测vLLM与SGLang的安装情况与版本信息)
uv pip install hpkv-2.0.0rc1-cp311-cp311-linux_x86_64.whl

Ascend NPU#

昇腾NPU环境下需要预先安装Ascend的固件、驱动及CANN套件。请参考硬件环境准备相应的硬件资源，并参考昇腾官网及软件环境要求下载和安装对应的软件环境。Ascend NPU vLLM需要安装CPU aarch64的版本，依赖的PyTorch也需要CPU aarch64版本。昇腾环境下需要安装单独的torch-npu以扩展官方PyTorch对Ascend NPU的适配，以及vLLM-Ascend。这些包的安装可参考昇腾的官方文档和代码仓库，这里只介绍vLLM、vLLM-Ascend和CT-HPKV:

# 创建并激活Python 3.11环境
uv venv --python 3.11
source .venv/bin/activate

# 安装vLLM v0.13.0
uv pip install vllm==0.13.0

# 安装vLLM-Ascend v0.13.0
uv pip install vllm-ascend==0.13.0

# 如果使用SGLang推理引擎
uv pip install sglang==0.5.7

# 安装CT-HPKV预编译二进制包
uv pip install hpkv-2.0.0rc1-cp311-cp311-manylinux_2_28_aarch64.whl

重要

vLLM框架具有良好的插件机制，昇腾官方在对vLLM官方代码零侵入的情况下，实现了单独的vLLM-Ascend项目。vLLM启动时依据插件机制自动加载对应的NPU Platform与General Register，实现用户无感的运行时Monkey Patch。然而，截止目前，SGLang框架并没有提供类似的插件机制，昇腾官方则采用通过提交代码PR到SGLang官方仓库的方式支持Ascend NPU。因此，vLLM框架有对应的vLLM-Ascend适配，而SGLang没有独立的SGLang-Ascend，其Ascend NPU的功能支持已集成在官方代码内。

源码安装#

CT-HPKV项目底层实现依赖 gRPC，而gRPC库又依赖 Protobuf库。因此，源码编译安装CT-HPKV前需要安装这两个库。此外，CT-HPKV项目采用了C++17标准，因此需要安装支持C++17标准的GCC编译器，常用的GCC 11.x+即可满足需求。如果当前使用的操作系统不支持C++17标准，请自行编译安装支持C++17的GCC编译器。

Protobuf安装#

apt#

# 更新包索引
(base) hpkv@ctyunos:~$ apt update

# 安装 protobuf 编译器（protoc）和运行时库
(base) hpkv@ctyunos:~$ apt install -y protobuf-compiler libprotobuf-dev

yum/dnf#

CentOS/RHEL 7

# 安装 EPEL 仓库（提供更多软件包）
(base) hpkv@ctyunos:~$ yum install -y epel-release

# 安装 protobuf
(base) hpkv@ctyunos:~$ yum install -y protobuf protobuf-devel protobuf-compiler

CentOS/RHEL 8+

# 安装 protobuf
(base) hpkv@ctyunos:~$ dnf install -y protobuf protobuf-devel protobuf-compiler

# 安装静态库
(base) hpkv@ctyunos:~$ dnf install -y protobuf-static

源码编译#

操作系统包管理工具自带的Protobuf库有时候版本较低，一些高级功能不支持。此时我们可以采用源码编译安装的方式安装较新版的Protobuf库：

# 下载Protobuf源码
(base) hpkv@ctyunos:~$ git clone -b v27.4 --recursive https://github.com/protocolbuffers/protobuf.git

# 配置编译选项并构建
(base) hpkv@ctyunos:~$ mkdir build && cd build
(base) hpkv@ctyunos:~$ cmake -DCMAKE_INSTALL_PREFIX=/usr/local   \
                            -DCMAKE_CXX_FLAGS="-fPIC"            \
                            -DCMAKE_C_FLAGS="-fPIC"              \
                            -DCMAKE_POSITION_INDEPENDENT_CODE=ON \
                            -Dprotobuf_ABSL_PROVIDER=module      \
                            -Dprotobuf_BUILD_TESTS=OFF           \
                            ..

# 并行编译并安装
(base) hpkv@ctyunos:~$ make -j32
(base) hpkv@ctyunos:~$ sudo make install

gRPC安装#

apt#

# 更新包索引
(base) hpkv@ctyunos:~$ apt update


# 安装 gRPC 开发包和编译器
(base) hpkv@ctyunos:~$ apt install -y libgrpc++-dev libgrpc-dev

yum/dnf#

# CentOS 7/8 的默认仓库没有 gRPC，必须从源码编译或使用 EPEL

源码编译#

# 下载gRPC源码
(base) hpkv@ctyunos:~$ git clone --recurse-submodules -b v1.72.0 --depth 1 \
                        --shallow-submodules https://github.com/grpc/grpc

# 配置编译选项并构建
(base) hpkv@ctyunos:~$ cd grpc
(base) hpkv@ctyunos:~$ mkdir -p cmake/build
(base) hpkv@ctyunos:~$ cd cmake/build
(base) hpkv@ctyunos:~$ cmake -DgRPC_INSTALL=ON         \
                    -DgRPC_BUILD_TESTS=OFF             \
                    -DCMAKE_CXX_STANDARD=17            \
                    -DCMAKE_POLICY_VERSION_MINIMUM=3.5 \
                    ../..

# 并行编译并安装
(base) hpkv@ctyunos:~$ make -j32
(base) hpkv@ctyunos:~$ sudo make install

重要

CT-HPKV项目采用Protobuf和gRPC库的静态链接方式，确保编译生成的Python whl包在未安装对应库时也能正确运行。因此，使用包管理工具安装时，需确保安装了对应的静态库。

Python依赖#

# 安装hpkv python依赖
(base) hpkv@ctyunos:~$ git clone https://xxx/hpkv.git
(base) hpkv@ctyunos:~$ cd hpkv && pip install -r requirements.txt

如果是Ascend NPU环境，需要安装torch-npu与vLLM-Ascend包:

# torch_npu包下载地址: https://gitcode.com/Ascend/pytorch/releases
# 安装torch-npu
(base) hpkv@ctyunos:~$ pip install torch_npu-2.8.0.post2-cp311-cp311-manylinux_2_28_x86_64.whl

# 安装vLLM-ascend
(base) hpkv@ctyunos:~$ pip install vllm-ascend=0.13.0

CT-HPKV安装#

CT-HPKV支持一键编译为Python whl包，并使用pip命令快速安装:

# 编译hpvk可安装的whl包
(base) hpkv@ctyunos:~$ python3 -m build --wheel --no-isolation

# 或者使用安静模式
(base) hpkv@ctyunos:~$ python3 -m build --wheel --no-isolation -C--quiet

# 安装编译后的hpkv whl包
(base) hpkv@ctyunos:~$ pip install dist/*.whl