Classifier

لمحة سريعة

يُسنِد NextPDF\Pro\Classifier نوعًا للمستند (فاتورة، عقد، تقرير، وما إلى ذلك) ولغةً مُكتشَفة باستخدام إرشادات حتمية على نص المستند وبنيته. وهو قائم على القواعد، لا نموذج تعلّم آلي.

التوفّر والترخيص

تُشحَن هذه القدرة في ⁨NextPDF Pro⁩ (nextpdf/pro) وتُفعَّل عبر مظروف ترخيص من فئة ⁨Pro⁩. لا يُحمِّل أي نشر يفتقر إلى هذا الاستحقاق أصناف هذه القدرة. قارِن الإصدارات واحصل على ترخيص.

لا يحكم هذه الوحدة أي علم قدرة في وقت التشغيل. تتوفر أصناف المُصنِّف متى كان nextpdf/pro مثبَّتًا.

التثبيت

composer require nextpdf/pro:^3

نظرة مفاهيمية عامة

يُنسِّق DocumentClassifier ثلاثة مُتعاونين:

• يفحص StructureAnalyzer ملف الـ ⁨PDF⁩ بحثًا عن عدد الصفحات، وأعداد الصور والخطوط، وحقول النماذج/التوقيع، مُنتِجًا StructureAnalysis.
• يُسجِّل HeuristicClassifier (وهو ClassifierInterface الافتراضي) النص مقابل قواميس كلمات مفتاحية لكل نوع، ويطبّق إرشادات بنيوية (مثلًا، تنحاز المستندات القصيرة بعيدًا عن “report”)، مُنتِجًا DocumentType ودرجة ثقة.
• يحدّد LanguageDetector اللغة من ملفّات تكرار ثلاثيات الأحرف لعشر لغات، مع الرجوع إلى الإنجليزية دون عتبة ثقة معيّنة.

يقبل classifyFromText() نصًا مُستخرَجًا مسبقًا (مع بايتات ⁨PDF⁩ خام اختيارية للبنية)؛ ويقبل classifyFromFile() بايتات ⁨PDF⁩ خام ويستخرج النص بتحليل مُعامِلات إظهار النص في §⁨9.4⁩ مباشرةً.

لماذا يعمل بهذه الطريقة

القرار الحامل هو التصنيف بإرشادات حتمية، لا بنموذج تعلّم آلي. المسار القائم على القواعد دالة نقية لمُدخَله: البايتات المتطابقة تُنتج دائمًا النوع والثقة واللغة نفسها، دون انحراف نموذج ودون أي استدعاء شبكي. تتيح تلك الحتمية للنتيجة أن تكشف ثقة صريحة، وبوابة isConfident()، وخريطة scores لكل نوع، فتُظهِر الوحدة كيف قررت بدلًا من إخفاء الاختيار خلف نموذج. لذلك يوجّه المستدعون المستندات منخفضة الثقة إلى المراجعة اليدوية بحكم العقد، والنص الأقصر من أن يُسجَّل يرجع إلى en وفق القاعدة الثابتة نفسها. المقايضة مقصودة: الدقة محدودة بملفّات الكلمات المفتاحية والثلاثيات الثابتة، مقابل قابلية إعادة الإنتاج، وقابلية الفحص، ومُصنِّف يعمل بالكامل داخل العملية.

خلفية التصميم: واجهة برمجية ترفض التخمين.

عقد السلوك

• المُدخَل. نص مُستخرَج (classifyFromText) أو بايتات ⁨PDF⁩ خام (classifyFromFile). المُدخَل الفارغ صالح ويُنتج نتيجة منخفضة الثقة، عادةً DocumentType::Other.
• المخرَج. ‏ClassificationResult بـ DocumentType، ودرجة ثقة في [0.0, 1.0]، وسمات بنيوية مُكتشَفة، ورمز لغة وفق ⁨ISO 639-1⁩، وبيانات وصفية. ‏isConfident(0.7) هو مساعد العتبة المُوثَّق.
• الحتمية. التصنيف واكتشاف اللغة دالتان نقيتان للمُدخَل — المُدخَل نفسه، النتيجة نفسها، لا عشوائية، لا شبكة.
• النطاق. اثنا عشر نوعًا للمستند وعشرة ملفّات لغة، وكلاهما ثابت في هذا الإصدار. يمكن تزويد استراتيجيات مخصّصة عبر ClassifierInterface.

سطح الـ ⁨API⁩ العام

النوع	الصنف	الأعضاء الرئيسيون
NextPDF\Pro\Classifier\DocumentClassifier	final class	static create(): self, classifyFromText(string $text, string $pdfData = ''): ClassificationResult, classifyFromFile(string $pdfData): ClassificationResult
NextPDF\Pro\Classifier\ClassifierInterface	interface	classify(string $text, StructureAnalysis $structure): ClassificationResult, supports(string $contentType): bool
NextPDF\Pro\Classifier\HeuristicClassifier	final class	implements ClassifierInterface
NextPDF\Pro\Classifier\StructureAnalyzer	final class	analyze(string $pdfData): StructureAnalysis
NextPDF\Pro\Classifier\LanguageDetector	final class	detect(string $text): string
NextPDF\Pro\Classifier\ClassificationResult	final readonly class	DocumentType $type, float $confidence, array $features, string $language, isConfident(float $threshold = 0.7): bool
NextPDF\Pro\Classifier\DocumentType	enum	12 cases (Invoice, Contract, Form, Report, Letter, Receipt, Legal, Medical, Financial, Technical, Academic, Other); label(): string

