Periplus

Periplus

️ Aviso: periplus está em alfa

Periplus está atualmente em Alpha e não está pronto para produção. O projeto está sob desenvolvimento ativo e ainda não é recomendado para uso em sistemas de produção.

Introdução

O Periplus é um cache de banco de dados de vetor em memória de código aberto, criado na biblioteca de busca de similaridade vetorial da Meta FAISS. O projeto pode ser melhor considerado como "Redis for Vector Bathabases". Ele foi projetado para armazenar um subconjunto dinamicamente atualizado de uma grande coleção de vetores inteiramente na memória, cumprindo consultas sem interagir com outros nós no horário da consulta. Quando o Periplus recebe uma consulta, primeiro avalia se tem a parte relevante do índice em residência. Se isso acontecer, resolve a consulta com a resposta apropriada. Caso contrário, ele retorna uma falta de cache e deixa o consultor buscar os dados do banco de dados. Periplus não foi projetado para funcionar isoladamente. Em vez disso, destina -se a formar uma camada de cache modular e flexível para um banco de dados vetorial separado que forma a camada de persistência. O objetivo disso é ativar a menor latência e a escala horizontal fácil para aumentar a taxa de transferência. Para uma descrição mais detalhada da inspiração por trás do Periplus e como ele funciona, você pode ler o blog de anúncios: Apresentando Periplus: Uma nova abordagem para o cache do banco de dados vetorial.

Como funciona

O Periplus usa um índice de arquivo invertido (fertilização in vitro) como base para o gerenciamento de cache. Os índices de arquivo invertido particionam o espaço vetorial em células contíguas definidas por um conjunto de vetores centróides, onde cada célula é definida como a região que está mais próxima de seu centróide do que de qualquer outro centróide. As consultas são então resolvidas pela primeira vez calculando as distâncias do vetor de consulta ao conjunto de centróides e depois pesquisando apenas as células definidas pelos centróides mais próximos do N_Probe (Pesquise Hyperparameter). A Periplus aproveita isso mantendo um subconjunto dessas células em residência a qualquer momento e apenas resolvendo consultas relevantes para esse subconjunto enquanto rejeitam as que não são as erros de cache. O periplus carrega e despeja células inteiras de fertilização in vitro de cada vez para manter a integridade do índice e garantir a recuperação equivalente (em hits de cache) a um índice de fertilização in vitro padrão. As células de fertilização in vitro são carregadas consultando o banco de dados vetorial por meio de um proxy com uma lista de IDs de vetores que o periplus mantém para rastrear quais vetores ocupam quais células. Essas operações podem ser invocadas pelo usuário usando comandos de carga , pesquisa e despejo . Para detalhes, consulte a seção Comandos Periplus abaixo.

Executando periplus

O periplus pode ser executado como um contêiner do docker ou pode ser construído a partir da fonte e executado como executável. No momento, nenhum binário oficial está disponível. Executar periplus como contêiner é a abordagem recomendada, mas ambos são opções viáveis.

? Executando periplus como um contêiner

Atualmente, a imagem do Docker suporta apenas arquiteturas AMD64. Essa restrição decorre da imagem base, mas mais arquiteturas serão apoiadas em um futuro próximo. Existem 2 maneiras de executar o Periplus como contêiner: Baixe a imagem oficial do Docker do DockerHub (recomendado) ou construa a imagem você mesmo. O primeiro passo em ambos os casos é instalar o Docker, se você ainda não o fez. As instruções para fazer isso podem ser encontradas aqui.

Usando a imagem oficial

1. Faça o download da imagem em execução: docker image pull qdl123/periplus:latest .
2. Execute o contêiner: docker run -p 3000:3000 qdl123/periplus:latest

Construindo a imagem

1. Clone o repositório: git clone https://github.com/QDL123/Periplus.git
2. CD para a raiz do repositório: cd <path-to-periplus-repo>/Periplus
3. Construa a imagem: docker build -t periplus-image .
4. Execute o contêiner: docker run -p 3000:3000 periplus-image .

