دليل استخدام امتداد pgvector في PostgreSQL ضمن ServBay

يعد pgvector امتداداً فعالاً لطرف ثالث لقواعد بيانات PostgreSQL، حيث يضيف نوع بيانات الشعاع (Vector) وأساليب فهرسة شعاعية سريعة مثل IVFFlat و HNSW. هذا يمكّن PostgreSQL من دعم تخزين الشعاعات والبحث عن التشابه بينها بشكل مدمج، مما يجعله خياراً مثالياً لتطوير تطبيقات الذكاء الاصطناعي، أنظمة التوصية، التعرف على الصور، ومعالجة اللغات الطبيعية التي تتعامل مع بيانات شعاعية عالية الأبعاد.

توفر ServBay بيئة تطوير ويب متكاملة ومحلية تشتمل بشكل مسبق على PostgreSQL وامتداد pgvector، مما يسهل بشكل كبير عملية تفعيل واستخدام قاعدة بيانات الشعاعات على جهازك المحلي. في هذا الدليل سنستعرض كيفية الاستفادة من pgvector عبر ServBay خطوة بخطوة.

ما هو pgvector؟ ولماذا هو مهم؟

في العديد من تطبيقات اليوم الحديثة، لم تعد البيانات فقط عبارة عن نصوص وأرقام منظمة. ومع انتشار الذكاء الاصطناعي وتعلم الآلة، تمثل البيانات غالباً على هيئة شعاعات (vectors) عالية الأبعاد، تُعرف بتضمينات ("embeddings"). هذه الشعاعات تلتقط المعاني أو السمات الداخلية للبيانات، مثل الخصائص البصرية للصور أو معاني النصوص أو تفضيلات المستخدمين.

يتيح امتداد pgvector تخزين هذه الشعاعات في PostgreSQL وإجراء بحوث تشابه فعّالة بينها (المعروف أيضاً بمجال البحث عن الجار الأقرب - Nearest Neighbor Search). هذا يمكّن المطورين من استخدام لغة SQL المعتادة للبحث عن البيانات الأكثر تشابهاً مع شعاع معين، دون الحاجة لتخزين الشعاعات في قاعدة بيانات منفصلة، مما يُبسط البنية التقنية للمشروع.

المتطلبات الأساسية

قبل البدء باستخدام pgvector، تأكد من توفر الأمور التالية:

1. تم تثبيت وتشغيل ServBay على جهاز macOS الخاص بك.
2. في قائمة "الحزم" ضمن ServBay، يجب أن تكون حزمة PostgreSQL مفعلة. إذا لم تكن مفعلة، يمكنك تفعيلها من واجهة ServBay عبر ضبط حالتها إلى "مفعلة".

تفعيل امتداد pgvector في PostgreSQL ضمن ServBay

تم تضمين ملفات امتداد pgvector مسبقاً في دليل تثبيت PostgreSQL لدى ServBay، فلا حاجة لتحميل أو ترجمة الملفات يدوياً. يتعين فقط تفعيله ضمن قاعدة البيانات التي ترغب باستخدام الشعاعات فيها.

إليك الخطوات اللازمة لتفعيل pgvector على قاعدة بيانات PostgreSQL في ServBay:

1. الاتصال بقاعدة بيانات PostgreSQL: يمكنك استخدام أداة سطر الأوامر psql للاتصال بقاعدة بيانات PostgreSQL المدمجة في ServBay. غالباً تسمح إعدادات ServBay افتراضياً بالاتصال المحلي مع المستخدم الافتراضي مثل postgres أو servbay، والمنفذ الافتراضي هو 5432. إذا كانت إعداداتك مختلفة، المرجو الرجوع إلى وثائق إعداد قاعدة البيانات لدى ServBay.

   افتح الطرفية، واستخدم الأمر التالي للاتصال (قم بتعديل اسم المستخدم وقاعدة البيانات حسب إعداداتك):

   psql -U servbay -d your_database_name -h localhost -p 5432

   • -U servbay: لتحديد اسم المستخدم (مثل servbay أو postgres).
   • -d your_database_name: اسم قاعدة البيانات المراد الاتصال بها. إذا لم تكن قد أنشأتها مسبقاً، أنشئها بواسطة أمر مثل CREATE DATABASE servbay_demo_db;.
   • -h localhost: يشير إلى الاتصال المحلي.
   • -p 5432: رقم منفذ PostgreSQL الافتراضي في ServBay.

2. تفعيل امتداد vector: بعد الاتصال بنجاح، نفذ الأمر التالي من داخل موجه psql لتفعيل امتداد pgvector:

   CREATE EXTENSION vector;

   إذا تم تفعيله مسبقاً، قد يظهر لك تنبيه بوجوده سابقاً.

