الاستخراج

لمحة سريعة

يجوب NextPDF\Pro\Extraction شجرة ⁨AST⁩ مستند مُحلَّلة ويُنتج كتلًا نصّية وجداول، تحمل كل منها مرساة استشهاد (فهرس الصفحة، والمربّع المُحيط، ومرجع العقدة). وهو مُستخرِج بنيوي حتمي لمسارات إسناد المصدر، لا محرّك بحث أو فهم.

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

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

التثبيت

composer require nextpdf/pro:^3

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

يأخذ المُستخرِجان كلاهما NextPDF\Ast\AstDocument — وهو شجرة مستند مُحلَّلة يُنتجها نظام ⁨AST⁩ الفرعي في ⁨Core.⁩ وهما لا يحلّلان بايتات ⁨PDF⁩ الخام بنفسيهما؛ فشجرة ⁨AST⁩ هي حدّ المُدخَل.

• يجوب CitedTextExtractor الشجرة ويُصدِر CitedTextBlock لكل عقدة نص جوهرية (فقرة، عنوان، عنصر قائمة، خلية جدول، شيفرة، تعليق توضيحي) يبلغ نصها المُشذَّب طولًا أدنى. وميزانية رموز اختيارية تقسم النص الطويل عند حدود الجمل. تحمل كل كتلة CitationAnchor بمعرّف العقدة، وفهرس الصفحة، والمربّع المُحيط، ودرجة ثقة مقروءة من العقدة (الافتراضي ⁨1.0⁩). تتلقّى العقد بلا مربّع مُحيط مربّعًا حارسًا صفري المساحة لكي تظل المرساة صالحة دائمًا.
• يعثر CitedTableExtractor على عقد Table، ويقرأ صفوفها وخلاياها، ويبني مصفوفة مستطيلة بترتيب الصفوف مُبطَّنة إلى أعرض صف. لا يجري التعمّق في الجداول المُتداخلة. ثقة الخلية افتراضيًا ⁨0.8⁩ ما لم تحمل العقدة قيمة صريحة.

تتوافق البنية الهرمية التي يجوبها هذان المُستخرِجان مع نموذج البنية المنطقية لـ ⁨PDF⁩ (⁨ISO 32000-2⁩:2020 §⁨14.7⁩) وعناصر بنية الجداول (§⁨14.8⁩) عندما يكون المستند المصدر مُوسومًا.

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

يأخذ المُستخرِج شجرة ⁨AST⁩ مُحلَّلة بوصفها حدّ مُدخَله، لا بايتات ⁨PDF⁩ الخام، لكي تبقى مخاطر التحليل منفصلة عن منطق الاستخراج. تُقرأ الثقة مباشرةً من عقدة ⁨AST⁩ وتُمرَّر دون تغيير؛ فالوحدة لا تحسبها ولا ترتّبها ولا تُحسّنها أبدًا. يبقى المخرَج بترتيب المستند، لا بترتيب الصلة، لأن إسناد المصدر يحتاج إلى مصدرية قابلة للتحقق لا إلى تخمين استدلالي لا يستطيع المُستخرِج الدفاع عنه. تحمل كل كتلة مرساة استشهاد — معرّف العقدة، وفهرس الصفحة، والمربّع المُحيط — كي يتمكّن مسار لاحق من تتبّع كل اقتباس إلى أصله. هذا يُبقي الوحدة عمدًا مُستخرِجًا بنيويًا حتميًا: تُبلِّغ بما تؤكّده شجرة ⁨AST⁩ وتمتنع عن اختراع أي شيء لا ينصّ عليه المستند.

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

عقد السلوك

• المُدخَل. ‏NextPDF\Ast\AstDocument. لا تقبل الوحدة بايتات ⁨PDF⁩ خام؛ أنتِج شجرة ⁨AST⁩ بنظام ⁨AST⁩ الفرعي في ⁨Core⁩ أولًا.
• المخرَج. ‏list<CitedTextBlock> أو list<CitedTableBlock> بترتيب المستند.
• الثقة مُمرَّرة. تُقرأ من سمات عقدة ⁨AST⁩ (أو من افتراضي ثابت). لا تحسب هذه الوحدة الثقة ولا تُحسّنها.
• لا معالجة دلالية. لا يُجري المُستخرِج أي تضمين، أو تشابه متّجهات، أو ترتيب، أو فهم للمستند. ترتيب المخرَج هو ترتيب المستند، لا ترتيب الصلة.
• الحتمية. لشجرة ⁨AST⁩ متطابقة، تكون الكتل والمراسي وفهارس الشذرات المُنتَجة مستقرّةً.

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