مثال شيفرة — بداية سريعة

<?php

declare(strict_types=1);

use NextPDF\Pro\Classifier\DocumentClassifier;

$result = DocumentClassifier::create()
    ->classifyFromText('Invoice #4471 — Amount due: $1,200.00');

printf(
    "%s (%.0f%% confidence), lang=%s\n",
    $result->type->label(),
    $result->confidence * 100,
    $result->language,
);

مثال شيفرة — إنتاج

<?php

declare(strict_types=1);

use NextPDF\Pro\Classifier\DocumentClassifier;
use NextPDF\Pro\Classifier\DocumentType;

function routeDocument(string $pdfBytes): string
{
    $result = DocumentClassifier::create()->classifyFromFile($pdfBytes);

    if (! $result->isConfident(0.7)) {
        return 'manual-review';
    }

    return match ($result->type) {
        DocumentType::Invoice, DocumentType::Receipt => 'accounts-payable',
        DocumentType::Contract, DocumentType::Legal   => 'legal-intake',
        default                                       => 'general-inbox',
    };
}

الحالات الحدّية والمزالق

• الثقة إرشادية. عامِل النتائج دون العتبة بوصفها “غير مؤكَّدة” ووجّهها إلى المراجعة اليدوية، كما يفعل مثال الإنتاج.
• يحتاج اكتشاف اللغة إلى نص كافٍ؛ والسلاسل القصيرة جدًا ترجع إلى الإنجليزية بحكم التصميم.
• يستخدم classifyFromFile() استخراج نص محدودًا على مستوى البايت؛ وملفات الـ ⁨PDF⁩ المضغوطة بشدة أو المؤلَّفة من صور فقط تقلّل النص المتاح للتسجيل.
• مجموعتا نوع المستند واللغة ثابتتان في هذا الإصدار؛ وسّع التصنيف بتنفيذ ClassifierInterface، لا بتعديل القواميس المُدمَجة.

إقامة البيانات وتخفيفات المعلومات الشخصية

يجري التصنيف داخل العملية دون أي استدعاءات شبكية ودون أي تخزين للمُدخَل. تتضمّن النتيجة DocumentType ورمز لغة، لا النص المصدر. إذا أبقى المستدعون على metadata، فراجِعها بحثًا عن أي معلومات شخصية عرضية قبل التخزين.

القياس عن بُعد الآمن وتنقية السجلات

لا تُصدِر الوحدة أي قياس عن بُعد ولا تُسجّل أي مُدخَل. على المستدعين الذين يضيفون التسجيل ألّا يدوّنوا سوى DocumentType ورمز اللغة الناتجين، لا النص المُصنَّف أبدًا.

الأداء

تسجيل الكلمات المفتاحية وعدّ الثلاثيات خطّيان بطول النص. تحليل البنية خطّي بطول بايتات الـ ⁨PDF⁩ مع سقف فكّ ضغط محدود. انظر performance_budget.

ملاحظات أمنية

يحلّل classifyFromFile() بايتات ⁨PDF⁩ غير موثوقة بمسح محدود وسقف لحجم فكّ الضغط لمقاومة مُدخَل قنبلة فكّ الضغط. لا يُنفَّذ أي سكربت مُضمَّن.

المطابقة

الادعاء	بند المعيار	الحالة
النص مُستردّ عبر Tj لتصنيف الملف	ISO 32000-2:2020 §9.4	مُتحقَّق منه (مجموعة وحدات)
النص مُستردّ عبر TJ لتصنيف الملف	ISO 32000-2:2020 §9.4	مُتحقَّق منه (مجموعة وحدات)
تصنيف قائم على التعلّم الآلي / النماذج	—	غير مدعوم (إرشادي فقط)

احتياط ⁨Core⁩ / بديله

لا يوجد مكافئ في ⁨Core⁩ لتصنيف المستندات أو اكتشاف اللغة.

ملاحظة حدود ⁨Enterprise⁩

هذا المُصنِّف قائم على القواعد وحتمي. لا يُجري أي تضمين، أو تشابه متّجهات، أو استدلال نماذج، أو فهم دلالي. تلك القدرات ليست جزءًا من هذه الوحدة ولا تتضمّنها ضمنًا.

حدود النشر

توثّق هذه الصفحة السلوك القابل للملاحظة خارجيًا وسطح ⁨API⁩ العام المدعوم فقط. مسارات فضاءات الأسماء الداخلية، والأصناف المساعدة، وجداول الآليات، وأسماء ملفات كتيّبات التشغيل، وبادئات التذاكر خارج النطاق.

انظر أيضًا

• ⁨Classifier⁩ — مرجع معمّق — سطح ⁨API⁩ العام الكامل، وترتيب المسار، وأنماط الإخفاق.
• ⁨Extraction⁩
• ⁨Filter⁩
• ⁨Diff⁩