دليل استخدام امتداد pgvector في PostgreSQL ضمن ServBay
يعد pgvector
امتداداً فعالاً لطرف ثالث لقواعد بيانات PostgreSQL، حيث يضيف نوع بيانات الشعاع (Vector) وأساليب فهرسة شعاعية سريعة مثل IVFFlat و HNSW. هذا يمكّن PostgreSQL من دعم تخزين الشعاعات والبحث عن التشابه بينها بشكل مدمج، مما يجعله خياراً مثالياً لتطوير تطبيقات الذكاء الاصطناعي، أنظمة التوصية، التعرف على الصور، ومعالجة اللغات الطبيعية التي تتعامل مع بيانات شعاعية عالية الأبعاد.
توفر ServBay بيئة تطوير ويب متكاملة ومحلية تشتمل بشكل مسبق على PostgreSQL وامتداد pgvector
، مما يسهل بشكل كبير عملية تفعيل واستخدام قاعدة بيانات الشعاعات على جهازك المحلي. في هذا الدليل سنستعرض كيفية الاستفادة من pgvector
عبر ServBay خطوة بخطوة.
ما هو pgvector؟ ولماذا هو مهم؟
في العديد من تطبيقات اليوم الحديثة، لم تعد البيانات فقط عبارة عن نصوص وأرقام منظمة. ومع انتشار الذكاء الاصطناعي وتعلم الآلة، تمثل البيانات غالباً على هيئة شعاعات (vectors) عالية الأبعاد، تُعرف بتضمينات ("embeddings"). هذه الشعاعات تلتقط المعاني أو السمات الداخلية للبيانات، مثل الخصائص البصرية للصور أو معاني النصوص أو تفضيلات المستخدمين.
يتيح امتداد pgvector
تخزين هذه الشعاعات في PostgreSQL وإجراء بحوث تشابه فعّالة بينها (المعروف أيضاً بمجال البحث عن الجار الأقرب - Nearest Neighbor Search). هذا يمكّن المطورين من استخدام لغة SQL المعتادة للبحث عن البيانات الأكثر تشابهاً مع شعاع معين، دون الحاجة لتخزين الشعاعات في قاعدة بيانات منفصلة، مما يُبسط البنية التقنية للمشروع.
المتطلبات الأساسية
قبل البدء باستخدام pgvector
، تأكد من توفر الأمور التالية:
- تم تثبيت وتشغيل ServBay على جهاز macOS الخاص بك.
- في قائمة "الحزم" ضمن ServBay، يجب أن تكون حزمة PostgreSQL مفعلة. إذا لم تكن مفعلة، يمكنك تفعيلها من واجهة ServBay عبر ضبط حالتها إلى "مفعلة".
تفعيل امتداد pgvector في PostgreSQL ضمن ServBay
تم تضمين ملفات امتداد pgvector
مسبقاً في دليل تثبيت PostgreSQL لدى ServBay، فلا حاجة لتحميل أو ترجمة الملفات يدوياً. يتعين فقط تفعيله ضمن قاعدة البيانات التي ترغب باستخدام الشعاعات فيها.
إليك الخطوات اللازمة لتفعيل pgvector
على قاعدة بيانات PostgreSQL في ServBay:
الاتصال بقاعدة بيانات PostgreSQL: يمكنك استخدام أداة سطر الأوامر
psql
للاتصال بقاعدة بيانات PostgreSQL المدمجة في ServBay. غالباً تسمح إعدادات ServBay افتراضياً بالاتصال المحلي مع المستخدم الافتراضي مثلpostgres
أوservbay
، والمنفذ الافتراضي هو5432
. إذا كانت إعداداتك مختلفة، المرجو الرجوع إلى وثائق إعداد قاعدة البيانات لدى ServBay.افتح الطرفية، واستخدم الأمر التالي للاتصال (قم بتعديل اسم المستخدم وقاعدة البيانات حسب إعداداتك):
bashpsql -U servbay -d your_database_name -h localhost -p 5432
1-U servbay
: لتحديد اسم المستخدم (مثلservbay
أوpostgres
).-d your_database_name
: اسم قاعدة البيانات المراد الاتصال بها. إذا لم تكن قد أنشأتها مسبقاً، أنشئها بواسطة أمر مثلCREATE DATABASE servbay_demo_db;
.-h localhost
: يشير إلى الاتصال المحلي.-p 5432
: رقم منفذ PostgreSQL الافتراضي في ServBay.
تفعيل امتداد
vector
: بعد الاتصال بنجاح، نفذ الأمر التالي من داخل موجهpsql
لتفعيل امتدادpgvector
:sqlCREATE EXTENSION vector;
1إذا تم تفعيله مسبقاً، قد يظهر لك تنبيه بوجوده سابقاً.
التحقق من التثبيت: للتأكد من نجاح تفعيل الامتداد، قم بعرض قائمة الامتدادات المثبتة عبر الأمر التالي:
sql\dx
1يجب أن يظهر امتداد باسم
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)
1
2
3
4
5
6(ملاحظة: رقم النسخة يختلف حسب إصدار pgvector المدمج في ServBay)
تهيئة واستخدام pgvector
عند تفعيل امتداد pgvector
، يمكنك الآن إنشاء وإدارة بيانات الشعاعات ضمن قاعدة البيانات.
إنشاء جدول لحفظ بيانات الشعاعات
أولاً، أنشئ جدولا لحفظ الشعاعات باستخدام نوع بيانات جديد VECTOR(dimensions)
، حيث dimensions
هو عدد أبعاد الشعاع.
مثال لإنشاء جدول باسم embeddings
لحفظ شعاعات ثلاثية الأبعاد:
sql
CREATE TABLE embeddings (
id SERIAL PRIMARY KEY,
-- تعريف عمود شعاع بثلاثة أبعاد
vector VECTOR(3)
);
1
2
3
4
5
2
3
4
5
بعدها يمكنك إدراج قيم شعاعية تجريبية على النحو التالي:
sql
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]'); -- أدخل بيانات إضافية لجعل نتائج الاستعلام أوضح لاحقاً
1
2
3
4
5
6
2
3
4
5
6
ملاحظة: يجب إدخال قيم الشعاع بين أقواس []
وبفواصل بين العناصر.
إنشاء فهرس شعاعي لتعزيز أداء الاستعلامات
إذا احتوى الجدول على كمية كبيرة من البيانات الشعاعية، فإن إنشاء فهرس محسن ضروري لتسريع البحث عن التشابه. يدعم pgvector
نوعي فهرسة أساسيين: IVFFlat و HNSW، ويعتمد اختيار الأدوات على طبيعة مشروعك (سرعة الاستعلام، وقت بناء الفهرس، استهلاك الذاكرة، نسبة الاسترجاع …إلخ).
- IVFFlat (Inverted File Index with Flat compression): يناسب البيانات الضخمة التي لا تتطلب أعلى معدلات الاسترجاع، ويتم بناؤه بسرعة نسبية.
- HNSW (Hierarchical Navigable Small World): يقدم عادة معدل استرجاع أعلى واستعلامات أسرع لكنه يستغرق وقتاً أطول للبناء ويستهلك ذاكرة أكثر.
للإشارة، إليك طريقة إنشاء الفهرسين على عمود vector
في جدول embeddings
:
إنشاء فهرس IVFFlat:
sql-- يفضل تنفيذ أمر ANALYZE لجمع إحصائيات قبل بناء فهرس IVFFlat ANALYZE embeddings; -- بناء فهرس IVFFlat -- WITH (lists = 100): تحديد عدد قوائم الفهرسة. اضبط الرقم حسب حجم البيانات -- كلما زاد العدد، زاد وقت بناء الفهرس، وتحسنت جودة نتائج البحث واستغرق البحث زمناً أطول أحياناً -- يوصى عادة بأن يكون lists = الجذر التربيعي لعدد الصفوف CREATE INDEX idx_ivfflat_vector ON embeddings USING ivfflat (vector) WITH (lists = 100);
1
2
3
4
5
6
7
8إنشاء فهرس HNSW:
sql-- بناء فهرس 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);
1
2
3
4
5
6ملاحظة: معلمات الفهرسة مثل
lists
,m
,ef_construction
تؤثر بشكل كبير على الأداء ونسبة الاسترجاع. ينصح بفهم طبيعة بياناتك وخيارات البحث لديك وتجربة عدة قيم عملياً. راجع دليل pgvector الرسمي لمزيد من التفاصيل والتوصيات حول ضبط الإعدادات.
استخدام pgvector لاستعلامات الشعاع
يوفر pgvector
مجموعة عوامل لحساب المسافة بين الشعاعات لإجراء بحث التشابه. من أبرزها:
<->
: المسافة L2 (مسافة إقليدية) لقياس المسافة المباشرة بين الشعاعات.<#>
: الضرب الداخلي (Inner Product)، مرتبط بمقياس التشابه الذي يعتمد على الاتجاه.<=>
: مسافة الكوساين (Cosine Distance)، وتساوي1 - تشابه الكوساين
، هي مقياس اتجاهي للشعاعات بغض النظر عن طولها.
إليك بعض الأمثلة على استعلامات الشعاع:
بحث الجار الأقرب (Nearest Neighbor Search)
للبحث عن الشعاعات الأكثر تشابهاً مع شعاع معين (أي ذات أقل مسافة)، استخدم ORDER BY مع عامل المسافة، وحدد عدد النتائج بواسطة LIMIT.
- استعلام عن أقرب 5 شعاعات لمسافة L2 من الشعاع
[0.2, 0.3, 0.4]
:sqlSELECT id, vector, -- احسب المسافة L2 مع الشعاع المطلوب vector <-> '[0.2, 0.3, 0.4]' AS distance FROM embeddings ORDER BY distance -- ترتيب تصاعدي حسب المسافة (الأقل الأكثر تشابهاً) LIMIT 5;
1
2
3
4
5
6
7
8
9
10
بحث التشابه الشعاعي (Similarity Search)
يشبه بحث الجار الأقرب لكن يركز أكثر على عرض قيمة التشابه.
- استعلام عن أقرب 5 شعاعات لمسافة الكوساين من الشعاع
[0.2, 0.3, 0.4]
مع عرض المسافة:sqlSELECT id, vector, -- احسب مسافة الكوساين مع الشعاع المُستعلم vector <=> '[0.2, 0.3, 0.4]' AS cosine_distance FROM embeddings ORDER BY cosine_distance -- ترتيب تصاعدي (الأقل الأكثر تشابهاً) LIMIT 5;
1
2
3
4
5
6
7
8
9
10
تصوير البيانات الشعاعية (اختياري)
تصوير الشعاعات عالية الأبعاد يساعدك على فهم توزع البيانات وتجمعها. إذا كانت الشعاعات ذات بعدين أو ثلاثة، يمكنك رسم مخطط نقاط مباشرة، وللأبعاد الأعلى غالباً تحتاج تقنيات "خفض الأبعاد" مثل PCA أو t‑SNE لإسقاط البيانات في مساحة ثنائية أو ثلاثية الأبعاد.
فيما يلي نموذج بسيط لاستخدام Python و مكتبة Matplotlib لتصوير الشعاعات ذات ثلاثة أبعاد.
تجهيز بيئة Python: يمكنك إعداد بيئة بايثون داخل أو خارج ServBay. إذا استخدمت الحزمة المدمجة في ServBay، تأكد من تفعيلها، وركّب مكتبة الاتصال بـ PostgreSQL (
psycopg2
) ومكتبة التصوير (matplotlib
):bash# حسب بايثون على نظامك أو حزمة بايثون في ServBay pip install psycopg2 matplotlib # إذا استخدمت بايثون ServBay قد تحتاج لمسار مختلف لـ pip # /Applications/ServBay/حزم/python/bin/pip install psycopg2 matplotlib
1
2
3
4
5عدّل مسار الأمر حسب بيئة بايثون لديك.
كتابة كود بايثون: أنشئ ملفاً باسم مثلاً
visualize_vectors.py
وضمّن الكود التالي. غيّر معطيات الاتصال حسب تكوين ServBay الخاص بك (اسم قاعدة البيانات، اسم المستخدم، كلمة السر، المضيف، والمنفذ).pythonimport 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()
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69تشغيل السكريبت: نفّذ السكريبت عبر الطرفية:
bashpython visualize_vectors.py
1سيقوم السكريبت بالاتصال بقاعدة بيانات 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، ستتمكن من بناء واختبار تطبيقات ويب حديثة ومشاريع البيانات المكثفة بأفضل صورة.