دروس فالذكاء الاصطناعي

بناء خدمة زبناء للتجارة الإلكترونية بـ Adaptive-RAG من الصفر: الاسترجاع التكيفي، التعرّف على النوايا وأدوات الطلبات عملياً

هاد الدليل غادي يرافقك باش تشغّل محلياً خدمة زبناء للتجارة الإلكترونية بـ Adaptive-RAG، وتفهم الاسترجاع الديناميكي، استكمال الأدلة على مراحل، التحقق من الوفاء للمصادر، والتعرّف على النوايا باستعمال Jev وDeepSeek، مع تجربة الإجابة على السياسات، البحث فَالطلبات، التأكيد البشري، الاختبارات والتقييم، ثم النشر باستعمال Docker.

October 15, 2026حوالي 31 دقايق ديال القراية

بناء خدمة زبناء للتجارة الإلكترونية بـ Adaptive-RAG من الصفر

مقدّمة على المشروع

Adaptive-RAG لخدمة الزبناء فالتجارة الإلكترونية هو مشروع ديال خدمة زبناء ذكية موجّه للاستفسارات على السياسات اللي فيها بزاف ديال الشروط. كيركّز على حلّ مشاكل بحال نقص الأدلة، والأجوبة اللي ما عندهاش أساس كافي، والأسئلة المعقّدة اللي ما يمكنش يكمّل البحث عليها فمرة وحدة. الباك إند مبني بـ FastAPI وLangGraph، والفرونت إند كيستعمل React. النظام كيقدر يختار ديناميكياً، حسب نية المستخدم وتعقيد السؤال، بين الجواب المباشر، والبحث فالمعرفة، والبحث التكميلي، وتنفيذ الأدوات، والتأكيد البشري، ورفض الجواب.

المشروع مناسب للعرض محلياً، وتعلّم سيرورة Adaptive RAG، والتحقق الهندسي. كيدعم الإشارة لمصادر السياسات، والبحث التجريبي فطلبات الشراء، والعمليات اللي كتحتاج التأكيد، وذاكرة المحادثة، واستجابات SSE، ولكن بيانات الطلبات والتوصيل ماشي بيانات حقيقية ديال نشاط تجاري.

حالياً الـ API كيقبل مباشرة user_id اللي كيدوزو الكليان، ومازال ما كيتحققش من الهوية الحقيقية ديالو. ما تنشرش المشروع مباشرة فالإنترنت العمومي بلا ما تربطو بنظام موثوق للتحقق من الهوية، وTLS، والتحكم فالوصول.

كيفاش كيعالج النظام طلب واحد

منين كيدوز المستخدم السؤال عبر صفحة الويب ولا HTTP API، الطلب كيدوز بالتتابع من حواجز الإدخال، والتعرّف على النية، والتوجيه حسب التعقيد. من بعد كيختار النظام المسار المناسب، وفالأخير كيكمل توليد الجواب، والتحقق من الوفاء للمصادر، وتحديث ذاكرة المحادثة، وإرجاع المراجع.

المستخدم → Web / HTTP API → حواجز الإدخال
         → التعرّف على النية → التوجيه حسب التعقيد
           ├─ جواب مباشر
           ├─ بحث → ترتيب دقيق → بحث تكميلي عند الحاجة
           ├─ تخطيط → تنفيذ الأدوات / تأكيد بشري
           └─ رفض الجواب
         → التوليد والتحقق من الوفاء للمصادر → ذاكرة المحادثة → الجواب والمراجع

التعرّف على النية يقدر يستعمل DeepSeek الافتراضي، ولا يقدر يتحوّل لـ TypeSafe Jev. خاص الانتباه أن Jev كيبدّل غير عقدة تصنيف النية؛ أما الحكم على التعقيد، وإعادة صياغة الاستعلام، وتخطيط المهام، وتوليد الأجوبة، والتحقق من الوفاء للمصادر، وتلخيص الذاكرة، وباقي عقد LLM، فكيبقاو مسؤولية DeepSeek.

القدرات الأساسية

