Periplus

Периплас

️ ПРЕДУПРЕЖДЕНИЕ: Периплас находится в Альфе

Periplus в настоящее время находится в Альфе и не готов к производству. Проект находится в активной разработке и еще не рекомендуется для использования в производственных системах.

Введение

Periplus-это кэш векторной базы данных с открытым исходным кодом, созданный в библиотеке поиска вектора сходства Meta Faiss. Проект лучше всего можно рассматривать как «Redis для векторных баз данных». Он предназначен для хранения динамически обновленного подмножества большой векторной коллекции, полностью в памяти, когда обслуживает запросы, не взаимодействуя с любыми другими узлами во время запроса. Когда Periplus получает запрос, он сначала оценивает, имеет ли он соответствующую часть индекса в резиденции. Если это так, он разрешает запрос с соответствующим ответом. Если это не так, он возвращает кеш -промальку и оставляет Querier для извлечения данных из базы данных. Periplus не предназначен для функционирования изоляции. Вместо этого он предназначен для формирования модульного и гибкого уровня кэширования для отдельной векторной базы данных, которая образует уровень стойкости. Цель этого состоит в том, чтобы обеспечить более низкую задержку и легкое горизонтальное масштабирование для увеличения пропускной способности. Для более подробного описания вдохновения Periplus и того, как он работает, вы можете прочитать блог объявлений: Представление Periplus: новый подход к кэшированию векторной базы данных.

Как это работает

Periplus использует индекс инвертированного файла (ЭКО) в качестве основы для управления кэшем. Индексы инвентаризации файла разделяют векторное пространство на смежные ячейки, определяемые набором центроидных векторов, где каждая ячейка определяется как область, которая ближе к ее центре, чем к любому другому центру. Затем запросы разрешаются путем сначала вычисления расстояний от вектора запроса до набора центроидов, а затем поиска только ячейки, определяемые ближайшими центроидами N_PROBE (поиск гиперпараметра). Periplus использует это, сохраняя подмножество этих ячеек в резиденции в любой момент времени и разрешив только запросы, которые имеют отношение к этому подмножеству, отвергая те, которые не так, как кеш не пропускает. Periplus загружает и выдвигает целые ячейки ЭКО за раз, чтобы поддерживать целостность индекса и обеспечить эквивалентный отзыв (в кэшах) для стандартного индекса ЭКО. Клетки ЭКО загружаются путем запроса векторной базы данных через прокси со списком идентификаторов векторов, которые Периплас поддерживает для отслеживания того, какие векторы занимают какие ячейки. Эти операции могут быть вызваны пользователем, использующим команды загрузки , поиска и выселения . Для получения подробной информации см. Раздел команд Periplus ниже.

Бег Periplus

Periplus можно запустить в качестве контейнера Docker, либо его можно построить из источника и запустить в качестве исполняемого файла. В настоящее время официальных двоичных файлов не доступно. Запуск Periplus в качестве контейнера является рекомендуемым подходом, но оба являются жизнеспособными вариантами.

? Запуск Periplus в качестве контейнера

В настоящее время изображение Docker поддерживает только архитектуры AMD64. Это ограничение связано с базовым изображением, но в ближайшем будущем будет поддерживаться больше архитектуры. Есть 2 способа запуска Periplus в качестве контейнера: загрузите официальное изображение Docker с Dockerhub (рекомендуется) или создайте изображение самостоятельно. Первый шаг в любом случае - установить 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 использует Cmake для своей системы сборки. Он ожидает, что все зависимости будут установлены предварительно скомпилированные двоичные файлы через Homebrew. Homebrew поддерживается MacOS, Ubuntu и WSL, если вы на Windows. Periplus был построен на MacOS/ARM64 и Ubuntu/AMD64. Все остальные операционные системы и комбинации архитектуры не проверены. Чтобы построить Periplus из источника, выполните следующие шаги:

1. Установите Homebrew: посетите официальный сайт Homebrew здесь для инструкций по установке.
2. Установите зависимости Перипласа. Чтобы установить их все сразу, запустите: 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 предназначен для того, чтобы быть наиболее полезным при работе с действительно большими векторными коллекциями (в миллиардах), где индекс должен жить в файловой системе, в отличие от оперативной памяти, хотя это не является требованием.

Прокси -сервер векторной базы данных

Цель прокси -сервера векторной базы данных состоит в том, чтобы обеспечить постоянный интерфейс для Periplus для взаимодействия с векторной базой данных. Прокси должен реализовать интерфейс REST, который принимает запросы POST в следующей форме:

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 Package Readme.md.

Периплас

Следуйте инструкциям выше, чтобы запустить экземпляр Periplus.

Клиентское приложение

