vectorflow
1.0.0
VectorFlow ist eine Open -Source -Einbettungspipeline mit hohem Durchsatz und toleranter Vektor. Mit einer einfachen API -Anfrage können Sie Rohdaten senden, die in jeder Vektor -Datenbank eingebettet und gespeichert werden oder an Sie zurückgegeben werden.
Diese aktuelle Version ist ein MVP. Wir empfehlen, es mit Kubernetes in der Produktion zu verwenden (siehe unten für Einzelheiten). Für textbasierte Dateien unterstützt es TXT, PDF, HTML und DOCX.
Mit drei Befehlen können Sie VectorFlow lokal ausführen:
git clone https://github.com/dgarnitz/vectorflow.git
cd vectorflow
./setup.sh
Um Dokumente lokal einzubetten, installieren Sie die VectorFlow Client Python Library in der virtuellen Umgebung Ihrer Python -Anwendung.
pip install vectorflow-client
Dann laufen Sie Folgendes aus
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)
Sie müssen das VectorFlow -Repo nicht klonen, um die Client -Funktionalität über PIP zu verwenden. Weitere Anweisungen finden Sie im client README.md .
Weitere Informationen zur Verwendung der Skripte testing_clients finden Sie im Anhang.
Der beste Weg, VectorFlow auszuführen, ist über docker compose . Wenn Sie dies auf Mac ausführen, können Sie Docker -Berechtigungen aus Ihrem Dokumentenordner wie hier angewiesene Berechtigungen geben. Wenn dies fehlschlägt, entfernen Sie den volume aus der docker-compose.yml .
Erstellen Sie zunächst einen Ordner, env_scripts , im Stamm für alle Umgebungsvariablen und erstellen Sie dann env_vars.env im Ordner env_scripts , um alle unten genannten Umgebungsvariablen hinzuzufügen. Sie müssen nur die Variable LOCAL_VECTOR_DB festlegen, wenn Sie QDRANT, MILVUS oder WEAVIEREN lokal ausführen.
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
Sie können eine Variable für INTERNAL_API_KEY , POSTGRES_PASSWORD und POSTGRES_DB auswählen, müssen jedoch festgelegt werden.
Stellen Sie sicher, dass Sie Kaninchen -MQ, Postgres, Min.io in Ihr lokales Docker -Repo ziehen. Wir empfehlen auch, einen Vektor -DB lokal auszuführen. Achten Sie daher darauf, das Bild des von Ihnen verwendeten. Unsere docker-compose Datei wird qdrant standardmäßig verdrehen und zwei Index-/Sammlungen erstellen. Wenn Sie planen, Milvus oder Weaviate auszuführen, müssen Sie sie selbst konfigurieren.
docker pull rabbitmq
docker pull postgres
docker pull qdrant/qdrant | docker pull semitechnologies/weaviate
docker pull minio/minio
Dann rennen:
docker-compose build --no-cache
docker-compose up -d
Beachten Sie, dass die init -Container ein Skript ausführen, das das Datenbankschema, den Vektor DB und den Min.io -Objektspeicher eingerichtet hat. Diese Container stoppen nach Abschluss des Skripts. Stellen Sie für QDRant sicher, dass Sie Version 1.9.1 ziehen, da dies die Version ist, mit der das Python -Paket von QDrant Client arbeiten soll.
Der beste Weg, VectorFlow zu verwenden, ist der Python -Client.
Um VectorFlow für die Entwicklung zu verwenden, stellen Sie eine HTTP -Anfrage an die URL Ihrer API - beispielsweise localhost:8000 von Ihrem Entwicklungsgerät oder vectorflow_api:8000 aus einem anderen Docker -Container.
Alle Anfragen erfordern einen HTTP -Header mit dem Authorization , der mit Ihrem zuvor definierten INTERNAL_API_KEY env -Var entspricht (siehe oben). Sie müssen Ihren Vektor-Datenbank-API-Schlüssel mit dem HTTP-Header X-VectorDB-Key übergeben, wenn Sie eine Verbindung zu einer Cloud-basierten Instanz eines Vektor-DB und dem Einbettungs-API-Schlüssel mit X-EmbeddingAPI-Key ausführen, wenn Sie OpenAI verwenden . Umarmen der Einbettung des Satzes Satztransformator müssen keine API -Taste erfordern. Sie müssen jedoch die oben genannten Schritte ausführen, um den Container mit dem von Ihnen benötigten Modell auszuführen.
VectorFlow unterstützt derzeit Tinecone-, QDRant- und Weaviate Vector -Datenbanken.
Um eine einzelne Datei zum Einbetten einzureichen, stellen Sie mit einer angehängten Datei eine POST an den /embed Endpunkt, den Header 'Content-Type: multipart/form-data' und die folgende Nutzlast:
{
'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'
}
Dies erstellt einen job und Sie erhalten die folgende Nutzlast zurück:
{
'message': f"Successfully added {batch_count} batches to the queue",
'JobID': job_id
}
Derzeit unterstützt dieser Endpunkt nur das Hochladen von einzelnen Dateien jeweils bis zu 25 MB aufgrund von Zeitüberschreitungen. Beachten Sie, dass es veraltet sein kann.
Um mehrere Dateien zum Einbetten einzureichen, stellen Sie eine POST an den Endpunkt /jobs . Die Nutzlast entspricht der Einbettung der einzelnen Dateien, außer dass Sie mehrere Dateien anhängen:
{
'files=[
('file', ('test_pdf.pdf', open(file1_path, 'rb'), 'application/octet-stream')),
('file', ('test_medium_text.txt', open(file2_path, 'rb'), 'application/octet-stream'))
]'
}
Hinweis: Sie müssen die Dateien an den Endpunkt stream und sie nicht als herkömmliche Postanforderung senden, da sie fehlschlägt.
Dieser Endpunkt erstellt einen job pro Datei hochgeladen. Sie erhalten die folgende JSON -Nutzlast zurück:
{
'successful_uploads': successfully_uploaded_files,
'failed_uploads': failed_uploads,
'empty_files_count': empty_files_count,
'duplicate_files_count': duplicate_files_count
}
Wobei successfully_uploaded_files eine Liste von Tupeln ist, die (file name, job id) und failed_uploads enthalten sind, ist eine Liste von Dateinamen, die nicht hochladen konnten, damit Sie sie wiederholen können.
Um den Status eines job zu überprüfen, stellen Sie eine GET -Anfrage zu diesem Endpunkt: /jobs/<int:job_id>/status . Die Antwort wird in der Form sein:
{
'JobStatus': job_status
}
Um den Status eines Multiples job zu überprüfen, stellen Sie eine POST an diesen Endpunkt: /jobs/status . Das Anfragegremium befindet sich in der Form:
{
'JobIDs': job_ids
}
und die Antwort wird in der Form sein
{
'Jobs': [{'JobID': job_id, 'JobStatus': job_status}, ...]}
Es gibt ein Beispiel in testing_clients/get_jobs_by_ids.py .
VectorFlow erzwingt ein standardisiertes Schema zum Hochladen von Daten in einen Vektorspeicher:
id: string
source_data: string
source_document: string
embeddings: float array
Die ID kann zur Deduplizierung und Idempotenz verwendet werden. Bitte beachten Sie, dass die ID für Weaviate als vectorflow_id bezeichnet wird.
Wir planen dies im nahen Futuer, um dynamisch erkannte und/oder konfigurierbare Schemata in der Straße zu unterstützen.
VectorFlows eingebaute Chunker zählen nach Token, nicht nach Charakter. Ein chunk in VectorFlow ist ein Wörterbuch mit den folgenden Schlüssel:
text: str
vector: list[float]
Sie können einen benutzerdefinierten Chunker ausführen, indem Sie eine Datei, custom_chunker.py , mit einer Methode, chunker(source_data: list[str]) zum src/worker -Verzeichnis hinzufügen, bevor Sie das Docker -Bild für den Arbeiter erstellen. Dieser Chunker muss eine Liste von chunk -Wörterbüchern zurückgeben, die dem obigen Standard entsprechen.
Sie können alle Tasten, die Sie möchten, dem chunk -Wörterbuch hinzufügen, solange der jSON -serialisierbare JSON -SERializier oder keine benutzerdefinierten Klassen oder Funktionen, DateTimes -Typen oder Rundschile -Code -Referenzen bedeutet. Sie können diesen benutzerdefinierten Teil verwenden, um Metadaten mit dem gewünschten Schema in den Vektor DB hochzuladen.
Wenn Sie VectorFlow nur zum Knacken und Erzeugen von Einbettungen verwenden möchten, geben Sie einen WebhookURL Parameter im Körper der /embed Einbettanforderung und einen X-Webhook-Key als Header weiter. VectorFlow geht davon aus, dass ein Webhook -Schlüssel erforderlich ist, um auf einen beliebigen Endpunkt zurückzuschreiben. Die Einbettungen werden zusammen mit den oben beschriebenen Quellböcken im chunk -Wörterbuch zurückgeschickt. Dies wird als JSON mit dem folgenden Formular gesendet:
{
'Embeddings': list[dict],
'DocumentID': str,
'JobID': int
}
Wenn Sie validieren möchten, welche Brocken Sie einbetten möchten, geben Sie einen ChunkValidationURL -Parameter in den Körper der /embed weiter. Dadurch wird die Anfrage mit der folgenden JSON -Payload, {"chunks": chunked_data} , gesendet, wobei chunked_data eine Liste von chunk -Wörterbüchern ist. Es wird erwartet, dass JSON mit einer Liste der gültigen Teile zum Einbettung von Key valid_chunks enthält. Dieser Endpunkt wird standardmäßig nach 30 Sekunden Zeitüberschreitungen, kann jedoch im Anwendungscode konfiguriert werden.
VectorFlow ist in AWS S3 integriert. Sie können anstelle einer Datei eine vorsignierte S3-URL im Körper des HTTP übergeben. Verwenden Sie das Feld Form PreSignedURL und drücken Sie den Endpunkt /s3 . Dieser Endpunkt hat die gleiche Konfiguration und Einschränkungen wie der /embed Einbettendpunkt.
VectorFlow verwendet Nachhog, um anonym Daten über die Verwendung zu sammeln. Dies sammelt keine persönlich identifizierbaren Informationen. Wenn Sie es jedoch deaktivieren möchten, fügen Sie die folgende Umweltvariable zu Ihrem env_vars.env hinzu:
TELEMETRY_DISABLED=True
kube/ können VectorFlow lokal in Kubernetes mit Minikube verwenden ./kube/scripts/deploy-local-k8s.sh Dieses Skript funktioniert nicht, wenn Sie Docker, Minikube und Kubectl nicht installiert haben.
Dieses Skript erstellt zuerst die Bilder lokal und übertragen sie dann in Minikube. Wenn Sie überprüfen möchten, welche Bilder in Minikube verfügbar sind, führen Sie Folgendes aus:
eval $(minikube docker-env)
docker images
Sie müssen minikube tunnel ausführen, um auf die Ressourcen im Cluster von Ihrer Entwicklungsmaschine zuzugreifen. Das Setup -Skript lädt die Bilder aus Ihrem lokalen Docker -Kontext in Minikube.
Sie können die YAML -Dateien in kube/ als Grundlage für eine Produktionsbereitstellung verwenden, müssen jedoch geringfügig an die Anforderungen Ihres spezifischen Cluster anpassen. Kontaktieren Sie uns, wenn Sie Hilfe benötigen.
Wir lieben Feedback aus der Community. Wenn Sie eine Vorstellung davon haben, wie Sie dieses Projekt verbessern können, empfehlen wir Ihnen, ein Problem zu eröffnen oder sich unserer Zwietracht anzuschließen. Bitte markieren Sie dgarnitz und danmeier2 .
Unsere Roadmap ist im Abschnitt unten beschrieben und wir würden es lieben, ihn beim Aufbau zu helfen. Unsere offenen Ausgaben sind ein großartiger Ausgangspunkt und können hier angesehen werden. Wenn Sie an etwas arbeiten möchten, das dort nicht aufgeführt ist, empfehlen wir Ihnen, ein Problem mit einem vorgeschlagenen Ansatz zu eröffnen, bevor Sie eine PR einreichen.
Bitte markieren Sie dgarnitz auf allen PRs und aktualisieren Sie die Readme, um Ihre Änderungen widerzuspiegeln.
Fügen Sie beim Einreichen eines PR Einheiten -Tests hinzu, um die von Ihnen hinzugefügten Funktionen abzudecken. Bitte führen Sie vorhandene Tests erneut ab, um sicherzustellen, dass keine regressiven Fehler vorhanden sind. Aus dem src -Verzeichnis laufen. Um einen individuellen Test zu verwenden:
python -m unittest module.tests.test_file.TestClass.test_method
So führen Sie alle Tests in der Dateiverwendung aus:
python -m unittest module.tests.test_file
Für End-to-End-Tests wird empfohlen, den Docker-Compose zu erstellen und auszuführen. Nehmen Sie jedoch den Container ab, den Sie ändern, und führen Sie ihn lokal auf Ihrer Entwicklungsmaschine aus. Dadurch wird die Notwendigkeit vermieden, die Bilder ständig wieder aufzubauen und die Behälter neu zu erledigen. Stellen Sie sicher, dass Sie die Umgebungsvariablen in Ihrem Entwicklungsmaschinenterminal auf die richtigen Werte (dh localhost anstelle von rabbitmq oder postgres ) ändern, damit die Docker -Container mit Ihrer Entwicklungsmaschine kommunizieren können. Sobald es lokal funktioniert, können Sie einen endgültigen Test mit allem in Docker-Compose durchführen.
Bitte überprüfen Sie, ob alle Änderungen mit Docker-Compose arbeiten, bevor Sie eine PR eröffnen.
Wir empfehlen auch, Überprüfungsbeweise wie Screenshots hinzuzufügen, die zeigen, dass Ihr Code am Ende zu Ende funktioniert.
Eine einfache Möglichkeit, VectorFlow zu verwenden, ist die unsere Testclients in testing_clients/ Verzeichnis. Es gibt mehrere Skripte mit unterschiedlichen Konfigurationen für das hochladende Hochladen von Daten. Wir empfehlen, beginnend mit dem testing_clients/standard_upload_client.py - Ausführen dieses Skripts senden ein einzelnes Dokument an VectorFlow zum Einbetten mit offenem AI ADA und laden Sie sie in die lokale QDRant -Instanz hoch. Sie können die Werte so ändern, dass sie Ihrer Konfiguration entsprechen. Um mehrere Dateien gleichzeitig hochzuladen, verwenden Sie die testing_clients/streaming_upload_client.py
Beachten Sie, dass die Variable TESTING_ENV das Äquivalent des environment im VectorDBMetadata entspricht, was einer Umgebung in Pincone, einer Klasse in WeaViate, einer Sammlung in QDrant usw. entspricht. Das Verzeichnis testing_clients enthält Beispielskripte, die Sie befolgen können, um VectorFlow auszuführen. Fügen Sie Ihre Einbettungs- und Datenbankschlüssel dem generierten Skript für env_scrips/env_vars.sh hinzu und setzen Sie die filepath -Variable in testing_clients/standard_upload_client.py fest, um auf die Datei zu verweisen, die Sie einbetten möchten. Dann rennen:
source env_scrips/env_vars.sh
python testing-clients/standard_upload_client.py
Um mehrere Dateien gleichzeitig hochzuladen, verwenden Sie die testing_clients/streaming_upload_client.py
Eine detailliertere Beschreibung der manuellen Einrichtung und Konfiguration des Systems finden Sie in der obigen. Bitte beachten Sie, dass das setup -Skript keine Entwicklungsumgebung auf Ihrem Computer erstellt, sondern nur die Docker-Compose eingerichtet und ausgeführt wird. Wir empfehlen nicht, VectorFlow unter Windows zu verwenden.
Um eine Suche durchzuführen, senden Sie eine POST an /images/search mit einer angehängten Bilddatei, dem Header 'Content-Type: multipart/form-data' und dem folgenden Körper:
{
'ReturnVectors': boolean,
'TopK': integer, less than 1000,
'VectorDBMetadata={
"vector_db_type": "PINECONE | QDRANT | WEAVIATE",
"index_name": "index_name",
"environment": "env_name"
}'
}
Alle Anfragen erfordern einen HTTP -Header mit dem Authorization , der mit Ihrem zuvor definierten INTERNAL_API_KEY env -Var entspricht (siehe oben). Sie müssen Ihre Vektor-Datenbank-API-Schlüssel mit dem HTTP-Header X-VectorDB-Key übergeben, wenn Sie eine Verbindung zu einer Cloud-basierten Instanz eines Vektor-DB ausführen.
Eine Image -Ähnlichkeitssuche gibt ein Antwortobjekt zurück, das die oberen K -Übereinstimmungen sowie die Rohvektoren enthält, wenn er angefordert wird, mit dem folgenden Formular:
{
"similar_images": list of match objects
"vectors": list of list of floats
}
wo `match`` -Objekte definiert sind als:
{
"id": str,
"score": float,
"metadata": {"source_document" : str}
}
Wenn Sie docker build und docker run verwenden möchten, um einzelne Bilder anstelle von docker-compose zu erstellen und auszuführen, folgen Sie folgenden Schritten:
cd src/docker build --file api/Dockerfile -t vectorflow_api:latest . zu bauen - vergessen Sie die Zeit am Ende nichtdocker run --network=vectorflow --name=vectorflow_api -d --env-file=../env_scripts/env_vars.env -p 8000:8000 vectorflow_api:latest um die API auszuführen. Sie brauchen das Port -Argument nicht, um den Arbeiter auszuführen