التوجيه التكيفي: كيجمع بين نية النشاط وتعقيد السؤال، وكيختار بين الجواب المباشر، والبحث بجولة وحدة، والبحث متعدد الجولات، وتنفيذ الأدوات، ولا رفض الجواب.
البحث الهجين: كيجمع بين استرجاع BM25 والمتجهات الكثيفة، وكيستعمل RRF لدمج النتائج، ويقدر يفعّل الترتيب الدقيق بـ Cross-Encoder.
تقوية الأدلة: كيدعم إعادة صياغة الاستعلام، والبحث التكميلي منين كتكون الأدلة ناقصة، والتحقق من وفاء الجواب، والتصحيح الذاتي.
دعامتان للنوايا: كيتستعمل DeepSeek افتراضياً، ويقدر Jev يتعرّف على 14 نوع محدد مسبقاً من نوايا النشاط عبر واجهة choice المهيكلة.
معالجة الوثائق: كيدعم Markdown مباشرة؛ ومن بعد تثبيت التبعيات الاختيارية وأدوات النظام، يقدر يعالج وثائق PDF وOffice وOCR.
التقسيم المهيكل: النص العادي كيستعمل افتراضياً نافذة من 500 حرف وتداخل من 60 حرف؛ والجداول اللي كيتعرّف عليها النظام كتتحط فكتل مستقلة، مع الاحتفاظ بالعنوان، والقسم، والمصدر، وباقي البيانات الوصفية.
أدوات النشاط: كيوفّر أدوات تجريبية خاصة بالطلبات، فيها التحقق من الصلاحيات، والتراجع، والتأكيد البشري، وآلية عدم التكرار، ويقدر حتى يربط أدوات MCP.
القدرات الهندسية: فيها ضغط ذاكرة المحادثة، وسجلات مهيكلة، ومؤشرات Prometheus، وفحص الصحة، واختبارات آلية.

تحضير بيئة التشغيل

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

Python 3.11 ولا إصدار أحدث.
إلى بغيتي تشغّل فرونت إند الويب، استعمل Node.js 20.19+ ولا 22.12+، وحضّر npm.
الوضع المحلي الافتراضي كيستعمل SQLite ومكوّنات البحث فالذاكرة، وما كيحتاجش تشغيل Docker من قبل.

خطوات التثبيت فـ Windows PowerShell

من بعد ما تستنسخ المستودع وتمشي لجذر المشروع، أنشئ البيئة الافتراضية، وثبّت تبعيات التطوير، وانسخ ملف الإعدادات، وولّد بيانات العرض:

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
Copy-Item .env.example .env
.\.venv\Scripts\python.exe -m scripts.seed_demo

إلى كان ملف .env موجود من قبل فجذر المشروع، خليه كيف ما هو وتجاوز أمر النسخ. من بعد شغّل FastAPI:

.\.venv\Scripts\python.exe -m uvicorn app.asgi:app --reload --host 127.0.0.1 --port 8000

macOS وLinux

فـ macOS ولا Linux، تقدر تنشئ البيئة الافتراضية وتفعّلها، ومن بعد تنفّذ أوامر التثبيت المناسبة:

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env
python -m scripts.seed_demo
python -m uvicorn app.asgi:app --reload --host 127.0.0.1 --port 8000

إعداد النماذج والخدمات المحلية

حلّ ملف .env اللي كاين فجذر المشروع. هادي أهم الإعدادات اللي خاصك تراجعها أولاً:

DEEPSEEK_API_KEY: كيفعّل سيرورة DeepSeek وتصنيف النية الافتراضي. الاستدعاءات الحقيقية للـ API تقدر تسبّب مصاريف.
INTENT_BACKEND: يقدر يكون deepseek الافتراضي ولا jev الاختياري.
JEV_API_KEY: ضروري لتفعيل تصنيف النية بـ Jev.
JEV_MODEL: القيمة الافتراضية الحالية فالمشروع هي jev-1.13.0.
DATABASE_URL: كيتستعمل افتراضياً sqlite+aiosqlite:///./data/local/app.db.
KNOWLEDGE_DIR: القيمة الافتراضية هي knowledge، ووثائق المعرفة اللي فيه كتدخل لقاعدة البيانات وقت التشغيل.
LOCAL_EMBEDDING_ENABLED: كيتحكم فوظيفة المتجهات الدلالية المحلية.
CROSS_ENCODER_ENABLED: كيتحكم فوظيفة الترتيب الدقيق المحلية.
REDIS_URL وQDRANT_URL: كيتستعملو لإعداد خدمات التخزين المؤقت والمتجهات الخارجية الاختيارية.

إلى ما ضبطتيش مفتاح DeepSeek، النظام يقدر يبقى خدام بمنطق العرض غير المتصل، ولكن جودة الأجوبة غتكون مختلفة على وضع النموذج الحقيقي. تقدر تشوف المتغيرات كاملة فـ مرجع الإعدادات وملف البيئة النموذجي.

تشغيل واجهة المحادثة بـ React

خلي عملية الباك إند خدامة، وفترمينال آخر دخل لمجلد الفرونت إند:

cd frontend
npm ci
npm run dev

