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。您不需要端口参数即可运行工人
