المُصنِّف — مرجع متعمّق

لمحة سريعة

هذه الصفحة هي المرجع على مستوى العقد لمُصنِّف مستندات ⁨NextPDF⁩ Pro. يتكوّن السطح من مُنسِّق واحد، ⁨NextPDF\Pro\Classifier\DocumentClassifier⁩، ومتعاونيه: ⁨StructureAnalyzer⁩ و⁨LanguageDetector⁩ واستراتيجية ⁨ClassifierInterface⁩ مع تنفيذها الافتراضي ⁨HeuristicClassifier⁩. تصل النتائج كائنًا غير قابل للتغيير من نوع ⁨ClassificationResult⁩ يحمل ⁨DocumentType⁩، وثقةً في المجال ⁨[0.0, 1.0]⁩، وقيم ⁨ClassificationFeature⁩ المكتشَفة، ورمز لغة وفق ISO 639-1. التصنيف قائم على القواعد وحتمي: لا استدلال نموذجي، ولا عشوائية، ولا استدعاء شبكي، ولا وصول إلى نظام الملفات. تنصّ هذه الصفحة على الـ⁨API⁩ العام، وعقد السلوك القابل للملاحظة، وأنماط الإخفاق.

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

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

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

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

الرمز	المُعاملات	السلوك الافتراضي	يُرجِع	يرمي أو يُخفق بـ	ملاحظات
DocumentClassifier	المُنشئ: StructureAnalyzer، LanguageDetector، ClassifierInterface	يُنسِّق تحليل البنية، وتصنيف الاستراتيجية، وكشف اللغة	—	—	final؛ احقن المتعاونين فقط للاستراتيجيات المخصّصة
DocumentClassifier::create()	لا شيء	يبني المتعاونين الافتراضيين مع HeuristicClassifier كاستراتيجية	self	—	تهيئة افتراضية حتمية
DocumentClassifier::classifyFromText()	$text، $pdfData = ''	يستخدم $pdfData الفارغ بنيةً فارغة؛ وتُضيف البايتات الخام غير الفارغة إشاراتٍ بنيوية	ClassificationResult	لا يرمي؛ يخفض المُدخَل المتناثر الثقة	يُشغَّل كشف اللغة دائمًا على $text
DocumentClassifier::classifyFromFile()	string $pdfData	يمسح تدفّقات المحتوى، ويستردّ نصّ §9.4، ويحلّل البنية، ويصنّف	ClassificationResult	لا يرمي؛ تقلّص التدفّقاتُ غير القابلة للقراءة النصَّ المُسترَدّ	مسح بايتات محدود، وليس تحليلًا كاملًا لـPDF
ClassifierInterface::classify()	$text، StructureAnalysis $structure	عقد الاستراتيجية الذي يستهلكه المُنسِّق	ClassificationResult	مُعرَّف حسب التنفيذ	نقطة توسيع لاستراتيجيات تصنيف مخصّصة
ClassifierInterface::supports()	string $contentType	فحص نوع المحتوى للمُصنِّفات المركّبة	bool	—	يستقبل نوع MIME أو واصف محتوى
HeuristicClassifier	لا شيء	الاستراتيجية الافتراضية: قواميس كلمات مفتاحية إضافةً إلى استدلالات بنيوية	—	لا يرمي	final؛ يقبل supports() القيمتين application/pdf وtext/plain
StructureAnalyzer::analyze()	string $pdfData	مسح بالتعبير النمطي للبايتات الخام؛ لا تحليل كامل لـPDF	StructureAnalysis	لا يرمي	يعدّ الصفحات والصور والخطوط؛ ويكشف حقول النماذج والتواقيع
LanguageDetector::detect()	string $text	مطابقة ملف تعريف الثلاثيات مع فحص مسبق لمجال محارف CJK	رمز ISO 639-1 من نوع non-empty-string	لا يرمي	يعود إلى en دون عتبة القبول
LanguageDetector::detectWithConfidence()	string $text	مثل detect()، مع كشف الثقة	array{language: non-empty-string, confidence: float}	لا يرمي	يُرجِع النص القصير en بثقة 0.0
ClassificationResult	المُنشئ: $type، $confidence، $features، $language، $metadata = []	كائن قيمة غير قابل للتغيير	—	—	final readonly؛ يحمل metadata القيمتين scores وmethod
ClassificationResult::isConfident()	float $threshold = 0.7	يقارن الثقة بالعتبة	bool	—	بوابة موثَّقة لتوجيه المراجعة اليدوية
StructureAnalysis	المُنشئ: $pageCount، $imageCount، $fontCount، $hasFormFields، $hasSignatureFields، $imageDensity، $detectedFeatures	كائن قيمة غير قابل للتغيير يُنتِجه StructureAnalyzer	—	—	final readonly؛ imageDensity هي عدد الصور لكل صفحة
DocumentType	تعداد مدعوم بسلسلة نصية، 12 حالة	الحالات: Invoice، Contract، Form، Report، Letter، Receipt، Legal، Medical، Financial، Technical، Academic، Other	قيم دعم invoice … other	—	يُرجِع label() اسمًا مقروءًا للبشر
ClassificationFeature	تعداد مدعوم بسلسلة نصية، 7 حالات	الحالات: HasTables، HasHeaders، HasSignatures، HasLogos، HasBarcodes، HasForms، IsScanned	قيم دعم has_tables … is_scanned	—	إشارات بنيوية تُغذّى في التصنيف

