نبذة على المشروع
مساعد قراءة وتعديل الأوراق البحثية محلياً هو CLI Agent خفيف موجه لـ Linux، كيساعد فالأوراق البحثية. منين كيدخل المستخدم سؤال، يقدر الموديل يستعمل الأدوات المحلية وقدرات البحث فالأوراق باش يعاون فالقراية والتلخيص وتحليل محتوى الأوراق المحلية.
المشروع كيستعمل افتراضياً Qwen3-14B-AWQ، وحجم أوزان الموديل تقريباً 9.4 GB. كيناسب المستخدمين اللي عندهم NVIDIA GPU وباغين يشغلو الموديل محلياً ويحافظو على خصوصية الأوراق والأسئلة ديالهم. افتراضياً، المشروع ما كيشغّلش البحث عبر الإنترنت، والأجوبة كتجي أساساً من قدرات الموديل ومن قاعدة المعرفة المحلية اللي كيبنيها المستخدم.
المشروع كيدعم بروتوكول MCP، ويقدر يربط خدمات MCP من خلال آلية تسجيل الأدوات. وبما أن ميزانية الإدخال، وتعليمات النظام، وطول مخرجات الأدوات كلها قابلة للإعداد، فالاستخدام ديالو ما كيتحصرش فمساعدة الأوراق البحثية.
أهم المميزات
- تشغيل Agent محلي مساعد فالأوراق البحثية داخل بيئة Linux.
- استعمال موديل Qwen3-14B-AWQ المحلي بشكل افتراضي.
- دعم بناء قاعدة معرفة محلية للبحث من ملفات PDF النصية وMarkdown وTXT.
- دعم طرح الأسئلة بشكل تفاعلي، وكذلك تنفيذ سؤال واحد من سطر الأوامر.
- دعم حفظ سجلات الأسئلة والأجوبة بصيغة Markdown.
- دعم بروتوكول MCP وآلية تسجيل الأدوات.
- دعم نقاط التحقق الاختيارية ديال LangGraph لمواصلة الجلسة بين النوافذ.
- توفير سكريبتات لفحص البيئة وGPU وإعدادات الموديل.
التحضير قبل التثبيت
المشروع موجه لـ Linux، وكينصح باستعمال جهاز فيه NVIDIA GPU. أوزان الموديل حجمها تقريباً 9.4 GB، وفوقت التشغيل خاص يتوفر كذلك قدر كافي من ذاكرة GPU لتشغيل الاستدلال. ومنين كتبدل الموديل أو ميزانية الإدخال أو طول المخرجات، خاصك تقيّم الإعدادات حسب سعة الذاكرة.
ملفات PDF الممسوحة ضوئياً ما كيدعمهاش OCR حالياً. إلا بغيتي تبحث فالأوراق الممسوحة، خاصك أولاً تحوّل المحتوى لنص، أو تستعمل PDF نصي أو Markdown أو TXT من الملفات اللي كيدعمها المشروع.
تحميل المشروع وتثبيتو
فاللول، نسخ مستودع GitHub وسمّي مجلد المشروع local-agent:
git clone https://github.com/Ayi914/paperchecker.git local-agent
cd local-agentإلا ما بغيتيش تستعمل Git، تقدر حتى تختار Code → Download ZIP من صفحة GitHub، وتفك الضغط، ومن بعد تفتح الطرفية داخل مجلد المشروع.
من بعد ما تدخل لمجلد المشروع، شغّل سكريبت التثبيت:
bash scripts/install.shمنين يكمل التثبيت، شغّل سكريبت البدء:
bash scripts/start.shفأول تشغيل خاصك تستنى حتى يتحمّل الموديل. منين يبان فلطرفية المحث >>>، تقدر تدخل السؤال. مثلاً:
>>> شرح شنو المشكل اللي كيحلّو الربط المتبقيمن بعد، كل مرة تدخل لمجلد المشروع غالباً غير شغّل bash scripts/start.sh باش تبدا.
أول تشغيل وإعداد الموديل
إلا كان مجلد الموديل ناقص، أو بغيتي تختار موديل من جديد، تقدر تنفذ:
bash scripts/setup.shإلا فشل تحميل الموديل، خاصك أولاً تفحص الشبكة. وتقدر حتى تحمّل مجلد الموديل كامل من جهاز فيه الإنترنت، ومن بعد تنسخو للجهاز الهدف وتختار الموديل الموجود خلال الإعداد.
إلا فشل تشغيل الموديل، شوف ملف السجل اللي كيبان فتنبيه الطرفية، وغالباً كيلقى هنا:
logs/cli-vllm-*.logوتأكد فالنفس الوقت أن ذاكرة GPU ما مستعملةش من طرف برامج أخرى.
استيراد الأوراق ديالك وبناء الفهرس
باش يخلي Agent يجاوب اعتماداً على الأوراق ديالك، حط ملفات PDF النصية أو Markdown أو TXT داخل المجلد data/knowledge/. مثلاً، يقدر المجلد يضم عدة أوراق وملاحظات مرتبطة بها.
منين توجد الملفات، نفّذ أمر فهرسة قاعدة المعرفة:
bash scripts/start.sh rag-indexفأول مرة كيتبنى فيها الفهرس، كيتحمّل موديل مستقل للبحث، وهادي علاش خاص اتصال بالإنترنت. منين يكمل الفهرس، عاود شغّل Agent التفاعلي:
bash scripts/start.shدابا تقدر تطرح أسئلة كتحتاج الأوراق المحلية، مثلاً:
لخّص الابتكارات الأساسية ديال YOLOv1 اعتماداً على الأوراق المحلية، وذكر المصادر.إلا ما حطيتي حتى ورقة أو ما بنيتيش الفهرس، فالأجوبة غادي تجي أساساً من معرفة الموديل، ماشي من محتوى الأوراق المحلية. المشروع ما كيشغّلش البحث عبر الإنترنت افتراضياً.
الاستعمال التفاعلي
منين يبدا البرنامج، دخل السؤال من بعد المحث >>> وضغط على Enter. هاد الطريقة مناسبة للأسئلة المتتابعة، ومقارنة وجهات نظر الأوراق، أو تحليل نفس الموضوع خطوة بخطوة.
تقدر تستعمل الأوامر المدمجة التالية لتدبير التفاعل:
/help: عرض أوامر الحوار./new: بداية جلسة جديدة./exitأو/quitأوCtrl+D: الخروج من البرنامج.
كل سؤال وجواب كيتحفظ افتراضياً فملف Markdown، وبنية المسار هي:
output/الشهر/اليوم/الوقت_الميكروثانية.mdتنفيذ مهمة واحدة من سطر الأوامر
إلا ما محتاجش تدخل للواجهة التفاعلية، تقدر تمرّر السؤال مباشرة كوسيط لسكريبت البدء:
bash scripts/start.sh "لخّص آلية الانتباه"استعمل --quiet باش يخرج الجواب بوحدو:
bash scripts/start.sh "لخّص آلية الانتباه" --quietإلا ما بغيتيش يتحفظ ملف الجواب، زِد --no-save:
bash scripts/start.sh "سؤال" --no-saveإعداد ميزانية الإدخال وطول المخرجات والتعليمات
تقدر تبدل ميزانية إدخال Agent وتعليمات النظام داخل config/agent.yaml، وبهذا يقدر المشروع يتستعمل حتى فسيناريوهات أخرى ديال الوكلاء المحليين.
خاص تفرّق مزيان بين جوج إعدادات: tool_output_max_chars: 4000 فملف الإعداد هو الحد الأقصى لاقتطاع حروف نتيجة الأداة، وماشي الحد الأقصى لرموز جواب الموديل. الطول الأقصى لمخرجات الموديل كيتحكم فيه LOCAL_AGENT_MAX_TOKENS فملف البيئة، و.env.example مضبوط افتراضياً على 2048 token.
ميزانية إدخال Agent مضبوطة افتراضياً على 4096 token. منين كتعدل ميزانية الإدخال أو تعليمات النظام أو طول مخرجات الأدوات أو الحد الأقصى لرموز الإخراج، خاصك تاخذ بعين الاعتبار طول السياق وذاكرة GPU المتوفرة، باش ما ترفعش الإعدادات بزاف ويتعطل الموديل.
حفظ واسترجاع الجلسة بين النوافذ
افتراضياً، سياق الجلسة كيبقى غير فالمسار الحالي للبرنامج. منين كتسد CLI، البرنامج ما كيرجعش السياق بوحدو، وملفات أجوبة Markdown اللي تولدات ما كيتقراوش من جديد تلقائياً.
إلا بغيتي تكمل نفس الجلسة بين النوافذ، بدّل run.checkpoint_enabled إلى true فـ config/agent.yaml، واستعمل دائماً نفس معرّف الجلسة:
bash scripts/start.sh -i --thread-id my-paperحالة الجلسة كيتحفظ هنا:
data/checkpoints/langgraph.sqliteالأمر /new، أو تشغيل نافذة تفاعلية جديدة بلا تحديد معرّف للجلسة، كينشئ جلسة جديدة. كل استدعاء للموديل كيستعمل افتراضياً آخر 4 جولات من الحوار، وكيبقى خاضعاً لميزانية إدخال قدرها 4096 token.
فحص البيئة وتشخيص الأعطاب
إلا وقع مشكل، كينصح أولاً بتشغيل سكريبت فحص البيئة:
bash scripts/doctor.shهاد السكريبت كيفحص البيئة وGPU وإعدادات الموديل، ولكن ما كيحمّلش الموديل الكبير وما كيبداش الاستدلال، وهادي علاش مناسب قبل التشغيل الرسمي أو أثناء تشخيص الأعطاب.
- ما كايناش GPU: كينصح باستعمال جهاز Linux فيه NVIDIA GPU.
- مجلد الموديل ناقص: شغّل
bash scripts/setup.sh، وعاود اختار الموديل أو كمّل التحميل. - فشل تحميل الموديل: فحص الشبكة، أو حمّل مجلد الموديل كامل من جهاز فيه الإنترنت ونسخو للبيئة الهدف.
- فشل تشغيل الموديل: شوف
logs/cli-vllm-*.logوتأكد أن ذاكرة GPU ما مستعملةش من برامج أخرى. - الأوراق المحلية ما تستعملاتش: تأكد أن الملفات كاينة فـ
data/knowledge/وأنك نفّذتيbash scripts/start.sh rag-index.
نصائح عملية للاستعمال
- قبل أول استعمال، شغّل
bash scripts/doctor.shباش تكتاشف بكري مشاكل GPU أو مجلد الموديل أو الإعدادات. - جمع الأوراق اللي محتاج تستشهد بها وتحللها فـ
data/knowledge/، ومن بعد كمّل الفهرسة قبل طرح الأسئلة. - منين كتطرح السؤال، وضّح نطاق التلخيص أو صيغة الإخراج أو طلب ذكر المصادر، باش يسهل التحقق من محتوى الأوراق المحلية.
- إلا كانت ذاكرة GPU غير كافية، ما تكبّرش بلا حساب ميزانية الإدخال أو الحد الأقصى لمخرجات الأدوات أو رموز الإخراج.
- إلا كنت غادي تعالج نفس الموضوع البحثي بشكل متواصل، فعّل نقاط التحقق وثبّت
--thread-id. - ملفات PDF الممسوحة ضوئياً ما تقدرش تعتمد فيها مباشرة على OCR ديال المشروع الحالي، وخاصك أولاً توجد محتوى نصي قابل للبحث.
الخلاصة
paperchecker كيوفر مساراً متكاملاً كيبدا بتشغيل الموديل المحلي، وكيشمل فهرسة الأوراق، وكيكمل بالأسئلة والأجوبة عبر CLI. من بعد تثبيت المشروع، تقدر تستعمل الموديل الافتراضي لتحليل الأسئلة العامة، أو تحط الأوراق النصية ديالك فقاعدة المعرفة وتبني الفهرس، باش يجاوب Agent اعتماداً على المصادر المحلية. ومن خلال agent.yaml ومتغيرات البيئة ونقاط التحقق ديال الجلسات، تقدر تزيد تضبط السياق والمخرجات وتدبير الجلسات.
كود المشروع مرخّص بموجب رخصة MIT. إلا واجهتي مشكل فالتشغيل أو فالموديل، شغّل أولاً سكريبت التشخيص وراجع السجلات.