Periplus

periplus

️ تحذير: Periplus في ألفا

Periplus حاليًا في ألفا وليس جاهزًا للإنتاج. يخضع المشروع إلى تطوير نشط ، ولا ينصح به بعد للاستخدام في أنظمة الإنتاج.

مقدمة

Periplus هو ذاكرة التخزين المؤقت لقاعدة بيانات المتجهات مفتوحة المصدر مبنية على مكتبة البحث عن ناقلات Meta FAISS. من الأفضل اعتبار المشروع "redis لقواعد بيانات المتجهات". تم تصميمه لتخزين مجموعة فرعية محدثة ديناميكيًا من مجموعة متجه كبيرة بالكامل في الذاكرة أثناء تقديم الاستعلامات دون التفاعل مع أي عقد أخرى في وقت الاستعلام. عندما يتلقى Periplus استعلامًا ، يقوم أولاً بتقييم ما إذا كان لديه الجزء ذي الصلة من الفهرس الداخلي. إذا كان الأمر كذلك ، فإنه يحل الاستعلام مع الاستجابة المناسبة. إذا لم يكن الأمر كذلك ، فإنه يعيد تفويت ذاكرة التخزين المؤقت ويترك أكثر جلبًا لجلب البيانات من قاعدة البيانات. Periplus غير مصمم للعمل في عزلة. بدلاً من ذلك ، يهدف إلى تشكيل طبقة تخزين مؤقت وحداسية ومرنة لقاعدة بيانات متجه منفصلة تشكل طبقة الثبات. والغرض من ذلك هو تمكين انخفاض الكمون والتحجيم الأفقي السهل لزيادة الإنتاجية. للحصول على وصف أكثر تفصيلاً للإلهام وراء Periplus وكيف يعمل ، يمكنك قراءة مدونة الإعلان: تقديم Periplus: نهج جديد لتخزين Database للتخزين المؤقت.

كيف تعمل

يستخدم Periplus فهرس ملف مقلوب (IVF) كأساس لإدارة ذاكرة التخزين المؤقت. فهرسة الملفات المقلوبة تقسيم مساحة المتجه إلى خلايا متجاورة محددة من قبل مجموعة من متجهات النقطه الوسطى حيث يتم تعريف كل خلية على أنها المنطقة التي تكون أقرب إلى النقط الوسطى من أي نقطية وسط أخرى. ثم يتم حل الاستعلامات عن طريق حساب المسافات أولاً من متجه الاستعلام إلى مجموعة الأوسطات الوسطى ثم البحث فقط عن الخلايا المحددة من قبل N_Probe (Search Hyperparameter) أقرب الوسطى. يستفيد Periplus من هذا من خلال الحفاظ على مجموعة فرعية من هذه الخلايا في الإقامة في أي وقت معين وحل فقط الاستعلامات ذات الصلة بتلك المجموعة الفرعية مع رفض تلك التي لا تفوت ذاكرة التخزين المؤقت. يحمل Periplus وطرد خلايا التلقيح الاصطناعي بأكملها في وقت واحد للحفاظ على سلامة الفهرس وضمان استدعاء مكافئ (على زيارات ذاكرة التخزين المؤقت) إلى مؤشر IVF قياسي. يتم تحميل خلايا التلقيح الاصطناعي عن طريق الاستعلام عن قاعدة بيانات المتجه عبر وكيل مع قائمة من معرفات المتجهات التي تحتفظ بها Periplus لتتبع المتجهات التي تشغل الخلايا. يمكن استدعاء هذه العمليات من قبل المستخدم باستخدام أوامر التحميل والبحث والإخلاء . للحصول على التفاصيل ، راجع قسم أوامر Periplus أدناه.

تشغيل periplus

يمكن تشغيل Periplus كحاوية Docker أو يمكن بناؤها من Source وتشغيلها على أنها قابلة للتنفيذ. لا توجد ثنائيات رسمية متاحة حاليا. إن تشغيل Periplus كحاوية هو النهج الموصى به ، ولكن كلاهما خيارات قابلة للحياة.

؟ تشغيل Periplus كحاوية

