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 索引Linuxx86-64 与 aarch64、OSX仅 arm64、Windowsx86-64faiss-gpuCPU GPUCUDA索引仅 Linux x86-64CUDA 11.4 与 12.1faiss-gpu-cuvsCPU 基于 NVIDIA cuVS 26.06 的 GPU 索引仅 Linux x86-64CUDA 13.2AMD ROCm 的 GPU 包目前尚未提供只能从源码构建见后文FAISS_ENABLE_ROCM。安装最新稳定版# CPU-only version $ conda install -c pytorch -c conda-forge faiss-cpu1.15.0 # GPU(CPU) version $ conda install -c pytorch -c nvidia -c conda-forge faiss-gpu1.15.0 # GPU(CPU) version with NVIDIA cuVS $ conda install -c pytorch -c nvidia -c rapidsai -c conda-forge libnvjitlink faiss-gpu-cuvs1.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.34Linux x86-64 还依赖libsvs-runtime 0.4.0nvidia通道对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-cpu1.15.0 # GPU(CPU) version $ pixi init -c pytorch -c nvidia -c conda-forge $ pixi add faiss-gpu1.15.0 # GPU(CPU) version with NVIDIA cuVS $ pixi init -c pytorch -c nvidia -c rapidsai -c conda-forge $ pixi add libnvjitlink faiss-gpu-cuvs1.15.0Pixi 从所列 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-gpu1.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-version13.2 # GPU(CPU) version using AMD ROCm not yet available在以上命令中可通过pytorch-cuda11或pytorch-cuda12指定特定 CUDA 版本如有需要。一个可安装 GPU 版 faiss 并配套 CUDA PyTorch 的版本组合示例INSTALL.md 给出截至 2024-05-15conda create --name faiss_1.8.0 conda activate faiss_1.8.0 conda install -c pytorch -c nvidia faiss-gpu1.8.0 pytorch**cuda* pytorch-cuda11 numpy二、源码构建的基本前提faiss 支持在 Linux、OSX、Windows 的 x86-64 机器上从源码构建CMake 驱动在其他平台上也有人成功运行。构建的基本需求与可选需求如下来自 INSTALL.md基本需求一个C20 编译器支持 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 toolkitAMD GPUAMD ROCm使用 NVIDIA cuVS 实现libcuvs26.06Python 绑定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 libcuvs26.06 cuda-version13.2更多 cuVS 26.06 安装方式可参考 RAPIDS 官方安装指南。在 CMake 侧启用方式见下文的-DFAISS_ENABLE_CUVSON从源码结构看启用后顶层 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_SVSON时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_GPUOFF禁用 GPU 索引构建ON/OFFON见 CMakeLists.txt-DFAISS_ENABLE_PYTHONOFF禁用 Python 绑定ON/OFFON-DFAISS_ENABLE_CUVSON启用 cuVS 的 IVF-Flat、IVF-PQ 与 CAGRA GPU 加速索引注意启用时FAISS_ENABLE_GPU必须为ONOFF-DBUILD_TESTINGOFF禁用 C 测试构建由 CTest 决定-DBUILD_SHARED_LIBSON构建动态库libfaiss.so默认构建静态库libfaiss.aOFF-DFAISS_ENABLE_C_APION启用 C API 构建OFF-DFAISS_ENABLE_SVSON启用 Intel SVS 集成会下载并构建 SVS runtimelibsvs_runtime.so。安装 Python 包时该库会被复制进包目录C 使用需保证该库在库搜索路径中OFF其中 GPU 选项在 CMakeLists.txt 中还会根据FAISS_ENABLE_ROCM决定启用 HIPROCm还是 CUDA 语言ROCm 路径下会执行 faiss/gpu/hipify.sh 对 CUDA 源码做 HIP 化转换并find_package(HIP/hipBLAS)。优化相关选项选项说明-DCMAKE_BUILD_TYPERelease启用通用编译优化如 gcc 的-O3-DFAISS_OPT_LEVELlevel开启生成优化 SIMD/向量指令所需的编译器标志。x86-64 取值按优化程度递增为generic、avx2、avx512、avx512_sprSapphire Rapids 起可用的 AVX-512 特性aarch64 取值为generic与sve-DFAISS_USE_LTOON启用链接期优化LTOFAISS_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_VENDORIntel10_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_ARCHITECTURES75;72指定目标 GPU 架构按显卡查 CUDA GPU 列表-DFAISS_ENABLE_ROCMON启用 AMD GPU 索引构建要求FAISS_ENABLE_GPU为ONPython 相关选项-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_LIBSON则生成libfaiss.so。-j开启多单元并行编译以加速构建但会增大内存占用风险建议内存吃紧时固定线程数如-j4。如果使用优化选项构建 swigfaiss 之前要先构建对应的优化目标# AVX2 $ make -C build -j faiss_avx2 # AVX512 $ make -C build -j faiss_avx512 # AVX512Sapphire 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.2Linux/macOS 使用 cp310 abi3 稳定 ABI作为源码发行 Python 包的替代路径。六、Step 4安装 C 库与头文件可选$ make -C build install这将把编译产物Linux 下为libfaiss.a或libfaiss.so与 C 头文件安装到系统范围。如果只装 Python 包此步骤不需要。七、Step 5测试与验证运行 C 测试套件确保 CMake 以-DBUILD_TESTINGON调用然后$ 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.txtEXCLUDE_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-tuneAPI可以通过更换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_APION即可随主构建一起编译具体编译与使用方式见 c_api/INSTALL.md其中给出了faiss_c、example_c等 make 目标及错误处理faiss_get_last_error()的完整示例。小结日常使用优先 condafaiss-cpuLinux/OSX/Windows、faiss-gpuLinux x86-64 CUDA 11.4/12.1、faiss-gpu-cuvsLinux 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→ 可选swigfaisssetup.py install→ 可选make install→ 可选make test与 demo 验证验证是否装好跑demo_ivfpq_indexing约 20sMKL 下约 2.5s或demo_sift1Mdemo_auto_tune.py做真实数据检验前置条件C20 编译器OpenMP ≥ 2、CMake ≥ 3.24、BLASIntel 机器强烈建议 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）
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 索引Linuxx86-64 与 aarch64、OSX仅 arm64、Windowsx86-64faiss-gpuCPU GPUCUDA索引仅 Linux x86-64CUDA 11.4 与 12.1faiss-gpu-cuvsCPU 基于 NVIDIA cuVS 26.06 的 GPU 索引仅 Linux x86-64CUDA 13.2AMD ROCm 的 GPU 包目前尚未提供只能从源码构建见后文FAISS_ENABLE_ROCM。安装最新稳定版# CPU-only version $ conda install -c pytorch -c conda-forge faiss-cpu1.15.0 # GPU(CPU) version $ conda install -c pytorch -c nvidia -c conda-forge faiss-gpu1.15.0 # GPU(CPU) version with NVIDIA cuVS $ conda install -c pytorch -c nvidia -c rapidsai -c conda-forge libnvjitlink faiss-gpu-cuvs1.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.34Linux x86-64 还依赖libsvs-runtime 0.4.0nvidia通道对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-cpu1.15.0 # GPU(CPU) version $ pixi init -c pytorch -c nvidia -c conda-forge $ pixi add faiss-gpu1.15.0 # GPU(CPU) version with NVIDIA cuVS $ pixi init -c pytorch -c nvidia -c rapidsai -c conda-forge $ pixi add libnvjitlink faiss-gpu-cuvs1.15.0Pixi 从所列 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-gpu1.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-version13.2 # GPU(CPU) version using AMD ROCm not yet available在以上命令中可通过pytorch-cuda11或pytorch-cuda12指定特定 CUDA 版本如有需要。一个可安装 GPU 版 faiss 并配套 CUDA PyTorch 的版本组合示例INSTALL.md 给出截至 2024-05-15conda create --name faiss_1.8.0 conda activate faiss_1.8.0 conda install -c pytorch -c nvidia faiss-gpu1.8.0 pytorch**cuda* pytorch-cuda11 numpy二、源码构建的基本前提faiss 支持在 Linux、OSX、Windows 的 x86-64 机器上从源码构建CMake 驱动在其他平台上也有人成功运行。构建的基本需求与可选需求如下来自 INSTALL.md基本需求一个C20 编译器支持 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 toolkitAMD GPUAMD ROCm使用 NVIDIA cuVS 实现libcuvs26.06Python 绑定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 libcuvs26.06 cuda-version13.2更多 cuVS 26.06 安装方式可参考 RAPIDS 官方安装指南。在 CMake 侧启用方式见下文的-DFAISS_ENABLE_CUVSON从源码结构看启用后顶层 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_SVSON时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_GPUOFF禁用 GPU 索引构建ON/OFFON见 CMakeLists.txt-DFAISS_ENABLE_PYTHONOFF禁用 Python 绑定ON/OFFON-DFAISS_ENABLE_CUVSON启用 cuVS 的 IVF-Flat、IVF-PQ 与 CAGRA GPU 加速索引注意启用时FAISS_ENABLE_GPU必须为ONOFF-DBUILD_TESTINGOFF禁用 C 测试构建由 CTest 决定-DBUILD_SHARED_LIBSON构建动态库libfaiss.so默认构建静态库libfaiss.aOFF-DFAISS_ENABLE_C_APION启用 C API 构建OFF-DFAISS_ENABLE_SVSON启用 Intel SVS 集成会下载并构建 SVS runtimelibsvs_runtime.so。安装 Python 包时该库会被复制进包目录C 使用需保证该库在库搜索路径中OFF其中 GPU 选项在 CMakeLists.txt 中还会根据FAISS_ENABLE_ROCM决定启用 HIPROCm还是 CUDA 语言ROCm 路径下会执行 faiss/gpu/hipify.sh 对 CUDA 源码做 HIP 化转换并find_package(HIP/hipBLAS)。优化相关选项选项说明-DCMAKE_BUILD_TYPERelease启用通用编译优化如 gcc 的-O3-DFAISS_OPT_LEVELlevel开启生成优化 SIMD/向量指令所需的编译器标志。x86-64 取值按优化程度递增为generic、avx2、avx512、avx512_sprSapphire Rapids 起可用的 AVX-512 特性aarch64 取值为generic与sve-DFAISS_USE_LTOON启用链接期优化LTOFAISS_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_VENDORIntel10_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_ARCHITECTURES75;72指定目标 GPU 架构按显卡查 CUDA GPU 列表-DFAISS_ENABLE_ROCMON启用 AMD GPU 索引构建要求FAISS_ENABLE_GPU为ONPython 相关选项-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_LIBSON则生成libfaiss.so。-j开启多单元并行编译以加速构建但会增大内存占用风险建议内存吃紧时固定线程数如-j4。如果使用优化选项构建 swigfaiss 之前要先构建对应的优化目标# AVX2 $ make -C build -j faiss_avx2 # AVX512 $ make -C build -j faiss_avx512 # AVX512Sapphire 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.2Linux/macOS 使用 cp310 abi3 稳定 ABI作为源码发行 Python 包的替代路径。六、Step 4安装 C 库与头文件可选$ make -C build install这将把编译产物Linux 下为libfaiss.a或libfaiss.so与 C 头文件安装到系统范围。如果只装 Python 包此步骤不需要。七、Step 5测试与验证运行 C 测试套件确保 CMake 以-DBUILD_TESTINGON调用然后$ 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.txtEXCLUDE_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-tuneAPI可以通过更换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_APION即可随主构建一起编译具体编译与使用方式见 c_api/INSTALL.md其中给出了faiss_c、example_c等 make 目标及错误处理faiss_get_last_error()的完整示例。小结日常使用优先 condafaiss-cpuLinux/OSX/Windows、faiss-gpuLinux x86-64 CUDA 11.4/12.1、faiss-gpu-cuvsLinux 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→ 可选swigfaisssetup.py install→ 可选make install→ 可选make test与 demo 验证验证是否装好跑demo_ivfpq_indexing约 20sMKL 下约 2.5s或demo_sift1Mdemo_auto_tune.py做真实数据检验前置条件C20 编译器OpenMP ≥ 2、CMake ≥ 3.24、BLASIntel 机器强烈建议 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），仅供参考