Pro sürüm

Extraction — Derinlemesine başvuru

Bir bakışta

Bu sayfa, NextPDF\Pro\Extraction için sözleşme düzeyinde başvurudur. Modül beş genel simge içerir: iki çıkarıcı (CitedTextExtractor, CitedTableExtractor) ve üç değiştirilemez değer nesnesi (CitedTextBlock, CitedTableBlock, CitedTableCell). Her iki çıkarıcı da ayrıştırılmış bir NextPDF\Ast\AstDocument tüketir; hiçbiri ham PDF baytlarını okumaz. Çıkarma belirlenimci ve yapısaldır. Bu modülün hiçbir yerinde anlamsal, gömme veya sıralama adımı yoktur. Göreve yönelik görünüm yetenek sayfasında bulunur.

Kullanılabilirlik ve lisanslama

Bu yetenek NextPDF Pro (nextpdf/pro) ile birlikte gelir ve Pro katmanı lisans zarfıyla etkinleşir. Bu yetkilendirmeye sahip olmayan bir dağıtım, yeteneğin sınıflarını yüklemez. Sürümleri karşılaştırın ve bir lisans edinin.

Hiçbir çalışma zamanı yetenek bayrağı bu modülü kapılamaz. Sınıflar, nextpdf/pro yüklü ve lisanslı olduğunda kullanılabilir.

Genel API yüzeyi

Simge	Parametreler	Varsayılan davranış	Döndürür	Şununla fırlatır veya başarısız olur	Notlar
`CitedTextExtractor::__construct()`	`?int $maxTokensPerChunk = null`, `int $minChunkLength = 10`	Belirteç bütçesi yok; 10 bayttan kısa kırpılmış metin atılır	`CitedTextExtractor`	Fırlatmaz	`null` bütçe, düğüm başına bir blok demektir.
`CitedTextExtractor::extract()`	`AstDocument $document`	Derinlik öncelikli gezinti; uygun her metin düğümü başına bir blok, belirteç bütçesine göre bölünür	`list<CitedTextBlock>`	Fırlatmaz	Belirlenimci; `chunkIndex` her çağrıda 0’a sıfırlanır.
`CitedTextBlock`	beş salt okunur alan	Değiştirilemez değer nesnesi; hiçbir serileştirici yöntemi yok	—	Fırlatmaz	`metadata` anahtarları: `nodeType`, `pageIndex`, ayrıca isteğe bağlı `structType`, `lang`, `alt`, `untagged`.
`CitedTextBlock::estimatedTokens()`	yok	`ceil(byte length / 4)`	`int`	Fırlatmaz	Bütçe buluşsalı; belirteçleyici değil.
`CitedTableExtractor::extract()`	`AstDocument $document`	Belge sırasına göre en dıştaki `Table` düğümlerini toplar	`list<CitedTableBlock>`	Fırlatmaz	Bir tablo alt ağacına asla inmez.
`CitedTableBlock`	beş salt okunur alan	Değiştirilemez dikdörtgen, satır öncelikli hücre matrisi	—	Fırlatmaz	Kısa satırlar çıkarma sırasında sağdan doldurulur.
`CitedTableBlock::toArray()`	yok	snake_case düz diziye serileştirir	`array<string, mixed>`	Fırlatmaz	İç içe hücreler `CitedTableCell::toArray()` aracılığıyla serileştirilir.
`CitedTableCell`	yedi salt okunur alan	Atıf koordinatları içeren değiştirilemez hücre kaydı	—	Fırlatmaz	Dolgu hücreleri boş bir `nodeId` ve 0.0 güven taşır.
`CitedTableCell::toArray()`	yok	snake_case düz diziye serileştirir; `bbox` iç içe geçer veya `null` olur	`array<string, mixed>`	Fırlatmaz	—

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

Davranış sözleşmesi

Düğüm seçimi. CitedTextExtractor, türü Paragraph, Heading, ListItem, TableCell, Code veya Annotation olan düğümler için blok yayımlar. Metni null olan bir düğüm atlanır. Bir düğüm yalnızca kırpılmış metin uzunluğu en az minChunkLength (varsayılan 10) olduğunda yayımlanır. Tüm uzunluklar bayt uzunluğudur.
Gezinti sırası. Gezinti, belge kökünden derinlik önceliklidir. Uygun bir düğüm, alt öğeleri ziyaret edilmeden önce yayımlanır. chunkIndex, tüm belge gezintisi boyunca artar ve her extract() çağrısında 0’a sıfırlanır.
Parçalama. maxTokensPerChunk ayarlanmadığında, her düğüm bir blok verir. Ayarlandığında, maxTokensPerChunk * 4 bayttan uzun metin bölünür. Bölücü, tercih edilen kesimden en fazla 200 bayt geriye doğru tarayarak bulunan bir cümle sınırını — bir satır sonu veya bir boşluğun izlediği bir nokta — tercih eder. Aksi hâlde bütçede sert biçimde bölünür. Bir kesimden sonraki boşluklar atlanır; boş parçalar atılır.
Atıf bağlantısı. Her bloğun CitationAnchor öğesi düğüm kimliğini, sayfa dizinini, bir sınırlayıcı kutuyu, bir güven değerini ve null bir içerik karmasını taşır. Sınırlayıcı kutusu olmayan düğümler, paylaşılan sıfır alanlı bir nöbetçi olan BoundingBox(0, 0, 0, 0) alır; böylece bağlantı her zaman yapısal olarak geçerlidir.
Metin güveni. Güven, düğümün confidence özniteliğini bir int veya float olduğunda okur; varsayılan 1.0’dır. Sayısal olmayan öznitelik değerleri varsayılana geri döner.
Blok meta verisi. metadata her zaman nodeType ve pageIndex taşır. structType, lang ve alt, düğümde mevcut olduklarında kopyalanır. untagged, düğüm bir untagged özniteliği taşıdığında true olarak ayarlanır.
Tablo seçimi. CitedTableExtractor, yalnızca en dıştaki Table düğümlerini belge sırasına göre toplar. Bir Table düğümü işlendikten sonra alt ağacı yeniden incelenmez; iç içe tablolar desteklenmez.
Matris şekli. Satırlar TableRow alt öğelerinden; hücreler onların TableCell alt öğelerinden gelir. Diğer alt öğe türleri yok sayılır. colCount, tüm satırlardaki en yüksek hücre sayısıdır. Kısa satırlar, sentetik hücrelerle colCount’a kadar sağdan doldurulur: boş nodeId, null metin, null bbox, tablonun sayfa dizini, 0.0 güven. Satırı veya sütunu olmayan bir tablo hiçbir blok üretmez.
Hücre güveni. Gerçek bir hücrenin güveni, confidence özniteliğini bir int veya float olduğunda okur; varsayılan 0.8’dir. Metin blokları varsayılan olarak 1.0; tablo hücreleri varsayılan olarak 0.8’dir.
Yapı eşlemesi. Gezilen hiyerarşi, PDF mantıksal yapı modeliyle eşleşir (ISO 32000-2:2020 §14.7). Tablo satırları, kaynak etiketlendiğinde TR yapı öğesiyle (§14.8) eşleşir.

