مستندات پروژه: Advanced FAISS Index Creator V4

این پروژه یک ابزار پیشرفته برای ایندکس‌سازی اسناد متنی (به‌ویژه اسناد حقوقی و فارسی) با استفاده از FAISS (Facebook AI Similarity Search) و مدل‌های embedding چندزبانه است. هدف این ابزار، آماده‌سازی اسناد برای استفاده در سیستم‌های RAG (Retrieval-Augmented Generation) است که در آن‌ها اطلاعات از اسناد استخراج و به مدل‌های زبانی ارائه می‌شود.

🎯 ویژگی‌های کلیدی این نسخه

1. قطعه‌بندی هوشمند پیشرفته

• تشخیص خودکار ساختار اسناد (مواد، تبصره‌ها، آیین‌نامه‌ها)
• حفظ زمینه و روابط منطقی
• ادغام هوشمند قطعات کوچک

2. متادیتای غنی

• استخراج شماره مواد و تبصره‌ها
• تشخیص جداول و لیست‌ها
• امتیازدهی کیفیت قطعات
• ردیابی ارجاعات

3. بهینه‌سازی‌های پیشرفته

• پردازش موازی اسناد
• نرمال‌سازی embeddingها
• ایندکس HNSW برای کارایی بهتر
• مدیریت حافظه بهینه

4. تحلیل و گزارش‌دهی

• آمار دقیق کیفیت
• توزیع انواع قطعات
• خلاصه جامع عملکرد

مقدمه

این ابزار برای پردازش اسناد متنی (مانند فایل‌های .txt و .md) طراحی شده است و قابلیت‌های زیر را ارائه می‌دهد:

• پشتیبانی از زبان فارسی: استفاده از مدل‌های embedding چندزبانه (مانند intfloat/multilingual-e5-large) برای پشتیبانی بهینه از اسناد فارسی.
• قطعه‌بندی هوشمند: تقسیم اسناد به قطعات معنادار با درک ساختار (مانند مواد قانونی، تبصره‌ها، جداول).
• بهینه‌سازی برای RAG: ایندکس‌سازی با FAISS برای جستجوی سریع و دقیق در سیستم‌های تولید پاسخ مبتنی بر اطلاعات.
• پردازش موازی: افزایش سرعت پردازش با استفاده از پردازش موازی.
• مدیریت داده‌های کوچک: سازگاری با مجموعه‌های کوچک داده (مانند 117 قطعه) با تنظیمات پویا.

پیش‌نیازها

برای اجرای این کد، نیاز به نصب کتابخانه‌های زیر دارید:

pip install sentence-transformers faiss-cpu scikit-learn tqdm numpy

اختیاری (برای دانلود سریع‌تر مدل‌ها):

pip install hf_xet

محیط پیشنهادی

• سیستم‌عامل: ویندوز، لینوکس، یا مک
• پایتون: نسخه 3.8 یا بالاتر
• محیط مجازی: توصیه می‌شود از یک محیط مجازی استفاده کنید:

  python -m venv rag_env
  source rag_env/bin/activate  # لینوکس/مک
  rag_env\Scripts\activate     # ویندوز
  

ساختار پروژه

فایل‌های اصلی

• advanced_faiss_indexer1.py: اسکریپت اصلی برای ایندکس‌سازی اسناد.
• پوشه documents/: جایی که فایل‌های ورودی (مانند taarefe1404.txt, power_factor_final.txt) قرار می‌گیرند.
• پوشه index_v4_upgraded/: جایی که فایل‌های خروجی (ایندکس FAISS، متادیتا، و خلاصه) ذخیره می‌شوند.

فایل‌های خروجی

• faiss_index_upgraded.index: فایل ایندکس FAISS برای جستجوی برداری.
• enhanced_metadata.json: متادیتای قطعات (مانند نوع، کلمات کلیدی، امتیاز کیفیت).
• comprehensive_summary.json: خلاصه آماری از فرآیند ایندکس‌سازی.

نحوه کار ابزار

این ابزار در چند مرحله اسناد را پردازش و ایندکس می‌کند:

1. بارگذاری اسناد:
   • اسناد متنی (.txt, .md) از پوشه documents/ خوانده می‌شوند.
   • پشتیبانی از اسناد فارسی با استفاده از کدگذاری UTF-8.
2. قطعه‌بندی هوشمند:
   • اسناد به قطعات کوچک‌تر (حداکثر 800 کاراکتر) تقسیم می‌شوند.
   • ساختار اسناد (مانند مواد قانونی، تبصره‌ها، جداول) شناسایی می‌شود.
   • قطعات با امتیاز کیفیت پایین (مثلاً خیلی کوتاه) فیلتر می‌شوند.
3. ایجاد Embedding:
   • از مدل intfloat/multilingual-e5-large برای تبدیل قطعات به بردارهای عددی استفاده می‌شود.
   • Embedding‌ها نرمال‌سازی می‌شوند برای جستجوی مبتنی بر شباهت کسینوسی.
