Validate local OCR retrieval for scanned PDFs
This commit is contained in:
Hamza Ayed
@@ -134,8 +134,8 @@
|
||||
- [x] فحص استرجاع أولي من 11 سؤالًا عربيًا وإنجليزيًا على API حي. ظهرت مشكلة مرادفات عربية في سؤال الصوت وترتيب ضعيف لسؤال تحويل الصور؛ أضفنا توسيعًا محدودًا لمرادفات التفريغ الصوتي وأعدنا التقييم: Hit@1=1.0 وHit@3=1.0 وMRR=1.0 ومعدل ظهور الدليل=1.0. قبل التحسين كان Hit@1=0.818. حُذفت ملفات التقييم المؤقتة من الفهرس بعد القياس. النتائج: `retrieval_2026-10-02_140339.json` و`retrieval_2026-10-02_140538.json`. تبقى العينة مصطنعة وصغيرة، فلا تثبت جودة عامة.
|
||||
- [x] قياس إضافي على 9 أسئلة عن ملفات الكود الفعلية (`workspace.py`, `knowledge.py`, `pdf_documents.py`, `main.py`). كشف التقييم أن تكرار مقاطع الملف الواحد يزاحم مصادر أخرى؛ حدّثنا البحث لجلب مجموعة أوسع ثم توزيع حتى مقطعين لكل ملف. بعد التعديل: Hit@1=0.667، Hit@3=1.0، MRR=0.833، وظهور الدليل=1.0. النتائج في `retrieval_2026-10-02_141132.json` (قبل التعديل) و`retrieval_2026-10-02_141337.json` (بعده). العينة صغيرة واختبارها معجمي؛ الدقة الدلالية وجودة الإجابة لم تُقاسا.
|
||||
- [x] جولة تحسين استرجاع المقاطع العميقة على 11 سؤالًا من المجموعة المحلية (2026-10-03): توسيع محدود لمرادفات صلاحيات المهارات بالعربية والإنجليزية، ورفع سقف النتائج من 5 إلى 8 مع إبقاء حد 4 مقاطع لكل ملف لحماية تنوع المصادر. على API محلي تجريبي بقاعدة معزولة: `Hit@1=1.0`, `Hit@3=1.0`, `MRR=1.0`, وظهور الدليل `11/11`؛ تقرير `evals/results/retrieval_2026-10-03_160000.json`. اجتازت اختبارات قاعدة المعرفة `12/12`.
|
||||
- [x] توسيع الحزمة وإضافة جواب الوكيل من الأدلة المفهرسة (2026-10-03): أضيف دليل تقني بطول 15.7 كيلوبايت فيه المعلومة المستهدفة في المقطع 17، وPDF نصي بحد فهرسة 30 صفحة، وأصبح مشغّل التقييم يحتفظ اختياريًا بإجابة الوكيل والمصادر لتراجع بشريًا دون منحها درجة آلية. في الجولة الكاملة على 13 حالة مع الملفات متداخلة: `Hit@1=1.0`, `Hit@3=1.0`, `MRR=1.0`, وظهور الدليل `13/13` (`evals/results/retrieval_extended_2026-10-03.json`). جولة إجابتين تجريبية أعادت حد PDF الصحيح وربطت سياسة الموافقة بالمقطع 17 (`evals/results/retrieval_long_pdf_agent_2026-10-03.json`). هذا لا يغطي OCR لملف PDF ممسوح ولا تقييمًا مستقلًا من المستخدم.
|
||||
- [ ] متابعة التقييم على PDFs ممسوحة ومجموعات مستندات طويلة متنوعة وأسئلة بشرية جديدة، وجمع مراجعة مستقلة لجودة إجابات النموذج فوق السياق المسترجع. لا تزال النتائج الحالية fixtures مصطنعة؛ الدرجات العالية تصف هذه الحالات فقط ولا تثبت جودة عامة.
|
||||
- [x] توسيع الحزمة وإضافة جواب الوكيل من الأدلة المفهرسة (2026-10-03): أضيف دليل تقني بطول 15.7 كيلوبايت فيه المعلومة المستهدفة في المقطع 17 وPDF نصي؛ حفظ المشغّل اختياريًا إجابات الوكيل ومصادرها للمراجعة دون منح درجة آلية. الجولة الأولى على 13 حالة أعادت `Hit@1=1.0`, `Hit@3=1.0`, `MRR=1.0`, وظهور الدليل `13/13` (`evals/results/retrieval_extended_2026-10-03.json`). بعد إصلاح وزن OCR المحلي المعطوب وإعادة تشغيله دون تنزيل، أضيف PDF ممسوح فعلي إلى المجموعة؛ على API التطبيق الحالي بقاعدة SQLite الحية المؤقتة ثم حذف عناصرها بعد القياس: `Hit@1=1.0`, `Hit@3=1.0`, `MRR=1.0`, وظهور الدليل `14/14` (`evals/results/retrieval_extended_14_2026-10-03.json`). جواب الوكيل على PDF الممسوح استخرج الموعد `17 October 2026` وذكر مصدره (`evals/results/retrieval_scanned_pdf_agent_2026-10-03.json`). تجربة EasyOCR المباشرة والـAPI استخدمتا أوزانًا محلية فقط؛ النسخة التالفة محفوظة احتياطيًا بجانب الوزن المُصلح.
|
||||
- [ ] متابعة التقييم على ملفات طويلة وPDFات متنوعة وأسئلة جديدة، وجمع مراجعة مستقلة لجودة إجابات النموذج فوق السياق المسترجع. النتائج الحالية fixtures صغيرة ومصطنعة؛ الدرجات تصف هذه الحالات ولا تثبت جودة عامة. مراجعة إجابات الوكيل محفوظة لكن لا توجد درجات مستقلة من المستخدم بعد.
|
||||
- [x] مهارات محلية أولية قابلة للاختيار من واجهة وضع الوكيل: شرح الكود، مراجعة الكود، وخطة اختبارات. تعرض `/v1/agent/skills` وصف كل مهارة وأدواتها؛ تُحقن التعليمات الموثوقة في سياق الوكيل وتُفلتر قائمة الأدوات، ويرفض الخادم استدعاء أداة خارج صلاحيات المهارة. لمهارة مراجعة الكود معاينة فقط ولا تطبيق مباشر. اجتازت اختبارات الصلاحيات والواجهة؛ يبقى تقييم دقة كل مهارة على أمثلة أكثر قبل اعتمادها افتراضيًا.
|
||||
- [x] قراءة رابط عام محدد عبر `POST /v1/web/read`: استخراج نص HTML الثابت وتمريره إلى Gemma المحلية للإجابة مع إرجاع الرابط والعنوان.
|
||||
- [x] بحث ويب متعدد المصادر تجريبي عبر DuckDuckGo بلا مفتاح API: اختيار نطاقات مختلفة، محاولة جلب الصفحات العامة، تلخيص بالنموذج المحلي مع روابط المصادر، ووسم المقتطفات عند تعذر فتح الصفحة. (2026-10-01: استجابة حية أعادت ملخصًا ومصدرين مختلفين عبر FastAPI/Gemma.) أضيف زمن جلب إجمالي وزمن لكل مصدر إلى الاستجابة لمساعدة تشخيص المصادر البطيئة؛ اختبارات الحجب ومزوّد رسمي اختياري ما زالت لاحقًا.
|
||||
@@ -145,7 +145,7 @@
|
||||
|
||||
- الصوت: حاليًا Groq خارجي للتفريغ. Gemma 4 E2B تدعم الصوت بحسب [بطاقة النموذج](https://ai.google.dev/gemma/docs/core/model_card_4)، لكن مسار إرسال الصوت إليها/نسخ محلي لم يُنفّذ؛ Whisper محلي لاحقًا.
|
||||
- [x] الصور: اختيار ورفع PNG/JPG/JPEG/WebP (حتى 3 صور) إلى `POST /v1/agent/images/analyze` محليًا. مع تثبيت `requirements-ocr.txt` يقرأ EasyOCR النص العربي/الإنجليزي ويغذي نصه والصورة معًا إلى نموذج الرؤية. تجربة اللقاء عبر FastAPI وMinistral المحلي أعادت HTTP 200 وتحليلًا لحقول الصورة؛ ترتيب صفوف RTL/LTR جمع العنوان العربي. بقي متوسط الثقة 0.625 وزمن OCR ~71 ثانية بعد تهيئة أولى ~45 ثانية على CPU. حد OCR مليونا بكسل للصورة، وتحليل الرؤية المحلي مسار رجوع عند غياب الحزمة أو الأوزان. راجع النص قبل استخدامه، وراجع ترخيص الأوزان قبل التوزيع التجاري.
|
||||
- [x] تحليل وفهرسة PDF رقمي أو ممسوح أو مختلط. يحدد الاستخراج حالة كل صفحة؛ النص الرقمي يحفظ ترتيب الصفحة، والممسوح يمر محليًا إلى OCR والرؤية. الحدود: 30 صفحة للملف، 3 صفحات ممسوحة للطلب، 2 مليون بكسل و4MB للصفحة، 8MB إجمالي صور، و8MB لملف PDF. نجحت اختبارات تحليل/استخراج PDF المختلط (2/2) واختبار فهرسة/استرجاع/حذف مختلط (1/1)؛ والتحقق الحي السابق شمل PDF ممسوحًا أيضًا. عند التوزيع يجب إرفاق تراخيص PDFium ومراجعة تراخيص أوزان OCR.
|
||||
- [x] تحليل وفهرسة PDF رقمي أو ممسوح أو مختلط. يحدد الاستخراج حالة كل صفحة؛ النص الرقمي يحفظ ترتيب الصفحة، والممسوح يمر محليًا إلى OCR والرؤية. الحدود: 30 صفحة للملف، 3 صفحات ممسوحة للطلب، 2 مليون بكسل و4MB للصفحة، 8MB إجمالي صور، و8MB لملف PDF. في 2026-10-03، رفض EasyOCR الوزن المحلي `arabic.pth` لبصمة غير مطابقة؛ استُعيد الوزن الصحيح من أرشيف موجود مسبقًا مع حفظ النسخة القديمة، ثم نجح OCR محليًا والـAPI في قراءة موعد من PDF ممسوح دون تنزيل. عند التوزيع يجب إرفاق تراخيص PDFium ومراجعة تراخيص أوزان OCR.
|
||||
- تصميم الواجهة لتوضيح ما إذا عولج الملف محليًا أم أرسل إلى مزوّد خارجي.
|
||||
|
||||
## المرحلة 7 — تقييم النماذج والتدريب
|
||||
|
||||
Binary file not shown.
@@ -11,3 +11,4 @@
|
||||
{"id": "skill-permissions-en", "query": "How does the server restrict tools for a selected skill?", "document": "skills.md", "expected_evidence": "allowed_tools", "text": "Each local agent skill declares an allowed_tools set. The server filters the advertised tools and rejects any model call outside that set."}
|
||||
{"id": "long-guide-deep-approval-en", "query": "What must happen before a proposed production change can be saved?", "document": "long_technical_guide.md", "expected_evidence": "two-stage approval", "source_path": "evals/fixtures/long_technical_guide.md"}
|
||||
{"id": "pdf-archive-page-limit-en", "query": "What is the maximum number of pages accepted when indexing one PDF?", "document": "archive_retention_policy.pdf", "expected_evidence": "30 pages", "source_path": "evals/fixtures/archive_retention_policy.pdf"}
|
||||
{"id": "scanned-pdf-ocr-deadline-en", "query": "What calendar date ends the archive restoration approval window?", "document": "scanned_approval_notice.pdf", "expected_evidence": "17 October 2026", "source_path": "evals/fixtures/scanned_approval_notice.pdf"}
|
||||
|
||||
@@ -0,0 +1,273 @@
|
||||
{
|
||||
"created_at_utc": "2026-10-03T16:27:51.027447+00:00",
|
||||
"base_url": "http://127.0.0.1:8000",
|
||||
"dataset": "evals\\knowledge_retrieval_extended.jsonl",
|
||||
"indexing": {
|
||||
"semantic_indexed_documents": 14,
|
||||
"documents": 14,
|
||||
"embedding_models": [
|
||||
"granite-embedding:278m"
|
||||
]
|
||||
},
|
||||
"metrics": {
|
||||
"cases": 14,
|
||||
"hit_at_1": 1.0,
|
||||
"hit_at_3": 1.0,
|
||||
"mean_reciprocal_rank": 1.0,
|
||||
"evidence_rate": 1.0
|
||||
},
|
||||
"results": [
|
||||
{
|
||||
"id": "conversation-storage-ar",
|
||||
"query": "أين تحفظ المحادثات؟",
|
||||
"expected_document": "storage.md",
|
||||
"expected_evidence": "SQLite",
|
||||
"rank": 1,
|
||||
"top_paths": [
|
||||
"storage.md",
|
||||
"long_technical_guide.md",
|
||||
"workspace.md",
|
||||
"scanned_approval_notice.pdf"
|
||||
],
|
||||
"expected_document_chunks": [
|
||||
0
|
||||
],
|
||||
"evidence_found": true,
|
||||
"search_mode": "hybrid"
|
||||
},
|
||||
{
|
||||
"id": "image-model-ar",
|
||||
"query": "ما النموذج الذي يعالج الصور تلقائيًا؟",
|
||||
"expected_document": "images.md",
|
||||
"expected_evidence": "Ministral 3:3b",
|
||||
"rank": 1,
|
||||
"top_paths": [
|
||||
"images.md",
|
||||
"routing.md",
|
||||
"timeout.md",
|
||||
"long_technical_guide.md"
|
||||
],
|
||||
"expected_document_chunks": [
|
||||
0
|
||||
],
|
||||
"evidence_found": true,
|
||||
"search_mode": "hybrid"
|
||||
},
|
||||
{
|
||||
"id": "preview-safety-ar",
|
||||
"query": "كيف نحمي معاينة الملف قبل الموافقة؟",
|
||||
"expected_document": "preview.md",
|
||||
"expected_evidence": "SHA256",
|
||||
"rank": 1,
|
||||
"top_paths": [
|
||||
"preview.md",
|
||||
"long_technical_guide.md",
|
||||
"archive_retention_policy.pdf",
|
||||
"workspace.md"
|
||||
],
|
||||
"expected_document_chunks": [
|
||||
0
|
||||
],
|
||||
"evidence_found": true,
|
||||
"search_mode": "hybrid"
|
||||
},
|
||||
{
|
||||
"id": "pdf-extraction-ar",
|
||||
"query": "كيف نستخرج النص من صفحات PDF؟",
|
||||
"expected_document": "pdf.md",
|
||||
"expected_evidence": "pypdf",
|
||||
"rank": 1,
|
||||
"top_paths": [
|
||||
"pdf.md",
|
||||
"archive_retention_policy.pdf",
|
||||
"images.md",
|
||||
"audio.md",
|
||||
"long_technical_guide.md"
|
||||
],
|
||||
"expected_document_chunks": [
|
||||
0
|
||||
],
|
||||
"evidence_found": true,
|
||||
"search_mode": "hybrid"
|
||||
},
|
||||
{
|
||||
"id": "voice-transcription-ar",
|
||||
"query": "أي خدمة تفرغ التسجيلات الصوتية؟",
|
||||
"expected_document": "audio.md",
|
||||
"expected_evidence": "Groq",
|
||||
"rank": 1,
|
||||
"top_paths": [
|
||||
"audio.md",
|
||||
"scanned_approval_notice.pdf",
|
||||
"archive_retention_policy.pdf",
|
||||
"long_technical_guide.md"
|
||||
],
|
||||
"expected_document_chunks": [
|
||||
0
|
||||
],
|
||||
"evidence_found": true,
|
||||
"search_mode": "hybrid"
|
||||
},
|
||||
{
|
||||
"id": "workspace-boundary-ar",
|
||||
"query": "كيف نحمي مساحة العمل من قراءة الملفات المخفية؟",
|
||||
"expected_document": "workspace.md",
|
||||
"expected_evidence": ".git",
|
||||
"rank": 1,
|
||||
"top_paths": [
|
||||
"workspace.md",
|
||||
"preview.md",
|
||||
"long_technical_guide.md",
|
||||
"archive_retention_policy.pdf"
|
||||
],
|
||||
"expected_document_chunks": [
|
||||
0
|
||||
],
|
||||
"evidence_found": true,
|
||||
"search_mode": "hybrid"
|
||||
},
|
||||
{
|
||||
"id": "web-search-en",
|
||||
"query": "Which provider searches multiple web sources?",
|
||||
"expected_document": "search.md",
|
||||
"expected_evidence": "DuckDuckGo",
|
||||
"rank": 1,
|
||||
"top_paths": [
|
||||
"search.md",
|
||||
"long_technical_guide.md",
|
||||
"skills.md",
|
||||
"routing.md"
|
||||
],
|
||||
"expected_document_chunks": [
|
||||
0
|
||||
],
|
||||
"evidence_found": true,
|
||||
"search_mode": "hybrid"
|
||||
},
|
||||
{
|
||||
"id": "database-version-en",
|
||||
"query": "How are old conversation answers migrated?",
|
||||
"expected_document": "migration.md",
|
||||
"expected_evidence": "selected_version",
|
||||
"rank": 1,
|
||||
"top_paths": [
|
||||
"migration.md",
|
||||
"archive_retention_policy.pdf",
|
||||
"long_technical_guide.md"
|
||||
],
|
||||
"expected_document_chunks": [
|
||||
0
|
||||
],
|
||||
"evidence_found": true,
|
||||
"search_mode": "hybrid"
|
||||
},
|
||||
{
|
||||
"id": "model-routing-ar",
|
||||
"query": "ما الحقول التي يعيدها API بعد تحويل الصور: requested_model وauto_routed؟",
|
||||
"expected_document": "routing.md",
|
||||
"expected_evidence": "auto_routed",
|
||||
"rank": 1,
|
||||
"top_paths": [
|
||||
"routing.md",
|
||||
"images.md",
|
||||
"storage.md",
|
||||
"timeout.md",
|
||||
"long_technical_guide.md"
|
||||
],
|
||||
"expected_document_chunks": [
|
||||
0
|
||||
],
|
||||
"evidence_found": true,
|
||||
"search_mode": "hybrid"
|
||||
},
|
||||
{
|
||||
"id": "api-timeout-ar",
|
||||
"query": "كيف يعرض API انتهاء مهلة النموذج؟",
|
||||
"expected_document": "timeout.md",
|
||||
"expected_evidence": "504",
|
||||
"rank": 1,
|
||||
"top_paths": [
|
||||
"timeout.md",
|
||||
"routing.md",
|
||||
"long_technical_guide.md",
|
||||
"skills.md"
|
||||
],
|
||||
"expected_document_chunks": [
|
||||
0
|
||||
],
|
||||
"evidence_found": true,
|
||||
"search_mode": "hybrid"
|
||||
},
|
||||
{
|
||||
"id": "skill-permissions-en",
|
||||
"query": "How does the server restrict tools for a selected skill?",
|
||||
"expected_document": "skills.md",
|
||||
"expected_evidence": "allowed_tools",
|
||||
"rank": 1,
|
||||
"top_paths": [
|
||||
"skills.md",
|
||||
"long_technical_guide.md",
|
||||
"migration.md"
|
||||
],
|
||||
"expected_document_chunks": [
|
||||
0
|
||||
],
|
||||
"evidence_found": true,
|
||||
"search_mode": "hybrid"
|
||||
},
|
||||
{
|
||||
"id": "long-guide-deep-approval-en",
|
||||
"query": "What must happen before a proposed production change can be saved?",
|
||||
"expected_document": "long_technical_guide.md",
|
||||
"expected_evidence": "two-stage approval",
|
||||
"rank": 1,
|
||||
"top_paths": [
|
||||
"long_technical_guide.md",
|
||||
"scanned_approval_notice.pdf",
|
||||
"migration.md"
|
||||
],
|
||||
"expected_document_chunks": [
|
||||
17,
|
||||
4,
|
||||
8
|
||||
],
|
||||
"evidence_found": true,
|
||||
"search_mode": "hybrid"
|
||||
},
|
||||
{
|
||||
"id": "pdf-archive-page-limit-en",
|
||||
"query": "What is the maximum number of pages accepted when indexing one PDF?",
|
||||
"expected_document": "archive_retention_policy.pdf",
|
||||
"expected_evidence": "30 pages",
|
||||
"rank": 1,
|
||||
"top_paths": [
|
||||
"archive_retention_policy.pdf",
|
||||
"pdf.md",
|
||||
"long_technical_guide.md"
|
||||
],
|
||||
"expected_document_chunks": [
|
||||
0
|
||||
],
|
||||
"evidence_found": true,
|
||||
"search_mode": "hybrid"
|
||||
},
|
||||
{
|
||||
"id": "scanned-pdf-ocr-deadline-en",
|
||||
"query": "What calendar date ends the archive restoration approval window?",
|
||||
"expected_document": "scanned_approval_notice.pdf",
|
||||
"expected_evidence": "17 October 2026",
|
||||
"rank": 1,
|
||||
"top_paths": [
|
||||
"scanned_approval_notice.pdf",
|
||||
"archive_retention_policy.pdf",
|
||||
"long_technical_guide.md"
|
||||
],
|
||||
"expected_document_chunks": [
|
||||
0
|
||||
],
|
||||
"evidence_found": true,
|
||||
"search_mode": "hybrid"
|
||||
}
|
||||
],
|
||||
"note": "Small deterministic fixture set. Retrieval metrics cover source ranking and evidence presence, not general RAG quality. Optional agent answers are retained for human review and are not auto-scored."
|
||||
}
|
||||
@@ -0,0 +1,49 @@
|
||||
{
|
||||
"created_at_utc": "2026-10-03T16:18:22.317786+00:00",
|
||||
"base_url": "http://127.0.0.1:8130",
|
||||
"dataset": "evals\\knowledge_retrieval_extended.jsonl",
|
||||
"indexing": {
|
||||
"semantic_indexed_documents": 1,
|
||||
"documents": 1,
|
||||
"embedding_models": [
|
||||
"granite-embedding:278m"
|
||||
]
|
||||
},
|
||||
"metrics": {
|
||||
"cases": 1,
|
||||
"hit_at_1": 1.0,
|
||||
"hit_at_3": 1.0,
|
||||
"mean_reciprocal_rank": 1.0,
|
||||
"evidence_rate": 1.0
|
||||
},
|
||||
"results": [
|
||||
{
|
||||
"id": "scanned-pdf-ocr-deadline-en",
|
||||
"query": "What calendar date ends the archive restoration approval window?",
|
||||
"expected_document": "scanned_approval_notice.pdf",
|
||||
"expected_evidence": "17 October 2026",
|
||||
"rank": 1,
|
||||
"top_paths": [
|
||||
"scanned_approval_notice.pdf"
|
||||
],
|
||||
"expected_document_chunks": [
|
||||
0
|
||||
],
|
||||
"evidence_found": true,
|
||||
"search_mode": "hybrid",
|
||||
"agent_answer": "تنتهي فترة موافقة استعادة الأرشيف في 17 أكتوبر 2026. (scanned_approval_notice.pdf · المقطع 0)",
|
||||
"agent_tool": "search_knowledge",
|
||||
"agent_files": [
|
||||
"scanned_approval_notice.pdf"
|
||||
],
|
||||
"agent_steps": [
|
||||
{
|
||||
"tool": "search_knowledge",
|
||||
"status": "completed"
|
||||
}
|
||||
],
|
||||
"human_rating": null
|
||||
}
|
||||
],
|
||||
"note": "Small deterministic fixture set. Retrieval metrics cover source ranking and evidence presence, not general RAG quality. Optional agent answers are retained for human review and are not auto-scored."
|
||||
}
|
||||
Reference in New Issue
Block a user