May-2-2025/note.md

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

معرفی

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

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

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

نحوه استفاده

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

result = get_context("شاه عباس که بود؟")

این تابع یک دیکشنری (Dictionary) با ساختار زیر برمی‌گرداند:

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

پارامترهای قابل تنظیم می‌توانید پارامترهای مربوط به خزش وب را هنگام فراخوانی تابع get_context به صورت زیر تنظیم کنید:

result = get_context("شاه عباس که بود؟", crawl_params={
    'max_depth': 3,              # حداکثر عمق خزش (تعداد لینک‌های دنبال شده)
    'max_links_per_page': 10,    # حداکثر تعداد لینک‌های استخراج شده از هر صفحه
    'max_paragraphs': 8,         # حداکثر تعداد پاراگراف‌های استخراج شده از هر صفحه
    'num_search_results': 15     # تعداد نتایج اولیه جستجو از DuckDuckGo
})

ساختار فایل‌ها سیستم از ساختار پوشه زیر برای ذخیره‌سازی داده‌ها استفاده می‌کند:

./rag_data/
  ├── documents/         # پوشه اسناد PDF بارگذاری شده
  │   └── docs.pkl       # فایل ذخیره‌سازی اسناد پردازش شده
  └── web_results/       # پوشه نتایج خزش وب
      └── web.json       # فایل ذخیره‌سازی نتایج وب

rag = ModularRAG()
rag.load_pdf("path/to/your/document.pdf")

سیستم به صورت خودکار اسناد پردازش‌شده و نتایج وب را ذخیره و در اجراهای بعدی مجدداً بارگذاری می‌کند تا از پردازش تکراری جلوگیری شود. این سیستم تنها وظیفه بازیابی متن مرتبط را بر عهده دارد و برای تولید پاسخ نهایی نیازی به فراخوانی مستقیم یک مدل زبانی بزرگ (LLM) توسط کاربر ندارد (هرچند خروجی آن می‌تواند به عنوان ورودی به LLM داده شود). برای استفاده از این سیستم در پروژه‌های دیگر، کافی است فایل پایتون مربوطه را وارد (import) کرده و تابع get_context را فراخوانی نمایید.

نکات مهم

• برای افزودن اسناد PDF جدید به سیستم، از تابع load_pdf استفاده کنید:

  rag = ModularRAG()
  rag.load_pdf("path/to/your/document.pdf")
  

• سیستم به صورت خودکار اسناد پردازش‌شده و نتایج وب را ذخیره و در اجراهای بعدی مجدداً بارگذاری می‌کند تا از پردازش تکراری جلوگیری شود.
• این سیستم تنها وظیفه بازیابی متن مرتبط را بر عهده دارد و برای تولید پاسخ نهایی نیازی به فراخوانی مستقیم یک مدل زبانی بزرگ (LLM) توسط کاربر ندارد (هرچند خروجی آن می‌تواند به عنوان ورودی به LLM داده شود).
• برای استفاده از این سیستم در پروژه‌های دیگر، کافی است فایل پایتون مربوطه را وارد (import) کرده و تابع get_context را فراخوانی نمایید.