vectorflow
1.0.0
VectorFlow es una tubería de incrustación de vector de código abierto, alto rendimiento y tolerante para fallas. Con una solicitud de API simple, puede enviar datos sin procesar que se fragmentarán, integrarán y almacenan en cualquier base de datos vectorial o se le devolverá.
Esta versión actual es un MVP. Recomendamos usarlo con Kubernetes en producción (ver más abajo para más detalles). Para archivos basados en texto, admite TXT, PDF, HTML y DOCX.
Con tres comandos puede ejecutar VectorFlow localmente:
git clone https://github.com/dgarnitz/vectorflow.git
cd vectorflow
./setup.sh
Para comenzar a incorporar documentos localmente, instale la biblioteca Python de Vectorflow Client en el entorno virtual de su aplicación Python.
pip install vectorflow-client
luego ejecuta lo siguiente
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)
No necesita clonar el repositorio VectorFlow para utilizar la funcionalidad del cliente a través de PIP. Para obtener más instrucciones, consulte el README.md en el directorio client .
Consulte el Apéndice para obtener detalles sobre cómo usar los scripts testing_clients .
La mejor manera de ejecutar VectorFlow es a través de docker compose . Si está ejecutando esto en Mac, otorgue permisos de Docker para leer la carpeta de su documentos como se indica aquí. Si esto falla, elimine la sección volume de docker-compose.yml .
Primero cree una carpeta, env_scripts , en la raíz de todas las variables de entorno, luego cree env_vars.env en la carpeta env_scripts para agregar todas las variables de entorno mencionadas a continuación. Solo necesita establecer la variable LOCAL_VECTOR_DB si está ejecutando Qdrant, Milvus o Weaviate 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
Puede elegir una variable para INTERNAL_API_KEY , POSTGRES_PASSWORD y POSTGRES_DB , pero deben estar configurados.
Asegúrese de tirar de Rabbit MQ, Postgres, Min.io en su repositorio local de Docker. También recomendamos ejecutar un DB vectorial en localmente, así que asegúrese de extraer la imagen de la que está utilizando. Nuestro archivo docker-compose girará Qdrant de forma predeterminada y creará dos índices/colecciones. Si planea ejecutar Milvus o Weaviate, deberá configurarlos por su cuenta.
docker pull rabbitmq
docker pull postgres
docker pull qdrant/qdrant | docker pull semitechnologies/weaviate
docker pull minio/minio
Luego corre:
docker-compose build --no-cache
docker-compose up -d
Tenga en cuenta que los contenedores init están ejecutando un script que establece el esquema de la base de datos, el vector DB y la tienda de objetos Min.io. Estos contenedores se detienen después de que se completa el script. Para Qdrant, asegúrese de extraer la versión 1.9.1, ya que esa es la versión con la que se supone que funciona el paquete Python Qdrant Client.
La mejor manera de usar VectorFlow es con el cliente Python.
Para usar VectorFlow para el desarrollo, realice una solicitud HTTP a la URL de su API, por ejemplo, localhost:8000 de su máquina de desarrollo, o vectorflow_api:8000 desde otro contenedor Docker.
Todas las solicitudes requieren un encabezado HTTP con la clave Authorization que es la misma que la var INTERNAL_API_KEY env var que definió antes (ver arriba). Debe pasar la tecla API de la base de datos vectorial con el encabezado HTTP X-VectorDB-Key si está ejecutando una conexión X-EmbeddingAPI-Key una instancia basada en la nube de un DB vector . Los incrustaciones del transformador de oraciones de Huggingface no requieren una clave API, pero debe seguir los pasos anteriores para ejecutar el contenedor con el modelo que necesita.
VectorFlow actualmente admite bases de datos de Vector de Pinecone, QDRANT y tejidos.
Para enviar un solo archivo para la incrustación, realice una solicitud POST al punto final /embed con un archivo adjunto, el encabezado 'Content-Type: multipart/form-data' y la siguiente 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'
}
Esto creará un job y obtendrá la siguiente carga útil:
{
'message': f"Successfully added {batch_count} batches to the queue",
'JobID': job_id
}
En este momento, este punto final solo admite cargar archivos únicos a la vez, hasta 25 MB debido a problemas de tiempo de espera. Tenga en cuenta que puede estar en desuso.
Para enviar múltiples archivos para la incrustación, haga una solicitud POST al punto final /jobs . La carga útil es la misma que para la incrustación de un solo archivo, excepto que la forma en que adjunta varios archivos es 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: debe stream los archivos al punto final, no enviarlo como una solicitud de publicación convencional o fallará.
Este punto final creará un job por archivo cargado. Recibirás la siguiente carga de JSON:
{
'successful_uploads': successfully_uploaded_files,
'failed_uploads': failed_uploads,
'empty_files_count': empty_files_count,
'duplicate_files_count': duplicate_files_count
}
Donde successfully_uploaded_files es una lista de tuplas que contienen (file name, job id) y failed_uploads es una lista de nombres de archivos que no pudo cargar para que pueda volver a intentarlos.
Para verificar el estado de un job , haga una solicitud GET a este punto final: /jobs/<int:job_id>/status . La respuesta estará en la forma:
{
'JobStatus': job_status
}
Para verificar el estado del job de múltiplos, haga una solicitud POST a este punto final: /jobs/status . El cuerpo de solicitud estará en el formulario:
{
'JobIDs': job_ids
}
y la respuesta estará en la forma
{
'Jobs': [{'JobID': job_id, 'JobStatus': job_status}, ...]}
Hay un ejemplo en testing_clients/get_jobs_by_ids.py .
Vectorflow aplica un esquema estandarizado para cargar datos en un almacén vectorial:
id: string
source_data: string
source_document: string
embeddings: float array
La ID se puede utilizar para deduplicación e idempotencia. Tenga en cuenta que para Weaviate, la ID se llama vectorflow_id .
Planeamos depreciar esto en el cercano futuo para admitir esquemas detectados y/o configurables dinámicamente en el futuro.
Vectorflow's incorporados a los que cuentan con token, no por carácter. Un chunk en Vectorflow es un diccionario que tiene las siguientes claves:
text: str
vector: list[float]
Puede ejecutar un chunker personalizado agregando un archivo, custom_chunker.py , con un método, chunker(source_data: list[str]) al directorio src/worker antes de construir la imagen Docker para el trabajador. Este chunker debe devolver una lista de diccionarios chunk que se ajustan al estándar anterior.
Puede agregar cualquier tecla que desee al Diccionario chunk siempre que sea su serializable JSON , lo que significa que no hay clases o funciones personalizadas, tipos de datos o referencias de código circular. Puede usar este fragmento personalizado para luego cargar metadatos al Vector DB con el esquema que desee.
Si desea utilizar VectorFlow solo para fragmentar y generar incrustaciones, pase un parámetro WebhookURL en el cuerpo de la solicitud /embed y una X-Webhook-Key como encabezado. Vectorflow asume que se requiere una clave webhook para volver a escribir en cualquier punto final. Los incrustaciones se envían junto con los trozos de origen en el diccionario chunk descritos anteriormente. Esto se envía como JSON con el siguiente formulario:
{
'Embeddings': list[dict],
'DocumentID': str,
'JobID': int
}
Si desea validar qué fragmentos desea incrustar, pase un parámetro ChunkValidationURL en el cuerpo de la solicitud /embed . Esto enviará la solicitud con la siguiente carga útil JSON, {"chunks": chunked_data} , donde chunked_data es una lista de diccionarios chunk . Esperará que JSON contenga la clave valid_chunks con una lista de fragmentos válidos para la incrustación. Este punto final tiempo tiempo después de 30 segundos de forma predeterminada, pero se puede configurar en el código de aplicación.
Vectorflow está integrado con AWS S3. Puede pasar una URL S3 previamente firmada en el cuerpo del HTTP en lugar de un archivo. Use el campo Formulario PreSignedURL y presione el punto final /s3 . Este punto final tiene la misma configuración y restricciones que el punto final /embed .
Vectorflow usa Posthog para recopilar datos de forma anónima sobre el uso. Esto no recopila ninguna información de identificación personal. Sin embargo, si desea deshabilitarlo, agregue la siguiente variable de entorno a su env_vars.env :
TELEMETRY_DISABLED=True
Puede ejecutar VectorFlow localmente en Kubernetes con Minikube usando ./kube/scripts/deploy-local-k8s.sh , que aplicará todos los archivos YAML ubicados en kube/ . Este script no funcionará si no ha instalado Docker, Minikube y Kubectl.
Este script primero construirá las imágenes localmente, luego las transferirá a Minikube. Si desea verificar qué imágenes están disponibles en Minikube, ejecute lo siguiente:
eval $(minikube docker-env)
docker images
Deberá ejecutar minikube tunnel para acceder a los recursos ubicados en el clúster desde su máquina de desarrollo. El script de configuración cargará las imágenes de su contexto de Docker local en Minikube.
Puede usar los archivos YAML en kube/ como base para una implementación de producción, pero deberá personalizar ligeramente las necesidades de su clúster específico. Contáctenos si necesita ayuda.
Nos encantan los comentarios de la comunidad. Si tiene una idea de cómo mejorar este proyecto, le recomendamos que abra un problema o se una a nuestra discordia. Por favor, etiquete dgarnitz y danmeier2 .
Nuestra hoja de ruta se describe en la sección a continuación y nos encantaría ayudar a construirla. Nuestros problemas abiertos son un excelente lugar para comenzar y se pueden ver aquí. Si desea trabajar en algo que no figura allí, le recomendamos que abra un problema con un enfoque propuesto en mente antes de enviar un PR.
Etiquete a dgarnitz en todos los PR y actualice el ReadMe para reflejar sus cambios.
Al enviar un PR, agregue las pruebas de unidades para cubrir la funcionalidad que ha agregado. Vuelva a ejecutar las pruebas existentes para asegurarse de que no haya errores regresivos. Correr desde el directorio src . Para ejecutar un uso de prueba individual:
python -m unittest module.tests.test_file.TestClass.test_method
Para ejecutar todas las pruebas en el uso del archivo:
python -m unittest module.tests.test_file
Para las pruebas de extremo a extremo, se recomienda construir y ejecutar usando Docker-Compose, pero elimine el contenedor que está alterando y ejecutarlo localmente en su máquina de desarrollo. Esto evitará la necesidad de reconstruir constantemente las imágenes y volver a ejecutar los contenedores. Asegúrese de cambiar las variables de entorno en el terminal de su máquina de desarrollo a los valores correctos (es decir, localhost en lugar de rabbitmq o postgres ) para que los contenedores Docker puedan comunicarse con su máquina de desarrollo. Una vez que funciona localmente, puede realizar una prueba final con todo en Docker-Compose.
Verifique que todos los cambios funcionen con Docker-Compose antes de abrir un PR.
También recomendamos que agregue evidencia de verificación, como capturas de pantalla, que muestran que su código funciona en un flujo de extremo a extremo.
Una manera fácil de usar VectorFlow es con nuestros clientes de prueba, ubicados en testing_clients/ Directory. Hay varios scripts, con diferentes configuraciones para los datos de carga Qickly. Recomendamos comenzar con testing_clients/standard_upload_client.py : ejecutar este script enviará un solo documento a Vector Flow para incrustar con ADA Open ADA y cargar a la instancia local de Qdrant. Puede cambiar los valores para que coincida con su configuración. Para cargar varios archivos a la vez, use testing_clients/streaming_upload_client.py
Tenga en cuenta que la variable TESTING_ENV es el equivalente del campo environment en el VectorDBMetadata , que corresponde a un entorno en Pincone, una clase en Weaviate, una colección en Qdrant, etc. El directorio testing_clients tiene scripts de muestra que puede seguir para ejecutar Vector Flow. Agregue las claves de incrustación y base de datos al script env_scrips/env_vars.sh que se generó y configure la variable filepath en testing_clients/standard_upload_client.py para señalar el archivo que desea incrustar. Luego corre:
source env_scrips/env_vars.sh
python testing-clients/standard_upload_client.py
Para cargar varios archivos a la vez, use testing_clients/streaming_upload_client.py
Consulte arriba para obtener una descripción más detallada de cómo configurar y configurar manualmente el sistema. Tenga en cuenta que el script setup no creará un entorno de desarrollo en su máquina, solo establece y ejecuta Docker-Compose. No recomendamos usar VectorFlow en Windows.
Para realizar una búsqueda, envíe una solicitud POST a /images/search Endpoint con un archivo de imagen adjunto, el encabezado 'Content-Type: multipart/form-data' y el siguiente cuerpo:
{
'ReturnVectors': boolean,
'TopK': integer, less than 1000,
'VectorDBMetadata={
"vector_db_type": "PINECONE | QDRANT | WEAVIATE",
"index_name": "index_name",
"environment": "env_name"
}'
}
Todas las solicitudes requieren un encabezado HTTP con la clave Authorization que es la misma que la var INTERNAL_API_KEY env var que definió antes (ver arriba). Debe pasar la tecla API de la base de datos Vector con el encabezado HTTP X-VectorDB-Key si está ejecutando una conexión a una instancia basada en la nube de un DB vectorial.
Una búsqueda de similitud de imagen devolverá un objeto de respuesta que contenga las coincidencias K superiores, más los vectores sin procesar si se solicita, con el siguiente formulario:
{
"similar_images": list of match objects
"vectors": list of list of floats
}
Donde los objetos `Match`` se definen como:
{
"id": str,
"score": float,
"metadata": {"source_document" : str}
}
Si desea usar docker build y docker run para construir y ejecutar imágenes individuales en lugar de docker-compose siga estos pasos:
cd src/docker build --file api/Dockerfile -t vectorflow_api:latest . Para construir, no olvide el período al finaldocker run --network=vectorflow --name=vectorflow_api -d --env-file=../env_scripts/env_vars.env -p 8000:8000 vectorflow_api:latest para ejecutar la API. No necesitas el argumento del puerto para ejecutar el trabajador
