‏⁨Extraction⁩ — مرجع متعمّق

لمحة سريعة

هذه الصفحة هي المرجع على مستوى العقد لـ NextPDF\Pro\Extraction. تحتوي الوحدة على خمسة رموز عامة: مُستخرِجَين (CitedTextExtractor وCitedTableExtractor) وثلاثة كائنات قيمة غير قابلة للتغيير (CitedTextBlock وCitedTableBlock وCitedTableCell). ويستهلك كلا المُستخرِجَين نسخة مُحلَّلة من NextPDF\Ast\AstDocument؛ ولا يقرأ أيٌّ منهما بايتات ⁨PDF⁩ الخام. والاستخراج حتمي وبنيوي. ولا توجد أي خطوة دلالية أو تضمين أو ترتيب في أي مكان من هذه الوحدة. ويوجد العرض الموجَّه بالمهام في صفحة القدرة.

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

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

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

سطح واجهة برمجة التطبيقات العامة

الرمز	المعاملات	السلوك الافتراضي	القيمة المُعادة	يرمي أو يفشل بـ	ملاحظات
CitedTextExtractor::__construct()	?int $maxTokensPerChunk = null، int $minChunkLength = 10	لا ميزانية للرموز؛ ويُسقَط النص المُشذَّب الأقصر من 10 بايتات	CitedTextExtractor	لا يرمي	ميزانية null تعني كتلة واحدة لكل عُقدة.
CitedTextExtractor::extract()	AstDocument $document	مسير بالعمق أولًا؛ كتلة واحدة لكل عُقدة نصّية مؤهَّلة، مُقسَّمة وفق ميزانية الرموز	list<CitedTextBlock>	لا يرمي	حتمي؛ يُعاد ضبط chunkIndex إلى 0 عند كل استدعاء.
CitedTextBlock	خمسة حقول ⁨readonly⁩	كائن قيمة غير قابل للتغيير؛ لا طريقة تسلسل	—	لا يرمي	مفاتيح metadata: nodeType وpageIndex، إضافةً إلى structType وlang وalt وuntagged الاختيارية.
CitedTextBlock::estimatedTokens()	لا شيء	ceil(byte length / 4)	int	لا يرمي	إرشاد ميزنة؛ ليس مُجزِّئ رموز.
CitedTableExtractor::extract()	AstDocument $document	يجمع عُقَد Table الخارجية بترتيب المستند	list<CitedTableBlock>	لا يرمي	لا ينزل أبدًا إلى شجرة جدول فرعية.
CitedTableBlock	خمسة حقول ⁨readonly⁩	مصفوفة خلايا مستطيلة بترتيب الصفوف أولًا، غير قابلة للتغيير	—	لا يرمي	تُبطَّن الصفوف القصيرة على اليمين وقت الاستخراج.
CitedTableBlock::toArray()	لا شيء	يُسلسِل إلى مصفوفة بسيطة بنمط ⁨snake_case⁩	array<string, mixed>	لا يرمي	تُسلسَل الخلايا المتداخلة عبر CitedTableCell::toArray().
CitedTableCell	سبعة حقول ⁨readonly⁩	سجلّ خلية غير قابل للتغيير بإحداثيات استشهاد	—	لا يرمي	تحمل خلايا التبطين nodeId فارغًا وثقة 0.0.
CitedTableCell::toArray()	لا شيء	يُسلسِل إلى مصفوفة بسيطة بنمط ⁨snake_case⁩؛ وbbox يتداخل أو يكون null	array<string, mixed>	لا يرمي	—

final class CitedTextExtractor

public function __construct(
    private readonly ?int $maxTokensPerChunk = null,
    private readonly int $minChunkLength = 10,
)

public function extract(AstDocument $document): array

final class CitedTableExtractor

public function extract(AstDocument $document): array

final readonly class CitedTextBlock

public function __construct(
    public string $text,
    public CitationAnchor $anchor,
    public float $confidence,
    public int $chunkIndex,
    public array $metadata,
)

public function estimatedTokens(): int

final readonly class CitedTableBlock

public function __construct(
    public readonly string $nodeId,
    public readonly int    $pageIndex,
    public readonly int    $rowCount,
    public readonly int    $colCount,
    public readonly array  $matrix,
)

