Periplus

Periplo

️ Advertencia: el periplus está en alfa

PERIPLUS se encuentra actualmente en alfa y no está listo para la producción. El proyecto está en desarrollo activo y aún no se recomienda su uso en los sistemas de producción.

Introducción

PERIPLUS es una caché de base de datos vectorial en memoria de código abierto basado en la biblioteca de búsqueda de similitud vectorial de Meta FAISS. El proyecto se puede considerar mejor como "Redis para las bases de datos vectoriales". Está diseñado para almacenar un subconjunto actualizado dinámicamente de una gran colección de vectores en la memoria mientras sirve consultas sin interactuar con ningún otro nodo en el momento de la consulta. Cuando Periplus recibe una consulta, primero evalúa si tiene la parte relevante del índice en residencia. Si lo hace, resuelve la consulta con la respuesta apropiada. Si no es así, devuelve una memoria de caché y deja la consulta para obtener los datos de la base de datos. PERIPLUS no está diseñado para funcionar de forma aislada. En cambio, está destinado a formar una capa de almacenamiento de almacenamiento modular y flexible para una base de datos vectorial separada que forma la capa de persistencia. El propósito de esto es permitir una menor latencia y una escala horizontal fácil para aumentar el rendimiento. Para una descripción más detallada de la inspiración detrás de Periplus y cómo funciona, puede leer el blog de anuncios: Presentación de Periplus: un nuevo enfoque para el almacenamiento en caché de la base de datos vectorial.

Cómo funciona

PERIPLUS utiliza un índice de archivos invertido (FIV) como base para la administración de caché. Los índices de archivos invertidos dividen el espacio vectorial en celdas contiguas definidas por un conjunto de vectores centroides donde cada celda se define como la región que está más cerca de su centroide que a cualquier otro centroide. Las consultas se resuelven luego calculando primero las distancias del vector de consulta al conjunto de centroides y luego buscando solo las celdas definidas por los centroides más cercanos N_Probe (Search Hyperparameter). PERIPLUS aprovecha esto al mantener un subconjunto de estas celdas en residencia en un momento dado y solo resolviendo consultas que son relevantes para ese subconjunto mientras rechazan las que no son como caché fallan. PERIPLUS Cargue y desalienta las celdas completas de FIV a la vez para mantener la integridad del índice y garantizar el recuerdo equivalente (en los golpes de caché) a un índice de FIF estándar. Las celdas de FIV se cargan consultando la base de datos de vectores a través de un proxy con una lista de ID de vectores que PERIPLUS mantiene para rastrear qué vectores ocupan qué celdas. El usuario puede invocar estas operaciones utilizando comandos de carga , búsqueda y desalojo . Para obtener más detalles, consulte la sección de comandos de Periplus a continuación.

Correr periplus

PERIPLUS se puede ejecutar como un contenedor Docker o se puede construir desde la fuente y ejecutar como ejecutable. No hay binarios oficiales disponibles actualmente. Ejecutar Periplus como contenedor es el enfoque recomendado, pero ambas son opciones viables.

? Ejecutando periplus como contenedor

Actualmente, la imagen de Docker solo admite arquitecturas AMD64. Esta restricción proviene de la imagen base, pero más arquitecturas serán compatibles con el futuro cercano. Hay 2 formas de ejecutar Periplus como contenedor: descargue la imagen oficial de Docker de Dockerhub (recomendado) o construya la imagen usted mismo. El primer paso en cualquier caso es instalar Docker si aún no lo ha hecho. Las instrucciones para hacerlo se pueden encontrar aquí.

Usando la imagen oficial

1. Descargue la imagen en ejecución: docker image pull qdl123/periplus:latest .
2. Ejecute el contenedor: docker run -p 3000:3000 qdl123/periplus:latest

Construyendo la imagen

1. Clone The Reposyory: git clone https://github.com/QDL123/Periplus.git
2. CD a la raíz del repositorio: cd <path-to-periplus-repo>/Periplus
3. Construya la imagen: docker build -t periplus-image .
4. Ejecute el contenedor: docker run -p 3000:3000 periplus-image .