حاليًا ، تدعم صورة Docker فقط بنيات AMD64. ينبع هذا القيد من الصورة الأساسية ، ولكن سيتم دعم المزيد من الهياكل في المستقبل القريب. هناك طريقتان لتشغيل Periplus كحاوية: قم بتنزيل صورة Docker الرسمية من DockerHub (الموصى بها) أو بناء الصورة بنفسك. الخطوة الأولى في كلتا الحالتين هي تثبيت Docker إذا لم تقم بالفعل. يمكن العثور على التعليمات للقيام بذلك هنا.

باستخدام الصورة الرسمية

1. قم بتنزيل الصورة عن طريق التشغيل: docker image pull qdl123/periplus:latest .
2. قم بتشغيل الحاوية: docker run -p 3000:3000 qdl123/periplus:latest

بناء الصورة

1. استنساخ المستودع: git clone https://github.com/QDL123/Periplus.git
2. قرص مضغوط إلى جذر المستودع: cd <path-to-periplus-repo>/Periplus
3. بناء الصورة: docker build -t periplus-image .
4. قم بتشغيل الحاوية: docker run -p 3000:3000 periplus-image .

بناء periplus من المصدر

يستخدم Periplus cmake لنظام البناء. وتتوقع أن يتم تثبيت جميع التبعيات ثنائيات مسبقة من خلال Homebrew. يتم دعم Homebrew بواسطة MacOS و Ubuntu و WSL إذا كنت على Windows. تم بناء Periplus على MacOS/ARM64 و Ubuntu/AMD64. جميع مجموعات نظام التشغيل والهندسة المعمارية الأخرى غير مختبرة. لبناء periplus من المصدر ، اتبع الخطوات التالية:

1. تثبيت Homebrew: قم بزيارة الموقع الرسمي للموقع هنا للحصول على تعليمات التثبيت.
2. تثبيت تبعيات Periplus. لتثبيتها جميعًا مرة واحدة ، قم بتشغيل: brew install faiss curl cpr rapidjson libomp catch2 cmake
3. استنساخ المستودع: git clone https://github.com/QDL123/Periplus.git
4. قرص مضغوط إلى جذر المستودع: cd <path-to-periplus-repo>/Periplus
5. توليد makefile: cmake -S . -B build
6. تجميع القابل للتنفيذ: cmake --build build
7. Run Periplus (الاستماع على المنفذ 3000): ./build/periplus -p 3000

باستخدام periplus

سيتألف أي نظام يستخدم Periplus من 4 مكونات: قاعدة بيانات المتجه ، وكيل قاعدة البيانات الذي يسمح لـ Periplus بتحميل البيانات من قاعدة البيانات ، ومثيل Periplus ، وتطبيق العميل.

مثال بنية التطبيق باستخدام periplus.

قاعدة بيانات المتجه

أي قاعدة بيانات متجه تسمح بالبحث عن البيانات من خلال معرف فريد (جميعها فعليًا) ستعمل. تم تصميم Periplus ليكون أكثر فائدة عند العمل مع Collections vector كبيرة حقًا (على نطاق مليار) حيث يتعين على الفهرس أن يعيش على نظام الملفات بدلاً من ذاكرة الوصول العشوائي ، على الرغم من أن هذا ليس شرطًا.

وكيل قاعدة بيانات المتجه

الغرض من وكيل قاعدة بيانات Vector هو توفير واجهة متسقة لـ Periplus للتفاعل مع قاعدة بيانات المتجه من خلال. يجب على الوكيل تنفيذ واجهة REST التي تقبل طلبات النموذج التالي:

عنوان URL: هذا مرن ويمكن تحديده بواسطة عميل Periplus.

الرؤوس: "Content-Type": "application/json

جسم:

{
    "ids" : [ " id-1 " , " id-2 " , " id-3 " ]
}

إجابة:

{
    "results" : [
        {
            "id" : " String " ,
            "embedding" : [ 0.1 , 0.2 , 0.3 ],
            "document" : " String " ,
            "metdata" : " String "
        }
    ]
}

لجعل تنفيذ نقطة النهاية هذه أسهل ، يمكنك استخدام حزمة Periplus-proxy Python التي تستخدم Fastapi لإعداد كل شيء. كل ما يتعين على المستخدم القيام به هو تنفيذ الوظيفة التالية وتمريرها كوسيطة:

async def fetch_ids(request: Query) -> QueryResult

