# **توضیح جامع سیستم RAG مدولار**

## **معرفی**

این سیستم RAG (Retrieval Augmented Generation) مدولار برای بازیابی اطلاعات از اسناد PDF و وب طراحی شده است. سیستم ابتدا در اسناد موجود جستجو می‌کند و در صورت عدم یافتن پاسخ، به صورت خودکار وب را برای یافتن اطلاعات مرتبط خزش می‌کند.

## **ویژگی‌های اصلی**

* **بازیابی دو مرحله‌ای:**
    * ابتدا در اسناد PDF بارگذاری شده جستجو می‌کند.
    * در صورت عدم یافتن پاسخ در اسناد، به صورت خودکار وب را خزش می‌کند.
* **ذخیره‌سازی خودکار:**
    * تمام اسناد و نتایج جستجوی وب در مسیر نسبی `./rag_data` ذخیره می‌شوند.
    * اسناد به فرمت `pickle` و نتایج وب به فرمت `JSON` ذخیره می‌گردند.
* **جستجوی کلیدواژه‌ای:**
    * از الگوریتم `BM25` برای یافتن مرتبط‌ترین اسناد استفاده می‌کند.
    * بهترین ۳ سند مرتبط را بازیابی می‌کند.
* **خزش وب پیشرفته:**
    * از موتور جستجوی DuckDuckGo استفاده می‌کند.
    * خزش بازگشتی (Recursive) با قابلیت دنبال کردن لینک‌ها انجام می‌دهد.
    * پارامترهای عمق خزش، تعداد لینک‌ها و تعداد پاراگراف‌ها قابل تنظیم هستند.
* **پشتیبانی از زبان فارسی:**
    * تمام پیام‌های خطا و خروجی‌ها به زبان فارسی نمایش داده می‌شوند.

## **نحوه استفاده**

برای استفاده از سیستم، کافی است تابع `get_context` را با پرسش خود فراخوانی کنید:

```python
result = get_context("شاه عباس که بود؟")
```
این تابع یک دیکشنری (Dictionary) با ساختار زیر برمی‌گرداند:

```python

{
    "has_context": True,  # آیا اطلاعاتی یافت شده است یا خیر
    "context": "متن مرتبط با پرسش شما...",  # متن بازیابی شده
    "source": "documents" یا "web",  # منبع اطلاعات (اسناد داخلی یا وب)
    "sources": ["url1", "url2", ...],  # فهرست منابع (فقط در صورت استفاده از نتایج وب)
    "language": "fa"  # زبان پاسخ (همیشه فارسی)
}
```
پارامترهای قابل تنظیم
می‌توانید پارامترهای مربوط به خزش وب را هنگام فراخوانی تابع get_context به صورت زیر تنظیم کنید:

```python

result = get_context("شاه عباس که بود؟", crawl_params={
    'max_depth': 3,              # حداکثر عمق خزش (تعداد لینک‌های دنبال شده)
    'max_links_per_page': 10,    # حداکثر تعداد لینک‌های استخراج شده از هر صفحه
    'max_paragraphs': 8,         # حداکثر تعداد پاراگراف‌های استخراج شده از هر صفحه
    'num_search_results': 15     # تعداد نتایج اولیه جستجو از DuckDuckGo
})
```
ساختار فایل‌ها
سیستم از ساختار پوشه زیر برای ذخیره‌سازی داده‌ها استفاده می‌کند:
```python
./rag_data/
  ├── documents/         # پوشه اسناد PDF بارگذاری شده
  │   └── docs.pkl       # فایل ذخیره‌سازی اسناد پردازش شده
  └── web_results/       # پوشه نتایج خزش وب
      └── web.json       # فایل ذخیره‌سازی نتایج وب
```
توضیح توابع اصلی
load_pdf: بارگذاری، پردازش و تقسیم‌بندی محتوای فایل‌های PDF.
search_duckduckgo: انجام جستجو در موتور جستجوی DuckDuckGo.
crawl_page: استخراج محتوای متنی و لینک‌های موجود در یک صفحه وب.
crawl_web: ترکیب جستجو و خزش صفحات وب برای یافتن اطلاعات مرتبط.
build_retriever: ساخت و آماده‌سازی بازیاب (Retriever) بر اساس الگوریتم BM25 برای جستجوی کلیدواژه‌ای در اسناد.
get_relevant_documents: یافتن مرتبط‌ترین اسناد موجود با پرسش کاربر.
extract_context_from_documents: استخراج متن مرتبط با پرسش از اسناد یافت‌شده.
extract_context_from_web: استخراج متن مرتبط با پرسش از نتایج خزش وب.
get_context: تابع اصلی و رابط کاربری سیستم که فرآیند جستجو در اسناد و یا خزش وب را مدیریت کرده و نتیجه نهایی را برمی‌گرداند.
نکات مهم
برای افزودن اسناد PDF جدید به سیستم، از تابع load_pdf استفاده کنید:
```python

rag = ModularRAG()
rag.load_pdf("path/to/your/document.pdf")
```
سیستم به صورت خودکار اسناد پردازش‌شده و نتایج وب را ذخیره و در اجراهای بعدی مجدداً بارگذاری می‌کند تا از پردازش تکراری جلوگیری شود.
این سیستم تنها وظیفه بازیابی متن مرتبط را بر عهده دارد و برای تولید پاسخ نهایی نیازی به فراخوانی مستقیم یک مدل زبانی بزرگ (LLM) توسط کاربر ندارد (هرچند خروجی آن می‌تواند به عنوان ورودی به LLM داده شود).
برای استفاده از این سیستم در پروژه‌های دیگر، کافی است فایل پایتون مربوطه را وارد (import) کرده و تابع get_context را فراخوانی نمایید.