AutoFaiss

自动创建具有最优相似性搜索参数的Faiss knn索引。

它选择最佳的索引参数，以在内存和查询速度限制下实现最高的召回率。

文档、文章和笔记本

使用faiss高效索引、二分搜索和启发式方法，Autofaiss可以在3小时内自动构建一个大型（2亿个向量，1TB）KNN索引，只需要很少的内存（15 GB），并且查询延迟仅为毫秒级（10ms）。

通过运行这个Colab笔记本开始使用，然后查看完整文档。 通过这个Colab笔记本了解自动索引选择功能的一些见解。

然后你可以查看我们的多模态搜索示例（使用OpenAI Clip模型）。

阅读Medium文章以了解更多信息！

安装

运行pip install autofaiss进行安装

最好创建一个虚拟环境：

python -m venv .venv/autofaiss_env
source .venv/autofaiss_env/bin/activate
pip install -U pip
pip install autofaiss

在Python中使用autofaiss

如果你想直接在Python中使用autofaiss，请查看API文档和示例

特别是，你可以使用autofaiss处理内存中或磁盘上的嵌入集合：

使用内存中的numpy数组

如果你有少量嵌入，可以使用autofaiss处理内存中的numpy数组：

from autofaiss import build_index
import numpy as np

embeddings = np.float32(np.random.rand(100, 512))
index, index_infos = build_index(embeddings, save_on_disk=False)

query = np.float32(np.random.rand(1, 512))
_, I = index.search(query, 1)
print(I)

使用保存为.npy文件的numpy数组

如果你有大量嵌入文件，最好将它们保存在磁盘上作为.npy文件，然后像这样使用autofaiss：

from autofaiss import build_index

build_index(embeddings="embeddings", index_path="my_index_folder/knn.index",
            index_infos_path="my_index_folder/index_infos.json", max_index_memory_usage="4G",
            current_memory_available="4G")

内存映射索引

Faiss可以使用内存映射索引。当你不需要快速搜索时间（>50ms）并且仍然想将内存占用降到最低时，这非常有用。

我们在build_index函数中提供了should_be_memory_mappable布尔值，用于仅生成内存映射索引。 注意：在faiss中，只有IVF索引可以进行内存映射，因此输出索引将是IVF索引。

要以内存映射模式加载索引，请使用以下代码：

import faiss
faiss.read_index("my_index_folder/knn.index", faiss.IO_FLAG_MMAP | faiss.IO_FLAG_READ_ONLY)

你可以查看示例了解如何使用它。

技术说明：你可以通过index.make_direct_map()（或直接从build_index函数通过传递make_direct_map布尔值）在IVF索引上创建直接映射。这样做会大大加快.reconstruct()方法的速度，该方法可以根据向量的排名给出其值。 然而，这个映射将存储在RAM中...我们建议你在内存映射的numpy数组中创建自己的直接映射，然后使用你的自定义direct_map调用.reconstruct_from_offset()。

在pyspark中使用autofaiss

Autofaiss允许你使用Spark构建索引，适用于以下两种用例：

• 以分布式方式构建大型索引
• 针对分区的嵌入数据集，并行且分布式地为每个分区构建一个索引。

先决条件：

1. 安装pyspark：pip install pyspark。
2. 准备你的嵌入文件（分区或非分区）。
3. 在调用autofaiss之前创建一个Spark会话。如果不存在Spark会话，将创建一个具有最小配置的默认会话。

以分布式方式创建大型索引

完整指南请参见distributed_autofaiss.md。

可以生成一个需要比可用内存更多内存的索引。为此，你可以通过nb_indices_to_keep控制组成索引的索引拆分数量。 例如，如果nb_indices_to_keep为10，index_path为knn.index，最终索引将分解为10个较小的索引：

• knn.index01
• knn.index02
• knn.index03
• ...
• knn.index10

具体示例展示了如何生成N个索引以及如何使用它们。

创建分区索引

对于分区的嵌入数据集，可以通过调用build_partitioned_indexes方法为每个分区创建一个索引。

请查看这个示例，了解如何创建分区索引。

使用命令行

创建嵌入

import os
import numpy as np
embeddings = np.random.rand(1000, 100)
os.mkdir("embeddings")
np.save("embeddings/part1.npy", embeddings)
os.mkdir("my_index_folder")

生成Knn索引

autofaiss build_index --embeddings="embeddings" --index_path="my_index_folder/knn.index" --index_infos_path="my_index_folder/index_infos.json" --metric_type="ip"

尝试使用索引

import faiss
import glob
import numpy as np