3. التحقق من التثبيت: للتأكد من نجاح تفعيل الامتداد، قم بعرض قائمة الامتدادات المثبتة عبر الأمر التالي:

   \dx

   يجب أن يظهر امتداد باسم vector والمعلومات الخاصة بالنسخة.

                              List of installed extensions
      Name   | Version |   Schema   |                         Description
   ----------+---------+------------+--------------------------------------------------------------
    plpgsql  | 1.0     | pg_catalog | PL/pgSQL procedural language
    vector   | 0.7.0   | public     | vector data type and ivfflat and hnsw access methods
   (2 rows)

   (ملاحظة: رقم النسخة يختلف حسب إصدار pgvector المدمج في ServBay)

تهيئة واستخدام pgvector

عند تفعيل امتداد pgvector، يمكنك الآن إنشاء وإدارة بيانات الشعاعات ضمن قاعدة البيانات.

إنشاء جدول لحفظ بيانات الشعاعات

أولاً، أنشئ جدولا لحفظ الشعاعات باستخدام نوع بيانات جديد VECTOR(dimensions)، حيث dimensions هو عدد أبعاد الشعاع.

مثال لإنشاء جدول باسم embeddings لحفظ شعاعات ثلاثية الأبعاد:

CREATE TABLE embeddings (
    id SERIAL PRIMARY KEY,
    -- تعريف عمود شعاع بثلاثة أبعاد
    vector VECTOR(3)
);

بعدها يمكنك إدراج قيم شعاعية تجريبية على النحو التالي:

INSERT INTO embeddings (vector) VALUES
('[0.1, 0.2, 0.3]'),
('[0.4, 0.5, 0.6]'),
('[0.7, 0.8, 0.9]'),
('[0.15, 0.25, 0.35]'),
('[0.6, 0.5, 0.4]'); -- أدخل بيانات إضافية لجعل نتائج الاستعلام أوضح لاحقاً

ملاحظة: يجب إدخال قيم الشعاع بين أقواس [] وبفواصل بين العناصر.

إنشاء فهرس شعاعي لتعزيز أداء الاستعلامات

إذا احتوى الجدول على كمية كبيرة من البيانات الشعاعية، فإن إنشاء فهرس محسن ضروري لتسريع البحث عن التشابه. يدعم pgvector نوعي فهرسة أساسيين: IVFFlat و HNSW، ويعتمد اختيار الأدوات على طبيعة مشروعك (سرعة الاستعلام، وقت بناء الفهرس، استهلاك الذاكرة، نسبة الاسترجاع …إلخ).

• IVFFlat (Inverted File Index with Flat compression): يناسب البيانات الضخمة التي لا تتطلب أعلى معدلات الاسترجاع، ويتم بناؤه بسرعة نسبية.
• HNSW (Hierarchical Navigable Small World): يقدم عادة معدل استرجاع أعلى واستعلامات أسرع لكنه يستغرق وقتاً أطول للبناء ويستهلك ذاكرة أكثر.

للإشارة، إليك طريقة إنشاء الفهرسين على عمود vector في جدول embeddings:

1. إنشاء فهرس IVFFlat:

   -- يفضل تنفيذ أمر ANALYZE لجمع إحصائيات قبل بناء فهرس IVFFlat
   ANALYZE embeddings;
   
   -- بناء فهرس IVFFlat
   -- WITH (lists = 100): تحديد عدد قوائم الفهرسة. اضبط الرقم حسب حجم البيانات
   -- كلما زاد العدد، زاد وقت بناء الفهرس، وتحسنت جودة نتائج البحث واستغرق البحث زمناً أطول أحياناً
   -- يوصى عادة بأن يكون lists = الجذر التربيعي لعدد الصفوف
   CREATE INDEX idx_ivfflat_vector ON embeddings USING ivfflat (vector) WITH (lists = 100);

2. إنشاء فهرس HNSW:

   -- بناء فهرس HNSW
   -- WITH (m = 16, ef_construction = 200): معلمات فهرس HNSW
   -- m: عدد الروابط الأعظم لكل عقدة (يؤثر في الأداء والاستهلاك)
   -- ef_construction: نطاق البحث أثناء بناء الفهرس (يؤثر بالجودة والاستهلاك)
   -- قيم المعلمات قابلة للتعديل حسب الحاجة
   CREATE INDEX idx_hnsw_vector ON embeddings USING hnsw (vector) WITH (m = 16, ef_construction = 200);

   ملاحظة: معلمات الفهرسة مثل lists, m, ef_construction تؤثر بشكل كبير على الأداء ونسبة الاسترجاع. ينصح بفهم طبيعة بياناتك وخيارات البحث لديك وتجربة عدة قيم عملياً. راجع دليل pgvector الرسمي لمزيد من التفاصيل والتوصيات حول ضبط الإعدادات.

