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

本文基于 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。