faiss 安装完全指南：从 conda 包到 CMake 源码构建（faiss 1.15.0）-编程实验室

faiss 安装完全指南：从 conda 包到 CMake 源码构建（faiss 1.15.0）

【免费下载链接】faissA library for efficient similarity search and clustering of dense vectors.项目地址: https://gitcode.com/GitHub_Trending/fa/faiss

本文基于 faiss 仓库根目录的 INSTALL.md 展开，系统覆盖 faiss 的两种官方安装路径：通过 conda/pixi 安装预编译包（faiss-cpu / faiss-gpu / faiss-gpu-cuvs），以及通过 CMake 从源码完整构建（含 GPU 索引、SIMD 优化等级、Python 绑定与测试运行）。读完后，你可以针对 CPU、NVIDIA CUDA GPU、AMD ROCm、Intel SVS 等不同硬件环境选对安装包或配对手动构建参数，并知道如何在构建后跑通 demo 与测试来验证安装是否成功。

一、选型概览：三种 conda 包的适用平台

faiss 官方支持的推荐安装方式是 conda。稳定版本会定期推送到 pytorch conda channel，同时也有预发布的 nightly 构建。根据 INSTALL.md 的说明与仓库 CMakeLists.txt 中project(VERSION 1.15.0)的版本号，当前主线版本为 1.15.0。三种可用包的定位如下：

包名	内容	平台与 CUDA 要求
`faiss-cpu`	仅 CPU 索引	Linux（x86-64 与 aarch64）、OSX（仅 arm64）、Windows（x86-64）
`faiss-gpu`	CPU + GPU（CUDA）索引	仅 Linux x86-64，CUDA 11.4 与 12.1
`faiss-gpu-cuvs`	CPU + 基于 NVIDIA cuVS 26.06 的 GPU 索引	仅 Linux x86-64，CUDA 13.2

AMD ROCm 的 GPU 包目前尚未提供，只能从源码构建（见后文FAISS_ENABLE_ROCM）。

安装最新稳定版：

# CPU-only version $ conda install -c pytorch -c conda-forge faiss-cpu=1.15.0 # GPU(+CPU) version $ conda install -c pytorch -c nvidia -c conda-forge faiss-gpu=1.15.0 # GPU(+CPU) version with NVIDIA cuVS $ conda install -c pytorch -c nvidia -c rapidsai -c conda-forge libnvjitlink faiss-gpu-cuvs=1.15.0 # GPU(+CPU) version using AMD ROCm not yet available

为什么必须加 conda-forge / nvidia / rapidsai 通道

各通道的作用在 INSTALL.md 中有明确解释，仓库的 conda 构建配方 conda/faiss/meta.yaml 也印证了这些依赖关系：

conda-forge是必需的，因为 BLAS 依赖（x86-64 上为 MKL、ARM 上为 OpenBLAS）需要较新的版本，而默认 Anaconda 通道并不定期更新。从 meta.yaml 可以看到，x86_64 的host/run段依赖mkl >=2024.2.2,<2026，非 x86_64 平台依赖openblas =0.3.34，Linux x86-64 还依赖libsvs-runtime =0.4.0；
nvidia通道对faiss-gpu额外必需，因为 CUDA 并未发布在 anaconda 主通道；
rapidsai + conda-forge + nvidia三个通道对faiss-gpu-cuvs都必需（cuVS 来自 RAPIDS 生态，libnvjitlink需一并安装）。

使用 Pixi 作为替代

如果你偏好 Pixi，可以用完全相同的通道与包名，以 Conda 兼容的工作流安装：

# CPU-only version $ pixi init -c pytorch -c conda-forge $ pixi add faiss-cpu=1.15.0 # GPU(+CPU) version $ pixi init -c pytorch -c nvidia -c conda-forge $ pixi add faiss-gpu=1.15.0 # GPU(+CPU) version with NVIDIA cuVS $ pixi init -c pytorch -c nvidia -c rapidsai -c conda-forge $ pixi add libnvjitlink faiss-gpu-cuvs=1.15.0

Pixi 从所列 Conda 通道解析包，因此上面提到的通道要求同样适用。

安装 nightly 预发布包

# CPU-only version $ conda install -c pytorch/label/nightly -c conda-forge faiss-cpu # GPU(+CPU) version $ conda install -c pytorch/label/nightly -c nvidia -c conda-forge faiss-gpu=1.15.0 # GPU(+CPU) version with NVIDIA cuVS (package built with CUDA 13.2) conda install -c pytorch -c rapidsai -c rapidsai-nightly -c conda-forge -c nvidia pytorch/label/nightly::faiss-gpu-cuvs 'cuda-version=13.2' # GPU(+CPU) version using AMD ROCm not yet available