النوع	الصنف	الأعضاء الرئيسيون
NextPDF\Pro\Extraction\CitedTextExtractor	final class	__construct(?int $maxTokensPerChunk = null, int $minChunkLength = 10), extract(AstDocument $document): list<CitedTextBlock>
NextPDF\Pro\Extraction\CitedTableExtractor	final class	extract(AstDocument $document): list<CitedTableBlock>
NextPDF\Pro\Extraction\CitedTextBlock	final readonly class	string $text, CitationAnchor $anchor, float $confidence, int $chunkIndex, array $metadata, estimatedTokens(): int
NextPDF\Pro\Extraction\CitedTableBlock	final readonly class	string $nodeId, int $pageIndex, int $rowCount, int $colCount, array $matrix
NextPDF\Pro\Extraction\CitedTableCell	final readonly class	int $row, int $col, ?string $textContent, float $confidence

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

<?php

declare(strict_types=1);

use NextPDF\Pro\Extraction\CitedTextExtractor;

/** @var \NextPDF\Ast\AstDocument $ast */
$blocks = (new CitedTextExtractor())->extract($ast);

foreach ($blocks as $block) {
    printf(
        "p%d chunk#%d (%d tokens): %s\n",
        $block->anchor->pageIndex,
        $block->chunkIndex,
        $block->estimatedTokens(),
        $block->text,
    );
}

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

<?php

declare(strict_types=1);

use NextPDF\Pro\Extraction\CitedTextExtractor;

function chunkForCitation(\NextPDF\Ast\AstDocument $ast): array
{
    // Token-bounded chunks for downstream citation storage.
    $extractor = new CitedTextExtractor(
        maxTokensPerChunk: 400,
        minChunkLength: 16,
    );

    $rows = [];
    foreach ($extractor->extract($ast) as $block) {
        $rows[] = [
            'text'      => $block->text,
            'page'      => $block->anchor->pageIndex,
            'node_id'   => $block->anchor->nodeId,
            'chunk'     => $block->chunkIndex,
        ];
    }

    return $rows;
}

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

• المستندات غير المُوسومة أو ضعيفة الوسم تُنتج عقد نص أقل؛ وجودة شجرة ⁨AST⁩ هي الحدّ الأعلى لجودة الاستخراج.
• العقد بلا مربّع مُحيط تتلقّى مربّعًا حارسًا صفري المساحة BoundingBox(0,0,0,0) — اكتشفه عبر width === 0.0 && height === 0.0 إذا كانت منطقة حقيقية مطلوبة.
• لا يجري التعمّق في الجداول المُتداخلة؛ فقط عقدة Table الأبعد تُصدَر.
• تُبطَّن الصفوف القصيرة بخلايا اصطناعية صفرية الثقة لكي يكون لكل صف عدد الأعمدة نفسه.

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

تعالج هذه الوحدة أي نص تحويه شجرة ⁨AST⁩ المُزوَّدة وتُعيده دون تغيير داخل الكتل. ولا تُجري أي استدعاءات شبكية، ولا تخزينًا خارجيًا، ولا تسجيلًا للمحتوى المُستخرَج. معالجة المعلومات الشخصية، والحجب، وضوابط الإقامة من مسؤولية المستدعي على الكتل المُنتَجة. انظر إرشاد معالجة المعلومات الشخصية في ⁨Core.⁩

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

لا يُصدِر المُستخرِج أي قياس عن بُعد ولا يُسجّل النص المُستخرَج. إذا غلّفه مستدعٍ بالتسجيل، فنقِّ text وmetadata وأي محتوى خلية قبل إصدار السجلات.

الأداء

الاستخراج جولة شجرة واحدة، خطّي بعدد العقد. يضيف تقسيم الشذرات عملًا متناسبًا مع طول النص. انظر performance_budget.

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

المُدخَل شجرة ⁨AST⁩ مُحلَّلة مسبقًا، لذا لا تحلّل هذه الوحدة بايتات ⁨PDF⁩ عدائية بنفسها. عامِل النص المُستخرَج بوصفه غير موثوق وهرّبه بما يناسب وجهته.

المطابقة

الادعاء	بند المعيار	الحالة
اجتياز عقد البنية المنطقية	ISO 32000-2:2020 §14.7	مُتحقَّق منه (مجموعة وحدات، شجرة AST مُوسومة)
استخراج صفوف/خلايا الجدول	ISO 32000-2:2020 §14.8	مُتحقَّق منه (مجموعة وحدات)
البحث الدلالي / التضمينات	—	غير مدعوم (خارج النطاق)

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

يُنتج نظام ⁨AST⁩ الفرعي في ⁨Core⁩ ‏AstDocument المُستهلَك هنا؛ ولا يوجد مكافئ في ⁨Core⁩ لاستخراج كتل الاستشهاد نفسه. انظر /modules/core/ast/.

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

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

حدود النشر

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

انظر أيضًا

• مرجع الاستخراج
• ⁨Classifier⁩
• ⁨Diff⁩
• ⁨Core AST⁩