public function toArray(): array

final readonly class CitedTableCell

public function __construct(
    public readonly string       $nodeId,
    public readonly int          $row,
    public readonly int          $col,
    public readonly ?string      $textContent,
    public readonly ?BoundingBox $bbox,
    public readonly int          $pageIndex,
    public readonly float        $confidence,
)

public function toArray(): array

عقد السلوك

• اختيار العُقَد. يُصدِر CitedTextExtractor كُتلًا للعُقَد التي يكون نوعها Paragraph أو Heading أو ListItem أو TableCell أو Code أو Annotation. وتُتخطّى العُقدة التي نصّها null. ولا تُصدَر عُقدة إلّا عندما لا يقلّ طول نصّها المُشذَّب عن minChunkLength (الافتراضي 10). وجميع الأطوال أطوال بالبايت.
• ترتيب الاجتياز. المسير بالعمق أولًا انطلاقًا من جذر المستند. وتُصدَر العُقدة المؤهَّلة قبل زيارة أبنائها. ويتزايد chunkIndex عبر مسير المستند بأكمله ويُعاد ضبطه إلى 0 عند كل استدعاء لـ extract().
• التجزئة إلى كتل. عندما لا يُضبَط maxTokensPerChunk، تُنتِج كل عُقدة كتلة واحدة. وعند ضبطه، يُقسَّم النص الأطول من maxTokensPerChunk * 4 بايت. ويُفضِّل المُقسِّم حدَّ جملة — سطر جديد، أو نقطة يتبعها مسافة — يُعثَر عليه بالفحص رجوعًا 200 بايت كحدّ أقصى من نقطة القطع المفضّلة. وإلّا فيقطع قطعًا صارمًا عند الميزانية. وتُتخطّى المسافات بعد القطع؛ وتُسقَط الكتل الفارغة.
• مرتكز الاستشهاد. يحمل CitationAnchor لكل كتلة مُعرِّف العُقدة، وفهرس الصفحة، وصندوقًا محيطًا، وثقة، وتجزئة محتوى null. وتتلقّى العُقَد التي بلا صندوق محيط نقطةً مرجعية مشتركة صفرية المساحة، BoundingBox(0, 0, 0, 0)، فيكون المرتكز صالحًا بنيويًا دائمًا.
• ثقة النص. تُقرأ الثقة من سمة confidence للعُقدة عندما تكون ⁨int⁩ أو ⁨float⁩؛ والافتراضي 1.0. وترتدّ قيم السمة غير العددية إلى الافتراضي.
• بيانات الكتلة الوصفية. يحمل metadata دائمًا nodeType وpageIndex. وتُنسَخ structType وlang وalt عند وجودها على العُقدة. وتُضبَط untagged إلى true عندما تحمل العُقدة سمة untagged.
• اختيار الجداول. يجمع CitedTableExtractor عُقَد Table الخارجية فقط، بترتيب المستند. وبمجرّد معالجة عُقدة Table لا تُفحَص شجرتها الفرعية مجددًا؛ والجداول المتداخلة غير مدعومة.
• شكل المصفوفة. تأتي الصفوف من أبناء TableRow؛ وتأتي الخلايا من أبناء TableCell التابعين لها. وتُتجاهَل أنواع الأبناء الأخرى. وcolCount هو أقصى عدد خلايا عبر جميع الصفوف. وتُبطَّن الصفوف القصيرة على اليمين حتى colCount بخلايا اصطناعية: nodeId فارغ، ونص null، وbbox بقيمة null، وفهرس صفحة الجدول، وثقة 0.0. والجدول الذي بلا صفوف أو بلا أعمدة لا يُنتِج أي كتلة.
• ثقة الخلية. تُقرأ ثقة الخلية الحقيقية من سمة confidence الخاصة بها عندما تكون ⁨int⁩ أو ⁨float⁩؛ والافتراضي 0.8. والكتل النصّية افتراضها ⁨1.0⁩؛ وخلايا الجداول افتراضها 0.8.
• تعيين البنية. تتطابق الهيكلية المُجتازة مع نموذج البنية المنطقية في ⁨PDF⁩ (⁨ISO 32000-2:2020 §14.7⁩). وتتطابق صفوف الجدول مع عنصر البنية TR (⁨§14.8⁩) عندما يكون المصدر موسومًا.

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

