Periplus

Periplus

配x警告：Periplus在Alpha

Periplus目前在Alpha，尚未准备就绪。该项目正在积极开发中，并且不建议用于生产系统。

介绍

Periplus是建立在Meta的Vector相似性搜索库Faiss上的开源内存矢量数据库缓存。该项目最好被视为“ vector数据库的重复”。它旨在将大型矢量集合的动态更新子集存储在内存中，同时在查询时，而无需在查询时间与其他任何节点进行交互。当Periplus收到查询时，它首先评估它是否具有索引居住的相关部分。如果确实如此，它将通过适当的响应解析查询。如果没有，它将返回缓存失误，并让Querier从数据库中获取数据。 Periplus并非设计用于隔离功能。取而代之的是，它旨在形成一个模块化和灵活的缓存层，用于形成持久层的单独矢量数据库。这样做的目的是使较低的延迟和易于水平缩放量表以增加吞吐量。有关Periplus背后的灵感及其工作方式的更详细说明，您可以阅读公告博客：介绍Periplus：矢量数据库缓存的新方法。

它如何工作

Periplus使用倒文件索引（IVF）作为缓存管理的基础。倒文件索引将矢量空间划分为由一组质心向量定义的连续单元，其中每个单元被定义为接近其质心的区域，而不是其他任何质心。然后通过首先计算从查询矢量到质心集的距离来解决查询，然后仅搜索由N_probe （搜索超参数）最接近的质心定义的细胞。 Periplus通过在任何给定时间将这些单元的子集保留在居住中，而仅解决与该子集相关的查询，同时拒绝与不像Cache失误相关的居民，则利用了这一点。 Periplus一次载荷并驱逐整个IVF单元，以维持索引的完整性，并确保（在高速缓存命中）对标准IVF指数（在缓存命中）上进行等效召回。通过通过代理查询矢量数据库，其中periplus维护以跟踪哪些向量占据了哪些细胞，从而加载了IVF单元。这些操作可以由用户使用加载，搜索和驱逐命令来调用。有关详细信息，请参见下面的“ Periplus命令”部分。

运行Periplus

Periplus可以作为Docker容器运行，也可以从源构建并作为可执行文件运行。目前没有官方二进制文件。推荐的方法是运行Periplus作为容器，但两者都是可行的选择。

？作为容器运行Periplus

当前，Docker映像仅支持AMD64架构。这种约束源于基本图像，但在不久的将来将支持更多的架构。有两种将Periplus作为容器运行的方法：从Dockerhub（推荐）下载官方Docker映像或自己构建图像。在任何一种情况下，第一步都是安装Docker，如果您还没有。这样做的说明可以在这里找到。

使用官方图像

1. 通过运行下载图像： docker image pull qdl123/periplus:latest 。
2. 运行容器： docker run -p 3000:3000 qdl123/periplus:latest

构建图像

1. 克隆存储库： git clone https://github.com/QDL123/Periplus.git
2. CD到存储库根： cd <path-to-periplus-repo>/Periplus
3. 构建图像： docker build -t periplus-image .
4. 运行容器： docker run -p 3000:3000 periplus-image .

从来源建造Periplus

Periplus使用CMAKE进行其构建系统。它预计所有依赖性都将通过自制的二进制文件进行预编译。如果您在Windows上，则由MacOS，Ubuntu和WSL支持Homebrew。 Periplus已建立在MacOS/ARM64和Ubuntu/AMD64上。所有其他操作系统和架构组合都未经测试。要从源建立Periplus，请按照以下步骤：

1. 安装自制：访问官方自制网站以获取安装说明。
2. 安装Periplus的依赖关系。要立即安装它们，请运行： brew install faiss curl cpr rapidjson libomp catch2 cmake
3. 克隆存储库： git clone https://github.com/QDL123/Periplus.git
4. CD到存储库根： cd <path-to-periplus-repo>/Periplus
5. 生成makefile： cmake -S . -B build
6. 编译可执行文件： cmake --build build
7. 运行periplus（在端口3000上听）： ./build/periplus -p 3000

使用Periplus

使用Periplus的任何系统都将由4个组件组成：矢量数据库，一个数据库代理，该数据库代理允许Periplus从数据库，Periplus实例和客户端应用程序中加载数据。

使用Periplus的应用程序的示例体系结构。

向量数据库

任何允许通过唯一标识符（几乎全部）查找数据的矢量数据库都将起作用。 Periplus的设计是在与真正的大型矢量集合（十亿个尺度）合作时最有益的，该指数必须在文件系统上而不是RAM，尽管这不是必需的。

向量数据库代理

向量数据库代理的目的是为Periplus提供与矢量数据库通过的一致接口。代理必须实现一个REST接口，该接口接受以下表格的发布请求：

URL：这是灵活的，可以由Periplus客户端指定。

标题： "Content-Type": "application/json

身体：

{
    "ids" : [ " id-1 " , " id-2 " , " id-3 " ]
}

回复：

{
    "results" : [
        {
            "id" : " String " ,
            "embedding" : [ 0.1 , 0.2 , 0.3 ],
            "document" : " String " ,
            "metdata" : " String "
        }
    ]
}

为了使实现此端点更容易，您可以使用Periplus-Proxy Python软件包，该软件包使用FastApi来设置所有内容。用户所要做的就是实现以下功能，并将其作为参数传递：