Uç durumlar ve hata modları

Bu yüzeyde hiçbir şey fırlatmaz. Her iki extract() yöntemi de uygun düğümü olmayan bir belge için boş bir liste döndürür.
Sıfır alanlı sınırlayıcı kutu, paylaşılan tekil bir nöbetçidir. Gerçek bir bölgeye ihtiyaç duyan çağıranların bunu açıkça algılaması gerekir: width === 0.0 && height === 0.0.
Tüm uzunluk kontrolleri ve bölmeler bayt tabanlıdır. 200 baytlık pencere içinde hiçbir cümle sınırı yoksa, sert bir kesim çok baytlı bir UTF-8 dizisinin içine düşebilir.
Belirteç başına 4 bayt rakamı yalnızca bütçeleme için bir buluşsal yöntemdir. Bir belirteçleyici değildir ve belirli bir modelin belirteçlemesiyle eşleşmez. estimatedTokens() aynı buluşsal yöntemi kullanır.
confidence özniteliğindeki sayısal bir dize zorlanmaz; varsayılan geçerlidir. Yalnızca int ve float değerleri dikkate alınır.
Bir kesimden sonra boşluk atlama yalnızca düz boşlukları kaldırır. Bir parça başındaki sekmeler ve satır sonları korunur.
TableCell metni tasarımı gereği iki kez çıkarılır: CitedTextExtractor tarafından metin blokları olarak ve CitedTableExtractor tarafından matrislerin içinde. Her iki çıkarıcıyı tek bir belge üzerinde çalıştırırken alt akışta yinelenenleri kaldırın.
Dolgu hücreleri, boş bir nodeId ve 0.0 güven ile tanınabilir. Gerçek ama boş bir hücre, boş olmayan nodeId değerini korur.
Bu modülde hiçbir kriptografik işlem gerçekleşmez, bu nedenle FIPS moduna özgü bir davranış yoktur.

Uygunluk

Kaynak belge etiketlendiğinde, AST, ISO 32000-2:2020 §14.7 mantıksal yapı hiyerarşisini yansıtır ve Table/TableRow düğümleri §14.8 Table/TR yapı öğelerine karşılık gelir. Çıkarma kalitesi etiketleme kalitesiyle sınırlıdır; etiketlenmemiş içerik daha az veya daha kaba düğümler üretir.

Bunlar yapısal hizalama ifadeleridir, uygunluk testi sonuçları değildir. NextPDF hiçbir sertifikaya sahip değildir ve hiçbirini vermez. Bu modül kendi başına hiçbir uygunluk iddiasında bulunmaz; Core AST alt sisteminin ürettiği yapıyı ne olursa olsun tüketir.

Geliştirme notları

Tek bir CitedTextExtractor örneğini belgeler arasında yeniden kullanmak sıralı olarak güvenlidir; extract(), her gezinti öncesinde chunkIndex değerini sıfırlar.
Gürültü düğümlerini (sayfa numaraları, başıboş glif dizileri) parçalamadan önce, sonrasında değil, filtrelemek için minChunkLength değerini ayarlayın.
CJK ve diğer çok baytlı betikler için bayt tabanlı buluşsal yöntem belirteçleri fazla sayar; maxTokensPerChunk değerini buna göre boyutlandırın.
CitedTableBlock::toArray() ve CitedTableCell::toArray(), JSON iş hatları için snake_case anahtarlar üretir. CitedTextBlock bir serileştiriciye sahip değildir; alanlarını kendiniz kodlayın.
CitationAnchor öğesinin contentHash alanı bu yüzeyde her zaman null’dır. İş hattı gerektiğinde içerik karmalarını alt akışta hesaplayın.

Yayın sınırı

Bu sayfa yalnızca dışarıdan gözlemlenebilir davranışı ve desteklenen genel API yüzeyini belgeler. Dahili ad alanı yolları, yardımcı sınıflar, mekanizma tabloları, çalışma kılavuzu dosya adları ve bilet önekleri kapsam dışıdır.