Чтобы взаимодействовать с вашим экземпляром Periplus, используйте клиентскую библиотеку Periplus. В настоящее время поддерживается только Python. Для получения подробной информации о клиентской библиотеке вы можете просмотреть его readme.md.

Команды Periplus

1. Инициализация : это команда настройки для Periplus. Он должен быть вызван перед любой другой командой, и любые последующие инициализированные вызовы будут уничтожать все данные и сбросить экземпляр Periplus. Существует 2 требуемых аргументов: D (размерность векторной сбора) и DB_URL (URL -адрес конечной точки прокси -концерта базы данных, используемый для загрузки данных). Существует также дополнительный аргумент объекта параметров с 2 доступными параметрами: ntotal и use_flat . Первый, нтотальный , является оценкой общего числа векторов в коллекции. Это используется для оптимизации количества ячеек ЭКО для использования. Если не указано, Periplus выберет среднюю землю, которая может привести к неоптимальной производительности. Второй, USE_FLAT , - это логический, который инструктирует Periplus использовать плоский индекс вместо применения любого квантования продукта (PQ). По умолчанию это значение является ложным, и в этом случае квантование продукта будет применяться, если векторы достаточно велики и легко делится на субвекторы. Если вместо этого будет использоваться плоский индекс ЭКО.
2. Поезд : Эта команда устанавливает положение центроидов в индексе ЭКО, которая составляет основу кэша. Как только позиции центроида устанавливаются, они не могут быть сброшены без полного вытирания кэша. Он принимает список векторных встроений в качестве аргумента, который должен быть репрезентативной выборкой вашей векторной коллекции. Рекомендуется использовать до 10% от вашей общей коллекции, но меньше для действительно больших наборов данных, где 10% сокрушит экземпляр Periplus.
3. Добавить : Эта команда рассказывает о Periplus о данных без заполнения кэша, чтобы позже можно было загрузить из базы данных. Любой вектор, который Periplus должен быть в состоянии загружать первым, должен быть зарегистрирован через команду ADD. Команда принимает два идентификатора аргументов и встраивания, которые представляют собой списки равных длины с векторными идентификаторами и соответствующим векторным встраиванием.
4. Нагрузка : эта команда инструктирует Periplus загружать ячейки (ы) ЭКО (см. Подробнее, см. В деталях) из базы данных. У него есть один необходимый аргумент, вектор, рассказывающий ему, какие ячейки нацелены, и дополнительный объект опций с одним доступным вариантом n_load , который сообщает, сколько ячеек загружать. Periplus загрузит ближайшие ячейки N_LOAD в вектор из базы данных (n_load по умолчанию на 1, если не указано). Это гарантирует, что последующая команда поиска с тем же вектором даст удар в кеш (при условии, что ячейка не была выселена заранее, и аргумент N_LOAD соответствует аргументу N_PROBE, указанному в поиске).
5. Поиск : эта команда запускает набор запросов против данных, хранящихся в Periplus. Требуется 2 требуемых аргумента: k , в котором указывается количество ближайших соседей для возвращения, и XQ , который является списком векторов запросов. Необязательно он принимает объект параметров с двумя доступными параметрами: n_probe и require_all . Первый указывает, сколько ячеек ЭКО для поиска. Большие значения приводят к увеличению задержки, но также к увеличению отзыва (и более низкой скорости попадания в кэш при использовании require_all ). Значение по умолчанию составляет 1, если не указано. Второй вариант require_all - это логическое, которое диктует поведение в кэше/пропустую. Если установить True, все ближайшие ячейки N_PROBE должны быть в резиденции, чтобы запрос был ударом в кеш. Если false, только ближайшая ячейка ЭКО должна быть в резиденции, чтобы запрос был ударом в кеш, и Periplus будет искать, какие ячейки ЭКО находятся в резиденции до ближайшей ячейки IVF N_Probe . Значение по умолчанию верно. Команда поиска возвращает список списков кортежей документов, где каждый список соответствует результатам K для соответствующего вектора запроса, предоставленного в этом индексе. Кэш пропустил список длины 0. В редких случаях, если длина составляет> 0 и <k, что указывает на то, что общее количество векторов в ближайших клетках N_Probe составляет <k. Каждый кортеж из документов имеет 4 поля: ID, встраивание, метаданные и документ, которые будут соответствовать значениям, предоставленным прокси -сервером базы данных при загрузке данных.
6. Высекание : эта команда работает точно так же, как нагрузка, за исключением того, что она высекает ячейки ЭКО, если они присутствуют из Periplus вместо их загрузки. У него есть один необходимый Arugment, вектор, рассказывающий ему, на какие ячейки нацелены, и дополнительный объект опций с одним доступным вариантом n_evict , который сообщает, сколько ячеек выселить. Periplus высеет ячейки, соответствующие ближайшим центроидам N_EVICT , вектору из Periplus (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 - для получения подробной информации см. Файл лицензии.