Extraction — การอ้างอิงเชิงลึก

ภาพรวมโดยสังเขป

หน้านี้เป็นการอ้างอิงระดับสัญญาของ NextPDF\Pro\Extraction โมดูลนี้มีสัญลักษณ์สาธารณะห้ารายการ ได้แก่ ตัวสกัดสองตัว ( CitedTextExtractor, CitedTableExtractor ) และวัตถุค่าที่เปลี่ยนแปลงไม่ได้สามตัว ( CitedTextBlock, CitedTableBlock, CitedTableCell ) ตัวสกัดทั้งสองรับ NextPDF\Ast\AstDocument ที่แจงแล้ว ไม่มีตัวใดอ่านไบต์ PDF ดิบ การสกัดเป็นแบบกำหนดผลได้แน่นอนและอิงโครงสร้าง ไม่มีขั้นตอน semantic, embedding หรือ ranking อยู่ที่ใดในโมดูลนี้ มุมมองที่เน้นงานอยู่ใน หน้าความสามารถ

ความพร้อมใช้งานและการอนุญาต

ความสามารถนี้มาพร้อมกับ NextPDF Pro ( nextpdf/pro ) และเปิดใช้งานด้วยซองใบอนุญาตระดับ Pro การติดตั้งที่ไม่มีสิทธิ์ดังกล่าวจะไม่โหลดคลาสของความสามารถนี้ เปรียบเทียบรุ่นและขอใบอนุญาต

ไม่มีแฟล็กความสามารถขณะรันที่จำกัดโมดูลนี้ คลาสจะพร้อมใช้งานเมื่อใดก็ตามที่ nextpdf/pro ถูกติดตั้งและมีใบอนุญาต

พื้นผิว API สาธารณะ

สัญลักษณ์	พารามิเตอร์	พฤติกรรมปริยาย	คืนค่า	โยนหรือล้มเหลวด้วย	หมายเหตุ
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 ห้าตัว	เมทริกซ์เซลล์สี่เหลี่ยมแบบ row-major ที่เปลี่ยนแปลงไม่ได้	—	ไม่โยนข้อยกเว้น	แถวที่สั้นถูกเติมทางขวาในเวลาที่สกัด
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 ไบต์จากจุดตัดที่ต้องการ มิฉะนั้นจะตัดแบบเด็ดขาดที่งบประมาณ ช่องว่างหลังจุดตัดจะถูกข้าม และก้อนที่ว่างเปล่าจะถูกทิ้ง
• Citation anchor CitationAnchor ของแต่ละบล็อกประกอบด้วย node id, ดัชนีหน้า, กล่องครอบ, ความเชื่อมั่น และ content hash ที่เป็น null โหนดที่ไม่มีกล่องครอบจะได้รับเซนทิเนลพื้นที่เป็นศูนย์ที่ใช้ร่วมกัน BoundingBox(0, 0, 0, 0) เพื่อให้ anchor ถูกต้องเชิงโครงสร้างเสมอ
• ความเชื่อมั่นของข้อความ ความเชื่อมั่นอ่านจากแอตทริบิวต์ 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 เสมอบนพื้นผิวนี้ ให้คำนวณ content hash ที่ปลายทางเมื่อไปป์ไลน์ต้องการ

ขอบเขตการเผยแพร่

หน้านี้บันทึกเฉพาะพฤติกรรมที่สังเกตได้จากภายนอกและพื้นผิว API สาธารณะที่รองรับเท่านั้น เส้นทาง namespace ภายใน, คลาสตัวช่วย, ตารางกลไก, ชื่อไฟล์ runbook และคำนำหน้าตั๋วอยู่นอกขอบเขต

ดูเพิ่มเติม

• Extraction — หน้าความสามารถ
• Classifier — การอ้างอิงเชิงลึก (Pro)
• Core AST