Faiss

Faiss 是一个用于高效相似性搜索和稠密向量聚类的库。它包含可在任意规模向量集合上进行搜索的算法，甚至适用于可能无法完全加载到内存中的大规模数据集。此外，Faiss 还提供了评估和参数调优的相关支持代码。Faiss 使用 C++ 编写，并为 Python/numpy 提供了完整的封装。其中一些最实用的算法已在 GPU 上实现。该库主要由 Meta 的 Fundamental AI Research 团队开发。

新闻

有关最新功能的详细信息，请参阅 CHANGELOG.md。

简介

Faiss 提供了多种相似性搜索方法。它假设实例以向量形式表示，并通过整数标识；同时，这些向量可以使用 L2（欧几里得）距离或点积进行比较。与查询向量相似的向量是指那些与查询向量具有最小 L2 距离或最大点积的向量。Faiss 也支持余弦相似度，因为这实际上是在归一化向量上的点积。

部分方法，例如基于二进制向量和紧凑量化码的方法，仅使用向量的压缩表示，无需保留原始向量。虽然这通常会降低搜索精度，但这些方法可以在单台服务器的主内存中扩展至数十亿个向量。其他方法，如 HNSW 和 NSG，则在原始向量之上构建索引结构，以提高搜索效率。

GPU 实现既可以接受来自 CPU 内存的数据，也可以接受来自 GPU 内存的数据。在配备 GPU 的服务器上，GPU 索引可以作为 CPU 索引的直接替代品（例如，将 IndexFlatL2 替换为 GpuIndexFlatL2），并且 GPU 内存之间的数据拷贝会自动处理。然而，如果输入和输出都保留在 GPU 上，性能将会更快。Faiss 支持单 GPU 和多 GPU 使用。

安装

Faiss 为 Anaconda 提供了预编译的 Python 库，包括 faiss-cpu、faiss-gpu 和 faiss-gpu-cuvs。该库主要用 C++ 实现，唯一的依赖是 BLAS 实现。可选的 GPU 支持通过 CUDA 或 AMD ROCm 提供，Python 接口也是可选的。NVIDIA 的 cuVS 后端 GPU 实现也可以选择启用。Faiss 使用 cmake 进行编译。更多详情请参阅 INSTALL.md。

Faiss 的工作原理

Faiss 以一种索引类型为核心，该索引类型存储一组向量，并提供基于 L2 距离和/或点积比较的搜索功能。一些索引类型较为简单，例如精确搜索。大多数可用的索引结构代表了以下方面的权衡：

• 搜索时间
• 搜索质量
• 每个索引向量占用的内存
• 训练时间
• 添加时间
• 是否需要无监督训练的外部数据

可选的 GPU 实现提供了目前（截至 2017 年 3 月）针对高维向量的最快精确和近似（压缩域）最近邻搜索实现、最快的 Lloyd k-means 算法以及已知最快的 k 最小值选择算法。具体实现细节请参见此处。

Faiss 的完整文档

以下是 Faiss 文档的入口：

• 完整文档可在 wiki 页面 上找到，包括 教程、常见问题解答 和 故障排除部分。
• Doxygen 文档 提供从代码注释中提取的类级信息。
• 若要复现我们的研究论文结果，包括 多义编码 和 使用 GPU 的十亿级相似性搜索，请参考 基准测试 README。对于 链接与代码：基于图和紧凑回归码的快速索引，请参阅 link_and_code README。

作者

Faiss 的主要作者如下：

• Hervé Jégou 发起了 Faiss 项目并编写了其首个实现。
• Matthijs Douze 实现了大部分 CPU 版本的 Faiss。
• Jeff Johnson 实现了全部 GPU 版本的 Faiss。
• Lucas Hosseini 实现了二进制索引和构建系统。
• Chengqi Deng 实现了 NSG、NNdescent 以及大量加性量化代码。
• Alexandr Guzhva 负责多项优化工作，包括 SIMD、内存分配与布局、向量编解码器的快速解码内核等。
• Gergely Szilvasy 负责构建系统和基准测试框架。

参考文献

在研究论文中使用 Faiss 时，请引用以下文献：