my_index = faiss.read_index(glob.glob("my_index_folder/*.index")[0])

query_vector = np.float32(np.random.rand(1, 100))
k = 5
distances, indices = my_index.search(query_vector, k)

print(list(zip(distances[0], indices[0])))

索引是如何选择的？

要更好地理解为什么选择这些索引以及它们的特征是什么，请查看索引选择演示

命令快速概览

autofaiss build_index命令的简要描述：

embeddings -> 以numpy格式存储的嵌入源路径。 index_path -> 创建的索引的目标路径。 index_infos_path -> 索引信息的目标路径。 save_on_disk -> 将索引保存在磁盘上。 metric_type -> 查询的相似度距离。 index_key -> （可选）描述要构建的索引。 index_param -> （可选）描述索引的超参数。 current_memory_available -> （可选）描述机器上可用的内存量。 use_gpu -> （可选）是否使用 GPU（未经测试）。

命令详情

autofaiss build_index 命令接受以下参数：

可用标志	默认值	描述
--embeddings	必需	包含 .npy 嵌入文件的目录（或目录列表）。如果有多个文件，它们将按字典顺序读取。可以是本地路径或其他文件系统中的路径，如 hdfs://root/... 或 s3://...
--index_path	必需	本地机器上 faiss 索引的目标路径。
--index_infos_path	必需	本地机器上 faiss 索引信息的目标路径。
--save_on_disk	必需	将索引保存到磁盘。
--file_format	"npy"	嵌入文件的文件格式。可以是 npy（用于 numpy 矩阵文件）或 parquet（用于 parquet 序列化表）
--embedding_column_name	"embeddings"	仅在 file_format=parquet 时需要。在这种情况下，这是包含嵌入的列的名称（每行一个向量）
--id_columns	无	仅在 file_format=parquet 时可用。在这种情况下，这些是包含向量 ID 的列的名称，将生成单独的文件以将这些 ID 映射到 KNN 索引中的索引
--ids_path	无	仅在 id_columns 不为 None 且 file_format=parquet 时有用。这将是存储 ID->向量索引映射文件（以 parquet 格式）的路径（在任何文件系统中）
--metric_type	"ip"	（可选）用于查询的相似度函数：（"ip" 表示内积，"l2" 表示欧几里得距离）
--max_index_memory_usage	"32GB"	（可选）创建的索引的最大大小（以 GB 为单位），此限制是严格的。
--current_memory_available	"32GB"	（可选）创建索引的机器上可用的内存（以 GB 为单位），拥有更多内存是一种提升，因为它减少了 RAM 和磁盘之间的交换。
--max_index_query_time_ms	10	（可选）KNN 搜索的查询时间限制，此限制是近似的。
--min_nearest_neighbors_to_retrieve	20	（可选）查询索引时要检索的最小最近邻数。此参数仅在索引超参数微调步骤中使用，不考虑选择索引算法。此参数优先于 max_index_query_time_ms 约束。
--index_key	无	（可选）如果存在，Faiss 索引将使用此描述字符串在 index_factory 中构建，更多详情请参阅 Faiss 文档
--index_param	无	（可选）如果存在，Faiss 索引将使用此超参数描述字符串进行设置，更多详情请参阅 Faiss 文档
--use_gpu	False	（可选）实验性功能，GPU 训练可能更快，但目前尚未测试此功能。
--nb_cores	无	（可选）要使用的核心数，默认将使用所有核心
--make_direct_map	False	（可选）创建允许重建嵌入的直接映射。这仅对 IVF 索引需要。请注意，这可能会增加 RAM 使用量（10 亿个嵌入约为 8GB）。
--should_be_memory_mappable	False	（可选）用于强制从具有磁盘上内存映射实现的索引中选择索引的布尔值。
--distributed	无	（可选）如果为 "pyspark"，则使用 pyspark 创建索引。否则，索引将在本地机器上创建。
--temporary_indices_folder	"hdfs://root/tmp/distributed_autofaiss_indices"	（可选）保存临时小索引的文件夹，仅在 distributed = "pyspark" 时使用
--verbose	20	（可选）设置日志输出的详细程度：DEBUG=10，INFO=20，WARN=30，ERROR=40，CRITICAL=50
--nb_indices_to_keep	1	（可选）当 distributed 为 "pyspark" 时最多保留的索引数量。

从源代码安装

首先，创建一个虚拟环境并安装依赖项：

python3 -m venv .env
source .env/bin/activate
make install

python -m pytest -x -s -v tests -k "test_get_optimal_hyperparameters" 运行特定测试