دخل لـ http://127.0.0.1:5173 باش تحل صفحة المحادثة. سيرفر التطوير غيدوز طلبات /api للمنفذ المحلي 8000.

الفرونت إند كيدعم مراجع المصادر، ولائحة الجلسات المحلية، وبطاقات تأكيد العمليات. الباك إند كيرسل المحتوى على دفعات عبر SSE من بعد ما يكمل التحقق من الجواب. إلى نفّذتي npm run build وتولّدات frontend/dist، FastAPI منين كيلقا هاد المجلد كيقدّم صفحة الفرونت إند من المسار الجذري.

الاستعمال الأساسي: الاستفسار على سياسة الإرجاع والاستبدال

أولاً تأكد من حالة الخدمة:

دابا استعمل PowerShell باش تبعث للواجهة ديال المحادثة سؤال فيه شروط متعددة ديال السياسة:

$payload = @{
    message = "دازو سبعة أيام على الكوب المخصص، ولكن فيه مشكل فالجودة، واش نقدر نرجعو؟"
    user_id = "u_demo"
} | ConvertTo-Json

Invoke-RestMethod `
    -Uri "http://127.0.0.1:8000/api/v1/chat" `
    -Method Post `
    -ContentType "application/json; charset=utf-8" `
    -Body ([System.Text.Encoding]::UTF8.GetBytes($payload))

النظام غيتعرّف أولاً على النية المرتبطة بالإرجاع والاستبدال، ومن بعد غيقرر حسب تعقيد السؤال واش خاصو يبحث فوثائق السياسة. إلى كانت الأدلة الأولى ناقصة، تقدر سيرورة العمل تعاود تصيغ الاستعلام وتكمّل البحث؛ ومن بعد توليد الجواب، غيتحقق النظام حتى واش الجواب وفيّ للأدلة المسترجعة، وغترجع المراجع المتاحة للمصادر.

إضافة للـ HTTP API، تقدر أثناء ما الباك إند خدام تنفّذ الأمر التالي باستعمال عميل الطرفية:

python -m app.cli

الاستعمال الأساسي: البحث فالطلبات التجريبية وتنفيذ العمليات عليها

الأمر scripts.seed_demo كينشئ الطلبات التجريبية بشكل صريح. تشغيل الـ API بوحدو ما كيكتبش هاد البيانات أوتوماتيكياً، لذلك ما تتجاوزش تهيئة البيانات فأول تشغيل. المستخدم التجريبي هو u_demo، والطلبات المتاحة هي:

ORD10001: تشحن، والمنتج هو سماعات عازلة للضجيج.
ORD10002: توصلات، والمنتج هو كوب مخصص.
ORD10003: تخلصات ومازال ما تشحناتش، والمنتج هو تي-شيرت.

مثلاً، كتب فصفحة المحادثة إلغاء الطلب ORD10003. منين كينفّذ النظام عملية كتحتاج التأكيد، يقدر يرجّع pending_action. خاص طلب التأكيد يرجّع معاه session_id اللي جا فالاستجابة، وتحط pending_action.action_id فـ confirm_action_id. صفحة الويب كتستعمل بطاقة التأكيد باش تعاونك تكمل هاد المسار.

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

إعداد متقدم: تفعيل التعرّف على النية بـ Jev

باش تحوّل عقدة تصنيف النية لـ TypeSafe Jev، زِد ولا بدّل الإعدادات التالية فـ .env المحلي:

INTENT_BACKEND=jev
JEV_API_KEY=your_jev_api_key
JEV_ENDPOINT=https://api.typesafe.ai/v1/systemone
JEV_MODEL=jev-1.13.0
JEV_TIMEOUT_SECONDS=10
JEV_MAX_RETRIES=2
JEV_INTENT_APPLY_OVERLAY=true

DEEPSEEK_API_KEY=your_deepseek_api_key

من بعد الحفظ عاود شغّل الباك إند. Jev كيتربط عبر HTTP، وما كيحتاجش تثبيت SDK خاص. النتيجة الراجعة كتدوز من تحقق Pydantic، ومن بعد كتتحوّل لنتيجة تصنيف موحّدة.

إلى كان مفتاح Jev ناقص، ولا فشل الطلب، ولا كانت الاستجابة غير صالحة، النظام كيرجع لـ IntentClassifier الأصلي. مسار الرجوع كيعطي الأولوية لـ DeepSeek المضبوط فالإعدادات؛ وفالوضع غير المتصل ولا منين كيفشل استدعاء النموذج، كيكمل باستعمال التصنيف بالقواعد. الأخطاء اللي يمكن إعادة المحاولة فيها كتستعمل تراجعاً أُسّياً، وJEV_MAX_RETRIES كتعني فالتنفيذ الحالي العدد الأقصى ديال المحاولات.

