vectorflow
1.0.0
O VectorFlow é um pipeline de incorporação de vetor de código aberto, alta taxa de transferência e falha. Com uma solicitação simples de API, você pode enviar dados brutos que serão fundidos, incorporados e armazenados em qualquer banco de dados vetorial ou devolvidos a você.
Esta versão atual é um MVP. Recomendamos usá -lo com Kubernetes na produção (veja abaixo para obter detalhes). Para arquivos baseados em texto, ele suporta TXT, PDF, HTML e DOCX.
Com três comandos, você pode executar o Vectorflow Localmente:
git clone https://github.com/dgarnitz/vectorflow.git
cd vectorflow
./setup.sh
Para começar a incorporar documentos localmente, instale a biblioteca Python Client Vectorflow no ambiente virtual do aplicativo Python.
pip install vectorflow-client
Em seguida, execute o seguinte
from vectorflow-client.client.vectorflow import Vectorflow
vectorflow = Vectorflow()
vectorflow.embeddings_api_key = os.getenv("OPEN_AI_KEY")
paths = ['path_to_your_file1', 'path_to_your_file2', ...]
response = vectorflow.upload(paths)
Você não precisa clonar o repo Vectorflow para utilizar a funcionalidade do cliente via PIP. Para obter mais instruções, consulte o README.md no diretório client .
Consulte o Apêndice para obter detalhes sobre como usar os scripts testing_clients .
A melhor maneira de executar o VectorFlow é via docker compose . Se você estiver executando isso no Mac, conceda às permissões do Docker ler na pasta Documents, conforme instruído aqui. Se isso falhar, remova a seção volume do docker-compose.yml .
Primeiro, crie uma pasta, env_scripts , na raiz de todas as variáveis de ambiente, depois crie env_vars.env na pasta env_scripts para adicionar todas as variáveis de ambiente mencionadas abaixo. Você só precisa definir a variável LOCAL_VECTOR_DB se estiver executando QDRANT, MILVUS ou TEAVIA LOCALMENTE.
INTERNAL_API_KEY=your-choice
POSTGRES_USERNAME=postgres
POSTGRES_PASSWORD=your-choice
POSTGRES_DB=vectorflow
POSTGRES_HOST=postgres
RABBITMQ_USERNAME=guest
RABBITMQ_PASSWORD=guest
RABBITMQ_HOST=rabbitmq
LOCAL_VECTOR_DB=qdrant | weaviate
API_STORAGE_DIRECTORY=/tmp
MINIO_ACCESS_KEY=minio99
MINIO_SECRET_KEY=minio123
MINIO_ENDPOINT=minio:9000
MINIO_BUCKET=vectorflow
Você pode escolher uma variável para INTERNAL_API_KEY , POSTGRES_PASSWORD e POSTGRES_DB , mas eles devem ser definidos.
Certifique -se de puxar o Rabbit MQ, Postgres, Min.io para o seu repositório local do Docker. Também recomendamos a execução de um db vetorial localmente, por isso, puxe a imagem da que você está usando. Nosso arquivo docker-compose girará o QDRANT por padrão e criará duas Índice/Coleções. Se você planeja executar o Milvus ou teatrar, precisará configurá -los por conta própria.
docker pull rabbitmq
docker pull postgres
docker pull qdrant/qdrant | docker pull semitechnologies/weaviate
docker pull minio/minio
Em seguida, corra:
docker-compose build --no-cache
docker-compose up -d
Observe que os contêineres init estão executando um script que configura o esquema do banco de dados, o Vector DB e o Min.io Object Store. Esses contêineres param após a conclusão do script. Para o QDRANT, puxe a versão 1.9.1, pois essa é a versão com que o pacote Python do cliente QDRANT deve funcionar.
A melhor maneira de usar o VectorFlow é com o cliente Python.
Para usar o VectorFlow para desenvolvimento, faça uma solicitação HTTP ao URL da sua API - por exemplo, localhost:8000 da sua máquina de desenvolvimento ou vectorflow_api:8000 De dentro de outro contêiner do docker.
Todas as solicitações exigem um cabeçalho HTTP com a chave Authorization , que é a mesma que o seu INTERNAL_API_KEY ENV VAR que você definiu antes (veja acima). Você deve passar pela chave da API do banco de dados vetorial com o cabeçalho HTTP X-VectorDB-Key se estiver executando uma conexão a uma instância baseada em nuvem de um db de vetor e a chave de API de incorporação com X-EmbeddingAPI-Key se estiver usando o OpenAI . A incorporação do transformador de sentença Huggingface não requer uma chave da API, mas você deve seguir as etapas acima para executar o contêiner com o modelo necessário.
Atualmente, o VectorFlow suporta bancos de dados de vetores Pinecone, QDrant e teatiam.
Para enviar um único arquivo para incorporação, faça uma solicitação POST ao endpoint /embed com um arquivo anexado, o cabeçalho 'Content-Type: multipart/form-data' e a seguinte carga útil:
{
'SourceData=path_to_txt_file'
'LinesPerBatch=4096'
'EmbeddingsMetadata={
"embeddings_type": "OPEN_AI",
"chunk_size": 512,
"chunk_overlap": 128,
"chunk_strategy": "EXACT | PARAGRAPH | SENTENCE | CUSTOM",
"model": "text-embedding-3-small | text-embedding-3-large | text-embedding-ada-002"
}'
'VectorDBMetadata={
"vector_db_type": "PINECONE | QDRANT | WEAVIATE",
"index_name": "index_name",
"environment": "env_name"
}'
'DocumentID=your-optional-internal-tracking-id'
}
Isso criará um job e você receberá a seguinte carga útil de volta:
{
'message': f"Successfully added {batch_count} batches to the queue",
'JobID': job_id
}
No momento, este terminal suporta apenas o upload de arquivos únicos por vez, até 25 MB devido a problemas de tempo limite. Observe que pode ser preterido.
Para enviar vários arquivos para incorporação, faça uma solicitação POST para o endpoint /jobs . A carga útil é a mesma da incorporação de arquivo único, exceto que a maneira como você anexa vários arquivos é diferente:
{
'files=[
('file', ('test_pdf.pdf', open(file1_path, 'rb'), 'application/octet-stream')),
('file', ('test_medium_text.txt', open(file2_path, 'rb'), 'application/octet-stream'))
]'
}
NOTA: Você deve stream os arquivos para o terminal, não enviá -los como uma solicitação de postagem convencional ou falhará.
Este terminal criará um job por arquivo enviado. Você receberá a seguinte carga útil JSON:
{
'successful_uploads': successfully_uploaded_files,
'failed_uploads': failed_uploads,
'empty_files_count': empty_files_count,
'duplicate_files_count': duplicate_files_count
}
Onde successfully_uploaded_files é uma lista de tuplas que contêm (file name, job id) e failed_uploads é uma lista de nomes de arquivos que falharam no upload para que você possa tentar novamente.
Para verificar o status de um job , faça uma solicitação GET este endpoint: /jobs/<int:job_id>/status . A resposta estará no formulário:
{
'JobStatus': job_status
}
Para verificar o status do job múltiplo, faça uma solicitação POST para este terminal: /jobs/status . O corpo de solicitação estará no formulário:
{
'JobIDs': job_ids
}
e a resposta estará na forma
{
'Jobs': [{'JobID': job_id, 'JobStatus': job_status}, ...]}
Há um exemplo em testing_clients/get_jobs_by_ids.py .
O VectorFlow aplica um esquema padronizado para fazer upload de dados para um loja de vetores:
id: string
source_data: string
source_document: string
embeddings: float array
O ID pode ser usado para desduplicação e idempotência. Por favor, observe para teatriado, o ID é chamado vectorflow_id .
Planejamos depreciar isso no futuro próximo para apoiar os esquemas detectados e/ou configuráveis detectados dinamicamente.
Os pedaços incorporados do Vectorflow contam por token não pelo personagem. Um chunk no Vectorflow é um dicionário que possui as seguintes chaves:
text: str
vector: list[float]
Você pode executar um Chunker personalizado adicionando um arquivo, custom_chunker.py , com um método, chunker(source_data: list[str]) ao diretório src/worker antes de construir a imagem do docker para o trabalhador. Este pedaço deve retornar uma lista de dicionários chunk que estão em conformidade com o padrão acima.
Você pode adicionar as chaves que deseja ao dicionário de chunk enquanto seu JSON serializável , o que significa que não há classes ou funções personalizadas, tipos de dados ou referências de código circular. Você pode usar esse pedaço personalizado para fazer upload de metadados no banco de dados vetorial com qualquer esquema que desejar.
Se você deseja usar o VectorFlow apenas para criticar e gerar incorporações, passe um parâmetro WebhookURL no corpo da solicitação /embed e uma X-Webhook-Key como cabeçalho. O VectorFlow assume que uma chave webhook é necessária para escrever de volta a qualquer ponto final. As incorporações são enviadas de volta junto com os pedaços de origem no dicionário chunk descritos acima. Isso é enviado como JSON com o seguinte formulário:
{
'Embeddings': list[dict],
'DocumentID': str,
'JobID': int
}
Se você deseja validar quais pedaços você deseja incorporar, passe um parâmetro ChunkValidationURL no corpo da solicitação /embed . Isso enviará a solicitação com a seguinte carga de pagamento JSON, {"chunks": chunked_data} , onde chunked_data é uma lista de dicionários chunk . Esperava -se JSON de volta contendo Key valid_chunks com uma lista de pedaços válidos para incorporação. Esse endpoint terá tempo limite após 30 segundos por padrão, mas pode ser configurado no código do aplicativo.
O VectorFlow é integrado ao AWS S3. Você pode passar por um URL S3 pré-assinado no corpo do HTTP em vez de um arquivo. Use o campo de formulário PreSignedURL e pressione o endpoint /s3 . Esse terminal possui a mesma configuração e restrições que o terminal /embed .
O VectorFlow usa o POFOG para coletar anonimamente dados sobre o uso. Isso não coleta nenhuma informação de identificação pessoal. Se você deseja desativá -lo, adicione a seguinte variável enxada ao seu env_vars.env :
TELEMETRY_DISABLED=True
Você pode executar o Vectorflow localmente em Kubernetes com Minikube usando ./kube/scripts/deploy-local-k8s.sh , que aplicará todos os arquivos YAML localizados em kube/ . Este script não funcionará se você não instalou o Docker, Minikube e Kubectl.
Este script primeiro construirá as imagens localmente e depois as transferirá para o Minikube. Se você quiser verificar quais imagens estão disponíveis no Minikube, execute o seguinte:
eval $(minikube docker-env)
docker images
Você precisará executar minikube tunnel para acessar os recursos localizados no cluster da sua máquina de desenvolvimento. O script de configuração carregará as imagens do contexto do Docker local no Minikube.
Você pode usar os arquivos YAML no kube/ como base para uma implantação de produção, mas precisará personalizar um pouco as necessidades do seu cluster específico. Entre em contato conosco se precisar de ajuda.
Adoramos feedback da comunidade. Se você tiver uma idéia de como melhorar esse projeto, incentivamos você a abrir um problema ou se juntar à nossa discórdia. Por favor, marque dgarnitz e danmeier2 .
Nosso roteiro está descrito na seção abaixo e gostaríamos de ajuda para construí -lo. Nossos problemas abertos são um ótimo lugar para começar e podem ser vistos aqui. Se você deseja trabalhar em algo não listado lá, recomendamos que você abra um problema com uma abordagem proposta em mente antes de enviar um PR.
Por favor, marque dgarnitz em todos os PRs e atualize o ReadMe para refletir suas alterações.
Ao enviar um PR, adicione testes de unidades para cobrir a funcionalidade que você adicionou. Por favor, execute novamente os testes existentes para garantir que não haja bugs regressivos. Corra do diretório src . Para executar um uso individual de teste:
python -m unittest module.tests.test_file.TestClass.test_method
Para executar todos os testes no uso do arquivo:
python -m unittest module.tests.test_file
Para testes de ponta a ponta, é recomendável construir e executar usando o Docker-Compose, mas retire o contêiner que você está alterando e execute-o localmente na sua máquina de desenvolvimento. Isso evitará a necessidade de reconstruir constantemente as imagens e executar novamente os contêineres. Certifique -se de alterar as variáveis de ambiente em seu terminal da máquina de desenvolvimento para os valores corretos (ou seja, localhost em vez de rabbitmq ou postgres ) para que os contêineres do Docker possam se comunicar com sua máquina de desenvolvimento. Depois de funcionar localmente, você pode realizar um teste final com tudo no Docker-Compompose.
Verifique se todas as alterações funcionam com o Docker-Compose antes de abrir um PR.
Também recomendamos que você adicione evidências de verificação, como capturas de tela, que mostram que seu código funciona em um fluxo de ponta a ponta.
Uma maneira fácil de usar o VectorFlow é com os nossos clientes de teste, localizados no Diretório testing_clients/ . Existem vários scripts, com diferentes configurações para fazer upload de dados Qickly. Recomendamos que começamos com o testing_clients/standard_upload_client.py - A execução deste script enviará um único documento ao Vectorflow para incorporar com AI ADA Open e fazer upload na instância local de QDRANT. Você pode alterar os valores para corresponder à sua configuração. Para fazer upload de vários arquivos de uma só vez, use o testing_clients/streaming_upload_client.py
Observe que a variável TESTING_ENV é o equivalente do campo environment no VectorDBMetadata , que corresponde a um ambiente em Pincona, uma classe em tecedas, uma coleção no QDRANT, etc. O diretório testing_clients possui scripts de amostra que você pode seguir para executar o fluxo de vetor. Adicione suas teclas de incorporação e banco de dados ao script env_scrips/env_vars.sh que foi gerado e defina a variável filepath em testing_clients/standard_upload_client.py para apontar para o arquivo que deseja incorporar. Em seguida, corra:
source env_scrips/env_vars.sh
python testing-clients/standard_upload_client.py
Para fazer upload de vários arquivos de uma só vez, use o testing_clients/streaming_upload_client.py
Veja acima para obter uma descrição mais detalhada de como configurar e configurar manualmente o sistema. Observe que o script setup não criará um ambiente de desenvolvimento em sua máquina, ele apenas configura e executa o Docker-Compose. Não aconselhamos o uso do Vectorflow no Windows.
Para executar uma pesquisa, envie uma solicitação POST para /images/search terminal com um arquivo de imagem anexado, o cabeçalho 'Content-Type: multipart/form-data' e o seguinte corpo:
{
'ReturnVectors': boolean,
'TopK': integer, less than 1000,
'VectorDBMetadata={
"vector_db_type": "PINECONE | QDRANT | WEAVIATE",
"index_name": "index_name",
"environment": "env_name"
}'
}
Todas as solicitações exigem um cabeçalho HTTP com a chave Authorization , que é a mesma que o seu INTERNAL_API_KEY ENV VAR que você definiu antes (veja acima). Você deve passar sua tecla API do banco de dados vetorial com o cabeçalho HTTP X-VectorDB-Key se estiver executando uma conexão a uma instância baseada em nuvem de um db vetorial.
Uma pesquisa de similaridade de imagem retornará um objeto de resposta que contém as melhores correspondências K, além dos vetores brutos, se solicitado, com o seguinte formulário:
{
"similar_images": list of match objects
"vectors": list of list of floats
}
onde os objetos `match`` são definidos como:
{
"id": str,
"score": float,
"metadata": {"source_document" : str}
}
Se você deseja usar docker build e docker run para construir e executar imagens individuais, em vez de docker-compose siga estas etapas:
cd src/docker build --file api/Dockerfile -t vectorflow_api:latest . Para construir - não esqueça o período no finaldocker run --network=vectorflow --name=vectorflow_api -d --env-file=../env_scripts/env_vars.env -p 8000:8000 vectorflow_api:latest para executar a API. você não precisa do argumento do porto para executar o trabalhador