4. ایندکس‌سازی با FAISS:
   • برای داده‌های کوچک (مثل 117 قطعه)، از IndexHNSWFlat یا IndexFlatL2 استفاده می‌شود.
   • برای داده‌های بزرگ‌تر، از IndexIVFPQ با تنظیمات پویا (تعداد خوشه‌ها، بیت‌ها) استفاده می‌شود.
5. ذخیره متادیتا و خلاصه:
   • اطلاعات متادیتا (مانند نوع قطعه، کلمات کلیدی) در فایل JSON ذخیره می‌شود.
   • خلاصه آماری (تعداد قطعات، کلمات، توزیع انواع قطعات) تولید می‌شود.

🚀 نحوه اجرا

1. آماده‌سازی اسناد

• فایل‌های متنی خود (مانند قوانین، آیین‌نامه‌ها، یا جداول Markdown) را در پوشه documents/ قرار دهید.
• اطمینان حاصل کنید که فایل‌ها با فرمت UTF-8 ذخیره شده‌اند.
• مثال: فایل‌هایی مثل taarefe1404.txt, siasatekolli.txt.

2. ساختار دایرکتوری

mkdir -p documents
# قرار دادن فایل‌های متنی در پوشه documents

3. اجرای اسکریپت

• کد را در فایل advanced_faiss_indexer1.py ذخیره کنید.
• در ترمینال یا خط فرمان، به دایرکتوری پروژه بروید:

  cd H:\HadiSadoghiYazdi\hadisadoghiyazdi1971.github.io\hadisadoghiyazdi1971.github.io\smart-power-mashhad
  

• اسکریپت را اجرا کنید:

  python advanced_faiss_indexer1.py
  

4. بررسی خروجی‌ها

• پوشه index_v4_upgraded/:
  • faiss_index_upgraded.index: ایندکس FAISS برای جستجو.
  • enhanced_metadata.json: اطلاعات قطعات (برای فیلتر در RAG).
  • comprehensive_summary.json: آمار فرآیند (مثل تعداد قطعات، میانگین امتیاز کیفیت).
• خروجی کنسول:
  • تعداد اسناد پردازش‌شده.
  • توزیع انواع قطعات (مثل article, table).
  • اندازه فایل‌های خروجی.

5. استفاده در RAG

• از ایندکس FAISS در ابزارهایی مثل LangChain استفاده کنید:

  from langchain.vectorstores import FAISS
  index = FAISS.load_local("./index_v4_upgraded", embeddings)
  

• متادیتا را برای فیلتر کردن نتایج (مثلاً فقط مواد قانونی) استفاده کنید.

تغییرات و ارتقاهای اعمال شده

پشتیبانی بهتر از زبان فارسی و اسناد قانونی

• مدل embedding به “intfloat/multilingual-e5-large” ارتقا یافته که عملکرد بهتری در زبان‌های multilingual (از جمله فارسی) دارد.
• الگوهای regex برای تشخیص ساختار بهبود یافته تا بهتر با متن‌های فارسی کار کند.

بهینه‌سازی قطعه‌بندی (Chunking)

• قطعه‌بندی ساختارآگاه (structure-aware) هوشمندتر شده
• overlap هوشمند (بر اساس جملات کامل) اضافه شده
• فیلتر قطعات بی‌کیفیت اضافه شده

بهینه‌سازی embedding و ایندکس FAISS

• embeddingها normalize شده برای cosine similarity بهتر
• ایندکس FAISS به HNSW ارتقا یافته
• پشتیبانی از compression ایندکس با PQ

پردازش موازی و کارایی

• پردازش موازی بهبود یافته
• هندلینگ خطاها بهتر شده

متادیتا و خلاصه غنی‌تر

• متادیتا شامل کلمات کلیدی استخراج‌شده
• خلاصه نهایی شامل آمار بیشتر و visualization

تنظیمات قابل تغییر

در بخش main() اسکریپت، می‌توانید تنظیمات را تغییر دهید:

config = {
    "documents_dir": "./documents",
    "index_dir": "./index_v4_upgraded",
    "embedding_model": "intfloat/multilingual-e5-large",  # یا "paraphrase-multilingual-mpnet-base-v2" برای سرعت بیشتر
    "max_chunk_size": 800,  # حداکثر اندازه قطعه
    "min_chunk_size": 150,  # حداقل اندازه قطعه
    "overlap_size": 50,     # همپوشانی بین قطعات
    "max_workers": 8,       # تعداد نخ‌های پردازش موازی
    "compression_dim": 16   # برای فشرده‌سازی PQ
}

• برای داده‌های کوچک: اگر تعداد قطعات کم است (مثل 117)، max_chunk_size را به 400 کاهش دهید تا قطعات بیشتری تولید شود.
• برای سرعت بیشتر: مدل سبک‌تر (paraphrase-multilingual-mpnet-base-v2) را امتحان کنید.

رفع مشکلات رایج

1. خطای NameError: name 'self' is not defined

• علت: کد خارج از کلاس تعریف شده یا تورفتگی اشتباه است.
• راه‌حل: اطمینان حاصل کنید که همه متدها (مثل create_optimized_faiss_index) درست در کلاس AdvancedFAISSIndexCreator قرار دارند.

