FAISS C++ 版本编译安装
本文将详细介绍如何在一个干净的 Ubuntu24.04.3 LTS 中编译安装 FAISS 的 C++ 版本。
本文所有信息均来自于官方手册与作者实操，如有疑问请参见官方手册。
编译前准备
首先理清思路、确定目标。使用命令 nvidia-smi 查看当前系统英伟达显卡驱动版本，博主的显卡驱动版本为580.126.09，最高 cuda toolkit 支持版本为 13.0，同时因为博主训练模型时使用的是 PyTorch 是 cu130 版本，因此本文使用 cuda toolkit 13.0 Update 2。但是目前暂时先不安装，因为安装后可能会导致后续 APT 源搜索不到 NCCL。
接下来梳理的 FAISS 的依赖关系。FAISS 在编译时可启用部分编译指令，其中使用默认编译配置安装后，使用 GPU 加速的 IVF-Flat, IVF-PQ 索引等，其速度可能比 Python 版本慢。其原因在于使用默认编译配置时，FAISS_ENABLE_CUVS 选项默认为 OFF，详情请参见官方安装文档。NVIDIA cuVS 是一个用于 GPU 加速向量搜索和数据聚类的开源库，可加快向量搜索和索引构建速度，具体性能测试请参见官方博客。因此本文在编译时将会启用该指令。除此之外，FAISS 需要 BLAS 实现，在 Intel 平台上推荐 Intel MKL 以获取更好的性能，博主使用的是 AMD CPU，因此使用 OpenBLAS。
启用 FAISS_ENABLE_CUVS 指令后需要安装 cuVS 库，且参照安装文档，版本需为 25.10，具体安装方法请参见官方文档，本文使用编译安装的方式安装该库。根据其源码的 CMakeLists.txt 可知，最低 CMake 版本为 3.30.4，而 Ubuntu24.04 LTS 官方 APT 源的 CMake 版本为 3.28.3，因此本文在这里选用 CMake 3 的最后一个版本 3.31.10。同时其使用的构建系统为 ninja，因此需要安装 ninja-build，此外编译该库时需要 NVIDIA NCCL 集合通信库。由此，可以整理出依赖关系。
FAISS
├── RAPIDS RAFT 25.10
├── RAPIDS RMM 25.10
├── NVIDIA cuVS 25.10
│ ├── CMake 3.31.10
│ ├── ninja
│ ├── NVIDIA NCCL 2.28.9
│ └── NVIDIA CUDA Toolkit 13.0
└── OpenBLAS/MKL
安装依赖 - CMake
首先安装 g++ 编译器和 git（否则后续会报错）：sudo apt install g++ git，然后前往CMake 官网，找到 3.31.10 版本，下载二进制分发版本，作者使用的是 Linux x86_64 平台，点击对应下载连接。使用以下指令解压并移动至 /opt/cmake，后续所有软件包均放在 /opt 目录下
$ tar -zxvf cmake-3.31.10-linux-x86_64.tar.gz
$ mv cmake-3.31.10-linux-x86_64 cmake-3.31.10 && sudo mkdir /opt/cmake && sudo mv cmake-3.31.10 /opt/cmake/ && cd /opt/cmake/cmake-3.31.10
批量将所有可执行程序通过符号链接到 /usr/local/bin，本项不设置环境变量的原因是后续使用 sudo cmake 将头文件和库安装至 /usr/local 时，sudo 会重置环境变量，导致 cmake 命令不可用，若不使用 sudo 则无法安装进系统目录
$ sudo find /opt/cmake/cmake-3.31.10/bin -type f -executable -exec ln -sf {} /usr/local/bin/ \;
接下来安装 ninja 构建工具
$ sudo apt install ninja-build
可以使用 cmake --version 命令查看是否安装成功。
安装依赖 - NVIDIA NCCL
前往英伟达官方下载页面，其最新版本的下载不需要登陆，但本文需要下载支持 CUDA 13.0 的版本，因此需要登陆英伟达开发者账号。选择支持 CUDA 13.0 的最新 NCCL 的版本 2.28.9，本文安装方式为网络安装，依次输入以下命令安装英伟达官方源
$ wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2404/x86_64/cuda-keyring_1.1-1_all.deb
$ sudo dpkg -i cuda-keyring_1.1-1_all.deb
$ sudo apt update
更新了源后输入以下命令安装 NCCL
$ sudo apt install libnccl2=2.28.9-1+cuda13.0 libnccl-dev=2.28.9-1+cuda13.0
安装依赖 - NVIDIA CUDA Toolkit
前文已阐述过，本文使用 CUDA 13.0 Update 2，因此前往英伟达官方下载界面，选择 Ubunu24.04，本文同上通过网络安装，因为上文已安装过英伟达官方源，因此这里不再安装，直接安装对应 CUDA 版本
$ sudo apt install cuda-toolkit-13-0
配置全局环境，打开 /etc/profile 文件并在底部追加以下环境变量，该部分使用环境变量而不采用上文的符号链接，便于切换版本
# CUDA
export PATH=/usr/local/cuda-13.0/bin:$PATH
export LD_LIBRARY_PATH=/usr/local/cuda-13.0/lib64:$LD_LIBRARY_PATH
退出登陆、重启或 source 一下即可生效，最后可以使用 nvcc --version 命令查看是否安装成功。
编译安装依赖 - RAPIDS RAFT
⚠️ 如果之前构建失败过的话需清除缓存重新构建，使用命令 rm -rf cpp/build
为和 NVIDIA cuVS 版本对齐，本文使用的版本为 25.10.00，前往 RAFT 官方 GitHub页面下载 25.10.00 版本源码，下载后解压
$ tar -zxvf raft-25.10.00.tar.gz
将其移动到 /opt 目录下并进入该目录
$ sudo mkdir /opt/rapids && sudo mkdir /opt/rapids/raft && sudo mv raft-25.10.00 /opt/rapids/raft && cd /opt/rapids/raft/raft-25.10.00
配置将文件安装至 /usr/local 目录下，并使用参数 -n 跳过安装（稍后使用 sudo 手动安装至 /usr/local 文件夹下）
$ PARALLEL_LEVEL=20 INSTALL_PREFIX=/usr/local ./build.sh libraft -n
编译完后安装
$ sudo cmake --build cpp/build --target install
编译安装依赖 - RAPIDS RMM
为和 NVIDIA cuVS 版本对齐，本文使用的版本为 25.10.00，前往 RMM 官方 GitHub页面下载 25.10.00 版本源码，下载后解压、编译并安装
$ tar -zxvf rmm-25.10.00.tar.gz
$ sudo mkdir /opt/rapids/rmm && sudo mv rmm-25.10.00 /opt/rapids/rmm && cd /opt/rapids/rmm/rmm-25.10.00
$ PARALLEL_LEVEL=20 INSTALL_PREFIX=/usr/local ./build.sh librmm -n
$ sudo cmake --build cpp/build --target install
编译安装依赖 - NVIDIA cuVS
本文使用的版本为 25.10.00，前往 cuVS 官方 GitHub页面下载 25.10.00 版本源码，下载后解压
$ tar -zxvf cuvs-25.10.00.tar.gz
$ sudo mkdir /opt/rapids/cuvs && sudo mv cuvs-25.10.00 /opt/rapids/cuvs/ && cd /opt/rapids/cuvs/cuvs-25.10.00
在编译前先确认好主机的内存容量，官方的编译脚本默认设定线程数为 CPU 核心数，例如作者的 CPU 核心数为24，如果使用默认设置，每个线程耗费 1～2 GB 内存，需要耗费高达 48 GB 内存，电脑会完全卡死。因此本文设置并行线程数为 6，确定好后使用以下命令执行编译，编译完成后安装。
$ PARALLEL_LEVEL=6 INSTALL_PREFIX=/usr/local ./build.sh libcuvs -n
$ sudo cmake --build cpp/build --target install
编译安装 - FAISS
$ tar -zxvf faiss-1.13.2.tar.gz
$ sudo mkdir /opt/faiss && sudo mv faiss-1.13.2 /opt/faiss && cd /opt/faiss
因为 FAISS 使用 OpenMP 作为并行化方式，因此本文也安装 OpenBLAS 的 OpenMP 版本
$ sudo apt install libopenblas-openmp-dev
执行以下命令配置编译参数
参数解释
- FAISS_ENABLE_GPU=ON: 编译 GPU 版本
- FAISS_ENABLE_PYTHON=OFF: 不编译 Python 绑定
- FAISS_ENABLE_CUVS=ON: 对 IVF-Flat, IVF-PQ 等使用 NVIDIA cuVS 实现
- FAISS_OPT_LEVEL=avx512: 使用 avx512 指令集加速
- FAISS_USE_LTO=ON: 启用 LTO 链接加速
- BUILD_TESTING=OFF: 不编译测试
- CMAKE_BUILD_TYPE=Release: 编译 Release 版本（在 gcc 上使用 O3 优化）
- CMAKE_CUDA_ARCHITECTURES: 指定需要编译的 GPU 架构（博主使用的 GPU 计算能力为 8.6，具体参见官方对照表）
$ cmake -B build . -DFAISS_ENABLE_GPU=ON -DFAISS_ENABLE_PYTHON=OFF -DFAISS_ENABLE_CUVS=ON -DFAISS_OPT_LEVEL=avx512 -DFAISS_USE_LTO=ON -DBUILD_TESTING=OFF -DCMAKE_BUILD_TYPE=Release -DCMAKE_CUDA_ARCHITECTURES="86"
编译并安装
$ sudo cmake --build build --target install --parallel 20
浙公网安备 33010602011771号