在以上命令中，可通过pytorch-cuda=11或pytorch-cuda=12指定特定 CUDA 版本（如有需要）。

一个可安装 GPU 版 faiss 并配套 CUDA + PyTorch 的版本组合示例（INSTALL.md 给出，截至 2024-05-15）：

conda create --name faiss_1.8.0 conda activate faiss_1.8.0 conda install -c pytorch -c nvidia faiss-gpu=1.8.0 pytorch=*=*cuda* pytorch-cuda=11 numpy

二、源码构建的基本前提

faiss 支持在 Linux、OSX、Windows 的 x86-64 机器上从源码构建（CMake 驱动），在其他平台上也有人成功运行。构建的基本需求与可选需求如下（来自 INSTALL.md）：

基本需求：

一个C++20 编译器，支持 OpenMP 2 及以上；
一个BLAS 实现（在 Intel 机器上强烈推荐使用 Intel MKL 以获得最佳性能）。

这与 CMakeLists.txt 中set(CMAKE_CXX_STANDARD 20)以及cmake_minimum_required(VERSION 3.24.0 FATAL_ERROR)的设置一致——构建 faiss 源码需要 CMake 3.24 或更高版本。

可选需求：

GPU 索引：nvcc+ CUDA toolkit；
AMD GPU：AMD ROCm；
使用 NVIDIA cuVS 实现：libcuvs=26.06；
Python 绑定：Python 3、numpy、swig。

具体的排错配置说明可参考官方 wiki 的 troubleshooting 部分（INSTALL.md 中为外链，此处不再展开）。

结合 NVIDIA cuVS 构建

cuVS 提供了若干在 GPU 上运行近似最近邻与聚类算法的高性能实现，构建于 RAPIDS RAFT 高性能机器学习原语之上。用 cuVS 构建 faiss 后，用户可以在 faiss 原生 GPU 实现与 cuVS 实现之间按算法选择。

libcuvs 依赖应通过 conda 安装：

conda install -c rapidsai -c conda-forge -c nvidia libcuvs=26.06 'cuda-version=13.2'

更多 cuVS 26.06 安装方式可参考 RAPIDS 官方安装指南。在 CMake 侧，启用方式见下文的-DFAISS_ENABLE_CUVS=ON；从源码结构看，启用后顶层 CMakeLists.txt 会加载cmake/thirdparty/fetch_rapids.cmake并find_package(cuvs)/find_package(rmm)，即构建系统会自动探测已安装的 cuVS 与 RMM 包。

结合 Intel SVS 构建

Intel(R) Scalable Vector Search (SVS) 是高性能向量检索库。启用 SVS 后可使用其图索引（例如 Vamana）实现。当-DFAISS_ENABLE_SVS=ON时，SVS 库会被 CMake 自动下载并构建。从源码结构看，该选项在 CMakeLists.txt 中默认关闭，同时提供FAISS_SVS_RUNTIME_VERSION变量（当前取v0）用于指定 SVS runtime API 版本；且 Linux x86-64 的 conda 包已将libsvs-runtime作为运行依赖（见 conda/faiss/meta.yaml），说明 SVS 集成已进入官方发行物的依赖面。

三、Step 1：调用 CMake 及全部构建选项

$ cmake -B build .

这会在build/子目录生成系统相关的配置/构建文件。可传给 CMake 的选项分四类：

通用选项

选项	说明	默认值
`-DFAISS_ENABLE_GPU=OFF`	禁用 GPU 索引构建（`ON`/`OFF`）	`ON`（见 CMakeLists.txt）
`-DFAISS_ENABLE_PYTHON=OFF`	禁用 Python 绑定（`ON`/`OFF`）	`ON`
`-DFAISS_ENABLE_CUVS=ON`	启用 cuVS 的 IVF-Flat、IVF-PQ 与 CAGRA GPU 加速索引；注意：启用时`FAISS_ENABLE_GPU`必须为`ON`	`OFF`
`-DBUILD_TESTING=OFF`	禁用 C++ 测试构建	由 CTest 决定
`-DBUILD_SHARED_LIBS=ON`	构建动态库（`libfaiss.so`），默认构建静态库`libfaiss.a`	`OFF`
`-DFAISS_ENABLE_C_API=ON`	启用 C API 构建	`OFF`
`-DFAISS_ENABLE_SVS=ON`	启用 Intel SVS 集成；会下载并构建 SVS runtime（`libsvs_runtime.so`）。安装 Python 包时该库会被复制进包目录；C++ 使用需保证该库在库搜索路径中	`OFF`

