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

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

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

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

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

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

المتطلبات المسبقة

قبل أن تبدأ باستخدام امتداد pgvector، يرجى التأكد من ما يلي:

1. أنك قمت بتثبيت ServBay وتفعيله على نظام macOS.
2. تم تفعيل حزمة PostgreSQL ضمن قائمة “الحزم البرمجية” في ServBay. إذا لم تكن مفعلة، افتح واجهة تطبيق ServBay وابحث عن PostgreSQL ثم اضبط الحالة على “مفعّل”.

تفعيل امتداد pgvector داخل PostgreSQL على ServBay

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

اتبع الخطوات التالية لتفعيل 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:

   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، يُمكنك إنشاء جداولك وإدارة بيانات المتجهات كما تريد.

إنشاء جدول يحوي بيانات المتجهات

أولًا، أنشئ جدولًا جديدًا لتخزين المتجهات. يوفر 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 (فهرسة ملف مقلوب بتسطير مسطح): مناسب للمجموعات الكبيرة مع متطلبات استرجاع (recall) غير عالية جدًا. سريع في البناء.
• HNSW (العوالم الصغيرة الملاحية الهرمية): غالبًا ما يوفر معدل استرجاع أعلى وسرعة بحث أكبر، لكن بناء الفهرس أبطأ واستهلاك الذاكرة أكبر.

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

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

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

2. إنشاء فهرس 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 أدوات متنوعة لحساب المسافة بين المتجهات؛ ما يتيح أداء عمليات البحث المشابهة (Similarity Search). من أهم معاملات البحث:

• <->: مسافة L2 (المسافة الإقليدية)، تقيس المسافة الخطية بين المتجهات
• <#>: الجداء الداخلي (Inner Product)، يرتبط بالتشابه الجيبي (cosine similarity)
• <=>: المسافة الجيبية (Cosine distance)، تساوي 1 - التشابه الجيبي

أمثلة استعلامية شائعة:

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

العثور على المتجهات الأقرب لمتجه البحث المحدد باستخدام ORDER BY وLIMIT.

1. إيجاد أقرب 5 متجهات إلى [0.2, 0.3, 0.4] باستخدام مسافة L2:

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

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

مشابه للبحث عن أقرب الجيران، لكنه يركّز أحيانًا على إظهار درجة التشابه.

1. البحث عن أقرب 5 متجهات بناءً على المسافة الجيبية وإظهار المسافة:

   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 أو خارجه). ينبغي تثبيت مكتبة الاتصال بـ PostgreSQL باسم psycopg2 ومكتبة الرسم matplotlib:

   # إذا كنت تستخدم Python الافتراضي أو المثبت بنفسك
   pip install psycopg2 matplotlib
   
   # إذا كنت تستخدم بايثون المفعّل من ServBay، استخدم أداة ServBay الطرفية أو مسار bin الخاص بها:
   # /Applications/ServBay/软件包/python/bin/pip install psycopg2 matplotlib

   اضبط مسار pip ليناسب بيئة بايثون لديك.

2. كتابة سكريبت Python: أنشئ ملفًا جديدًا مثل visualize_vectors.py، والصق فيه الكود التالي. لا تنسَ تعديل إعدادات الاتصال (dbname, user, password, host, port) بحسب إعداداتك في ServBay.

   import psycopg2
   import matplotlib.pyplot as plt
   from mpl_toolkits.mplot3d import Axes3D # لاستيراد أدوات الرسم ثلاثية الأبعاد
   
   # إعدادات الاتصال بقاعدة البيانات - عدلها حسب بيئتك
   db_params = {
       "dbname": "your_database_name", # اسم قاعدة بياناتك
       "user": "servbay",              # اسم مستخدم PostgreSQL (servbay أو postgres غالبًا)
       "password": "",                 # كلمة المرور إن وجدت (أحيانًا فارغة للاتصال المحلي)
       "host": "localhost",            # عادة محليًا في ServBay
       "port": "5432"                  # منفذ PostgreSQL الافتراضي في ServBay
   }
   
   conn = None
   cur = None
   
   try:
       # الاتصال بقاعدة البيانات
       conn = psycopg2.connect(**db_params)
       cur = conn.cursor()
   
       # استعلام بيانات المتجهات
       # ملاحظة: النوع vector يقرأ كسلسلة نصية، يجب تحليلها يدويًا
       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()
   
       # التأكد من تطابق الأبعاد (هنا: 3D)
       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('البعد 1')
       ax.set_ylabel('البعد 2')
       ax.set_zlabel('البعد 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 مثبتة ومفعلة جيدًا. ملف الامتداد يجب أن يكون داخل مجلد share/extension بتركيب PostgreSQL. إذا كان مفقودًا، جرب إعادة تثبيت/تحديث حزمة PostgreSQL ضمن ServBay.

• س: تظهر لي رسالة خطأ مصادقة عند الاتصال بقاعدة البيانات، ما الحل؟ ج: راجع متغيرات المستخدم، كلمة المرور، المضيف والمنفذ المستعملة في أمر psql أو السكريبت للتأكد من تطابقها مع إعداداتك. عادةً، المستخدم الافتراضي هو servbay أو postgres وغالبًا بلا كلمة مرور للاتصال المحلي.

• س: كيف أختار معلمات فهرسة المتجهات lists, m, ef_construction؟ ج: لا توجد قيم موحدة أو مثالية دومًا، إذ أن تأثيرها على الأداء والاسترجاع كبير. ستحتاج غالبًا لإجراء تجارب متعددة بناءً على حجم بياناتك وخصائص الاستعلام والأداء المطلوب. اطلع على وثائق pgvector لمزيد من النصائح حول التهيئة.

الخلاصة

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

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