JEV_INTENT_APPLY_OVERLAY كيتحكم فتصحيح القواعد من بعد نجاح Jev فالتصنيف، وهو مفعّل افتراضياً. هاد الخيار ما كيتحكمش فطبقة التصحيح ديال مصنّف الرجوع نفسه. باش ترجع لتصنيف النية الافتراضي، غير بدّل INTENT_BACKEND ورجّعو لـ deepseek.

إعدادات متقدمة: تحسين الاسترجاع وتحليل الوثائق

تثبيت تبعيات المتجهات المحلية وإعادة الترتيب

.\.venv\Scripts\python.exe -m pip install -e ".[rerank]"

تبعيات rerank مخصصة لنماذج المتجهات الكثيفة المحلية وCross-Encoder. النموذج الافتراضي للمتجهات هو BAAI/bge-small-zh-v1.5، ونموذج إعادة الترتيب الافتراضي هو BAAI/bge-reranker-base. عند أول تحميل، يمكن يتنزلو أوزان النماذج؛ وإذا ما كانش النموذج متاح، النظام كيرجع لوضع بديل، وبالتالي النتيجة ما كتكونش بحال إعداد كامل بالنموذج.

تثبيت تبعيات تحليل الوثائق الإضافية

.\.venv\Scripts\python.exe -m pip install -e ".[docs]"

تبعيات docs مخصصة لتحليل الوثائق باستعمال Unstructured. عند معالجة ملفات PDF وOCR وOffice، يمكن تحتاج حتى تثبّت Poppler وTesseract وحزم اللغة الصينية وLibreOffice. التفاصيل كاينة فـ شرح التحليل والاسترجاع.

معرّف كل قطعة معرفة كيتولد انطلاقاً من مسار الوثيقة ورقم القطعة. إلا بقى المسار ونتيجة التقسيم كيف ما هما، فإعادة إدخال البيانات تقدر تحافظ على نفس المعرّفات؛ من بعد نقل الملف أو تعديل المحتوى أو تغيير استراتيجية التقسيم، ما كاينش ضمان أن الإحالات القديمة تبقى كتشير لنفس المحتوى.

تشغيل الخدمة كاملة باستعمال Docker

إلا بغيتي تشغّل API وPostgreSQL وRedis وQdrant والواجهة Web المبنية فـ نفس الوقت، وجد أولاً ملف .env محلي، ومن بعد شغّل:

docker compose up --build

من بعد التشغيل، دخل لـ http://127.0.0.1:8000. كلمة سر قاعدة البيانات وربط المنافذ فـ Compose مخصصين غير للعرض المحلي. قبل النشر على الإنترنت، خاصك تبدّل كلمات السر التجريبية، وتقيّد منافذ قاعدة البيانات والذاكرة المؤقتة، وتفعّل المصادقة الموثوقة وTLS، وتوجد خطة موثوقة للاستمرارية والتشغيل.

الاختبارات والفحص الثابت والتقييم

شغّل اختبارات الخلفية وفحوصات الجودة من جذر المشروع:

.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\python.exe -m ruff check app eval tests
.\.venv\Scripts\python.exe -m mypy
.\.venv\Scripts\python.exe -m eval.runner --task retrieval

خاص تشغيل اختبارات الواجهة وأوامر البناء من داخل مجلد frontend:

npm test
npm run build

إعدادات الاختبار كتعزل مفاتيح النماذج المحلية وكتستعمل قاعدة بيانات للاختبار. قبل تشغيل تقييم نموذج حقيقي بشكل منفصل، خاصك تراجع إعدادات النموذج والشبكة، حيث إن استدعاء النماذج الخارجية يقدر يسبب مصاريف.

مقارنة تصنيف النوايا بين Jev وDeepSeek

من بعد إعداد المفاتيح المحلية للنموذجين، تقدر تشغّل المقارنة على نفس العينات وبنفس شروط طبقة التغطية:

.\.venv\Scripts\python.exe -m eval.compare_intent --backend both --limit 10 --no-overlay --output data/local/intent-comparison.json

التقرير كيتضمن الدقة، وزمن الاستجابة P50 وP95، وعدد مرات الرجوع للوضع البديل، وعدد مرات تطبيق القواعد. الخيار --no-overlay كيعطّل تصحيح القواعد فـ المصنّفين بجوج، باش تقدر تلاحظ نتائج التصنيف ديال النموذج بوحدو؛ وإلا حيدتي هاد الخيار، تقدر تقارن النتيجة من بعد إضافة طبقة التغطية.

