Çıkarma

Bir bakışta

NextPDF\Pro\Extraction, ayrıştırılmış bir belge AST’sini dolaşır ve her biri bir alıntı çapası (sayfa dizini, sınırlayıcı kutu, düğüm başvurusu) taşıyan metin ve tablo blokları üretir. Kaynak ataması işlem hatları için belirlenimci bir yapısal çıkarıcıdır, bir arama veya anlama motoru değildir.

Kullanılabilirlik ve lisanslama

Bu özellik NextPDF Pro (nextpdf/pro) içinde sunulur ve bir Pro katmanı lisans zarfıyla etkinleşir. Bu yetkilendirmesi olmayan bir dağıtım, özelliğin sınıflarını yüklemez. Bu modülü hiçbir çalışma zamanı yetenek bayrağı kapılamaz; Extraction sınıfları, nextpdf/pro yüklü olduğunda her zaman kullanılabilir. Sürümleri karşılaştırın ve bir lisans edinin.

Kurulum

composer require nextpdf/pro:^3

Kavramsal genel bakış

Her iki çıkarıcı da bir NextPDF\Ast\AstDocument — Core AST alt sistemi tarafından üretilen ayrıştırılmış bir belge ağacı — alır. Ham PDF baytlarını kendileri ayrıştırmaz; AST, girdi sınırıdır.

• CitedTextExtractor, ağacı dolaşır ve kırpılmış metni en az bir uzunluğa ulaşan her esaslı metin düğümü (paragraf, başlık, liste öğesi, tablo hücresi, kod, açıklama) için bir CitedTextBlock yayar. İsteğe bağlı bir belirteç bütçesi, uzun metni tümce sınırlarında böler. Her blok; düğüm kimliği, sayfa dizini, sınırlayıcı kutu ve düğümden okunan bir güven (varsayılan 1.0) içeren bir CitationAnchor taşır. Sınırlayıcı kutusu olmayan düğümler, çapanın her zaman geçerli olması için sıfır alanlı bir nöbetçi kutu alır.
• CitedTableExtractor, Table düğümlerini bulur, satırlarını ve hücrelerini okur ve en geniş satıra doldurulmuş, dikdörtgen bir satır öncelikli matris oluşturur. İç içe tablolara girilmez. Düğüm açık bir değer taşımadıkça hücre güveni varsayılan olarak 0.8’dir.

Bu çıkarıcıların dolaştığı yapısal hiyerarşi, kaynak belge etiketlendiğinde PDF mantıksal yapı modeline (ISO 32000-2:2020 §14.7) ve tablo yapısı öğelerine (§14.8) karşılık gelir.

Neden bu şekilde çalışır

Çıkarıcı, girdi sınırı olarak ham PDF baytlarını değil ayrıştırılmış bir AST’yi alır; böylece ayrıştırma riski çıkarma mantığından ayrı kalır. Güven, doğrudan AST düğümünden okunur ve değişmeden geçirilir; modül onu asla hesaplamaz, sıralamaz veya iyileştirmez. Çıktı, alaka sırasında değil belge sırasında kalır, çünkü kaynak ataması, çıkarıcının savunamayacağı sezgisel bir tahmin yerine doğrulanabilir bir köken gerektirir. Her blok bir alıntı çapası taşır — düğüm kimliği, sayfa dizini, sınırlayıcı kutu — böylece aşağı akış bir işlem hattı her alıntıyı kökenine kadar izleyebilir. Bu, modülü kasıtlı olarak belirlenimci bir yapısal çıkarıcı olarak tutar: AST’nin öne sürdüğünü bildirir ve belgenin belirtmediği hiçbir şeyi uydurmayı reddeder.

Tasarım arka planı: Tahmin etmeyi reddeden bir API.

Davranış sözleşmesi