للحصول على تفاصيل حول كيفية القيام بذلك ، يمكنك التحقق من حزمة Periplus-proxy readme.md.

periplus

اتبع الإرشادات أعلاه لبدء مثيل Periplus.

تطبيق العميل

للتفاعل مع مثيل Periplus الخاص بك ، استخدم مكتبة عميل Periplus. حاليا فقط Python مدعوم. للحصول على تفاصيل حول مكتبة العميل ، يمكنك عرضها readMe.md.

أوامر periplus

1. تهيئة : هذا هو أمر الإعداد لـ Periplus. يجب استدعاؤه قبل أي أمر آخر وأي مكالمات تهيئة لاحقة سوف يمسح جميع البيانات وإعادة ضبط مثيل Periplus. هناك وسيطتان مطلوبان: D (أبعاد مجموعة المتجهات) ، و DB_URL (عنوان URL لنقطة نهاية وكيل قاعدة البيانات المستخدمة لتحميل البيانات). هناك أيضًا وسيطة كائن خيارات اختيارية مع خيارين متاحين: ntotal و use_flat . الأول ، ntotal ، هو تقدير إجمالي عدد المتجهات في المجموعة. يستخدم هذا لتحسين عدد خلايا التلقيح الاصطناعي لاستخدامه. إذا لم يتم تحديدها ، فسيقوم Periplus باختيار أرض وسط يمكن أن يؤدي إلى أداء دون المستوى الأمثل. والثاني ، use_flat ، هو منطقي يرشد Periplus إلى استخدام فهرس مسطح بدلاً من تطبيق أي كمية للمنتج (PQ). بشكل افتراضي ، هذه القيمة خاطئة ، وفي هذه الحالة سيتم تطبيق كمية المنتج إذا كانت المتجهات كبيرة بما يكفي وقابلة للقسمة بسهولة إلى عوامل فرعية. إذا تم ضبطه على TRUE ، فسيتم استخدام مؤشر IVF مسطح بدلاً من ذلك.
2. القطار : يحدد هذا الأمر موضع النطاقات الوسطى في مؤشر التلقيح الاصطناعي الذي يشكل أساس ذاكرة التخزين المؤقت. بمجرد تعيين مواضع النقطه الوسطى ، لا يمكن إعادة تعيينها دون مسح ذاكرة التخزين المؤقت تمامًا. يستغرق قائمة بتضمينات المتجهات كوسيطة يجب أن تكون عينة تمثيلية من مجموعة المتجهات الخاصة بك. يوصى باستخدام ما يصل إلى 10 ٪ من إجمالي مجموعتك ، ولكن أقل على ما يرام بالنسبة لمجموعات البيانات الكبيرة حقًا حيث يطغى 10 ٪ على مثيل Periplus.
3. إضافة : هذا الأمر يجعل Periplus على دراية بالبيانات دون ملء ذاكرة التخزين المؤقت فعليًا ، بحيث يمكن تحميلها لاحقًا من قاعدة البيانات. أي ناقل يجب أن يكون Periplus قادرًا على التحميل أولاً ، يجب تسجيله عبر أمر ADD. يأخذ الأمر اثنين من الوسيطة معرفات وتضمينات وهما قوائم ذات أطوال متساوية مع معرفات المتجهات وتضمين المتجه المقابل.
4. التحميل : يرشد هذا الأمر periplus لتحميل خلايا (خلية) IVF (انظر كيف يعمل للحصول على التفاصيل) من قاعدة البيانات. يحتوي على وسيطة مطلوبة واحدة ، ومتجه يخبرها عن الخلايا التي تستهدفها ، وكائن خيارات اختيارية مع خيار واحد متاح n_load الذي يخبرها عدد الخلايا التي يجب تحميلها. سيقوم Periplus بتحميل أقرب خلايا N_Load إلى المتجه من قاعدة البيانات (N_LOAD الافتراضية إلى 1 إذا لم يتم تحديدها). هذا يضمن أن أمر البحث اللاحق مع نفس المتجه سيؤدي إلى نجاح ذاكرة التخزين المؤقت (على افتراض أن الخلية لم يتم طردها مسبقًا وأن وسيطة N_Load تتطابق مع وسيطة N_Probe الواردة في البحث).
5. البحث : يقوم هذا الأمر بتشغيل مجموعة من الاستعلامات مقابل البيانات المخزنة في Periplus. يتطلب الأمر 2 وسيطتين مطلوبان: K الذي يحدد عدد أقرب الجيران للعودة ، و XQ وهي قائمة من متجهات الاستعلام. يأخذ اختياريا كائن خيارات مع خيارين متاحين: n_probe و require_all . الأول يحدد عدد خلايا التلقيح الاصطناعي للبحث. تؤدي القيم الأكبر إلى زيادة الكمون ولكن أيضًا زيادة الاستدعاء (ومعدل ضرب ذاكرة التخزين المؤقت أقل عند استخدام require_all ). القيمة الافتراضية هي 1 إذا كانت غير محددة. الخيار الثاني المتطلبات هو منطقية تملي سلوك ذاكرة التخزين المؤقت/MISS. إذا تم ضبطها على TRUE ، فيجب أن تكون جميع الخلايا الأقرب N_Probe في حالة إقامة للاستعلام ليكون عملية ذاكرة التخزين المؤقت. إذا كان خطأ ، يجب أن يكون أقرب خلية التلقيح الاصطناعي فقط في حالة إقامة للاستعلام ليكون ضربة ذاكرة التخزين المؤقت ، وسوف يبحث Periplus عن خلايا التلقيح الاصطناعي على الإطلاق حتى أقرب خلية IVF N_Probe . القيمة الافتراضية صحيحة. يقوم أمر البحث بإرجاع قائمة قوائم مستندات المستندات حيث تتوافق كل قائمة مع نتائج K لمتجه الاستعلام المقابل المقدم في هذا الفهرس. ستحتوي أخطاء ذاكرة التخزين المؤقت على قائمة بطول 0. في حالات نادرة ، إذا كان الطول> 0 و <k يشير إلى أن العدد الإجمالي للناقلات في أقرب خلايا N_Probe هو <k. يحتوي كل مستند Tuple على 4 حقول: ID ، التضمين ، بيانات التعريف ، والوثيقة التي ستتوافق مع القيم التي يوفرها وكيل قاعدة البيانات عند تحميل البيانات.
6. EVICT : يعمل هذا الأمر تمامًا مثل التحميل باستثناء أنه يفسد خلية (خلية) IVF إذا كانت موجودة من Periplus بدلاً من تحميلها. إنه يحتوي على إحراق واحد مطلوب ، ومتجه يخبره بالخلايا التي تستهدفها ، وكائن خيارات اختيارية مع خيار واحد متاح N_EVICT يخبرها عدد الخلايا التي يجب إخلائها. سوف يطرد Periplus الخلايا المقابلة لأقرب N_EVICT Centroids إلى المتجه من Periplus (N_EVICT الافتراضية إلى 1 لم يتم تحديدها).