@article{douze2024faiss,
      title={The Faiss library},
      author={Matthijs Douze and Alexandr Guzhva and Chengqi Deng and Jeff Johnson and Gergely Szilvasy and Pierre-Emmanuel Mazaré and Maria Lomeli and Lucas Hosseini and Hervé Jégou},
      year={2024},
      eprint={2401.08281},
      archivePrefix={arXiv},
      primaryClass={cs.LG}
}

对于 Faiss 的 GPU 版本，请引用：

@article{johnson2019billion,
  title={Billion-scale similarity search with {GPUs}},
  author={Johnson, Jeff and Douze, Matthijs and J{\'e}gou, Herv{\'e}},
  journal={IEEE Transactions on Big Data},
  volume={7},
  number={3},
  pages={535--547},
  year={2019},
  publisher={IEEE}
}

加入 Faiss 社区

如需公开讨论 Faiss 或提出问题，请访问 https://github.com/facebookresearch/faiss/discussions。

我们也会监控仓库的 问题页面，您可以在那里报告 bug、提问等。

法律声明

Faiss 采用 MIT 许可证授权，详情请参阅顶级目录下的 LICENSE 文件。

版权所有 © Meta Platforms, Inc.

Faiss 快速上手指南

Faiss 是一个由 Meta 开发的高效稠密向量相似度搜索与聚类库。它支持在海量向量集（甚至超出内存容量）中进行快速检索，提供多种索引算法以平衡搜索速度、精度和内存占用，并原生支持 GPU 加速。

环境准备

• 操作系统：Linux (推荐), macOS, Windows (部分功能受限)
• 语言环境：Python 3.8+ (推荐通过 Anaconda/Miniconda 管理)
• 核心依赖：
  • CPU 版本：仅需基础 Python 环境，底层依赖 BLAS 线性代数库（Conda 包已内置）。
  • GPU 版本：需要 NVIDIA GPU 及对应的 CUDA Toolkit，或 AMD GPU 及 ROCm 环境。
• 硬件建议：处理亿级向量时建议配备大容量内存；追求极致速度建议使用 NVIDIA GPU。

安装步骤

推荐使用 Conda 进行安装，这是最简便且依赖冲突最少的方式。国内用户可使用清华或中科大镜像源加速下载。

1. 配置国内镜像源 (可选但推荐)

conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free/
conda config --set show_channel_urls yes

2. 安装 CPU 版本

适用于无 GPU 环境或中小规模数据检索。

conda install -c pytorch faiss-cpu

3. 安装 GPU 版本

适用于拥有 NVIDIA GPU 的环境，可大幅提升检索和训练速度。

conda install -c pytorch -c nvidia faiss-gpu

(注：若使用 AMD ROCm 环境，请参考官方文档安装 faiss-gpu-rocm)

基本使用

以下示例演示如何构建一个简单的扁平化索引（Exact Search），添加向量数据，并执行相似度搜索。

import numpy as np
import faiss

# 1. 准备数据
# 假设我们有 1000 条数据，每条数据是 128 维的浮点向量 (float32)
d = 128                           # 向量维度
nb = 1000                         # 数据库向量数量
np.random.seed(1234)              # 设置随机种子以保证结果可复现
xb = np.random.random((nb, d)).astype('float32')
# Faiss 要求向量矩阵行对齐，通常不需要额外操作，但确保是 float32 类型至关重要

# 2. 创建索引
# 使用 L2 距离 (欧几里得距离) 的暴力搜索索引
index = faiss.IndexFlatL2(d)      

# 3. 添加向量到索引
print(f"索引初始数量：{index.ntotal}")
index.add(xb)                     
print(f"添加后数量：{index.ntotal}")

# 4. 执行搜索
# 假设有 5 条查询向量
nq = 5
xq = np.random.random((nq, d)).astype('float32')

k = 4                             # 返回每个查询最近的 4 个邻居
D, I = index.search(xq, k)        # D: 距离矩阵，I: 索引编号矩阵

# 5. 查看结果
print("查询向量的最近邻索引编号:")
print(I)
print("对应的距离值:")
print(D)

进阶提示：

• 若需使用余弦相似度，请先对向量进行归一化处理 (faiss.normalize_L2)，然后使用 IndexFlatIP (内积)。
• 对于大规模数据（百万/亿级），请探索 IndexIVFFlat、IndexHNSW 等近似搜索索引以节省内存并提升速度。
• 启用 GPU 加速只需将索引类替换为 faiss.GpuIndexFlatL2 (需先初始化 GpuResources)。