vectorflow
1.0.0
VectorFlowは、オープンソース、高スループット、フォールトトレラントベクトル埋め込みパイプラインです。簡単なAPIリクエストを使用すると、任意のベクトルデータベースにチャンク、埋め込み、保存される生データを送信するか、返品することができます。
この現在のバージョンはMVPです。生産中のKubernetesで使用することをお勧めします（詳細については、以下を参照）。テキストベースのファイルの場合、TXT、PDF、HTML、DOCXをサポートします。
3つのコマンドを使用すると、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)
PIPを介してクライアント機能を利用するために、VectorFlow Repoをクローンする必要はありません。詳細については、 clientディレクトリのREADME.md参照してください。
testing_clientsスクリプトの使用方法の詳細については、付録を参照してください。
VectorFlowを実行する最良の方法は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リポジトリに引くようにしてください。また、ベクターDBをローカルで実行することをお勧めしますので、使用している画像の画像を必ず引っ張ってください。 docker-composeファイルは、デフォルトでQDRANTをスピンアップし、2つのインデックス/コレクションを作成します。 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の場合は、QDRANTクライアントPythonパッケージが操作するはずのバージョンであるため、バージョン1.9.1をプルするようにしてください。
VectorFlowを使用する最良の方法は、Pythonクライアントを使用することです。
開発にVectorFlowを使用するには、APIのURLにHTTPリクエストを作成します。たとえば、Dovelwrow_Apiからのlocalhost:8000 、または別のDockerコンテナ内のvectorflow_api:8000 。
すべてのリクエストには、 Authorizationキーを備えたHTTPヘッダーが必要です。これは、以前に定義したINTERNAL_API_KEY varと同じです（上記参照）。ベクターDBのクラウドベースのインスタンスに接続する場合は、HTTPヘッダーX-VectorDB-Key X-EmbeddingAPI-Key使用してベクトルデータベースAPIキーを渡す必要があります。 。 Huggingface文の変圧器埋め込みはAPIキーを必要としませんが、必要なモデルでコンテナを実行するには、上記の手順に従う必要があります。
VectorFlowは現在、Pinecone、Qdrant、Weaviate Vectorデータベースをサポートしています。
埋め込み用の単一のファイルを送信するには、ファイルが添付された/embedエンドポイントへの'Content-Type: multipart/form-data'ヘッダーと次のペイロードを含む /埋め込みエンドポイントへの[ POST ]リクエストを作成します。
{
'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必要があります。これは、従来のPOSTリクエストとして送信されない場合、失敗します。
このエンドポイントは、アップロードされたファイルごとに1つの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のステータスを確認するには、このエンドポイント： /jobs/<int:job_id>/statusにGET requestを作成します。応答は形式になります：
{
'JobStatus': job_status
}
倍数のjobのステータスを確認するには、このエンドポイント： /jobs/statusにPOSTリクエストを行います。リクエスト本体は形になります：
{
'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と呼ばれます。
私たちは、これを近くのFutuerで非難して、道路の動的に検出された、および/または構成可能なスキーマをサポートします。
VectorFlowの組み込みのチャンカーは、キャラクターではなくトークンによってカウントされます。 VectorFlowのchunkは、次のキーを備えた辞書です。
text: str
vector: list[float]
ワーカーのDockerイメージを構築する前に、メソッド、 chunker(source_data: list[str]) src/workerディレクトリに追加するファイルcustom_chunker.pyを追加することで、カスタムチャンカーを実行できます。このチャンカーは、上記の標準に準拠したchunk辞書のリストを返す必要があります。
JSON Serializableである限り、任意のキーをchunk Dictionaryに追加できます。このカスタムチャンクを使用して、必要なスキーマを使用してメタデータをベクトルDBにアップロードできます。
埋め込みのチャンクと生成にのみVectorFlowを使用する場合は、 /embed要求の本体にWebhookURLパラメーターを渡し、ヘッダーとしてX-Webhook-Key渡します。 VectorFlowは、任意のエンドポイントに書き戻すためにWebhookキーが必要であると想定しています。埋め込みは、上記のchunk辞書のソースチャンクとともに送り返されます。これは、次のフォームでJSONとして送信されます。
{
'Embeddings': list[dict],
'DocumentID': str,
'JobID': int
}
どのチャンクを埋め込みたいかを検証したい場合は、 /embed要求の本体にChunkValidationURLパラメーターを渡します。これにより、次のJSONペイロード{"chunks": chunked_data} chunked_dataリクエストが送信されます。Chunked_Dataはchunk辞書のリストです。埋め込みのための有効なチャンクのリストを備えたKey valid_chunksを含むJSONが予想されます。このエンドポイントは、デフォルトで30秒後にタイムアウトしますが、アプリケーションコードで構成できます。
VectorFlowはAWS S3と統合されています。ファイルの代わりに、HTTPの本体に事前に署名されたS3 URLを渡すことができます。フォームフィールドPreSignedURLを使用し、エンドポイント/s3を押します。このエンドポイントには、 /embedエンドポイントと同じ構成と制限があります。
VectorFlowはPosthogを使用して、使用に関するデータを匿名で収集します。これは、個人を特定できる情報を収集しません。ただし、無効にしたい場合は、次の環境変数をenv_vars.envに追加します。
TELEMETRY_DISABLED=True
./kube/scripts/deploy-local-k8s.shを使用して、minikubeを使用してKubernetesでVectorflowをローカルkube/実行できます。 Docker、Minikube、Kubectlをインストールしていない場合、このスクリプトは機能しません。
このスクリプトは、最初に画像をローカルで構築し、次にminikubeに転送します。 Minikubeで利用可能な画像を確認する場合は、次のことを実行してください。
eval $(minikube docker-env)
docker images
開発マシンからクラスター内にあるリソースにアクセスするには、 minikube tunnelを実行する必要があります。セットアップスクリプトは、ローカルDockerコンテキストからMinikubeに画像をロードします。
kube/のYAMLファイルを生産展開の基礎として使用できますが、特定のクラスターのニーズに合わせてわずかにカスタマイズする必要があります。助けが必要な場合はお問い合わせください。
コミュニティからのフィードバックが大好きです。このプロジェクトをより良くする方法についてのアイデアがある場合は、問題を開くか、私たちの不一致に参加することをお勧めします。 dgarnitzとdanmeier2にタグを付けてください。
私たちのロードマップは以下のセクションで概説されています。それを構築するのに役立ちます。私たちのオープンな問題は、開始するのに最適な場所であり、ここで見ることができます。そこにリストされていないものに取り組みたい場合は、PRを提出する前に提案されたアプローチを念頭に置いて問題を開くことをお勧めします。
すべてのPRSでdgarnitzタグ付けし、変更を反映するようにReadMeを更新してください。
PRを送信するときは、ユニットテストを追加して、追加した機能をカバーしてください。退行性のバグがないことを確認するために、既存のテストを再実行してください。 srcディレクトリから実行します。個々のテストを実行するには：
python -m unittest module.tests.test_file.TestClass.test_method
ファイルですべてのテストを実行するには：
python -m unittest module.tests.test_file
エンドツーエンドのテストには、Docker-Composeを使用して構築および実行することをお勧めしますが、変更しているコンテナを削除して、開発マシンでローカルに実行します。これにより、画像を常に再構築し、コンテナを再実行する必要性が回避されます。 Dockerコンテナが開発マシンと通信できるように、開発マシン端末の環境変数を正しい値（つまり、 rabbitmqまたはpostgresの代わりにlocalhost ）に変更してください。ローカルで動作すると、Docker-Composeのすべてを使用して最終テストを実行できます。
PRを開く前に、すべての変更がDocker-Composeで動作することを確認してください。
また、スクリーンショットなどの検証証拠を追加することをお勧めします。これは、コードがエンドツーエンドフローで機能することを示すことをお勧めします。
VectorFlowを使用する簡単な方法の1つは、 testing_clients/ディレクトリにあるテストクライアントを使用することです。いくつかのスクリプトがあり、Qicklyアップロードデータのための異なる構成があります。 testing_clients/standard_upload_client.pyから始めることをお勧めします - このスクリプトを実行すると、Open AI ADAを埋め込んでローカルQDRANTインスタンスにアップロードするために単一のドキュメントをVectorFlowに送信します。構成に合わせて値を変更できます。複数のファイルを一度にアップロードするには、 testing_clients/streaming_upload_client.pyを使用します
TESTING_ENV変数は、 VectorDBMetadataのenvironmentフィールドに相当し、Pinconeの環境、Weaviateのクラス、Qdrantのコレクションなどに対応していることに注意してください。Test_Clientsディレクトリには、VectorFlow testing_clients実行するために従うことができるサンプルスクリプトがあります。生成された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を使用することはアドバイスしません。
検索を実行するには、 'Content-Type: multipart/form-data'ヘッダーと次のボディを添付した画像ファイルを添付した/images/searchエンドポイントにPOST Requestを送信します。
{
'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 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 。労働者を実行するためにポート引数は必要ありません