استخدام pgvector لاستعلامات الشعاع

يوفر pgvector مجموعة عوامل لحساب المسافة بين الشعاعات لإجراء بحث التشابه. من أبرزها:

• <->: المسافة L2 (مسافة إقليدية) لقياس المسافة المباشرة بين الشعاعات.
• <#>: الضرب الداخلي (Inner Product)، مرتبط بمقياس التشابه الذي يعتمد على الاتجاه.
• <=>: مسافة الكوساين (Cosine Distance)، وتساوي 1 - تشابه الكوساين، هي مقياس اتجاهي للشعاعات بغض النظر عن طولها.

إليك بعض الأمثلة على استعلامات الشعاع:

بحث الجار الأقرب (Nearest Neighbor Search)

للبحث عن الشعاعات الأكثر تشابهاً مع شعاع معين (أي ذات أقل مسافة)، استخدم ORDER BY مع عامل المسافة، وحدد عدد النتائج بواسطة LIMIT.

1. استعلام عن أقرب 5 شعاعات لمسافة L2 من الشعاع [0.2, 0.3, 0.4]:

   SELECT
       id,
       vector,
       -- احسب المسافة L2 مع الشعاع المطلوب
       vector <-> '[0.2, 0.3, 0.4]' AS distance
   FROM
       embeddings
   ORDER BY
       distance -- ترتيب تصاعدي حسب المسافة (الأقل الأكثر تشابهاً)
   LIMIT 5;

بحث التشابه الشعاعي (Similarity Search)

يشبه بحث الجار الأقرب لكن يركز أكثر على عرض قيمة التشابه.

1. استعلام عن أقرب 5 شعاعات لمسافة الكوساين من الشعاع [0.2, 0.3, 0.4] مع عرض المسافة:

   SELECT
       id,
       vector,
       -- احسب مسافة الكوساين مع الشعاع المُستعلم
       vector <=> '[0.2, 0.3, 0.4]' AS cosine_distance
   FROM
       embeddings
   ORDER BY
       cosine_distance -- ترتيب تصاعدي (الأقل الأكثر تشابهاً)
   LIMIT 5;

تصوير البيانات الشعاعية (اختياري)

تصوير الشعاعات عالية الأبعاد يساعدك على فهم توزع البيانات وتجمعها. إذا كانت الشعاعات ذات بعدين أو ثلاثة، يمكنك رسم مخطط نقاط مباشرة، وللأبعاد الأعلى غالباً تحتاج تقنيات "خفض الأبعاد" مثل PCA أو t‑SNE لإسقاط البيانات في مساحة ثنائية أو ثلاثية الأبعاد.

فيما يلي نموذج بسيط لاستخدام Python و مكتبة Matplotlib لتصوير الشعاعات ذات ثلاثة أبعاد.

1. تجهيز بيئة Python: يمكنك إعداد بيئة بايثون داخل أو خارج ServBay. إذا استخدمت الحزمة المدمجة في ServBay، تأكد من تفعيلها، وركّب مكتبة الاتصال بـ PostgreSQL (psycopg2) ومكتبة التصوير (matplotlib):

   # حسب بايثون على نظامك أو حزمة بايثون في ServBay
   pip install psycopg2 matplotlib
   
   # إذا استخدمت بايثون ServBay قد تحتاج لمسار مختلف لـ pip
   # /Applications/ServBay/حزم/python/bin/pip install psycopg2 matplotlib

   عدّل مسار الأمر حسب بيئة بايثون لديك.