تواقيع نقاط الدخول

public static function create(): self

public function classifyFromText(string $text, string $pdfData = ''): ClassificationResult

public function classifyFromFile(string $pdfData): ClassificationResult

public function classify(string $text, StructureAnalysis $structure): ClassificationResult;

public function supports(string $contentType): bool;

public function analyze(string $pdfData): StructureAnalysis

public function detect(string $text): string

public function detectWithConfidence(string $text): array

public function __construct(
    public DocumentType $type,
    public float $confidence,
    public array $features,
    public string $language,
    public array $metadata = [],
) {}

public function isConfident(float $threshold = 0.7): bool

عقد السلوك

ترتيب خط الأنابيب

يُشغِّل ⁨DocumentClassifier⁩ تحليل البنية، ثم تصنيف الاستراتيجية، ثم كشف اللغة، ويجمع ⁨ClassificationResult⁩. تُوفِّر الاستراتيجيةُ النوعَ والثقة والسمات والبيانات الوصفية؛ ويُوفِّر الكاشفُ اللغة. يستبدل ⁨classifyFromText()⁩ دون بايتات ⁨PDF⁩ بنيةً فارغة: صفر صفحات، صفر عدادات، لا سمات. يشتقّ ⁨classifyFromFile()⁩ كلًّا من البنية والنص من البايتات الخام نفسها.

التسجيل الاستدلالي

يُسجِّل ⁨HeuristicClassifier⁩ النصَّ المحوَّل إلى حروف صغيرة مقابل قواميس كلمات مفتاحية لكل نوع مستند، مُطبَّعًا بطول النص. القواميسُ والأوزانُ والعتباتُ المحدَّدة تفاصيلُ تنفيذ ولا تُنشَر. ثم تُعدِّل الإشاراتُ البنيوية الدرجات: تُعزِّز قيم ⁨ClassificationFeature⁩ المطابِقة الأنواعَ المرتبطة بها؛ وتنحاز المستنداتُ فوق عتبة صفحات بعيدًا عن ⁨Letter⁩ و⁨Receipt⁩؛ وتتلقّى المستنداتُ متعدّدة الصفحات ذات الترويسات والجداول تعزيزًا لـ⁨Report⁩؛ وتُضيف سمةُ نموذج مكتشَفة إشارةً قوية لـ⁨Form⁩. تفوز الدرجةُ الأعلى وتُطابَق إلى ⁨DocumentType⁩. يُطابِق تطبيعٌ محدود الدرجةَ الخام إلى المجال ⁨[0.0, 1.0]⁩. تُنتِج الدرجةُ دون الحد الأدنى ⁨DocumentType::Other⁩ مع أرضية ثقة صغيرة غير صفرية. يحمل ⁨metadata⁩ في النتيجة خريطةَ ⁨scores⁩ لكل نوع و⁨method: heuristic⁩. يُبلِّغ ⁨HeuristicClassifier⁩ وحده عن اللغة ⁨en⁩؛ ويتجاوزها ⁨DocumentClassifier⁩ بمخرجات الكاشف.

كشف اللغة