async def fetch_ids(request: Query) -> QueryResult

有关如何执行此操作的详细信息，您可以查看Periplus-Proxy软件包readme.md。

Periplus

请按照上述说明启动Periplus实例。

客户端应用程序

要与您的Periplus实例进行交互，请使用Periplus客户端库。目前仅支持Python。有关客户端库的详细信息，您可以查看其readme.md。

Periplus命令

1. 初始化：这是Periplus的设置命令。必须在任何其他命令和任何后续初始化调用之前擦除所有数据并重置Periplus实例。有2个必需的参数：d（矢量集合的维度）和db_url（数据库代理端点的URL用于加载数据）。还有一个可选的选项对象参数，其中有2个可用选项： ntotal和use_flat 。第一个， NTOTAL ，是对藏品中向量总数的估计。这用于优化要使用的IVF单元的数量。如果未指定，Periplus将选择可能导致次优性能的中间立场。第二个是Use_flat ，是一个布尔值，它指示Periplus使用平面索引，而不是应用任何产品量化（PQ）。默认情况下，此值是错误的，在这种情况下，如果向量足够大且易于将其分解为子向量，则将应用产品量化。如果设置为true，则将使用平坦的IVF索引。
2. 火车：此命令设置了构成缓存基础的IVF索引中质心的位置。一旦设置了质心位置，就无法完全擦拭缓存，就无法重置它们。它将向量嵌入的列表作为参数，应该是您的向量集合的代表性示例。建议最多使用总收集的10％，但是对于真正的大数据集来说，可以使用少于10％的Periplus实例。
3. 补充：此命令使Periplus意识到数据，而无需实际填充缓存，因此可以从数据库中加载它。 Periplus应该首先加载的任何向量都需要通过Add命令注册。该命令采用两个参数ID和嵌入，它们是具有向量ID和相应向量嵌入的相等长度的列表。
4. 加载：此命令指示Periplus从数据库中加载IVF单元格（S）（请参阅其工作方式）。它具有一个必需的参数，一个向量告诉它要靶向的单元格，以及一个可选的选项对象，其中一个可用的选项n_load ，它告诉它加载了多少个单元格。 Periplus将从数据库加载最近的N_load单元格到向量（如果未指定的话，N_load默认值为1）。这确保了具有相同向量的后续搜索命令将产生缓存命中（假设尚未事先驱逐单元格，并且N_load参数与搜索中给出的N_probe参数匹配）。
5. 搜索：此命令针对Periplus中存储的数据运行一组查询。它需要2个必需的参数： k指定返回最近邻居的数量， xq是查询向量列表。它可以选择采用一个选项对象，其中有两个可用的选项： N_Probe和require_all 。第一个指定要搜索多少IVF单元。较大的值导致延迟增加，但也增加了回忆（使用recure_all时，缓存率较低）。如果未指定，则默认值为1。第二个选项require_all是一个布尔值，它决定了缓存命中/错过行为。如果设置为true，则所有N_probe最近的单元格必须在驻留式中才能使查询成为缓存。如果是错误的，则只有最近的IVF单元才能在驻留式中是缓存的命中率，而Periplus将搜索IVF细胞在最接近的IVF细胞的N_probe始终存在的。默认值是正确的。搜索命令返回文档列表的列表，其中每个列表对应于该索引上提供的相应查询向量的K结果。缓存误差将具有长度为0的列表。在极少数情况下，如果长度为> 0和<k，则表明最近的N_probe细胞中的向量总数为<k。每个文档元组都有4个字段：ID，嵌入，元数据和文档，它们将在加载数据时对数据库代理提供的值。
6. 驱逐：此命令的工作原理与负载完全相同，但如果它们从Periplus出现而不是加载它们，则驱逐IVF单元格。它具有一个必需的灌溉，一个矢量告诉它要靶向的单元格，并且具有可用选项的可选选项对象n_evict whch告诉它要驱逐多少个单元。 Periplus将从Periplus驱逐与最接近的N_EVICT质心相对应的单元格（N_EVICT默认为1个未指定）。

例子

 from periplus_client import Periplus

# host, port
client = Periplus ( "localhost" , 13 )

# vector dimensionality, database proxy url, options: (nTotal)
await client . initialize ( d = d , db_url = url , options = { "nTotal" : 50000 })

training_data = [[ 0.43456 , ..., 0.38759 ], ...]
await client . train ( training_data )

ids = [ "0" , ..., "n" ]
embeddings = [[ 0.43456 , ..., 0.38759 ], ...]
await client . add ( ids = ids , embeddings = embeddings )

load_options = { "n_load" : 2 }
# query_vector, optional: options object
await client . load ([ embeddings [ 0 ]] load_options )

# k, query_vector
response = await client . search ( 5 , [ embeddings [ 0 ]])
print ( response )
'''
[ // Results for each of the n query vectors in xq
    [ // K nearest neighbors to this corresponding index in the xq list
        (
            id="n",
            embedding=[0.43456, ..., 0.38759],
            document="",
            metadata="{}"
        ),
        ...
    ],
    ...
]
'''

# query_vector
await client . evict ( embeddings [ 0 ])

基准测试

即将推出！

贡献

我们欢迎对Periplus的贡献！要了解如何入门，请查看贡献指南。

执照

该项目是根据MIT许可证获得许可的 - 有关详细信息，请参见许可证文件。