Edificio PERIPLUS de la fuente

PERIPLUS utiliza CMake para su sistema de construcción. Espera que todas las dependencias tengan binarios precompilados instalados a través de Homebrew. Homebrew es compatible con MacOS, Ubuntu y WSL si está en Windows. PERIPLUS se ha construido en MacOS/ARM64 y Ubuntu/AMD64. Todas las demás combinaciones de sistema operativo y arquitectura no se han probado. Para construir Periplus a partir de la fuente, siga los siguientes pasos:

1. Instale HomeBrew: visite el sitio oficial de Homebrew aquí para obtener instrucciones de instalación.
2. Instale las dependencias de Periplus. Para instalarlos todos a la vez, ejecute: brew install faiss curl cpr rapidjson libomp catch2 cmake
3. Clone The Reposyory: git clone https://github.com/QDL123/Periplus.git
4. CD a la raíz del repositorio: cd <path-to-periplus-repo>/Periplus
5. Genere el makefile: cmake -S . -B build
6. Compilar el ejecutable: cmake --build build
7. Ejecute Periplus (escuchando en el puerto 3000): ./build/periplus -p 3000

Usando PERIPLUS

Cualquier sistema que use Periplus consistirá en 4 componentes: la base de datos Vector, un proxy de la base de datos que permite que Periplus cargue datos de la base de datos, una instancia de Periplus y una aplicación cliente.

Ejemplo de arquitectura de una aplicación utilizando Periplus.

La base de datos de vector

Cualquier base de datos vectorial que permita buscar datos de un identificador único (prácticamente todos) funcionará. PERIPLUS está diseñado para ser más beneficioso cuando se trabaja con Collectons vectoriales realmente grandes (mil millones de escala) donde el índice tiene que vivir en el sistema de archivos en lugar de RAM, aunque eso no es un requisito.

El proxy de la base de datos vectorial

El propósito del proxy de la base de datos de Vector es proporcionar una interfaz consistente para que Periplus interactúe con la base de datos Vector. El proxy debe implementar una interfaz REST que acepte solicitudes de publicación del siguiente formulario:

URL: Esto es flexible y puede ser especificado por el cliente Periplus.

Encabezados: "Content-Type": "application/json

Cuerpo:

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

Respuesta:

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

Para facilitar la implementación de este punto final, puede usar el paquete Periplus-Proxy Python que usa FastAPI para configurar todo. Todo lo que el usuario tiene que hacer es implementar la siguiente función y pasarla como argumento:

async def fetch_ids(request: Query) -> QueryResult

Para obtener detalles sobre cómo hacer esto, puede consultar el paquete Periplus-Proxy ReadMe.md.

Periplo

Siga las instrucciones anteriores para iniciar una instancia de Periplus.

Aplicación del cliente

Para interactuar con su instancia de Periplus, use la biblioteca del cliente Periplus. Actualmente, solo Python es compatible. Para obtener detalles en la biblioteca de clientes, puede ver su readme.md.

Comandos de periplus