Construindo periplus da fonte

O Periplus usa o CMake para o sistema de construção. Ele espera que todas as dependências tenham binários pré-compilados instalados via Homebrew. O Homebrew é suportado por MacOS, Ubuntu e WSL se você estiver no Windows. O periplus foi construído no macOS/ARM64 e Ubuntu/AMD64. Todas as outras combinações de sistema operacional e arquitetura não são testadas. Para construir periplus a partir da fonte, siga as seguintes etapas:

1. Instale Homebrew: Visite o site oficial do Homebrew aqui para obter instruções de instalação.
2. Instale as dependências da Periplus. Para instalá -los ao brew install faiss curl cpr rapidjson libomp catch2 cmake
3. Clone o repositório: git clone https://github.com/QDL123/Periplus.git
4. CD para a raiz do repositório: cd <path-to-periplus-repo>/Periplus
5. Gere o makefile: cmake -S . -B build
6. Compilar o executável: cmake --build build
7. Execute periplus (ouvindo na porta 3000): ./build/periplus -p 3000

Usando periplus

Qualquer sistema que use periplus consistirá em 4 componentes: o banco de dados vetorial, um proxy de banco de dados que permite que o periplus carregue dados do banco de dados, uma instância do Periplus e um aplicativo cliente.

Exemplo de arquitetura de um aplicativo usando periplus.

O banco de dados vetorial

Qualquer banco de dados vetorial que permita procurar dados por um identificador exclusivo (praticamente todos eles) funcionará. O Periplus foi projetado para ser mais benéfico ao trabalhar com colecos de vetor realmente grandes (escala bilhão), onde o índice deve viver no sistema de arquivos em oposição à RAM, embora isso não seja um requisito.

O proxy do banco de dados vetorial

O objetivo do proxy do banco de dados Vector é fornecer uma interface consistente para o periplus interagir com o banco de dados do vetor. O proxy deve implementar uma interface REST que aceite solicitações de postagens do seguinte formulário:

URL: Isso é flexível e pode ser especificado pelo cliente Periplus.

Cabeçalhos: "Content-Type": "application/json

Corpo:

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

Resposta:

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

Para facilitar a implementação desse terminal, você pode usar o pacote Python Periplus-Proxy, que usa o FASTAPI para configurar tudo. Tudo o que o usuário precisa fazer é implementar a seguinte função e passá -la como um argumento:

async def fetch_ids(request: Query) -> QueryResult

Para detalhes sobre como fazer isso, você pode conferir o pacote periplus-proxy readme.md.

Periplus

Siga as instruções acima para iniciar uma instância do Periplus.

Aplicativo cliente

Para interagir com sua instância do Periplus, use a biblioteca do cliente Periplus. Atualmente, apenas o Python é suportado. Para detalhes sobre a biblioteca do cliente, você pode ver que é readme.md.

Comandos periplus