• لا شيء في هذا السطح يرمي. وتُعيد كلتا طريقتَي extract() قائمة فارغة لمستند بلا عُقَد مؤهَّلة.
• الصندوق المحيط صفري المساحة نقطة مرجعية مفردة مشتركة. وعلى المُستدعِين الذين يحتاجون منطقة فعلية اكتشافه صراحةً: width === 0.0 && height === 0.0.
• جميع فحوص الأطوال وعمليات القطع قائمة على البايت. وعندما لا يوجد حدُّ جملة ضمن نافذة الـ 200 بايت، قد يقع القطع الصارم داخل تسلسل ⁨UTF-8⁩ متعدّد البايتات.
• رقم 4 بايتات لكل رمز إرشاد للميزنة فقط. وليس مُجزِّئ رموز ولا يطابق تجزئة رموز أي نموذج محدّد. وتستخدم estimatedTokens() الإرشاد نفسه.
• السلسلة العددية في سمة confidence لا تُحوَّل؛ فينطبق الافتراضي. ولا تُعتمَد إلّا قيم ⁨int⁩ و⁨float⁩.
• تخطّي المسافات البيضاء بعد القطع يزيل المسافات العادية فقط. وتُحفَظ علامات الجدولة والأسطر الجديدة عند بداية الكتلة.
• يُستخرَج نص TableCell مرّتين عن قصد: ككتل نصّية عبر CitedTextExtractor، وداخل المصفوفات عبر CitedTableExtractor. فأزِل التكرار في المراحل اللاحقة عند تشغيل المُستخرِجَين معًا على مستند واحد.
• تُميَّز خلايا التبطين بـ nodeId فارغ وثقة 0.0. أمّا الخلية الحقيقية لكن الفارغة فتحتفظ بـ nodeId غير الفارغ.
• لا تجري أي عملية تشفير في هذه الوحدة، فلا يوجد سلوك خاص بوضع ⁨FIPS⁩.

المطابقة

عندما يكون المستند المصدر موسومًا، يعكس ⁨AST⁩ هيكلية البنية المنطقية في ⁨ISO 32000-2:2020 §14.7⁩، وتقابل عُقَد Table/TableRow عنصري البنية Table/TR في ⁨§14.8⁩. وجودة الاستخراج محدودة بجودة الوسم؛ والمحتوى غير الموسوم يُنتِج عُقَدًا أقلّ أو أخشن.

هذه عبارات مواءمة بنيوية، لا نتائج اختبار مطابقة. ⁨NextPDF⁩ لا تملك أي شهادة ولا تمنح أيّها. ولا تُقدِّم هذه الوحدة أي ادّعاء مطابقة خاص بها؛ بل تستهلك أيًّا كانت البنية التي أنتجها نظام ⁨Core AST⁩ الفرعي.

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

• إعادة استخدام نسخة واحدة من CitedTextExtractor عبر عدّة مستندات آمنة تسلسليًا؛ إذ يُعيد extract() ضبط chunkIndex قبل كل مسير.
• اضبط minChunkLength لترشيح عُقَد الضجيج (أرقام الصفحات، وسلاسل المحارف الشاردة) قبل التجزئة لا بعدها.
• بالنسبة للغات ⁨CJK⁩ وسائر الكتابات متعدّدة البايتات، يُفرِط الإرشاد القائم على البايت في عدّ الرموز؛ فحدِّد حجم maxTokensPerChunk وفق ذلك.
• تُصدِر CitedTableBlock::toArray() وCitedTableCell::toArray() مفاتيح بنمط ⁨snake_case⁩ لخطوط أنابيب ⁨JSON⁩. أمّا CitedTextBlock فلا مُسلسِل له؛ فرمِّز حقوله بنفسك.
• حقل contentHash في CitationAnchor دائمًا null على هذا السطح. فاحسب تجزئات المحتوى في المراحل اللاحقة عندما يحتاجها خط الأنابيب.

حدود النشر

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

انظر أيضًا

• ‏⁨Extraction⁩ — صفحة القدرة
• ‏⁨Classifier⁩ — مرجع متعمّق (‏⁨Pro⁩)
• ‏⁨Core AST⁩