vectorflow
1.0.0
Vectorflow هو خط أنابيب مفتوح المصدر ، عالي الإنتاجية ، ناقلات التضمين المتسامح. باستخدام طلب API بسيط ، يمكنك إرسال بيانات أولية سيتم قطعها وتضمينها وتخزينها في أي قاعدة بيانات متجه أو إعادة إليك.
هذا الإصدار الحالي هو MVP. نوصي باستخدامه مع Kubernetes في الإنتاج (انظر أدناه للحصول على التفاصيل). بالنسبة للملفات المستندة إلى النص ، فإنه يدعم TXT و PDF و HTML و DOCX.
مع ثلاثة أوامر ، يمكنك تشغيل Vectorflow محليًا:
git clone https://github.com/dgarnitz/vectorflow.git
cd vectorflow
./setup.sh
لبدء تضمين المستندات محليًا ، قم بتثبيت مكتبة Python Client 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 Vectorflow لاستخدام وظائف العميل عبر PIP. لمزيد من الإرشادات ، راجع README.md في دليل client .
راجع التذييل للحصول على تفاصيل حول كيفية استخدام البرامج النصية testing_clients .
أفضل طريقة لتشغيل Vectorflow هي عبر docker compose . إذا كنت تقوم بتشغيل هذا على نظام التشغيل Mac ، فيرجى منح أذونات Docker للقراءة من مجلد المستندات الخاص بك وفقًا لما تم توجيهه هنا. إذا فشل هذا ، فقم بإزالة قسم volume من docker-compose.yml .
قم أولاً بإنشاء مجلد ، env_scripts ، في الجذر لجميع متغيرات البيئة ، ثم قم بإنشاء env_vars.env في مجلد env_scripts لإضافة جميع متغيرات البيئة المذكورة أدناه. تحتاج فقط إلى تعيين متغير LOCAL_VECTOR_DB إذا كنت تقوم بتشغيل Qdrant أو Milvus أو Weaviate محليًا.
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 الخاص بنا بشكل افتراضي وإنشاء فهرس/مجموعات. إذا كنت تخطط لتشغيل 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 تقوم بتشغيل برنامج نصي يقوم بإعداد مخطط قاعدة البيانات ، ومتجر كائن Vector DB و Min.io. تتوقف هذه الحاويات بعد اكتمال البرنامج النصي. بالنسبة إلى QDrant ، تأكد من سحب الإصدار 1.9.1 نظرًا لأن هذا هو الإصدار الذي من المفترض أن تعمل حزمة Python العميل QDrant.
أفضل طريقة لاستخدام Vectorflow هي مع عميل Python.
لاستخدام Vectorflow للتطوير ، قم بتقديم طلب HTTP إلى عنوان URL الخاص بـ API - على سبيل المثال ، localhost:8000 من جهاز التطوير الخاص بك ، أو vectorflow_api:8000 من داخل حاوية Docker أخرى.
تتطلب جميع الطلبات رأس HTTP مع مفتاح Authorization الذي هو نفسه INTERNAL_API_KEY env var الذي حددته من قبل (انظر أعلاه). يجب أن تمرر مفتاح واجهة برمجة تطبيقات قاعدة بيانات المتجه الخاصة بك باستخدام مفتاح HTTP Header X-VectorDB-Key إذا كنت تقوم بتشغيل مثيل قائم على السحابة لمؤسسة DB ، ومفتاح API التضمين مع X-EmbeddingAPI-Key إذا كنت تستخدم Openai . لا تتطلب تضمينات Transpeddings لعناق الجمل مفتاح API ، ولكن يجب عليك اتباع الخطوات المذكورة أعلاه لتشغيل الحاوية مع النموذج الذي تحتاجه.
يدعم Vectorflow حاليًا قواعد بيانات Pinecone و Qdrant و Weaviate.
لإرسال ملف واحد للتضمين ، قم بتقديم طلب POST إلى نقطة النهاية /embed مع ملف مرفق ، رأس '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 ميغابايت بسبب مشكلات المهلة. لاحظ أنه قد يتم إهمالها.
لإرسال ملفات متعددة للتضمين ، قدم طلبًا 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'))
]'
}
ملاحظة: يجب عليك 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 هي قائمة من tuples التي تحتوي على (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 .
يفرض Vectorflow مخططًا موحدًا لتحميل البيانات إلى متجر متجه:
id: string
source_data: string
source_document: string
embeddings: float array
يمكن استخدام المعرف للتكريس والتعويض. يرجى ملاحظة لـ Weaviate ، يسمى المعرف vectorflow_id .
نحن نخطط لاعتداء هذا في المستقبلي القريب لدعم المخططات المكتشفة و/أو القابلة للتكوين ديناميكيا على الطريق.
CATECTINGFLOW المدمجة في الأجزاء العد من رمز ليس حسب الشخصية. chunk في Vectorflow هو قاموس يحتوي على المفاتيح التالية:
text: str
vector: list[float]
يمكنك تشغيل مجموعة مخصصة عن طريق إضافة ملف ، custom_chunker.py ، مع طريقة ، chunker(source_data: list[str]) إلى دليل src/worker قبل إنشاء صورة Docker للعامل. يجب أن تُرجع هذه المجموعة قائمة بقواميس chunk تتوافق مع المعيار أعلاه.
يمكنك إضافة أي مفاتيح تريدها إلى قاموس chunk طالما أن JSON قابلة للتسلسل ، مما يعني عدم وجود فئات مخصصة أو وظيفة ، أو أنواع DateTimes أو مراجع التعليمات البرمجية الدائرية. يمكنك استخدام هذا الجزء المخصص لتحميل البيانات الوصفية إلى المتجه DB مع أي مخطط تريده.
إذا كنت ترغب في استخدام vectorflow فقط للتشكيل وتوليد التضمينات ، فالمرض معلمة WebhookURL في جسم طلب /embed X-Webhook-Key كرئيس. يفترض Vectorflow أن مفتاح WebHook مطلوب للكتابة إلى أي نقطة نهاية. يتم إرسال التضمينات مرة أخرى مع قطع المصدر في قاموس chunk الموضحة أعلاه. يتم إرسال هذا كـ JSON مع النموذج التالي:
{
'Embeddings': list[dict],
'DocumentID': str,
'JobID': int
}
إذا كنت ترغب في التحقق من صحة القطع التي ترغب في تضمينها ، فالمرض معلمة ChunkValidationURL في جسم طلب /embed . سيؤدي ذلك إلى إرسال الطلب باستخدام حمولة JSON التالية ، {"chunks": chunked_data} ، حيث chunked_data عبارة عن قائمة بقواميس chunk . من المتوقع أن يعود JSON الذي يحتوي على مفتاح valid_chunks مع قائمة من القطع الصحيحة للتضمين. ستؤدي نقطة النهاية هذه إلى مهلة بعد 30 ثانية افتراضيًا ولكن يمكن تكوينها في رمز التطبيق.
تم دمج Vectorflow مع AWS S3. يمكنك تمرير عنوان URL S3 موقّع مسبقًا في جسم HTTP بدلاً من ملف. استخدم حقل النموذج PreSignedURL واضغط على نقطة النهاية /s3 . نقطة النهاية هذه لها نفس التكوين والقيود مثل /embed ins ins included.
يستخدم Vectorflow ما بعد ذلك لجمع البيانات المجهولة حول الاستخدام. هذا لا يجمع أي معلومات شخصية. إذا كنت ترغب في تعطيله ، فأضف المتغير التالي إلى env_vars.env :
TELEMETRY_DISABLED=True
يمكنك تشغيل Vectorflow محليًا في Kubernetes مع Minikube باستخدام ./kube/scripts/deploy-local-k8s.sh ، والتي ستطبق جميع ملفات yaml الموجودة في kube/ . لن يعمل هذا البرنامج النصي إذا لم تقم بتثبيت Docker و Minikube و Kubectl.
سيقوم هذا البرنامج النصي أولاً ببناء الصور محليًا ، ثم نقلها إلى Minikube. إذا كنت ترغب في التحقق من الصور المتوفرة في Minikube ، قم بتشغيل ما يلي:
eval $(minikube docker-env)
docker images
ستحتاج إلى تشغيل minikube tunnel للوصول إلى الموارد الموجودة في المجموعة من آلة التطوير الخاصة بك. سيقوم برنامج Setup Script بتحميل الصور من سياق Docker المحلي إلى Minikube.
يمكنك استخدام ملفات YAML في kube/ كأساس لنشر الإنتاج ولكن ستحتاج إلى التخصيص قليلاً لاحتياجات المجموعة المحددة. اتصل بنا إذا كنت بحاجة إلى مساعدة.
نحن نحب ردود الفعل من المجتمع. إذا كانت لديك فكرة عن كيفية تحسين هذا المشروع ، فنحن نشجعك على فتح مشكلة أو الانضمام إلى خلافنا. يرجى علامة dgarnitz و danmeier2 .
تم تحديد خارطة الطريق الخاصة بنا في القسم أدناه ونود المساعدة في بنائها. مشكلاتنا المفتوحة هي مكان رائع للبدء ويمكن عرضه هنا. إذا كنت ترغب في العمل على شيء غير مدرج هناك ، فإننا نوصيك بفتح مشكلة مع اتباع نهج مقترح في الاعتبار قبل تقديم العلاقات العامة.
يرجى وضع علامة على dgarnitz على جميع PRS وتحديث ReadMe لتعكس التغييرات الخاصة بك.
عند إرسال العلاقات العامة ، يرجى إضافة اختبارات الوحدات لتغطية الوظيفة التي أضفتها. يرجى إعادة تشغيل الاختبارات الحالية للتأكد من عدم وجود أخطاء تراجعية. يركض من دليل src . لتشغيل استخدام اختبار فردي:
python -m unittest module.tests.test_file.TestClass.test_method
لتشغيل جميع الاختبارات في الملف استخدام:
python -m unittest module.tests.test_file
بالنسبة للاختبار من طرف إلى طرف ، يوصي ببناء وتشغيل باستخدام Docker-Cormse ، ولكن قم بإنزال الحاوية التي تقوم بتغييرها وتشغيلها محليًا على آلة التطوير الخاصة بك. هذا سيتجنب الحاجة إلى إعادة بناء الصور باستمرار وإعادة تشغيل الحاويات. تأكد من تغيير متغيرات البيئة في محطة آلة التطوير الخاصة بك إلى القيم الصحيحة (أي localhost بدلاً من rabbitmq أو postgres ) حتى تتمكن حاويات Docker من التواصل مع آلة التطوير الخاصة بك. بمجرد أن تعمل محليًا ، يمكنك إجراء اختبار نهائي مع كل شيء في Docker-Corm.
يرجى التحقق من أن جميع التغييرات تعمل مع Docker-Compose قبل فتح العلاقات العامة.
نوصيك أيضًا بإضافة أدلة التحقق ، مثل لقطات الشاشة ، والتي تظهر أن الكود الخاص بك يعمل في نهاية التدفق.
إحدى الطرق السهلة لاستخدام Vectorflow هي مع عملاء الاختبار لدينا ، الموجود في testing_clients/ Directory. هناك العديد من البرامج النصية ، مع تكوينات مختلفة لتحميل بيانات QICKLY. نوصى بالبدء في testing_clients/standard_upload_client.py - سيقوم تشغيل هذا البرنامج النصي بتقديم مستند واحد إلى Vectorflow للتضمين مع AI AI Open وتحميل إلى مثيل QDrant المحلي. يمكنك تغيير القيم لمطابقة التكوين الخاص بك. لتحميل ملفات متعددة في وقت واحد ، استخدم testing_clients/streaming_upload_client.py
لاحظ أن متغير TESTING_ENV هو ما يعادل حقل environment في VectorDBMetadata ، والذي يتوافق مع بيئة في pincone ، فئة في Weaviate ، مجموعة في QDrant ، إلخ testing_clients أضف مفاتيح التضمين وقاعدة البيانات الخاصة بك إلى البرنامج النصي env_scrips/env_vars.sh الذي تم إنشاؤه وتعيين متغير filepath في testing_clients/standard_upload_client.py للإشارة إلى الملف الذي تريد تضمينه. ثم قم بالتشغيل:
source env_scrips/env_vars.sh
python testing-clients/standard_upload_client.py
لتحميل ملفات متعددة في وقت واحد ، استخدم testing_clients/streaming_upload_client.py
انظر أعلاه للحصول على وصف أكثر تفصيلاً لكيفية إعداد النظام وتكوينه يدويًا. يرجى ملاحظة أن البرنامج النصي setup لن ينشئ بيئة تطوير على جهازك ، فهو يقوم فقط بإعداد وتشغيل Docker-Corm. نحن لا ننصح باستخدام Vectorflow على Windows.
لإجراء بحث ، أرسل طلبًا 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"
}'
}
تتطلب جميع الطلبات رأس HTTP مع مفتاح Authorization الذي هو نفسه INTERNAL_API_KEY env var الذي حددته من قبل (انظر أعلاه). يجب أن تمرر مفتاح API لقاعدة بيانات المتجه مع رأس HTTP X-VectorDB-Key إذا كنت تقوم بتشغيل متصل بمثيل قائم على السحابة لمتجه DB.
سيعود البحث عن تشابه الصورة إلى كائن استجابة يحتوي على مطابقة K Top 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 لتشغيل واجهة برمجة التطبيقات. لا تحتاج إلى وسيطة المنفذ لتشغيل العامل