其中 GPU 选项在 CMakeLists.txt 中还会根据FAISS_ENABLE_ROCM决定启用 HIP（ROCm）还是 CUDA 语言：ROCm 路径下会执行 faiss/gpu/hipify.sh 对 CUDA 源码做 HIP 化转换，并find_package(HIP/hipBLAS)。

优化相关选项

选项	说明
`-DCMAKE_BUILD_TYPE=Release`	启用通用编译优化（如 gcc 的`-O3`）
`-DFAISS_OPT_LEVEL=<level>`	开启生成优化 SIMD/向量指令所需的编译器标志。x86-64 取值按优化程度递增为`generic`、`avx2`、`avx512`、`avx512_spr`（Sapphire Rapids 起可用的 AVX-512 特性）；aarch64 取值为`generic`与`sve`
`-DFAISS_USE_LTO=ON`	启用链接期优化（LTO）

FAISS_OPT_LEVEL在 faiss/CMakeLists.txt 中按取值生成不同的构建目标（faiss_avx2、faiss_avx512、faiss_avx512_spr、sve等）；源码中还额外支持dd（运行时 SIMD 动态分发）取值，它会把各 ISA 变体编译进主库并按 CPU 能力运行时选择——仓库中 faiss/docs/simd_dynamic_dispatch_migration.md 对此有专门说明。

BLAS 相关选项

-DBLA_VENDOR=Intel10_64_dyn -DMKL_LIBRARIES=/path/to/mkl/libs

用于指定 Intel MKL BLAS 实现（显著快于 OpenBLAS）。BLA_VENDOR各取值的含义见 CMake 的 FindBLAS 模块文档。仓库还提供了 cmake/FindMKL.cmake 辅助 MKL 探测。

GPU 相关选项

选项	说明
`-DCUDAToolkit_ROOT=/path/to/cuda-10.1`	提示 CUDA toolkit 路径
`-DCMAKE_CUDA_ARCHITECTURES="75;72"`	指定目标 GPU 架构（按显卡查 CUDA GPU 列表）
`-DFAISS_ENABLE_ROCM=ON`	启用 AMD GPU 索引构建；要求`FAISS_ENABLE_GPU`为`ON`

Python 相关选项

-DPython_EXECUTABLE=/path/to/python3.7

为不同于默认解释器的 Python 构建接口（含义见 CMake FindPython 模块文档）。

另外，从源码结构看，顶层 CMakeLists.txt 还有一个FAISS_ENABLE_EXTRAS选项（默认ON），控制是否构建demos/、benchs/、tutorial/cpp/子目录——本文第四步之后编译 demo 就依赖它。

四、Step 2：调用 Make 编译 C++ 库

$ make -C build -j faiss

这构建 C++ 库：默认产物为libfaiss.a；若 CMake 时传了-DBUILD_SHARED_LIBS=ON则生成libfaiss.so。-j开启多单元并行编译以加速构建，但会增大内存占用风险，建议内存吃紧时固定线程数（如-j4）。

如果使用优化选项，构建 swigfaiss 之前要先构建对应的优化目标：

# AVX2 $ make -C build -j faiss_avx2 # AVX512 $ make -C build -j faiss_avx512 # AVX512（Sapphire Rapids 起可用的特性） $ make -C build -j faiss_avx512_spr

这样才能保证构建和安装 Python 包时必要的文件已生成。各优化等级对应的 SIMD 源码集合可以在 faiss/CMakeLists.txt 的 SIMD 文件注册表中看到：FAISS_SIMD_AVX2_SRC、FAISS_SIMD_AVX512_SRC、FAISS_SIMD_AVX512_SPR_SRC分别覆盖 fast_scan、HNSW、PQ 码距、标量量化器、Hamming 距离等模块的对应指令集实现，aarch64 则对应 NEON 与 SVE 源码集。

五、Step 3：构建 Python 绑定（可选）

$ make -C build -j swigfaiss $ (cd build/faiss/python && python setup.py install)

第一条命令构建 faiss 的 Python 绑定，第二条生成并安装 Python 包。绑定源码由 SWIG 包装生成，入口在 faiss/python/swigfaiss.swig；构建需求（python 3、numpy、swig）与 INSTALL.md 所述一致。此外，仓库现在也提供了基于 scikit-build-core 的 wheel 构建入口 pyproject.toml（要求 Python ≥ 3.10、swig ≥ 4.2，Linux/macOS 使用 cp310 abi3 稳定 ABI），作为源码发行 Python 包的替代路径。

六、Step 4：安装 C++ 库与头文件（可选）