2. كتابة كود بايثون: أنشئ ملفاً باسم مثلاً visualize_vectors.py وضمّن الكود التالي. غيّر معطيات الاتصال حسب تكوين ServBay الخاص بك (اسم قاعدة البيانات، اسم المستخدم، كلمة السر، المضيف، والمنفذ).

   import psycopg2
   import matplotlib.pyplot as plt
   from mpl_toolkits.mplot3d import Axes3D # استيراد أداة الرسم ثلاثي الأبعاد
   
   # بيانات اتصال قاعدة البيانات - ضبط حسب إعداداتك في ServBay
   db_params = {
       "dbname": "your_database_name", # ضع اسم قاعدة بياناتك هنا
       "user": "servbay",              # اسم المستخدم (servbay أو postgres غالباً)
       "password": "",                 # كلمة السر (قد تُترك فارغة للاتصال المحلي)
       "host": "localhost",            # عادةً يعمل ServBay PostgreSQL على localhost
       "port": "5432"                  # المنفذ الافتراضي
   }
   
   conn = None
   cur = None
   
   try:
       # الاتصال بقاعدة البيانات
       conn = psycopg2.connect(**db_params)
       cur = conn.cursor()
   
       # استعلام الشعاعات
       # ملاحظة: psycopg2 يقرأ نوع vector كسلسلة نصية '[x, y, z]'
       # يمكن معالجة القيمة يدوياً أو الاستفادة من إصدار وتوافق متقدم بين المسننات
       cur.execute("SELECT vector FROM embeddings")
       vectors_raw = cur.fetchall()
   
       # تحويل الشعاعات النصية إلى قوائم أرقام
       vectors = []
       for row in vectors_raw:
           vec_str = row[0].strip('[]')
           coords = [float(c) for c in vec_str.split(',')]
           vectors.append(coords)
   
       if not vectors:
           print("لم يتم العثور على بيانات شعاعية.")
           exit()
   
       # تأكد من صحة الأبعاد للجميع (هنا ثلاثي الأبعاد)
       if any(len(v) != 3 for v in vectors):
            print("تحذير: أبعاد الشعاعات غير متناسقة أو ليست ثلاثية لا يمكن رسم ثلاثي الأبعاد.")
            exit()
   
       x = [v[0] for v in vectors]
       y = [v[1] for v in vectors]
       z = [v[2] for v in vectors]
   
       # رسم النقاط ثلاثية الأبعاد
       fig = plt.figure()
       ax = fig.add_subplot(111, projection='3d')
       ax.scatter(x, y, z)
   
       ax.set_xlabel('Dimension 1')
       ax.set_ylabel('Dimension 2')
       ax.set_zlabel('Dimension 3')
       ax.set_title('تصوير الشعاعات ثلاثية الأبعاد')
   
       plt.show()
   
   except psycopg2.Error as e:
       print(f"خطأ في الاتصال أو الاستعلام من قاعدة البيانات: {e}")
   except Exception as e:
       print(f"حدث خطأ: {e}")
   finally:
       # إغلاق الاتصال بالقاعدة
       if cur:
           cur.close()
       if conn:
           conn.close()

3. تشغيل السكريبت: نفّذ السكريبت عبر الطرفية:

   python visualize_vectors.py

   سيقوم السكريبت بالاتصال بقاعدة بيانات PostgreSQL، ثم سحب البيانات الشعاعية ويرسم لك نافذة بها مخطط نقاط ثلاثي الأبعاد عبر Matplotlib.

الأسئلة الشائعة (FAQ)

• س: ماذا أفعل إذا لم يظهر امتداد vector في نتيجة الأمر \dx؟ ج: تأكد أنك نفذت أمر CREATE EXTENSION vector; بنجاح ولم تتلقَ أي أخطاء. إذا لم يظهر الامتداد، تحقق من تثبيت وتفعيل حزمة PostgreSQL ضمن ServBay بشكل صحيح. يجب أن تتواجد ملفات pgvector في دليل share/extension في PostgreSQL. إذا كانت الملفات مفقودة، ربما يلزم إعادة تثبيت أو تحديث حزمة PostgreSQL في ServBay.
• س: أواجه رسالة فشل في اعتماد الاتصال بقاعدة البيانات، ما الحل؟ ج: افحص بيانات الدخول (اسم المستخدم، كلمة السر، المضيف، والمنفذ) في أمر psql أو كود بايثون لتتطابق مع إعدادات ServBay. الاتصال المحلي عادة يتم باسم المستخدم servbay أو postgres وربما بدون كلمة سر.
• س: كيف أختار معلمات الفهرسة مثل lists, m, ef_construction؟ ج: هذه الإعدادات تؤثر كثيراً في الأداء ونسبة الاسترجاع، ولا توجد قيم مثالية واحدة. يجب تجربة عدة إعدادات حسب حجم البيانات وعدد الأبعاد ومتطلبات سرعة وقوة الاستعلام. راجع الوثائق الرسمية لـ pgvector للحصول على توصيات مفصلة.

الخلاصة

يجلب pgvector قوة قواعد البيانات الشعاعية إلى نظام PostgreSQL المستقر، ويوفر للمطورين إمكانيات تطبيقات الذكاء الاصطناعي والبحث الشعاعي بسهولة على بيئة التطوير المحلية. تسهيل ServBay لتفعيل امتداد pgvector يجعل بناء البيئة أكثر بساطة.

مع اتباع خطوات هذا الدليل، يمكنك تفعيل pgvector بسهولة ضمن PostgreSQL في ServBay، وإنشاء الجداول الشعاعية، بناء الفهارس السريعة، وتنفيذ استعلامات التشابه بكفاءة. مع أدوات التطوير الأخرى التي تتيحها ServBay، ستتمكن من بناء واختبار تطبيقات ويب حديثة ومشاريع البيانات المكثفة بأفضل صورة.