2. خطای FAISS: nx >= k

• علت: تعداد قطعات (مثل 117) کمتر از تعداد خوشه‌های مورد نیاز (256) است.
• راه‌حل: کد به‌روز شده از bits=4 (16 خوشه) برای داده‌های کوچک استفاده می‌کند یا به IndexHNSWFlat برمی‌گردد.

3. هشدارهای HuggingFace (Symlink یا Xet Storage)

• هشدار Symlink:
  • در ویندوز، حالت Developer Mode را فعال کنید یا پایتون را به‌صورت ادمین اجرا کنید.
  • یا متغیر محیطی را تنظیم کنید:

    set HF_HUB_DISABLE_SYMLINKS_WARNING=1
    

• هشدار Xet Storage:
  • برای دانلود سریع‌تر، نصب کنید:

    pip install hf_xet
    

4. کندی پردازش

• علت: مدل intfloat/multilingual-e5-large روی CPU کند است.
• راه‌حل:
  • از GPU (با faiss-gpu) استفاده کنید.
  • مدل سبک‌تر (paraphrase-multilingual-mpnet-base-v2) را امتحان کنید.
  • تعداد نخ‌ها (max_workers) را افزایش دهید اگر CPU قوی دارید.

مثال خروجی

برای 11 سند با 117 قطعه:

================================================================================
🚀 FAISS Index Creator V4 - Upgraded RAG Optimized
================================================================================
پردازش اسناد: 100%|███████████████████████████| 11/11 [00:00<00:00, 22.34it/s]
2025-10-15 23:25:28,636 - INFO - ✅ تعداد قطعات استخراج‌شده: 117
ایجاد embeddingها: 100%|████████████████████████| 4/4 [01:59<00:00, 29.92s/it]
2025-10-15 23:25:28,636 - INFO - ✅ embeddingها با موفقیت ایجاد شدند
2025-10-15 23:25:30,313 - INFO - ✅ ایندکس FAISS با موفقیت ایجاد و ذخیره شد
2025-10-15 23:25:30,315 - INFO - ✅ متادیتا ذخیره شد در: index_v4_upgraded/enhanced_metadata.json
2025-10-15 23:25:30,315 - INFO - ✅ خلاصه جامع ذخیره شد در: index_v4_upgraded/comprehensive_summary.json

================================================================================
✅ ایجاد ایندکس با موفقیت کامل شد!
================================================================================
📊 خلاصه نهایی:
   📄 اسناد پردازش شده: 11
   ✂️  کل قطعات: 117
   📝 کل کلمات: 12,345
   🔤 کل کاراکترها: 78,901
   📏 اندازه متوسط قطعات: 674 کاراکتر
   ⭐ میانگین امتیاز کیفیت: 0.82
   🤖 مدل embedding: intfloat/multilingual-e5-large
   📁 دایرکتوری ایندکس: index_v4_upgraded

توزیع انواع قطعات:
   - article: 45
   - table: 20
   - general: 30
   - regulation: 15
   - note: 7

📁 فایل‌های ایجاد شده:
   📄 faiss_index_upgraded.index (0.15 MB)
   📄 enhanced_metadata.json (0.03 MB)
   📄 comprehensive_summary.json (0.01 MB)

نکات پیشرفته

• ادغام با LangChain:
  • برای استفاده در یک سیستم RAG، از کتابخانه LangChain استفاده کنید:

    from langchain.vectorstores import FAISS
    from sentence_transformers import SentenceTransformer
    model = SentenceTransformer("intfloat/multilingual-e5-large")
    vector_store = FAISS.load_local("./index_v4_upgraded", model)
    results = vector_store.similarity_search("ماده قانونی درباره تعرفه", k=5)
    

• فیلتر با متادیتا:
  • از enhanced_metadata.json برای فیلتر کردن نتایج (مثلاً فقط قطعات article یا table) استفاده کنید.
• افزایش مقیاس:
  • برای داده‌های بزرگ‌تر، compression_dim را به 64 یا 96 افزایش دهید.
  • از faiss-gpu برای سرعت بالاتر استفاده کنید.

محدودیت‌ها

• داده‌های کوچک: برای داده‌های خیلی کوچک (مثل <1000 قطعه)، دقت PQ ممکن است کاهش یابد. کد به‌طور خودکار به IndexHNSWFlat برمی‌گردد.
• عملکرد CPU: مدل‌های بزرگ (مثل multilingual-e5-large) روی CPU کند هستند. برای تولید سریع‌تر، از GPU یا مدل سبک‌تر استفاده کنید.
• پشتیبانی از فرمت‌ها: در حال حاضر فقط .txt و .md پشتیبانی می‌شود. برای PDF، ابتدا متن را استخراج کنید.

توسعه‌دهندگان

این پروژه توسط تیم xAI و با الهام از نیازهای پروژه‌های RAG توسعه یافته است. برای سؤالات یا پیشنهادات، با ما در تماس باشید.

منابع اضافی

• مستندات FAISS
• مستندات Sentence Transformers
• آموزش LangChain

آخرین به‌روزرسانی: مهر 1404 (اکتبر 2025)