استكشاف الأخطاء وإصلاحها¶

دفتر تشغيل خدمة البحث¶

حالة الخدمة: تعمل بكفاءة

خدمة البحث، المدعومة بـ OpenSearch، هي العمود الفقري لاسترجاع البيانات في منصة لبيب. توفر نتائج بحث سريعة، قابلة للتوسع، وذات صلة من خلال الجمع بين البحث بالكلمات الرئيسية التقليدي والبحث الدلالي الحديث القائم على المتجهات.

1. المسؤوليات الأساسية¶

فهرسة البيانات: تخزين وفهرسة جميع المقالات المعالجة، مما يجعلها متاحة للبحث.
البحث الهجين: تنفيذ استعلامات بحث هجينة، تجمع بين نتائج البحث المعجمي (BM25) والبحث الدلالي (k-NN).
مسارات البحث: استضافة وإدارة مسارات OpenSearch المستخدمة لدمج النتائج في وقت الاستعلام (مثل Reciprocal Rank Fusion - RRF).
البنية التحتية كشيفرة برمجية (IaC): تتم إدارة جميع تكوينات العنقود — قوالب الفهارس، قوالب المكونات، والمسارات — كملفات JSON خاضعة للتحكم في الإصدارات.

2. البيانات التشغيلية الرئيسية¶

يوفر هذا القسم الأوامر ونقاط النهاية الأساسية لتشغيل عنقود OpenSearch.

العملية	الأمر / نقطة النهاية
صحة العنقود	`curl http://localhost:9200/_cluster/health?pretty`
عرض الفهارس	`curl http://localhost:9200/_cat/indices?v`
عرض مخطط الفهرس	`curl http://localhost:9200/news_docs/_mapping?pretty`
فتح الطرفية	`docker compose exec opensearch bash`

3. البنية التحتية كشيفرة برمجية (IaC)¶

نحن لا ندير عنقود OpenSearch يدويًا. يتم تعريف جميع التكوينات كشيفرة برمجية لضمان الاتساق، قابلية التكرار، والتحكم في الإصدارات.

موقع ملفات IaC

التعريفات الأساسية بصيغة JSON لجميع موارد OpenSearch موجودة في المجلد api/resources/search/.

قوالب الفهارس: تحدد المخططات (mappings)، الإعدادات، والأسماء المستعارة لفهارسنا (مثل news_docs.json).
قوالب المكونات: وحدات بناء قابلة لإعادة الاستخدام لقوالب الفهارس (مثل knn_base.json, analysis_ar.json).
مسارات المعالجة: تحدد المعالجات لعمليات الجلب والبحث (مثل hybrid_rrf.json).

سكربتات إدارة IaC¶

يتم استخدام سكربتين أساسيين في المجلد tools/search/ لإدارة هذا التكوين.

install.sh

سكربت إعداد لمرة واحدة يقوم بتطبيق جميع ملفات IaC على عنقود OpenSearch. يقوم بإنشاء القوالب والمسارات المطلوبة لكي يعمل النظام.
smoke.sh

سكربت قوي ومتطابق النتائج يتحقق من تكوين البحث بأكمله. يقوم بتثبيت جميع الموارد إذا كانت مفقودة، وينشئ فهرسًا للاختبار، ويغذيه بالبيانات، ويجري سلسلة من الاستعلامات للتأكد من أن البحث الهجين يعمل بشكل صحيح.
هذه هي أداتك الأساسية للتحقق من النظام الفرعي للبحث.
```
# قم بتشغيل اختبار التحقق (smoke test) للتحقق من أو إصلاح تكوين البحث
bash tools/search/smoke.sh
```

4. استكشاف الأخطاء وإصلاحها¶

وضع الفشل الشائع: حالة العنقود صفراء أو حمراء

العرض: نقطة النهاية /_cluster/health تظهر status بقيمة yellow أو red.

خطوات الفرز والتشخيص:

التحقق من حالة العقد: حالة yellow غالبًا ما تشير إلى وجود أجزاء (shards) غير مخصصة ولكن العنقود لا يزال يعمل. حالة red تعني أن جزءًا أساسيًا واحدًا على الأقل غير متاح، والعنقود لا يعمل.
البحث عن العقد المتعطلة: استخدم docker compose logs opensearch للبحث عن الأخطاء، خاصة استثناءات نفاد الذاكرة (OutOfMemoryError).
تخصيص المزيد من الذاكرة: إذا رأيت أخطاء في الذاكرة، قم بزيادة قيمة OPENSEARCH_JAVA_OPTS في ملف docker-compose.yml (على سبيل المثال، من -Xms512m -Xmx512m إلى -Xms1g -Xmx1g).

وضع الفشل الشائع: مخططات غير صحيحة

العرض: فشل سكربت smoke.sh مع خطأ مثل embedding.dimension != 768.

خطوات الفرز والتشخيص:

تشغيل اختبار التحقق (Smoke Test): تم تصميم سكربت smoke.sh لاكتشاف مشاكل المخططات وإصلاحها تلقائيًا في كثير من الأحيان عن طريق الانتقال إلى فهرس جديد.
فحص المخططات يدويًا: استخدم curl http://localhost:9200/news_docs/_mapping?pretty لفحص المخطط الحالي ومقارنته بالتعريف في api/resources/search/templates/news_docs.json.
إعادة تثبيت القوالب: إذا كانت المخططات غير صحيحة، يمكنك إعادة تشغيل سكربت install.sh يدويًا، على الرغم من أن هذا لا ينبغي أن يكون ضروريًا عادةً.