مثال

 from periplus_client import Periplus

# host, port
client = Periplus ( "localhost" , 13 )

# vector dimensionality, database proxy url, options: (nTotal)
await client . initialize ( d = d , db_url = url , options = { "nTotal" : 50000 })

training_data = [[ 0.43456 , ..., 0.38759 ], ...]
await client . train ( training_data )

ids = [ "0" , ..., "n" ]
embeddings = [[ 0.43456 , ..., 0.38759 ], ...]
await client . add ( ids = ids , embeddings = embeddings )

load_options = { "n_load" : 2 }
# query_vector, optional: options object
await client . load ([ embeddings [ 0 ]] load_options )

# k, query_vector
response = await client . search ( 5 , [ embeddings [ 0 ]])
print ( response )
'''
[ // Results for each of the n query vectors in xq
    [ // K nearest neighbors to this corresponding index in the xq list
        (
            id="n",
            embedding=[0.43456, ..., 0.38759],
            document="",
            metadata="{}"
        ),
        ...
    ],
    ...
]
'''

# query_vector
await client . evict ( embeddings [ 0 ])

القياس

قريباً!

المساهمة

نرحب بالمساهمات في Periplus! لمعرفة كيفية البدء ، ألق نظرة على دليل المساهمة.

رخصة

تم ترخيص هذا المشروع بموجب ترخيص معهد ماساتشوستس للتكنولوجيا - راجع ملف الترخيص للحصول على التفاصيل.