مجموعة بيانات النوايا الحالية ما زالت مجموعة تطوير، والدقة كتشمل عينات الرجوع للوضع البديل، لذلك ما يمكنش اعتبارها مباشرة مقياساً لقدرة نموذج Jev المستقل على التعميم. التقييمات القديمة حتى هي ما كتثبتش أن النسخة الحالية تعاود التحقق منها، وما كتضمنش النتائج فـ الأعمال الحقيقية.

نصائح هندسية عملية

بدا أولاً بالوضع المحلي الافتراضي للتحقق من المسار: SQLite ومكوّنات الاسترجاع فالذاكرة كافيين للعرض الأساسي، وما كاينش داعي تنشر قاعدة بيانات خارجية وخدمة متجهات من البداية.
فرّق بين نموذج النوايا ونموذج سير العمل: التبديل إلى Jev ما كيبدّلش عقد DeepSeek الأخرى. إلا بغيتي تشغّل سير عمل كامل على الإنترنت، خاصك تبقى مهيّأ DeepSeek.
استعمل واجهات الصحة لتشخيص المشاكل: /api/v1/health مخصص لفحص العملية، و/api/v1/ready أنسب للتأكد واش التبعيات واجدة.
بدّل استراتيجية التقسيم بحذر: تغيّر المسار أو محتوى النص أو معاملات التقسيم يقدر يأثر على معرّفات القطع والإحالات القديمة.
ما تعتمدش على حالة التأكيد داخل العملية: العمليات اللي كتستنى التأكيد عندها مدة صلاحية افتراضية قدرها 15 دقيقة، وقد تضيع بسبب إعادة التشغيل أو التبديل بين عمليات متعددة.
حمي البيانات الحساسة: ما ترفعش .env ولا المفاتيح الحقيقية ولا قاعدة البيانات المحلية ولا السجلات ولا الوثائق اللي كيحمّلها المستخدمون ولا الملفات الخاصة إلى GitHub.
راجع نقل البيانات الخارجية: قبل استعمال نموذج خارجي أو MCP بعيد، تأكد أن الطلبات ما فيهاش معلومات المستخدمين اللي ما خاصهاش تخرج للخارج.
خطّط لتحديث قاعدة المعرفة: النظام الحالي كيدخل جميع البيانات عند التشغيل، وما زال ما كيوفّرش مساراً كاملاً للحذف التدريجي.

نظرة سريعة على مجلدات المشروع

app/api: واجهة HTTP وSSE.
app/agents: رسم التنفيذ ديال LangGraph وعقد سير العمل.
app/retrieval: التحليل والتقسيم والاسترجاع والدمج وإعادة الترتيب.
app/providers: تكييف النماذج وخدمات المتجهات.
app/tools: أدوات الأعمال وتسجيل الأدوات والتحكم فالصلاحيات.
app/mcp: ربط أدوات MCP.
app/memory: ذاكرة الجلسة والضغط.
app/guardrails: فحص الإدخال والجواب.
app/observability: السجلات والمقاييس.
frontend: واجهة الدردشة بـ React وTypeScript.
knowledge: وثائق المعرفة المتعلقة بالسياسات.
tests وeval: الاختبارات الآلية وبيانات التقييم والمشغّل.

الخلاصة

Adaptive-RAG لخدمة زبناء التجارة الإلكترونية كيعرض مساراً هندسياً متكاملاً نسبياً لخدمة ذكية: كيبدا بالتعرف على النية وتقدير التعقيد، ومن بعد كيركّب حسب الحاجة بين الاسترجاع المختلط، واستكمال الأدلة عبر عدة جولات، واستدعاء الأدوات، والتأكيد البشري، والتحقق من مطابقة الجواب للمصادر. تقدر تبدا بـ SQLite والطلبات التجريبية والمنطق غير المتصل باش تجرّب بسرعة، ومن بعد تفعّل تدريجياً DeepSeek وJev ونموذج المتجهات المحلي وCross-Encoder وتحليل الوثائق الإضافي وخدمات Docker.

قبل الدخول فـ الأعمال الحقيقية، خاص بالخصوص استكمال المصادقة على الهوية، وربط نظام الطلبات الحقيقي، وتخزين حالات التأكيد، والصيانة التدريجية لقاعدة المعرفة، وتدبير المفاتيح، وأمن الشبكة بمستوى الإنتاج. المشروع مرخّص بموجب MIT License، ويمكن الاطلاع على مزيد من التفاصيل حول البنية والقيود فـ البنية ومسار التشغيل وتصميم الاسترجاع والقيود وخارطة الطريق.