عمليات معالجة المستندات
معالجة المستندات — التشغيل والمقياس
Section titled “معالجة المستندات — التشغيل والمقياس”السطح التشغيلي لـمنصة ذكاء المستندات
(بقايا المرحلة 9 وما بعدها). كل شيء مدفوع عبر خدمة الاستيراد المشتركة
DocumentIngestionService؛ لا يوجد مُحلِّل ثانٍ ولا مسار كتابة موازٍ.
مواضيع ذات صلة: مسارات الـ API · أمن المستندات · خريطة المراحل · قائمة فحص الإنتاج · مصفوفة الدخان · دليل منتج ذكاء المستندات
جاهزية تحليل PDF / OCR (للمشغّلين)
Section titled “جاهزية تحليل PDF / OCR (للمشغّلين)”تستخدم ملفات PDF الإلكترونية مقارنة أداء متعددة المحركات بنظام نقاط (bake-off)
(PyMuPDF أساسًا ← pypdfium2 اختياريًا ← pdfplumber ← pypdf). الطبقات
الممسوحة ضوئيًا / الفارغة / ذات نمط العرض التقديمي تُوجَّه إلى OCR معزول عبر
Tesseract (ترتيب تلقائي ara+eng). التفاصيل الكاملة على مستوى المنتج:
ذكاء المستندات ← استخراج نص PDF.
| الفحص | الإشارة السليمة |
|---|---|
GET /api/documents/ops/readiness (أو الإعدادات ← المستندات) | مُحلِّل PDF جاهز عند تثبيت PyMuPDF أو pdfplumber |
| pypdfium2 / pypdf فقط | المُحلِّل مُتدهور (نص فقط — الجداول لا تُعلَن) |
| PDF إلكتروني عربي | رموز بالترتيب المنطقي؛ بيانات IR الوصفية extractor / extraction_score |
| مسح ضوئي عربي | Tesseract + بيانات traineddata الخاصة بـara على PATH؛ قد يبقى OCR غير مثالي |
بعد kazma update | استيرادات CLI تعمل (kazma serve يشتغل)؛ انظر تحديث كاظمه |
اعتماديات النشر: pip install -e ".[document-platform]" (pymupdf + pypdfium2)
وTesseract على مستوى النظام مع حزمتي eng + ara عند الحاجة إلى OCR.
أسطح المشغّل في اليوم الثاني (Day-2)
Section titled “أسطح المشغّل في اليوم الثاني (Day-2)”| السطح | الاستخدام |
|---|---|
الويب /documents | الرفع، والمكتبة، والتفاصيل، ولوحة التشغيل (السعة، الجاهزية، التدقيق، جمع القمامة GC) |
الإعدادات /settings?tab=documents | الإطلاق التدريجي الحي، والاستيراد، والعمّال، وOCR، والبرمجيات الخبيثة، وجمع القمامة |
GET /api/documents/ops/* | المقاييس، والسعة، والجاهزية، والاحتفاظ، والتدقيق |
POST /api/documents/ops/maintenance/{dry-run,run} | جمع القمامة الإداري |
python scripts/certify_documents.py | فحص دخان الشهادة / --soak |
المقاييس
Section titled “المقاييس”تُصدَر مقاييس المستندات عبر العرض القياسي لـ Prometheus عند
/metrics (لا اعتمادية قياس جديدة؛ تتحلل إلى عمليات فارغة عند غياب
prometheus-client). وتتوفر أيضًا لقطة رقمية خالية من المحتوى عند
GET /api/documents/ops/metrics.
| النطاق | المقاييس |
|---|---|
| الاستيراد | kazma_documents_intake_files_total{outcome}، و…_intake_bytes_total، و…_intake_rejections_total{reason} |
| الطابور | …_queue_depth، و…_queue_oldest_age_seconds، و…_active_leases، و…_retry_waiting، و…_dead_letter_current |
| المراحل | …_stage_total{stage,outcome}، و…_stage_latency_seconds{stage} |
| المُحلِّل/OCR | …_parser_total{parser,outcome}، و…_pages_total{kind} |
| بيئة الحماية | …_sandbox_terminations_total{reason} (timeout/oom/output/degraded) |
| التخزين | …_storage_logical_bytes، و…_storage_physical_bytes، و…_storage_dedup_ratio |
| الفهرسة | …_index_latency_seconds، و…_index_chunks_total |
| التوليد | …_generation_failures_total{operation}، و…_redaction_failures_total |
حصة المستأجر هي واجهة استعلام API، لا وسم Prometheus
(كاردينالية وسوم مستأجرين غير محدودة أمر غير آمن). اقرأها من لقطة
المقاييس (tenant_quota) أو من GET /api/documents/ops/capacity.
السجلات/التتبعات تحمل معرّفات الارتباط فقط (المستأجر/مساحة العمل/
المستند/الإصدار/المهمة/المحاولة/المُحلِّل) — أبدًا ليست محتوى المستند أو
أسماء الملفات أو مصطلحات التنقيح أو الأسرار. تُصدَر مقاطع OpenTelemetry
اختيارية عند تثبيت opentelemetry؛ وإلا فهي عمليات فارغة.
التدقيق التشغيلي
Section titled “التدقيق التشغيلي”كل إجراء موجّه للمشغّل/المستأجر (الاستيراد، والوصول، والفهرسة، والتوليد،
والتحويل، والتعديل، والتنقيح، والتنزيل، والإلغاء، وإعادة المحاولة، والحذف،
وجمع القمامة) يُلحَق بسجلّ تدقيق غير قابل للتغيير ومقيّد بالمستأجر
(document_audit_events). على SQLite يعيش في documents.db؛ وعلى البيانات
الوصفية في Postgres يستخدم نفس اسم الجدول في التجمع المشترك. وهو يكمّل —
ولا يكرر — سجلّ أحداث المراحل الخاص بكل مهمة. اقرأ صفحة عبر
GET /api/documents/ops/audit?limit=&before_id=. التفاصيل مقيّدة بقائمة سماح
من القيم القياسية الآمنة؛ المحتوى لا يدخل التدقيق أبدًا.
الضغط العكسي، والسعة، وحدود المعدل
Section titled “الضغط العكسي، والسعة، وحدود المعدل”يُرفَض الاستيراد بحالة صادقة + Retry-After عند بلوغ أي حد:
| الحد | الحالة | مفتاح الإعداد |
|---|---|---|
| الحد الأدنى للمساحة الحرة للتخزين | 507 | documents.capacity.storage_free_floor_bytes |
| سقف الطابور العام | 503 | documents.capacity.max_queued_jobs |
| حد المهام المنتظرة لكل مستأجر | 429 | documents.capacity.max_tenant_queued_jobs |
| حد المهام النشطة لكل مستأجر | 429 | documents.capacity.max_tenant_active_jobs |
| نافذة معدل/بايتات الاستيراد | 429 | documents.capacity.intake_rate_per_minute، و…intake_bytes_per_minute |
سعة الطابور الدائم هي المرجع؛ نافذة المعدل/البايتات في الذاكرة حامٍ إضافي
من الاندفاعات. يعيد GET /api/documents/ops/capacity لقطة متوافقة مع
التنبيهات مع degraded_reasons قابلة للقراءة آليًا.
الحد الافتراضي للمساحة الحرة هو 512 ميبيبايت؛ كثير من مضيفي الإنتاج يرفعونه إلى ≥ 1 جيبيبايت عبر الإعدادات ← المستندات أو ConfigStore.
الاحتفاظ وجمع القمامة
Section titled “الاحتفاظ وجمع القمامة”الاحتفاظ حي مدعوم بـ ConfigStore (documents.retention.*، وdocuments.gc.*).
الجامع آمن ضد الانهيار بنمط الوسم/الاجتياح (mark/sweep) مع قاعدة
البيانات سلطةً وحيدة (مسار البيانات الوصفية SQLite):
- يستردّ الكتل (blobs) اليتيمة/غير المُشار إليها، ونسخ الحجر الصحي بعد الترقية، ومحتوى شواهد الحذف (tombstones) منتهية الصلاحية، ومحتوى الإصدارات الفاشلة نهائيًا (المرفوضة/الرسائل الميتة)، وصفوف الكتل اليتيمة، والبيانات (manifests) اليتيمة، وصفوف التدقيق المتقادمة.
- أبدًا لا يحذف الكتل المُشار إليها، أو محتوى الإصدار الحالي، أو المصنّفات (إزالة تكرار العنونة بالمحتوى محفوظة).
- يحترم فترة سماح، ويحدّ عدد الحذف في كل تشغيل
(
documents.gc.max_deletions_per_run)، ويرفض التتبع أو الحذف عبر رابط رمزي/نقطة وصل أو خارج جذر المخزن.
حلقة مجدولة تعمل كل documents.gc.interval_hours (تُلغى بنظافة عند
الإيقاف). يستطيع المشغّلون التشغيل التجريبي ثم التأكيد من صفحة
المستندات أو عبر POST /api/documents/ops/maintenance/dry-run و…/run
(مقيّد بالمشرف).
البيانات الوصفية في Postgres: عمليات CRUD آمنة لتعدد النسخ ويُشغَّل جمع
القمامة على كلا الواجهتين الخلفيتين — يوجّه retention._mark إلى
repository.gc_mark، الذي تنفذه كلٌّ من repository.py وrepository_pg.py.
(الإصدارات الأقدم كانت تتخطى جمع القمامة على Postgres مع
gc_postgres_metadata_sql_port_pending؛ أُزيل ذلك الحاجز ويؤكد اختبار أنه
لن يعود.)
فحص البرمجيات الخبيثة
Section titled “فحص البرمجيات الخبيثة”يشغّل الاستيراد ClamAV عند تهيئته (documents.security.malware_scan =
auto/on/off). يظهر الفحص في الجاهزية وفي الإعدادات ← المستندات.
انظر أمن المستندات.
النسخ الاحتياطي
Section titled “النسخ الاحتياطي”يلتقط النسخ الاحتياطي الأصلي (كل 6 ساعات) documents.db أولًا
(sqlite3.backup() ← نقطة زمنية) حين تكون البيانات الوصفية SQLite، ثم
ينسخ المحتوى الذي تشير إليه ويتحقق من بصمة كل كتلة/بيان — لقطة ممزقة
لقاعدة البيانات/الكتل أمر مستحيل لأن ملفات الكتل تُكتَب دائمًا قبل
صفوفها. تهبط النسخ الاحتياطية تحت
kazma-data/backups/document-store-<ts>/ مع manifest.json.
حين تكون البيانات الوصفية Postgres، تكون الحالة العلائقية جزءًا من منظومة
النسخ الاحتياطي لقاعدة بيانات المنصة (pg_dump / kazma migrate)؛ انسخ
احتياطيًا شجرة العنونة بالمحتوى أيضًا.
الترحيل
Section titled “الترحيل”ينقل kazma migrate export|verify|import كلًّا من documents.db (عند
وجوده) + شجرة العنونة بالمحتوى + البيانات. لا تحتوي documents.db على
مسارات مضمّنة، فلا تحتاج إعادة كتابة؛ يعيد المستورد تنصيبها هي والشجرة في
جذر مخزن مستندات الهدف عبر مسار التهيئة الذرّية القائم: تجميع ← تحقق ←
نسخ احتياطي ← استبدال. انظر الترحيل.
جاهزية تعدد النسخ
Section titled “جاهزية تعدد النسخ”| المكوّن | تعدد نسخ؟ | كيف |
|---|---|---|
| طابور المهام | نعم (Postgres) | KAZMA_DATABASE_URL + jobs_pg.py؛ التجاوز بـ KAZMA_DOCUMENTS_JOBS_BACKEND=sqlite |
| البيانات الوصفية | نعم (Postgres) | KAZMA_DOCUMENTS_METADATA_BACKEND=postgres أو auto؛ repository_pg.py |
| البيانات الوصفية | لا (SQLite الافتراضي) | نسخة تطبيق واحدة مقابل مخزن مشترك |
| الكتل (blobs) | وحدة تخزين مشتركة | يجب أن ترى كل النسخ نفس شجرة documents.storage_root |
| جمع القمامة | SQLite فقط حاليًا | يُتخطى على البيانات الوصفية PG مع خطأ صادق |
اقرأ دائمًا GET /api/documents/ops/readiness:
{ "status": "ready|degraded", "jobs_backend": "postgres|sqlite", "jobs_multi_replica": true, "metadata_backend": "postgres|sqlite", "metadata_multi_replica": true, "multi_replica": true, "degraded_reasons": [], "malware": { "available": true, "scanner": "clamdscan", "mode": "auto" }}حالة status لا تكون degraded إلا عندما لا تكون خلفية مضبوطة هي التي
تخدم: jobs_postgres_unavailable_fell_back_to_sqlite،
metadata_postgres_unavailable_fell_back_to_sqlite (وأسباب البرمجيات
الخبيثة أو الإطلاق التدريجي التي تضيفها الخدمة). الخلفية المختارة في
.env — بيانات وصفية SQLite بجوار مهام Postgres، وهو الشكل الشائع
للخادم الواحد — حالة ready مع metadata_multi_replica: false؛
وmulti_replica لا يصبح true إلا عندما يكون كلٌّ من المهام والبيانات
الوصفية كذلك.
الشهادة واختبار التحمّل (soak)
Section titled “الشهادة واختبار التحمّل (soak)”python scripts/certify_documents.pypython scripts/certify_documents.py --soak --soak-iterations 100python scripts/certify_documents.py --output report.jsonاختبارات Pytest: tests/test_document_certification_phase10.py (البنية،
والانهيار، وإمكانية الوصول a11y، والإطلاق التدريجي). تاريخ التقارير:
docs/audits/AUDIT_DOCUMENT_CERTIFICATION.md.