دليل RAGLight الشامل: من RAG الأساسي إلى سير العمل الوكيل
⏱️ وقت القراءة المقدر: 15 دقيقة
مقدمة
RAGLight هو إطار عمل Python خفيف الوزن ومعياري مصمم لتبسيط تنفيذ التوليد المعزز بالاسترجاع (Retrieval-Augmented Generation - RAG). من خلال الجمع بين استرجاع المستندات ونماذج اللغة الكبيرة (Large Language Models - LLM)، يتيح لك RAGLight بناء أنظمة ذكاء اصطناعي واعية بالسياق يمكنها الإجابة على الأسئلة بناءً على مستنداتك وقواعد معرفتك الخاصة.
في هذا الدليل الشامل، ستتعلم كيفية:
- إعداد RAGLight مع مزودي LLM المختلفين (Ollama، OpenAI، Mistral)
- بناء خطوط RAG الأساسية للإجابة على الأسئلة القائمة على المستندات
- تنفيذ Agentic RAG لمهام الاستدلال متعددة الخطوات
- استخدام RAT (Retrieval-Augmented Thinking) للاستدلال المحسّن
- دمج الأدوات الخارجية باستخدام MCP (Model Context Protocol)
ما الذي يجعل RAGLight مميزاً؟
يتميز RAGLight بما يلي:
- البنية المعيارية: سهولة تبديل LLMs والتضمينات ومخازن المتجهات
- دعم موفرين متعددين: Ollama، OpenAI، Mistral، LMStudio، vLLM، Google AI
- خطوط أنابيب متقدمة: RAG الأساسي، Agentic RAG، و RAT مع طبقات الاستدلال
- تكامل MCP: ربط الأدوات ومصادر البيانات الخارجية بسلاسة
- تكوين مرن: تخصيص كل جانب من جوانب خط RAG الخاص بك
المتطلبات الأساسية
قبل البدء في هذا الدليل، تأكد من توفر:
1. بيئة Python
# تحقق من إصدار Python (مطلوب 3.8 أو أعلى)
python3 --version
# إنشاء بيئة افتراضية (موصى به)
python3 -m venv raglight-env
source raglight-env/bin/activate # على macOS/Linux
# raglight-env\Scripts\activate # على Windows
2. تثبيت Ollama (لـ LLM المحلي)
# macOS
brew install ollama
# أو التنزيل من https://ollama.ai/download
# بدء خدمة Ollama
ollama serve
# سحب نموذج (في terminal جديد)
ollama pull llama3.2:3b
البديل: استخدم OpenAI أو Mistral API إذا كنت تفضل LLMs المستندة إلى السحابة.
3. تثبيت RAGLight
pip install raglight
التثبيت والإعداد
تكوين البيئة
أنشئ ملف .env
لتخزين مفاتيح API الخاصة بك (عند استخدام موفري السحابة):
# ملف .env
OPENAI_API_KEY=your_openai_key_here
MISTRAL_API_KEY=your_mistral_key_here
هيكل المشروع
قم بإعداد دليل مشروعك:
mkdir raglight-tutorial
cd raglight-tutorial
mkdir data
mkdir knowledge_base
إنشاء بيانات تجريبية
أنشئ بعض المستندات التجريبية للاختبار:
# data/document1.txt
cat > data/document1.txt << 'EOF'
RAGLight هو إطار عمل Python معياري للتوليد المعزز بالاسترجاع.
يدعم العديد من موفري LLM بما في ذلك Ollama و OpenAI و Mistral.
تشمل الميزات الرئيسية التكامل المرن لمخزن المتجهات مع ChromaDB و FAISS.
EOF
# data/document2.txt
cat > data/document2.txt << 'EOF'
يوسع Agentic RAG RAG التقليدي من خلال دمج الوكلاء المستقلين.
يمكن لهؤلاء الوكلاء أداء الاستدلال متعدد الخطوات واسترجاع المعلومات الديناميكي.
تشمل حالات الاستخدام الإجابة على الأسئلة المعقدة ومساعدي الأبحاث.
EOF
# data/document3.txt
cat > data/document3.txt << 'EOF'
يضيف RAT (Retrieval-Augmented Thinking) طبقة استدلال متخصصة.
يستخدم LLMs الاستدلالية لتعزيز جودة الاستجابة والعمق التحليلي.
RAT مثالي للمهام التي تتطلب تفكيراً عميقاً واستدلالاً متعدد القفزات.
EOF
خط RAG الأساسي
فهم بنية RAG
يتكون خط RAG الأساسي من ثلاثة مكونات رئيسية:
- استيعاب المستندات (Document Ingestion): يتم تقسيم مستنداتك إلى أجزاء وتحويلها إلى تضمينات
- التخزين المتجه (Vector Storage): يتم تخزين التضمينات في قاعدة بيانات متجهات (ChromaDB، FAISS، إلخ)
- الاسترجاع والتوليد (Retrieval & Generation): عند الاستعلام، يتم استرجاع المستندات ذات الصلة وتمريرها إلى LLM
التنفيذ
إليك مثال كامل لخط RAG أساسي:
#!/usr/bin/env python3
"""خط RAG أساسي باستخدام RAGLight"""
from raglight.rag.simple_rag_api import RAGPipeline
from raglight.config.rag_config import RAGConfig
from raglight.config.vector_store_config import VectorStoreConfig
from raglight.config.settings import Settings
from raglight.models.data_source_model import FolderSource
from dotenv import load_dotenv
# تحميل متغيرات البيئة
load_dotenv()
# إعداد التسجيل
Settings.setup_logging()
# تكوين مخزن المتجهات
vector_store_config = VectorStoreConfig(
embedding_model=Settings.DEFAULT_EMBEDDINGS_MODEL,
api_base=Settings.DEFAULT_OLLAMA_CLIENT,
provider=Settings.HUGGINGFACE,
database=Settings.CHROMA,
persist_directory="./chroma_db",
collection_name="my_knowledge_base"
)
# تكوين RAG
config = RAGConfig(
llm="llama3.2:3b", # نموذج Ollama
k=5, # عدد المستندات للاسترجاع
provider=Settings.OLLAMA,
system_prompt=Settings.DEFAULT_SYSTEM_PROMPT,
knowledge_base=[FolderSource(path="./data")]
)
# تهيئة وبناء خط الأنابيب
print("تهيئة خط RAG...")
pipeline = RAGPipeline(config, vector_store_config)
print("بناء قاعدة المعرفة...")
pipeline.build()
# الاستعلام من خط الأنابيب
query = "ما هي الميزات الرئيسية لـ RAGLight؟"
print(f"\nالاستعلام: {query}")
response = pipeline.generate(query)
print(f"\nالاستجابة:\n{response}")
خيارات التكوين الرئيسية
خيارات مخزن المتجهات:
database
: CHROMA أو FAISS أو QDRANTprovider
: HUGGINGFACE أو OLLAMA أو OPENAI للتضميناتpersist_directory
: مكان تخزين قاعدة بيانات المتجهات
خيارات RAG:
llm
: اسم النموذج (مثل “llama3.2:3b”، “gpt-4”، “mistral-large-2411”)k
: عدد المستندات ذات الصلة للاسترجاعprovider
: OLLAMA أو OPENAI أو MISTRAL أو LMSTUDIO أو GOOGLE
استخدام موفري LLM المختلفين
OpenAI:
config = RAGConfig(
llm="gpt-4",
k=5,
provider=Settings.OPENAI,
api_key=Settings.OPENAI_API_KEY,
knowledge_base=[FolderSource(path="./data")]
)
Mistral:
config = RAGConfig(
llm="mistral-large-2411",
k=5,
provider=Settings.MISTRAL,
api_key=Settings.MISTRAL_API_KEY,
knowledge_base=[FolderSource(path="./data")]
)
خط Agentic RAG
ما هو Agentic RAG؟
يوسع Agentic RAG RAG التقليدي من خلال دمج وكيل مستقل يمكنه:
- أداء الاستدلال متعدد الخطوات
- تحديد متى يتم استرجاع معلومات إضافية
- التكرار خلال دورات استرجاع-توليد متعددة
- التعامل مع الأسئلة المعقدة التي تتطلب مصادر بيانات متعددة
التنفيذ
"""خط Agentic RAG باستخدام RAGLight"""
from raglight.rag.simple_agentic_rag_api import AgenticRAGPipeline
from raglight.config.agentic_rag_config import AgenticRAGConfig
from raglight.config.vector_store_config import VectorStoreConfig
from raglight.config.settings import Settings
from raglight.models.data_source_model import FolderSource
from dotenv import load_dotenv
load_dotenv()
Settings.setup_logging()
# تكوين مخزن المتجهات
vector_store_config = VectorStoreConfig(
embedding_model=Settings.DEFAULT_EMBEDDINGS_MODEL,
api_base=Settings.DEFAULT_OLLAMA_CLIENT,
provider=Settings.HUGGINGFACE,
database=Settings.CHROMA,
persist_directory="./agentic_chroma_db",
collection_name="agentic_knowledge_base"
)
# تكوين Agentic RAG
config = AgenticRAGConfig(
provider=Settings.MISTRAL,
model="mistral-large-2411",
k=10,
system_prompt=Settings.DEFAULT_AGENT_PROMPT,
max_steps=4, # الحد الأقصى لخطوات الاستدلال
api_key=Settings.MISTRAL_API_KEY,
knowledge_base=[FolderSource(path="./data")]
)
# التهيئة والبناء
print("تهيئة خط Agentic RAG...")
agentic_rag = AgenticRAGPipeline(config, vector_store_config)
print("بناء قاعدة المعرفة...")
agentic_rag.build()
# استعلام معقد يتطلب خطوات متعددة
query = """
قارن قدرات RAG الأساسي و Agentic RAG.
ما هي حالات الاستخدام المحددة التي سيكون فيها Agentic RAG أكثر فائدة؟
"""
print(f"\nالاستعلام: {query}")
response = agentic_rag.generate(query)
print(f"\nالاستجابة:\n{response}")
الميزات الرئيسية لـ Agentic RAG
max_steps: يتحكم في عدد تكرارات الاستدلال التي يمكن للوكيل تنفيذها
# استعلام بسيط: خطوات أقل مطلوبة
config = AgenticRAGConfig(max_steps=2, ...)
# تحليل معقد: خطوات أكثر مسموح بها
config = AgenticRAGConfig(max_steps=10, ...)
موجه وكيل مخصص: تخصيص سلوك الوكيل
custom_agent_prompt = """
أنت مساعد بحث. عند الإجابة على الأسئلة:
1. قسّم الاستعلامات المعقدة إلى أسئلة فرعية
2. استرجع المعلومات ذات الصلة لكل سؤال فرعي
3. اجمع النتائج في إجابة شاملة
4. اذكر المصادر عند الإمكان
"""
config = AgenticRAGConfig(
system_prompt=custom_agent_prompt,
...
)
RAT (التفكير المعزز بالاسترجاع)
فهم RAT
يضيف RAT طبقة استدلال متخصصة إلى خط RAG:
- الاسترجاع (Retrieval): جلب المستندات ذات الصلة
- الاستدلال (Reasoning): استخدام LLM استدلالي لتحليل المحتوى المسترجع
- التفكير (Thinking): توليد خطوات استدلال وسيطة
- التوليد (Generation): إنتاج الإجابة النهائية مع سياق محسّن
التنفيذ
"""خط RAT باستخدام RAGLight"""
from raglight.rat.simple_rat_api import RATPipeline
from raglight.config.rat_config import RATConfig
from raglight.config.vector_store_config import VectorStoreConfig
from raglight.config.settings import Settings
from raglight.models.data_source_model import FolderSource
Settings.setup_logging()
# تكوين مخزن المتجهات
vector_store_config = VectorStoreConfig(
embedding_model=Settings.DEFAULT_EMBEDDINGS_MODEL,
api_base=Settings.DEFAULT_OLLAMA_CLIENT,
provider=Settings.HUGGINGFACE,
database=Settings.CHROMA,
persist_directory="./rat_chroma_db",
collection_name="rat_knowledge_base"
)
# تكوين RAT
config = RATConfig(
cross_encoder_model=Settings.DEFAULT_CROSS_ENCODER_MODEL,
llm="llama3.2:3b",
k=Settings.DEFAULT_K,
provider=Settings.OLLAMA,
system_prompt=Settings.DEFAULT_SYSTEM_PROMPT,
reasoning_llm=Settings.DEFAULT_REASONING_LLM,
reflection=3, # عدد تكرارات الاستدلال
knowledge_base=[FolderSource(path="./data")]
)
# التهيئة والبناء
print("تهيئة خط RAT...")
pipeline = RATPipeline(config, vector_store_config)
print("بناء قاعدة المعرفة...")
pipeline.build()
# استعلام يتطلب استدلالاً عميقاً
query = """
حلل الاختلافات المعمارية بين RAG و Agentic RAG و RAT.
ما هي المقايضات من حيث التعقيد والأداء وجودة الإخراج؟
"""
print(f"\nالاستعلام: {query}")
response = pipeline.generate(query)
print(f"\nالاستجابة:\n{response}")
خيارات تكوين RAT
reflection: عدد تكرارات الاستدلال
# استدلال سريع
config = RATConfig(reflection=1, ...)
# تفكير تحليلي عميق
config = RATConfig(reflection=5, ...)
cross_encoder_model: نموذج إعادة الترتيب لاسترجاع أفضل
config = RATConfig(
cross_encoder_model="cross-encoder/ms-marco-MiniLM-L-12-v2",
...
)
تكامل MCP
ما هو MCP؟
يسمح Model Context Protocol (MCP) لخط RAG الخاص بك بالتفاعل مع الأدوات والخدمات الخارجية. هذا يتيح:
- تكامل البحث على الويب
- استعلامات قاعدة البيانات
- استدعاءات API للخدمات الخارجية
- بيئات تنفيذ الكود
- تكامل الأدوات المخصصة
إعداد خادم MCP
أولاً، قم بتكوين خادم MCP الخاص بك (مثال باستخدام MCPClient):
"""تكوين خادم MCP"""
from raglight.rag.simple_agentic_rag_api import AgenticRAGPipeline
from raglight.config.agentic_rag_config import AgenticRAGConfig
from raglight.config.settings import Settings
# تكوين عنوان URL لخادم MCP
config = AgenticRAGConfig(
provider=Settings.OPENAI,
model="gpt-4o",
k=10,
mcp_config=[
{"url": "http://127.0.0.1:8001/sse"} # عنوان URL لخادم MCP الخاص بك
],
system_prompt=Settings.DEFAULT_AGENT_PROMPT,
max_steps=4,
api_key=Settings.OPENAI_API_KEY
)
# التهيئة مع MCP
pipeline = AgenticRAGPipeline(config, vector_store_config)
pipeline.build()
# يمكن للوكيل الآن استخدام الأدوات الخارجية
query = "ابحث في الويب عن التحديثات الأخيرة على أطر RAG ولخص النتائج"
response = pipeline.generate(query)
حالات استخدام MCP
تكامل البحث على الويب:
# يمكن للوكيل البحث ودمج نتائج الويب
query = "ما هي آخر التطورات في تقنية RAG في عام 2024؟"
استعلامات قاعدة البيانات:
# يمكن للوكيل الاستعلام عن قواعد البيانات للحصول على بيانات في الوقت الفعلي
query = "استرجع إحصائيات المستخدم من قاعدة بياناتنا وحلل الاتجاهات"
تكامل API:
# يمكن للوكيل استدعاء APIs الخارجية
query = "تحقق من API الطقس وأوصِ بالأنشطة بناءً على التوقعات"
مقارنة الأداء
خصائص خطوط الأنابيب
نوع خط الأنابيب | التعقيد | وقت الاستجابة | حالة الاستخدام |
---|---|---|---|
RAG الأساسي | منخفض | سريع (< 5 ثواني) | Q&A بسيط، البحث عن المستندات |
Agentic RAG | متوسط | معتدل (5-15 ثانية) | استدلال متعدد الخطوات، بحث |
RAT | عالي | بطيء (15-30 ثانية) | تحليل عميق، استدلال معقد |
RAG + MCP | متغير | يعتمد على الأدوات | تكامل الأدوات الخارجية |
اختيار خط الأنابيب المناسب
استخدم RAG الأساسي عندما:
- تحتاج إلى استجابات سريعة
- الأسئلة مباشرة
- البحث عن مستند واحد كافٍ
استخدم Agentic RAG عندما:
- الأسئلة تتطلب خطوات متعددة
- تحتاج إلى استرجاع ديناميكي
- المهمة تتضمن بحثاً أو استكشافاً
استخدم RAT عندما:
- مطلوب تفكير تحليلي عميق
- الجودة أكثر أهمية من السرعة
- مطلوب استدلال معقد متعدد القفزات
استخدم تكامل MCP عندما:
- تحتاج إلى بيانات خارجية في الوقت الفعلي
- المهمة تتطلب استخدام أدوات
- المعلومات الديناميكية ضرورية
أفضل الممارسات
1. إعداد المستندات
تحسين حجم الجزء:
# للمستندات التقنية
chunk_size = 512
# للمحتوى السردي
chunk_size = 1024
تنظيم المجلدات:
knowledge_base/
├── technical_docs/
├── user_manuals/
├── api_reference/
└── faq/
2. إدارة مخزن المتجهات
الاستمرارية:
# استخدم دائماً التخزين الدائم في الإنتاج
vector_store_config = VectorStoreConfig(
persist_directory="./prod_vectordb",
collection_name="production_kb"
)
تنظيم المجموعات:
# مجموعات منفصلة للمجالات المختلفة
collections = {
"technical": "tech_docs_collection",
"business": "business_docs_collection",
"general": "general_knowledge_collection"
}
3. اختيار LLM
التطوير:
# استخدم النماذج المحلية للتطوير
config = RAGConfig(
llm="llama3.2:3b",
provider=Settings.OLLAMA
)
الإنتاج:
# استخدم نماذج أقوى للإنتاج
config = RAGConfig(
llm="gpt-4",
provider=Settings.OPENAI
)
4. معالجة الأخطاء
"""خط RAG قوي مع معالجة الأخطاء"""
try:
pipeline = RAGPipeline(config, vector_store_config)
pipeline.build()
response = pipeline.generate(query)
except Exception as e:
print(f"خطأ في خط الأنابيب: {e}")
# الرجوع إلى LLM الأساسي بدون RAG
response = fallback_generate(query)
5. تكوين المجلدات المتجاهلة
عند فهرسة مستودعات الكود، استبعد الدلائل غير الضرورية:
# مجلدات مخصصة للتجاهل
custom_ignore_folders = [
".venv",
"venv",
"node_modules",
"__pycache__",
".git",
"build",
"dist",
"my_custom_folder_to_ignore"
]
config = AgenticRAGConfig(
ignore_folders=custom_ignore_folders,
...
)
6. المراقبة والتسجيل
"""تمكين التسجيل التفصيلي"""
import logging
# تكوين مستوى التسجيل
logging.basicConfig(level=logging.INFO)
# أو استخدم إعداد RAGLight
Settings.setup_logging()
# مراقبة الأداء
import time
start_time = time.time()
response = pipeline.generate(query)
elapsed_time = time.time() - start_time
print(f"تمت معالجة الاستعلام في {elapsed_time:.2f}ث")
التخصيص المتقدم
منشئ خط أنابيب مخصص
"""خط RAG مخصص بنمط المنشئ"""
from raglight.rag.builder import Builder
from raglight.config.settings import Settings
# بناء خط أنابيب مخصص
rag = Builder() \
.with_embeddings(
Settings.HUGGINGFACE,
model_name=Settings.DEFAULT_EMBEDDINGS_MODEL
) \
.with_vector_store(
Settings.CHROMA,
persist_directory="./custom_db",
collection_name="custom_collection"
) \
.with_llm(
Settings.OLLAMA,
model_name="llama3.2:3b",
system_prompt_file="./custom_prompt.txt",
provider=Settings.OLLAMA
) \
.build_rag(k=5)
# استيعاب المستندات
rag.vector_store.ingest(data_path='./data')
# الاستعلام
response = rag.generate("سؤالك هنا")
فهرسة مستودع الكود
"""فهرسة مستودعات الكود"""
# فهرسة الكود مع استخراج التوقيعات
rag.vector_store.ingest(repos_path=['./repo1', './repo2'])
# البحث عن الكود
code_results = rag.vector_store.similarity_search("منطق المصادقة")
# البحث عن توقيعات الصف
class_results = rag.vector_store.similarity_search_class("تعريف صف User")
تكامل مستودع GitHub
"""فهرسة مستودعات GitHub مباشرة"""
from raglight.models.data_source_model import GitHubSource
knowledge_base = [
GitHubSource(url="https://github.com/Bessouat40/RAGLight"),
GitHubSource(url="https://github.com/your-org/your-repo")
]
config = RAGConfig(
knowledge_base=knowledge_base,
...
)
نشر Docker
مثال Dockerfile
FROM python:3.10-slim
WORKDIR /app
# تثبيت التبعيات
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
# نسخ التطبيق
COPY . .
# إضافة تعيين المضيف لـ Ollama/LMStudio
# التشغيل: docker run --add-host=host.docker.internal:host-gateway your-image
CMD ["python", "app.py"]
البناء والتشغيل
# بناء الصورة
docker build -t raglight-app .
# التشغيل مع الوصول إلى شبكة المضيف (لـ Ollama)
docker run --add-host=host.docker.internal:host-gateway raglight-app
استكشاف الأخطاء وإصلاحها
المشاكل الشائعة
1. خطأ اتصال Ollama:
# تحقق من تشغيل Ollama
# macOS/Linux:
ollama serve
# تحديث قاعدة API إذا لزم الأمر
vector_store_config = VectorStoreConfig(
api_base="http://localhost:11434", # عنوان URL الافتراضي لـ Ollama
...
)
2. مشاكل الذاكرة:
# تقليل حجم الجزء وقيمة k
config = RAGConfig(
k=3, # استرجاع عدد أقل من المستندات
...
)
3. الأداء البطيء:
# استخدام نماذج تضمين أصغر
vector_store_config = VectorStoreConfig(
embedding_model="all-MiniLM-L6-v2", # نموذج أصغر وأسرع
...
)
4. أخطاء مخزن المتجهات:
# المسح وإعادة البناء
rm -rf ./chroma_db
python rebuild_kb.py
الخلاصة
يوفر RAGLight إطار عمل قوي ومرن لبناء أنظمة التوليد المعززة بالاسترجاع. سواء كنت بحاجة إلى Q&A بسيط للمستندات أو سير عمل وكيل معقدة مع تكامل الأدوات الخارجية، فإن البنية المعيارية لـ RAGLight تجعل من السهل البناء والتوسع.
النقاط الرئيسية
- ابدأ ببساطة: ابدأ بـ RAG الأساسي وقم بالترقية إلى Agentic RAG أو RAT حسب الحاجة
- اختر بحكمة: اختر خط الأنابيب المناسب بناءً على حالة الاستخدام ومتطلبات الأداء
- خصص بشكل واسع: يتيح تصميم RAGLight المعياري التخصيص الكامل
- قم بالتوسع تدريجياً: ابدأ محلياً مع Ollama، ثم انتقل إلى موفري السحابة للإنتاج
الخطوات التالية
- تجربة: جرب موفري LLM ومخازن المتجهات المختلفة
- تحسين: ضبط قيم k وأحجام الأجزاء واختيار النماذج
- دمج: أضف خوادم MCP للوصول إلى الأدوات الخارجية
- نشر: احتوي مع Docker للنشر في الإنتاج
الموارد
- RAGLight GitHub: https://github.com/Bessouat40/RAGLight
- حزمة PyPI: https://pypi.org/project/raglight/
- Ollama: https://ollama.ai
- ChromaDB: https://www.trychroma.com
- بروتوكول MCP: ابحث عن “Model Context Protocol” للوثائق
بناءً سعيداً مع RAGLight! 🚀