يُشغَّل فحصُ مجال المحارف لنص CJK قبل تسجيل الثلاثيات. تُحدِّد هيمنةُ الهانغول ⁨ko⁩؛ وتُحدِّد أيُّ كانا ⁨ja⁩؛ وإلا تُحدِّد نسبةٌ كافية من الرموز التصويرية ⁨zh⁩. يُسجَّل كلُّ نص آخر بتردّد ثلاثيات المحارف مقابل عشرة ملفات تعريف مدمجة. القيمُ المُمكنة للإرجاع هي رموز ISO 639-1 التالية: ⁨en⁩ و⁨zh⁩ و⁨ja⁩ و⁨ko⁩ و⁨de⁩ و⁨fr⁩ و⁨es⁩ و⁨pt⁩ و⁨it⁩ و⁨nl⁩. يُرجِع النصُّ دون حد أدنى للطول ⁨en⁩ بثقة ⁨0.0⁩. كما تُرجِع النتيجةُ دون عتبة القبول بهامش ضيّق ⁨en⁩ أيضًا. تعكس الثقةُ الهامشَ بين أفضل درجتي ملف تعريف وثانيهما.

استرداد نص الملف

يمسح ⁨classifyFromFile()⁩ البايتات الخام بحثًا عن مقاطع ⁨stream⁩/⁨endstream⁩. يُجرَّب كلُّ مقطع بوصفه بيانات Flate تحت سقف انكماش محدود؛ وعند الإخفاق تُستخدَم بايتاتُ المقطع الخام. عندما يُعلِن قاموسُ التدفّق المجاور مُتنبِّئ PNG في ⁨/DecodeParms⁩، يُراعي العكسُ مُعاملات ⁨Predictor⁩ و⁨Columns⁩ و⁨Colors⁩ و⁨BitsPerComponent⁩ وفق ⁨ISO 32000-2⁩:2020 §7.4.4.4، باستخدام فئتَي ⁨DecodeParms⁩ و⁨PngPredictor⁩ في وحدة Filter. ثم يُسترَدّ النصُّ من مشغّلات إظهار النص §⁨9.4⁩: السلاسل الحرفية المعروضة بـ⁨Tj⁩ والسلاسل الحرفية داخل مصفوفات ⁨TJ⁩. يُسجِّل المُصنِّفُ النصَّ المُسترَدّ؛ ولا يعتمد على التخطيط البصري.

تحليل البنية

يعدّ ⁨StructureAnalyzer::analyze()⁩ رموزَ الصفحات والصور والخطوط في البايتات الخام، ويكشف ⁨/AcroForm⁩ وحقول التواقيع، ويشتقّ كثافة الصور. كشفُ السمات استدلالي: يُشير رسمُ المستطيلات المتكرّر إلى جداول، وتُشير إعلاناتُ أحجام الخطوط الكبيرة إلى ترويسات، وتُشير كثافةُ الصور العالية مع قلّة الخطوط إلى مستند ممسوح ضوئيًا. تعكس العداداتُ الرموزَ المرئية في البايتات الخام؛ ولا تُعَدّ البنى المُسلسَلة داخل تدفّقات كائنات مضغوطة.

الحتمية

خطُّ الأنابيب بأكمله دالةٌ خالصة من بايتات مُدخَله. يُنتِج المُدخَلُ المتطابق ⁨ClassificationResult⁩ متطابقًا. لا استدلال نموذجي، ولا عشوائية، ولا استدعاء شبكي، ولا وصول إلى نظام الملفات.

الحالات الحدّية وأنماط الإخفاق