1. Inicializar : este es el comando de configuración para Periplus. Debe llamarse antes de que cualquier otro comando y cualquier llamada de inicialización posterior borrará todos los datos y restablecerá la instancia de Periplus. Hay 2 argumentos requeridos: D (dimensionalidad de la colección de vectores) y db_url (URL del punto final de proxy de la base de datos utilizada para cargar datos). También hay un argumento de objeto opcional de opciones con 2 opciones disponibles: NTOTAL y USE_FLAT . El primero, Ntotal , es una estimación del número total de vectores en la colección. Esto se usa para optimizar el número de celdas FIV para usar. Si no se especifica, Periplus elegirá un terreno medio que puede conducir a un rendimiento subóptimo. El segundo, Use_flat , es un booleano que le indica a Periplus a usar un índice plano en lugar de aplicar cualquier cuantificación de producto (PQ). Por defecto, este valor es falso, en cuyo caso se aplicará la cuantización del producto si los vectores son lo suficientemente grandes y fácilmente divisibles en subvectores. Si se establece en True, se utilizará un índice plano de FIV.
2. Train : este comando establece la posición de los centroides en el índice de FIV que forma la base del caché. Una vez que se establecen las posiciones del centroide, no se pueden restablecer sin limpiar completamente el caché. Se necesita una lista de integridades vectoriales como argumento que debería ser una muestra representativa de su colección de vectores. Se recomienda utilizar hasta el 10% de su colección total, pero menos está bien para conjuntos de datos realmente grandes donde el 10% abrumará la instancia de Periplus.
3. Agregar : este comando hace que Periplus consciente de los datos sin completar el caché, para que luego se pueda cargar desde la base de datos. Cualquier vector que Periplus debería poder cargar primero debe registrarse a través del comando Agregar. El comando toma dos ID de argumentos e incrustaciones que son listas de longitudes iguales con ID de vectores e incrustación de vectores correspondientes.
4. Carga : este comando instruye a Periplus a cargar celdas (s) de FIV (consulte cómo funciona para detalles) desde la base de datos. Tiene un argumento requerido, un vector que le dice qué celdas apuntar y un objeto de opciones opcional con una opción disponible N_LOAD que le dice cuántas celdas cargar. PERIPLUS cargará las celdas N_LOAD más cercanas al vector desde la base de datos (N_LOAD es predeterminado a 1 si no se especifica). Esto garantiza que un comando de búsqueda posterior con el mismo vector generará un golpe de caché (suponiendo que la celda no haya sido desalojada de antemano y el argumento N_LOAD coincida con el argumento n_probe dado en la búsqueda).
5. Búsqueda : este comando ejecuta un conjunto de consultas contra los datos almacenados en Periplus. Se necesitan 2 argumentos requeridos: k que especifica el número de vecinos más cercanos a regresar, y XQ, que es una lista de vectores de consulta. Opcionalmente, toma un objeto de opciones con dos opciones disponibles: n_probe y request_all . El primero especifica cuántas celdas de FIV para buscar. Los valores más grandes dan como resultado una mayor latencia pero también un aumento de la recuperación (y una tasa de aciertos de caché más baja cuando se usa requirir )). El valor predeterminado es 1 si no se especifica. La segunda opción require_alt es un booleano que dicta el comportamiento de golpes de caché. Si se establece en True, todas las celdas más cercanas de N_Probe deben estar en residencia para que la consulta sea un golpe de caché. Si es falso, solo la celda FIV más cercana debe estar en residencia para que la consulta sea un golpe de caché, y el periplus buscará cualquiera de las células FIV que se encuentren en residencia hasta la celda IVF más cercana n_probe . El valor predeterminado es verdadero. El comando de búsqueda devuelve una lista de listas de tuplas de documentos donde cada lista corresponde a los resultados k para el vector de consulta correspondiente proporcionado en ese índice. Cache Misss tendrá una lista de longitud 0. En casos raros, si la longitud es> 0 y <k, eso indica que el número total de vectores en las celdas n_probe más cercanas es <k. Cada tupla de documento tiene 4 campos: ID, incrustación, metadatos y documento que correspondirán a los valores proporcionados por el proxy de la base de datos cuando se cargaron los datos.
6. Evict : este comando funciona exactamente igual que la carga, excepto que desalienta las celdas de FIV si están presentes desde Periplus en lugar de cargarlos. Tiene un argamiento requerido, un vector que le dice qué celdas apuntar y un objeto de opciones opcional con una opción disponible N_EVICT WHCH le dice cuántas celdas desalojar. PERIPLUS desalojará las celdas correspondientes a los centroides N_EVICT más cercanos al vector desde PERIPLUS (N_EVICT es predeterminado a 1 no especificado).

Ejemplo

 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 ])

Margen de evaluación

¡Muy pronto!

Que contribuye

¡Agradecemos las contribuciones a Periplus! Para aprender a comenzar, eche un vistazo a la guía de contribución.

Licencia

Este proyecto tiene licencia bajo la licencia MIT; consulte el archivo de licencia para obtener más detalles.