加入我们的Discord | 网站 | 联系我们 | 文档 | 免费托管版本
介绍
VectorFlow是一个开源、高吞吐量、容错的向量嵌入管道。通过简单的API请求,您可以发送原始数据,这些数据将被切分、嵌入并存储在任何向量数据库中或返回给您。
当前版本是一个MVP。我们建议在生产环境中使用Kubernetes(详见下文)。对于基于文本的文件,它支持TXT、PDF、HTML和DOCX。
本地运行
通过三个命令,您可以在本地运行VectorFlow:
git clone https://github.com/dgarnitz/vectorflow.git
cd vectorflow
./setup.sh
使用客户端嵌入文档
要在本地开始嵌入文档,请在您的python应用程序的虚拟环境中安装VectorFlow Client 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)
您不需要克隆VectorFlow仓库即可通过pip利用客户端功能。更多说明请参见client
目录中的README.md
。
请查看附录了解如何使用testing_clients
脚本。
Docker-Compose
运行VectorFlow的最佳方式是通过docker compose
。如果您在Mac上运行,请授予Docker从您的Documents文件夹读取的权限如这里所述。如果失败,请删除docker-compose.yml
中的volume
部分。
1) 设置环境变量
首先在根目录下创建一个文件夹env_scripts
,用于存放所有的环境变量文件,然后在env_scripts
文件夹中创建env_vars.env
文件,并添加下列环境变量。只有当您本地运行qdrant、Milvus或Weaviate时,才需要设置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
,但它们必须被设置。
2) 运行Docker-Compose
确保您将Rabbit MQ、Postgres、Min.io拉到您的本地docker仓库。我们也建议本地运行一个向量数据库,所以请确保拉取您使用的向量数据库镜像。我们的docker-compose
文件默认启动qdrant并创建两个索引/集合。如果您计划运行Milvus或Weaviate,您将需要自行配置它们。
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
容器正在运行一个脚本,该脚本设置数据库模式、向量数据库和Min.io对象存储。该容器在脚本完成后停止。对于qdrant,请确保拉取版本1.9.1,因为这是qdrant客户端python包应使用的版本。
使用VectorFlow
使用VectorFlow的最佳方式是使用python客户端。
要在开发中使用VectorFlow,可以向API的URL发出HTTP请求——例如,从您的开发机器向localhost:8000
发出请求,或在另一个docker容器内向vectorflow_api:8000
发出请求。
请求和响应负载
所有请求都需要带有Authorization
键的HTTP头,其值应与之前定义的INTERNAL_API_KEY
环境变量相同(见上文)。如果您正在连接云实例的向量数据库,必须通过带有HTTP头X-VectorDB-Key
传递您的向量数据库API密钥,如果使用OpenAI,必须通过HTTP头X-EmbeddingAPI-Key
传递嵌入API密钥。如果使用的是HuggingFace Sentence Transformer嵌入不需要API密钥,但您必须按照上述步骤运行所需模型的容器。
VectorFlow目前支持Pinecone、Qdrant和Weaviate向量数据库。
嵌入单个文件
要提交单个文件进行嵌入,请将文件附加并带有'Content-Type: multipart/form-data'
头以及以下负载,通过POST
请求发送给/embed
端点:
{
'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,因超时问题可能会失败。注意它可能会被弃用。
同时嵌入多个文件
要同时提交多个文件进行嵌入,请将负载以不同的方式附加多个文件后,通过POST
请求发送给/jobs
端点。与单个文件嵌入相同,只是附加多个文件的方法不同:
{
'files=[
('file', ('test_pdf.pdf', open(file1_path, 'rb'), 'application/octet-stream')),
('file', ('test_medium_text.txt', open(file2_path, 'rb'), 'application/octet-stream'))
]'
}
注意: 您必须以流方式将文件发送到端点,而不是以常规POST请求发送,否则会失败。
这个端点将为上传的每个文件创建一个job
。您将获得以下JSON负载返回:
{
'successful_uploads': successfully_uploaded_files,
'failed_uploads': failed_uploads,
'empty_files_count': empty_files_count,
'duplicate_files_count': duplicate_files_count
}
其中successful_uploads
是包含(文件名, job id)
的元组列表,failed_uploads
是上传失败的文件名列表,您可以重新尝试上传。
获取单个Job状态
要检查job
的状态,请向此端点发送GET
请求:/jobs/<int:job_id>/status
。响应形式如下:
{
'JobStatus': job_status
}
获取多个Job状态
要检查多个job
的状态,请向此端点发送POST
请求:/jobs/status
。请求正文形式如下:
{
'JobIDs': job_ids
}
响应形式如下:
{
'Jobs': [{'JobID': job_id, 'JobStatus': job_status}, ...]}
在testing_clients/get_jobs_by_ids.py
中有一个示例。
向量数据库标准元数据模式
VectorFlow对于向量存储的数据上传强制执行标准化的模式:
id: string
source_data: string
source_document: string
embeddings: float array
id可以用于去重和幂等。请注意,对于Weaviate,id被称为vectorflow_id
。
我们计划在不久的将来弃用这一点,以支持动态检测和/或可配置的模式。
分块模式和自定义分块
VectorFlow内置的分块器按token计数而不是字符。VectorFlow中的chunk
是一个包含以下键的字典:
text: str
vector: list[float]
您可以通过在构建worker的docker镜像之前将一个名为custom_chunker.py
,带有chunker(source_data: list[str])
方法的文件,添加到src/worker
目录中来运行自定义分块器。这个分块器必须返回一个符合上述标准的chunk
字典列表。
您可以向chunk
字典中添加任何键,只要它是_JSON可序列化的_,这意味着不能是自定义类或函数、日期时间类型或循环代码引用。您可以使用这个自定义块,然后将元数据上传到具有您所需模式的向量数据库中。
原始嵌入的Webhook
如果只希望使用VectorFlow进行分块和生成嵌入,请在/embed
请求体中传递WebhookURL
参数,并通过HTTP头X-Webhook-Key
传递一个Webhook密钥。VectorFlow假设写回任何端点需要一个webhook密钥。嵌入将与上述chunk
字典一起发送回去。它作为json发送,形式如下:
{
'Embeddings': list[dict],
'DocumentID': str,
'JobID': int
}
分块验证的Webhook
如果希望验证嵌入的块,请在/embed
请求体中传递ChunkValidationURL
参数。这将以包含{"chunks": chunked_data}
的json负载发送请求,其中chunked_data
是chunk
字典的列表。期望返回包含valid_chunks
键和有效块列表的json。此端点默认超时30秒,但可以在应用程序代码中配置。
S3 端点
VectorFlow 集成了 AWS S3。您可以在 HTTP 的主体中传递预签名的 S3 URL,而不是文件。使用表单字段 PreSignedURL
并访问端点 /s3
。此端点具有与 /embed
端点相同的配置和限制。
遥测
VectorFlow 使用 PostHog 匿名收集使用数据。这不会收集任何个人身份信息。如果您想禁用它,请将以下环境变量添加到您的 env_vars.env
中:
TELEMETRY_DISABLED=True
Kubernetes
您可以使用 minikube 在 Kubernetes 中本地运行 VectorFlow,通过 ./kube/scripts/deploy-local-k8s.sh
,这将应用位于 kube/
中的所有 yaml 文件。如果您没有安装 docker、minikube 和 kubectl,此脚本将无法工作。
此脚本首先会在本地构建镜像,然后将它们传输到 minikube。如果您想检查 minikube 中有哪些镜像,请运行以下命令:
eval $(minikube docker-env)
docker images
您需要运行 minikube tunnel
以从开发机器访问集群中的资源。设置脚本将从您的本地 docker 环境加载镜像到 minikube 的上下文中。
您可以使用 kube/
中的 yaml 文件作为生产部署的基础,但需要根据特定集群的需求稍作自定义。如果需要帮助,请联系我们。
贡献
我们欢迎社区的反馈。如果您有任何改进项目的建议,我们鼓励您提出 issue 或加入我们的 Discord。请标记 dgarnitz
和 danmeier2
。
我们的路线图在下面部分说明,我们希望能有更多帮助来实现它。我们的开放问题是一个很好的起点,可以在 这里 查看。如果您想要处理未列出的问题,我们建议您先提出一个带有建议方法的 issue,然后再提交 PR。
请在所有 PR 上标记 dgarnitz
并更新 README 以反映您的更改。
测试
提交 PR 时,请添加单元测试以覆盖您添加的功能。请重新运行现有测试以确保没有倒退错误。从 src
目录运行。要运行单个测试,请使用:
python -m unittest module.tests.test_file.TestClass.test_method
要运行文件中的所有测试,请使用:
python -m unittest module.tests.test_file
对于端到端测试,建议使用 docker-compose 构建和运行,但先停止您要更改的容器并在开发机器上本地运行它。这样可以避免不断重建镜像和重新运行容器。确保在开发机器终端中将环境变量更改为正确的值(例如将 rabbitmq
或 postgres
改为 localhost
),以便 docker 容器能够与您的开发机器通信。一旦本地测试通过,您可以在 docker-compose 中进行最终测试。
验证
在打开 PR 之前,请确保所有更改都在 docker-compose 中工作。
我们还建议您添加验证证据,如截图,显示您的代码在端到端流程中工作。
路线图
- 支持从 Salesforce、Google Drive 等源进行多文件、目录数据摄取
- 重试机制
- Langchain 集成
- 支持回调将对象元数据写入单独的存储
- 动态可配置的向量数据库架构
- 去重功能
- 向量版本控制
- “智能”分块器
- “智能”元数据提取器
附录
使用测试脚本嵌入
使用 VectorFlow 的一种简便方法是使用我们位于 testing_clients/
目录中的测试客户端。有几个脚本具有不同的配置,可快速上传数据。我们建议从 testing_clients/standard_upload_client.py
开始 - 运行此脚本将提交一个文档到 VectorFlow 进行 Open AI ADA 嵌入,并上传到本地 qdrant 实例。您可以更改这些值以匹配您的配置。要一次性上传多个文件,请使用 testing_clients/streaming_upload_client.py
请注意,TESTING_ENV
变量等同于 VectorDBMetadata
中的 environment
字段,对应于 Pincone 中的环境、Weaviate 中的类、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
环境变量相同(见上文)。如果您正在连接到云端的向量数据库实例,则必须在 HTTP 头部中传递您的向量数据库 API 密钥 X-VectorDB-Key
。
响应
图像相似性搜索将返回包含前 K 个匹配项以及原始向量(如果请求)的响应对象,其形式如下:
{
"similar_images": list of match objects
"vectors": list of list of floats
}
其中 match
对象定义为:
{
"id": str,
"score": float,
"metadata": {"source_document" : str}
}
使用 Docker 命令构建单个镜像
如果您希望使用 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。运行 worker 时不需要端口参数