$ make -C build install

这将把编译产物（Linux 下为libfaiss.a或libfaiss.so）与 C++ 头文件安装到系统范围。如果只装 Python 包，此步骤不需要。

七、Step 5：测试与验证

运行 C++ 测试套件

确保 CMake 以-DBUILD_TESTING=ON调用，然后：

$ make -C build test

从源码结构看，顶层 CMakeLists.txt 在非 Windows 且非交叉编译时还会把 perf_tests/ 与 GPU 测试（faiss/gpu/test）纳入 CTest 范围。

运行 Python 测试套件

$ (cd build/faiss/python && python setup.py build) $ PYTHONPATH="$(ls -d ./build/faiss/python/build/lib*/)" pytest tests/test_*.py

基础示例：demo_ivfpq_indexing

仓库内置的基础用法示例见 demos/demo_ivfpq_indexing.cpp：它创建一个小型 IVFPQ 索引（128 维、200k 向量、4*sqrt(nb)个质心、4 字节码/8 比特子码），训练后存储索引并执行检索。正常机器上运行约 20 秒，配备 Intel MKL BLAS 的快机器上约 2.5 秒。构建并运行：

$ make -C build demo_ivfpq_indexing $ ./build/demos/demo_ivfpq_indexing

该目标定义在 demos/CMakeLists.txt（EXCLUDE_FROM_ALL，因此不会随默认构建生成，需显式 make）。

基础 GPU 示例

$ make -C build demo_ivfpq_indexing_gpu $ ./build/demos/demo_ivfpq_indexing_gpu

它产生与 CPU 版demo_ivfpq_indexing等价的 GPU 代码，并演示索引在 CPU 与 GPU 之间的转换。

真实场景基准：SIFT1M

更长的示例会在 SIFT1M 数据集上运行并评估 faiss。运行前，请从 ANN_SIFT1M 数据集来源下载数据，解压到源码目录根部的sift1M子目录，然后编译运行（需先完成 faiss 安装）：

$ make -C build demo_sift1M $ ./build/demos/demo_sift1M

该 demo 演示了高层自动调优（auto-tune）API，可以通过更换index_key来比较不同索引结构的性能。对应源码为 demos/demo_sift1M.cpp。

多索引类型实测：demo_auto_tune.py

以下脚本把demo_sift1M扩展到了多种索引类型，必须在仓库源码根目录执行：

$ mkdir tmp # 输出图会写到这里 $ python demos/demo_auto_tune.py

它会遍历若干类索引并寻找最优工作点，你可以自由调整索引类型组合。脚本入口为 demos/demo_auto_tune.py。

GPU 实测

上述脚本同样支持 GPU：编辑 demos/demo_auto_tune.py（约第 100 行）中的配置为：

keys_to_test = keys_gpu use_gpu = True

然后运行：

$ python demos/demo_auto_tune.py

即可测试 GPU 代码路径。

八、附：C API 构建入口

若需要通过纯 C 接口（供 Rust、Julia 等 FFI 语言绑定使用），在配置时开启-DFAISS_ENABLE_C_API=ON即可随主构建一起编译，具体编译与使用方式见 c_api/INSTALL.md，其中给出了faiss_c、example_c等 make 目标及错误处理（faiss_get_last_error()）的完整示例。

小结

日常使用优先 conda：faiss-cpu（Linux/OSX/Windows）、faiss-gpu（Linux x86-64 + CUDA 11.4/12.1）、faiss-gpu-cuvs（Linux x86-64 + CUDA 13.2 + cuVS 26.06），通道组合pytorch/nvidia/rapidsai/conda-forge缺一不可；nightly 包走pytorch/label/nightly；
源码构建五步走：cmake -B build .（按需传 GPU/SIMD/BLAS/C_API/SVS 选项）→make -C build -j faiss（优化等级下先构建faiss_avx2/faiss_avx512/faiss_avx512_spr）→ 可选swigfaiss+setup.py install→ 可选make install→ 可选make test与 demo 验证；
验证是否装好：跑demo_ivfpq_indexing（约 20s，MKL 下约 2.5s）或demo_sift1M+demo_auto_tune.py做真实数据检验；
前置条件：C++20 编译器（OpenMP ≥ 2）、CMake ≥ 3.24、BLAS（Intel 机器强烈建议 MKL）、GPU 场景需 CUDA toolkit 或 ROCm。

【免费下载链接】faissA library for efficient similarity search and clustering of dense vectors.项目地址: https://gitcode.com/GitHub_Trending/fa/faiss

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

faiss 安装完全指南：从 conda 包到 CMake 源码构建（faiss 1.15.0）