vectorflow
1.0.0
矢量流是開源，高吞吐量，容錯的矢量嵌入管道。使用簡單的API請求，您可以發送將在任何矢量數據庫中塊，嵌入並存儲的原始數據，也可以返回給您。
該當前版本是MVP。我們建議在生產中與Kubernetes一起使用它（有關詳細信息，請參見下文）。對於基於文本的文件，它支持TXT，PDF，HTML和DOCX。
使用三個命令，您可以在本地運行vectorflow：
git clone https://github.com/dgarnitz/vectorflow.git
cd vectorflow
./setup.sh
要開始本地嵌入文檔，請在Python應用程序的虛擬環境中安裝VectorFlow客戶端Python庫。
pip install vectorflow-client
然後運行以下
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)
您不需要克隆矢量流repo即可通過PIP使用客戶端功能。有關更多說明，請參見client端目錄中的README.md 。
有關如何使用testing_clients腳本的詳細信息，請參見附錄。
運行向量流的最佳方法是通過docker compose 。如果您在Mac上運行此操作，請按照此處指示授予Docker權限從文檔文件夾中讀取。如果失敗，請從docker-compose.yml中刪除volume部分。
首先，在所有環境變量的根中創建一個文件夾， env_scripts ，然後在env_scripts文件夾中創建env_vars.env ，以添加下面提到的所有環境變量。您只需要在本地運行QDrant，Milvus或編織時設置LOCAL_VECTOR_DB變量。
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
您可以為INTERNAL_API_KEY ， POSTGRES_PASSWORD和POSTGRES_DB選擇一個變量，但必須設置它們。
確保將Rabbit MQ，Postgres，Min.io拉到當地的Docker Repo中。我們還建議在本地運行矢量數據庫，因此請確保拉動所使用的矢量圖像。我們的docker-compose文件將默認情況下旋轉QDRANT，並創建兩個索引/集合。如果您打算運行Milvus或編織，則必須自己配置它們。
docker pull rabbitmq
docker pull postgres
docker pull qdrant/qdrant | docker pull semitechnologies/weaviate
docker pull minio/minio
然後運行：
docker-compose build --no-cache
docker-compose up -d
請注意， init容器正在運行一個設置數據庫架構，向量db和min.io對象存儲的腳本。這些容器在腳本完成後停止。對於QDRANT，請確保拉動版本1.9.1，因為那是QDRANT客戶端Python軟件包應該使用的版本。
使用VectorFlow的最佳方法是與Python客戶端一起使用。
要使用vectorflow進行開發，請向API的URL提出HTTP請求 - 例如， localhost:8000從您的開發機器或vectorflow_api:8000從另一個Docker容器內部使用。
所有請求都需要具有Authorization的HTTP標頭，該鍵與您之前定義的INTERNAL_API_KEY env var相同（請參見上文）。如果您正在運行連接到vector db的基於雲的實例，則必須使用HTTP標頭X-VectorDB-Key傳遞矢量數據庫API鍵，如果您使用openai，則使用X-EmbeddingAPI-Key的嵌入API鍵。 HuggingFace句子Transformer嵌入不需要API鍵，但是您必須按照上述步驟使用所需的模型來運行容器。
VectorFlow當前支持Pinecone，QDrant和編織矢量數據庫。
要提交單個文件以進行嵌入，請在/embed端點上提出POST請求，並附有一個文件， 'Content-Type: multipart/form-data'標頭和以下有效載荷：
{
'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'
}
這將創建一個job ，您將獲得以下有效負載：
{
'message': f"Successfully added {batch_count} batches to the queue",
'JobID': job_id
}
目前，由於超時問題，此端點僅支持一次上傳單個文件，最高25 MB。請注意，它可能被棄用。
要提交多個文件以進行嵌入，請向/jobs端點POST請求。有效載荷與單個文件嵌入相同，除了您附加多個文件不同的方式不同：
{
'files=[
('file', ('test_pdf.pdf', open(file1_path, 'rb'), 'application/octet-stream')),
('file', ('test_medium_text.txt', open(file2_path, 'rb'), 'application/octet-stream'))
]'
}
注意：您必須將文件stream到端點，而不是作為常規的郵政請求發送，否則會失敗。
此端點將創建每個文件上傳的job 。您將獲得以下JSON有效負載：
{
'successful_uploads': successfully_uploaded_files,
'failed_uploads': failed_uploads,
'empty_files_count': empty_files_count,
'duplicate_files_count': duplicate_files_count
}
如果successfully_uploaded_files是包含(file name, job id)和failed_uploads的元組列表，是未能上傳的文件名列表，以便您可以重試。
要檢查job的狀態，請向此端點GET請求： /jobs/<int:job_id>/status 。響應將以形式：
{
'JobStatus': job_status
}
要檢查倍數job的狀態，請向此端點提出POST請求： /jobs/status 。請求主體將處於形式：
{
'JobIDs': job_ids
}
響應將以形式
{
'Jobs': [{'JobID': job_id, 'JobStatus': job_status}, ...]}
testing_clients/get_jobs_by_ids.py中有一個示例。
向量流執行標準化架構，以將數據上傳到向量存儲：
id: string
source_data: string
source_document: string
embeddings: float array
該ID可用於重複數據刪除和能力。請注意，對於編織，ID稱為vectorflow_id 。
我們計劃在近乎未來的情況下對此進行棄用，以支持在道路上動態檢測到的和/或可配置的模式。
Vectorflow的內置塊數不按字符來計算。矢量流中的chunk是具有以下鍵的字典：
text: str
vector: list[float]
您可以通過添加文件， custom_chunker.py ，使用方法， chunker(source_data: list[str])來運行自定義塊，然後在構建src/worker的docker映像之前。該塊必須返回符合上述標準的chunk詞典列表。
您可以將想要的任何鍵添加到chunk詞典中，只要其JSON可序列化，這意味著沒有自定義類或功能，DateTimes類型或循環代碼參考。您可以使用此自定義塊將元數據上傳到矢量數據庫中，並使用所需的任何模式上傳。
如果您只想將vectorflow用於切塊和生成嵌入，請在/embed請求的正文中傳遞WebhookURL參數，將X-Webhook-Key作為標頭傳遞。 VectorFlow假定將Webhook鍵寫回任何端點所需的Webhook鍵。嵌入與上面概述的chunk詞典中的源塊一起發送回去。這是作為JSON發送的，並帶有以下表格：
{
'Embeddings': list[dict],
'DocumentID': str,
'JobID': int
}
如果您想驗證要嵌入哪些塊，請通過/embed請求的正文中的ChunkValidationURL參數。這將以以下JSON有效載荷{"chunks": chunked_data}發送請求，其中chunked_data是chunk詞典的列表。它將期望回到JSON，其中包含鍵valid_chunks ，其中包含有效塊的列表。默認情況下30秒後，此端點將超時，但可以在應用程序代碼中配置。
VectorFlow與AWS S3集成。您可以在HTTP主體中傳遞預簽名的S3 URL，而不是文件。使用表單字段PreSignedURL並擊中端點/s3 。該端點具有與/embed端點相同的配置和限制。
VectorFlow使用postthog匿名收集有關使用情況的數據。這不會收集任何個人身份信息。但是，如果要禁用它，請在env_vars.env中添加以下環境變量：
TELEMETRY_DISABLED=True
您可以使用./kube/scripts/deploy-local-k8s.sh在Kubernetes中本地運行矢量流，該文件將應用位於kube/所有YAML文件。如果您尚未安裝Docker，Minikube和Kubectl，則此腳本將無效。
該腳本將首先在本地構建圖像，然後將其轉移到Minikube中。如果要檢查Minikube中有哪些圖像，請運行以下內容：
eval $(minikube docker-env)
docker images
您將需要運行minikube tunnel ，以訪問開發機器中群集中的資源。設置腳本將將圖像從您本地的Docker上下文加載到Minikube中。
您可以將kube/中的YAML文件作為生產部署的基礎，但是您需要稍微自定義特定群集的需求。如果您需要幫助，請與我們聯繫。
我們喜歡社區的反饋。如果您對如何改善該項目有一個想法，我們鼓勵您打開問題或加入我們的不和諧。請標記dgarnitz和danmeier2 。
我們的路線圖在下面的部分中概述了，我們希望幫助建立它。我們的開放問題是一個很好的起點，可以在這裡查看。如果您想從事未列出的事情，建議您在提交PR之前牢記提出的方法開設問題。
請在所有PRS上標記dgarnitz ，並更新讀書文件以反映您的更改。
提交PR時，請添加單元測試以涵蓋您添加的功能。請重新進行現有測試，以確保沒有回歸錯誤。從src目錄運行。運行單獨的測試使用：
python -m unittest module.tests.test_file.TestClass.test_method
在文件中運行所有測試：
python -m unittest module.tests.test_file
對於端到端測試，建議使用Docker-Compose構建和運行，但請拆除您正在更改的容器，並在開發機上本地運行。這將避免需要不斷重建圖像並重新運行容器。確保將開發機終端中的環境變量更改為正確的值（即localhost而不是rabbitmq或postgres ），以便Docker容器可以與開發機通信。一旦在本地工作，您就可以對Docker-Compose中的所有內容進行最終測試。
請在打開PR之前驗證所有更改與Docker-Compose一起工作。
我們還建議您添加驗證證據，例如屏幕截圖，表明您的代碼在端到端流中起作用。
使用VectorFlow的一種簡單方法是與testing_clients/ Directory中的測試客戶端一起使用。有幾個腳本，具有不同的配置，用於上傳數據。我們推薦從testing_clients/standard_upload_client.py開始 - 運行此腳本將向vectorflow提交單個文檔，以嵌入打開AI ADA並上傳到本地QDRANT實例。您可以更改值以匹配您的配置。要一次上傳多個文件，請使用testing_clients/streaming_upload_client.py
請testing_clients ， TESTING_ENV變量是VectorDBMetadata中environment字段的等效，它對應於Pincone中的環境，編織的類，QDRANT中的集合等。Testing_clients目錄具有示例腳本，您可以遵循以遵循的向量vectorFlow。將您的嵌入式和數據庫密鑰添加到生成的env_scrips/env_vars.sh腳本中，並在testing_clients/standard_upload_client.py中設置filepath變量，以指向要嵌入的文件。然後運行：
source env_scrips/env_vars.sh
python testing-clients/standard_upload_client.py
要一次上傳多個文件，請使用testing_clients/streaming_upload_client.py
有關如何手動設置和配置系統的更詳細說明，請參見上文。請注意， setup腳本不會在計算機上創建開發環境，它僅設置並運行Docker-Compose。我們不建議在Windows上使用VectorFlow。
要執行搜索，請將POST請求發送到/images/search端點，並附有圖像文件， 'Content-Type: multipart/form-data'標頭和以下主體：
{
'ReturnVectors': boolean,
'TopK': integer, less than 1000,
'VectorDBMetadata={
"vector_db_type": "PINECONE | QDRANT | WEAVIATE",
"index_name": "index_name",
"environment": "env_name"
}'
}
所有請求都需要具有Authorization的HTTP標頭，該鍵與您之前定義的INTERNAL_API_KEY env var相同（請參見上文）。如果您正在運行連接到向量db的基於雲的實例，則必須使用HTTP標頭X-VectorDB-Key傳遞矢量數據庫API鍵。
圖像相似性搜索將返回包含頂部K匹配的響應對象，以及如果要求，請使用以下形式：
{
"similar_images": list of match objects
"vectors": list of list of floats
}
``匹配''對象的定義為：
{
"id": str,
"score": float,
"metadata": {"source_document" : str}
}
如果要使用docker build和docker run來構建和運行單個圖像，而不是docker-compose請執行以下步驟：
cd src/docker build --file api/Dockerfile -t vectorflow_api:latest .建造 - 不要忘記結束時期docker run --network=vectorflow --name=vectorflow_api -d --env-file=../env_scripts/env_vars.env -p 8000:8000 vectorflow_api:latest運行API。您不需要端口參數即可運行工人