1. Inicializar : este é o comando de configuração para periplus. Ele deve ser chamado antes de qualquer outro comando e quaisquer chamadas de inicialização subsequente limparão todos os dados e redefinirão a instância do Periplus. Existem 2 argumentos necessários: D (dimensionalidade da coleção vetorial) e db_url (URL do ponto final do proxy do banco de dados usado para carregar dados). Há também um argumento de objeto de opções opcionais com 2 opções disponíveis: ntotal e use_flat . O primeiro, Ntotal , é uma estimativa do número total de vetores da coleção. Isso é usado para otimizar o número de células de fertilização in vitro para usar. Se não for especificado, o Periplus escolherá um meio termo que pode levar ao desempenho abaixo do ideal. O segundo, use_flat , é um booleano que instrui Periplus a usar um índice plano em vez de aplicar qualquer quantização do produto (PQ). Por padrão, esse valor é falso; nesse caso, a quantização do produto será aplicada se os vetores forem grandes o suficiente e facilmente divisíveis em subvetores. Se definido como true, um índice de fertilização in vitro será usado.
2. Trem : Este comando define a posição dos centróides no índice de fertilização in vitro que forma a base do cache. Depois que as posições centróides são definidas, elas não podem ser redefinidas sem limpar completamente o cache. É preciso uma lista de incorporações vetoriais como um argumento que deve ser uma amostra representativa da sua coleção de vetores. É recomendável usar até 10% da sua coleção total, mas menos é bom para conjuntos de dados realmente grandes, onde 10% sobrecarregarão a instância do Periplus.
3. Adicionar : Este comando informa o Periplus dos dados sem preencher o cache, para que possa ser carregado posteriormente no banco de dados. Qualquer vetor que o Periplus deve ser capaz de carregar primeiro precisa ser registrado através do comando add. O comando leva dois argumentos IDs e incorporações, que são listas de comprimentos iguais com IDs vetoriais e incorporação de vetor correspondente.
4. Carga : Este comando instrui o periplus a carregar células de fertilização in vitro (veja como funciona para obter detalhes) no banco de dados. Ele possui um argumento exigido, um vetor informando quais células segmentarem e um objeto de opções opcionais com uma opção disponível n_load que informa quantas células carregam. O periplus carregará as células N_LOAD mais próximas no vetor do banco de dados (n_load padrão para 1 se não for especificado). Isso garante que um comando de pesquisa subsequente com o mesmo vetor produza um acerto de cache (supondo que a célula não tenha sido despejada de antemão e o argumento n_load corresponda ao argumento n_probe fornecido na pesquisa).
5. Pesquisa : Este comando executa um conjunto de consultas contra os dados armazenados no Periplus. São necessárias 2 argumentos necessários: K , que especifica o número de vizinhos mais próximos para retornar e XQ , que é uma lista de vetores de consulta. Opcionalmente, leva um objeto de opções com duas opções disponíveis: n_probe e requer_all . O primeiro especifica quantas células de fertilização in vitro a pesquisar. Valores maiores resultam em aumento da latência, mas também aumentando a recuperação (e uma taxa de acerto de cache mais baixa quando requer_ll é usado). O valor padrão é 1 se não especificado. A segunda opção requer_all é um booleano que determina o comportamento de acerto de cache/erros. Se definido como true, todas as células mais próximas n_probe devem estar em residência para que a consulta seja um acerto de cache. Se false, apenas a célula de fertilização in vitro mais próxima deve estar em residência para que a consulta seja um acerto de cache, e periplus pesquisará as células de fertilização in vitro que estão em residência até a célula de fertilização in vitro mais próxima da N_Probe . O valor padrão é verdadeiro. O comando de pesquisa retorna uma lista de listas de tuplas de documentos, onde cada lista corresponde aos K Resultados para o vetor de consulta correspondente fornecido nesse índice. O Cache Misses terá uma lista de comprimento 0. Em casos raros, se o comprimento for> 0 e <k indica que o número total de vetores nas células N_Probe mais próximo é <k. Cada tupla do documento possui 4 campos: ID, incorporação, metadados e documentos que corresponderão aos valores fornecidos pelo proxy do banco de dados quando os dados foram carregados.
6. EVIT : Este comando funciona exatamente da mesma forma que a carga, exceto que despeja células de fertilização in vitro se estiverem presentes no periplus em vez de carregá -las. Ele possui uma raia necessária, um vetor informando qual células segmentar e um objeto de opções opcionais com uma opção disponível n_evict whch informa quantas células despejam. Periplus despejará as células correspondentes aos centróides n_evict mais próximos ao vetor de periplus (n_evict padrão é 1 não especificado).

Exemplo

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

Benchmarking

Em breve!

Contribuindo

Congratulamo -nos com contribuições para o Periplus! Para aprender a começar, dê uma olhada no guia de contribuição.

Licença

Este projeto está licenciado sob a licença do MIT - consulte o arquivo de licença para obter detalhes.