• Girdi. Bir NextPDF\Ast\AstDocument. Modül ham PDF baytlarını kabul etmez; AST’yi önce Core AST alt sistemiyle üretin.
• Çıktı. Belge sırasında list<CitedTextBlock> veya list<CitedTableBlock>.
• Güven, geçişlidir. AST düğümü özniteliklerinden (veya sabit bir varsayılandan) okunur. Bu modül güveni hesaplamaz veya iyileştirmez.
• Anlamsal işleme yok. Çıkarıcı hiçbir gömme, vektör benzerliği, sıralama veya belge anlama gerçekleştirmez. Çıktı sıralaması, alaka sıralaması değil, belge sırasıdır.
• Belirlenimcilik. Aynı bir AST için üretilen bloklar, çapalar ve parça dizinleri kararlıdır.

Genel API yüzeyi

Tür	Çeşit	Temel üyeler
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

Kod örneği — Hızlı başlangıç

<?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,
    );
}

Kod örneği — Üretim

<?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;
}

Uç durumlar ve dikkat edilmesi gerekenler

• Etiketsiz veya kötü etiketlenmiş belgeler daha az metin düğümü verir; AST kalitesi, çıkarım kalitesinin üst sınırıdır.
• Sınırlayıcı kutusu olmayan düğümler, sıfır alanlı bir nöbetçi BoundingBox(0,0,0,0) alır — gerçek bir bölge gerekiyorsa bunu width === 0.0 && height === 0.0 aracılığıyla algılayın.
• İç içe tablolar dolaşılmaz; yalnızca en dıştaki Table düğümü yayılır.
• Kısa satırlar, her satırın aynı sütun sayısına sahip olması için yapay sıfır güvenli hücrelerle doldurulur.

Veri yerleşimi ve PII azaltımları

Bu modül, sağlanan AST’nin içerdiği metni işler ve onu bloklar içinde değişmeden döndürür. Hiçbir ağ çağrısı, hiçbir harici depolama ve çıkarılan içeriğin günlüğe kaydedilmesini gerçekleştirmez. PII işleme, maskeleme ve yerleşim denetimleri, üretilen bloklarda çağıranın sorumluluğundadır. Core PII işleme kılavuzuna bakın.

Güvenli telemetri ve günlük temizleme

Çıkarıcı hiçbir telemetri yaymaz ve çıkarılan metni günlüğe kaydetmez. Bir çağıran onu günlükle sararsa, günlükleri yaymadan önce text, metadata ve herhangi bir hücre içeriğini temizleyin.

Performans

Çıkarım, düğüm sayısında doğrusal tek bir ağaç dolaşımıdır. Parça bölme, metin uzunluğuyla orantılı çalışma ekler. Bkz. performance_budget.

Güvenlik notları

Girdi, önceden ayrıştırılmış bir AST’dir; bu nedenle bu modül husumetli PDF baytlarını kendisi ayrıştırmaz. Çıkarılan metni güvenilmeyen olarak değerlendirin ve hedefi için kaçışlayın.

Uygunluk

İddia	Standart maddesi	Durum
Mantıksal yapı düğümü dolaşımı	ISO 32000-2:2020 §14.7	Doğrulandı (birim paketi, etiketli AST)
Tablo satırı/hücresi çıkarımı	ISO 32000-2:2020 §14.8	Doğrulandı (birim paketi)
Anlamsal arama / gömmeler	—	Desteklenmiyor (kapsam dışı)

Core geri dönüşü / alternatifi

Core AST alt sistemi, burada tüketilen AstDocument öğesini üretir; alıntı bloğu çıkarımının kendisi için hiçbir Core eşdeğeri yoktur. Bkz. /modules/core/ast/.

Enterprise sınır notu

Bu modül yalnızca bir yapısal çıkarıcıdır. Hiçbir anlamsal arama, vektör gömme, benzerlik sıralaması veya belge zekâsı gerçekleştirmez. Bu yetenekler bu modülün parçası değildir ve onun tarafından ima edilmez.

Yayın sınırı

Bu sayfa yalnızca dışarıdan gözlemlenebilen davranışı ve desteklenen genel API yüzeyini açıklar. İç ad alanı yolları, yardımcı sınıflar, mekanizma tabloları, runbook dosya adları ve bilet önekleri kapsam dışıdır.

Ayrıca bkz.

• Extraction başvurusu
• Classifier
• Diff
• Core AST