• يُنتِج النصُّ الفارغ أو شبه الفارغ ⁨DocumentType::Other⁩ منخفض الثقة عن قصد. تفرّع على ⁨isConfident()⁩ بدلًا من النوع وحده.
• لا يرمي أيُّ أسلوب عام في هذه الوحدة. تُمسَح التدفّقاتُ التي يُخفق إلغاءُ ضغطها خامًا؛ وتعود مُعاملاتُ المُتنبِّئ المُشوَّهة أو غير المدعومة إلى البايتات غير المُرشَّحة.
• يُطابِق استردادُ النص صيغتي السلسلة الحرفية ⁨Tj⁩ و⁨TJ⁩ فقط. لا تُسترَدّ السلاسلُ الست عشرية، والنصُّ داخل محتوى مُشفَّر، والمشغّلاتُ المقسومة عبر تدفّقات، ما يقلّص النصَّ المتاح للتسجيل.
• يحدّ سقفُ إلغاء الضغط الذاكرةَ أثناء انكماش التدفّق ويقاوم مُدخَل قنبلة إلغاء الضغط. لا يُنكمَش المحتوى الذي يتجاوز السقف.
• تستردّ ملفاتُ ⁨PDF⁩ المكوَّنة من صور فقط أو المضغوطة بكثافة نصًّا قليلًا؛ توقّع نتائج منخفضة الثقة ووجّهها إلى المراجعة اليدوية.
• يُرجِع كشفُ اللغة دون الحد الأدنى لطول النص ⁨en⁩ بثقة ⁨0.0⁩؛ ولا تُنتِج السلاسلُ القصيرة جدًّا نتيجةً غير إنجليزية أبدًا.
• الأنواعُ الاثنا عشر للمستندات وملفاتُ تعريف اللغات العشرة ثابتة لهذا الإصدار. التوسيعُ يكون عبر تنفيذ ⁨ClassifierInterface⁩ مخصّص، لا بتحرير البيانات المدمجة.
• لا تحدث أيُّ عملية تشفيرية في هذه الوحدة، فلا يوجد سلوك خاص بوضع FIPS.

المطابقة

الادّعاء	المعيار	البند
يستردّ تصنيفُ الملف النصَّ المعروض بمشغّل Tj.	ISO 32000-2:2020	§9.4
يستردّ تصنيفُ الملف السلاسلَ الحرفية داخل مشغّلات مصفوفة TJ.	ISO 32000-2:2020	§9.4
يُراعي عكسُ مُتنبِّئ PNG مُعاملات المُرشِّح Predictor وColumns وColors وBitsPerComponent.	ISO 32000-2:2020	§7.4.4.4

تتّبع رموزُ اللغة ISO 639-1؛ وهذا بيانٌ لتنسيق المخرجات قائم على المنتج، لا ادّعاء مطابقة مُستشهَد به. جميعُ البنود مُعاد صياغتها؛ ولا يُعيد ⁨NextPDF⁩ إنتاج النص المعياري. هذه بياناتُ قدرة، لا شهادات. لا يحمل ⁨NextPDF⁩ أيَّ شهادة ولا يمنح أيًّا. التصنيفُ استدلالي وأفضل-جهد: تؤكّد الوحدةُ الحتميةَ، لا الدقّة، ويملك المستدعون عتبةَ القرار.

ملاحظات التطوير

• متوفّر منذ ⁨nextpdf/pro⁩ ⁨2.2.0⁩؛ وحالي في ⁨nextpdf/pro⁩ 3.1.0.
• استخدم ⁨DocumentClassifier::create()⁩ لخط الأنابيب الافتراضي. احقن المتعاونين فقط لتوفير استراتيجية ⁨ClassifierInterface⁩ مخصّصة.
• عامِل النتائجَ دون العتبة على أنها غير مؤكّدة ووجّهها إلى المراجعة اليدوية؛ و⁨isConfident()⁩ بقيمته الافتراضية ⁨0.7⁩ هي البوابة الموثَّقة.
• لا تُخزِّن الوحدةُ شيئًا، ولا تُصدِر قياسًا عن بُعد، ولا تُسجِّل مُدخَلًا. إن أبقى المستدعون على ⁨metadata⁩، فراجعوها مقابل سياسة معالجة البيانات الخاصة بهم أولًا.
• تسجيلُ الكلمات المفتاحية وعدُّ الثلاثيات خطّيان في طول النص. تحليلُ البنية خطّي في طول بايتات ⁨PDF⁩ تحت سقف إلغاء الضغط المحدود. ميزانيةُ الصفحة 1000 ms زمن جدار و64 MB ذروة ذاكرة.

حدود النشر

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

اطّلع أيضًا

• المُصنِّف (القدرة) — التثبيت، والبدء السريع، وعيّنات التوجيه الإنتاجي.
• الاستخراج — مرجع معمّق — سطح استخراج النص الكامل لنص مُدخَل أغنى.
• المُرشِّح — مرجع معمّق — DecodeParms وPngPredictor، المستخدمان أثناء تصنيف الملف.
• الفرق — مرجع معمّق — سطح مقارنة المستندات النظير على مستوى البايت.