Bir OCR çağrısını durdurmak için TerminateThread bariz yol gibi görünür; taramalı bir sayfada UI'nin beklemeye razı olduğundan uzun süre uğraşıyordur bu çağrı. Windows dokümantasyonu neden olmadığını açıklar: hedef thread process heap kilidini tutuyorsa o kilit hiç serbest bırakılmaz ve başka bir thread'deki sıradaki ayırma sonsuza kadar bloke olabilir. OCR bir kez kendi process'inizin içinde çalışmaya başlayınca tek güvenli duruş işbirlikçi olandır, inference aşamaları arasındaki checkpoint'lerde; ONNX modellerini bir kez yükleyip sıcak tutmanın bedeli budur
Delphi ekiplerinin çoğunun önce denediği alternatif bir child process'tir. Sayfa başına bir Python worker her an öldürülebilir, cazibesi bundadır; ama her çağrı bir interpreter başlatır, runtime'ını import eder ve bir piksel okumadan detection ile recognition modellerini yükler. 500 sayfalık bir arşiv işi düşünün: o açılış işi 500 kez döner ve deployment, native bir executable'ın yanına oturmuş bir Python ortamı içerir
Taramalardan HPDFCreateRapidOCRDLLOCREngine ile aranabilir PDF
HotPDF, RapidOCR'ı HPDFRapidOCRRecognition unit'inde tanımlı HPDFCreateRapidOCRDLLOCREngine üzerinden süreç içinde çalıştırır. Factory, HotPDFRapidOCR.dll yükler, ONNX detection, isteğe bağlı angle classification ve recognition modellerini bir kez ilklendirir ve bir IHPDFOCREngine döndürür. O engine, diğer OCR engine'leri gibi tam olarak THotPDF.ApplyLoadedOCRTextLayer'a takılır: belge her sayfayı render eder, DLL CPU inference'ını çalıştırır ve sonuç görünmez bir Unicode metin katmanı olarak commit edilir. Ne Python ne child process. Adaptör, Delphi, C++Builder ve Windows FPC/Lazarus build'leriyle gelir
Doğrulama factory'de, hiçbir sayfaya dokunulmadan yapılır. Her model ve sözlük dosyası çözümlenebilmeli, HPDFRapidOCRAbiVersion 1 döndürmeli ve gerekli export'lar, HPDFRapidOCRCreate modelleri kurmadan önce var olmalı. Konfigürasyon hataları EArgumentException fırlatır; yüklenmeyi reddeden bir model, DLL'in kendi tanısıyla EInvalidOperation fırlatır — recognition modeliyle uyuşmayan bir sözlük gibi
uses
SysUtils, HPDFTypes, HPDFDoc, HPDFRapidOCRRecognition;
procedure MakeSearchable(const SourceFile, TargetFile: string);
var
Doc: THotPDF;
Engine: IHPDFOCREngine;
Options: THPDFOCRTextLayerOptions;
Info: THPDFOCRTextLayerInfo;
begin
// Modeller burada yüklenir, herhangi bir recognition deadline'ı dışında.
// THPDFRapidOCRDLLOptions.Default içindeki göreli adlar model dizinine
// göre çözülür
Engine := HPDFCreateRapidOCRDLLOCREngine(
'C:\OCR\Win64\HotPDFRapidOCR.dll', 'C:\OCR\models');
Doc := THotPDF.Create(nil);
try
Doc.AutoLaunch := False;
if Doc.LoadFromFile(SourceFile) < 1 then
raise Exception.Create('Cannot load ' + SourceFile);
Options := THPDFOCRTextLayerOptions.Default; // 300 DPI, MinimumConfidence 0.5
// boş sayfa listesi = her sayfa; SkipPagesWithText varsayılan olarak True
if not Doc.ApplyLoadedOCRTextLayer([], Engine, Options, Info) then
raise Exception.Create(string(Info.Diagnostic));
Writeln(string(Info.EngineName), ': ', Info.AcceptedWordCount,
' lines accepted, ', Info.DroppedWordCount, ' dropped');
Doc.SaveLoadedDocument(TargetFile);
finally
Doc.Free;
end;
end;
THPDFRapidOCRDLLOptions.Default; ch_PP-OCRv3_det_infer.onnx, ch_PP-OCRv3_rec_infer.onnx, ch_ppocr_mobile_v2.0_cls_infer.onnx ve ppocr_keys_v1.txt adlarını, tek CPU thread, 16.777.216 piksel input sınırı ve recognition çağrısı başına 60.000 ms deadline ile taşır. Diğer yazı sistemleri için THPDFRapidOCRDLLOptions.ForLanguage o varsayılanları korur ve dokuz profilden birine, Geleneksel Çince ve Kiril'den Arapça ile Devanagari'ye, <profile>/recognition.onnx artı <profile>/dictionary.txt takar. Her engine tek dil okur; profili sayfa başına ya da belge başına seçin. Model ile sözlüğün neden daima çift olarak gezdiği HotPDF'de RapidOCR çok dilli modeller ve CTC sözlükleri yazısında
Engine, kendini Info.EngineName içinde RapidOCR (native DLL) olarak bildirir. O string'i loglayın. Aynı servis harici Tesseract OCR process adaptörünü ya da yerleşik şablon eşlemeli OCR engine'ini de çalıştırıyorsa, kötü bir sayfayı hangi tanıyıcının ürettiğini anlamanın en hızlı yolu budur
C ABI'si neden yalnızca int32_t ve UTF-8 baytları konuşur?
HotPDFRapidOCR.dll sınırı sabit genişlikte tamsayılar, ham pointer'lar ve açık bayt uzunlukları kullanır; çünkü Delphi, C++Builder ve Free Pascal, MSVC ile C çağrı kuralının ötesinde hiçbir şey paylaşmaz. Bir std::string, bir std::vector veya C++ istisnası, tek bir derleyiciye ve tek bir runtime kütüphanesine ait bir bellek düzeni ile bir unwinding modeli taşır; bunlardan herhangi birinin Pascal koduna geçmesine izin vermek bozuk bir stack'te ya da yanlış ayırıcı tarafından serbest bırakılmış bir heap bloğunda biter
ABI sürüm 1 kısa bir kural listesidir. Her export cdecl'dir ve bir int32_t durum döndürür: başarı için 1, başarısızlık için 0. Başarısız olabilen her fonksiyon, çağıranın malı bir teşhis tamponu ve bayt cinsinden boyutunu alır; DLL, sığacak biçimde kırpılmış NUL ile biten bir UTF-8 mesaj yazar. DLL'in içinde her export gövdesi, hem catch (const std::exception &) hem catch (...) içeren bir try'a sarılır. Bir ONNX Runtime hatası, bir OpenCV assertion'ı veya bozuk bir sözlük, durum 0 artı metne dönüşür
| Export | Görev | Adaptör ne zaman çözer |
|---|---|---|
HPDFRapidOCRAbiVersion | 1 döndürür; başka her değer reddedilir | DLL yüklendikten hemen sonra |
HPDFRapidOCRCreate | Detection, isteğe bağlı classification, recognition modellerini ve sözlüğü yükler | Factory'de |
HPDFRapidOCRRecognize | Bir bitmap çalıştırır, metin satırı başına bir callback üretir | Factory'de |
HPDFRapidOCRDestroy | Model örneğini serbest bırakır | Factory'de |
HPDFRapidOCRSetReadingDirection | İsteğe bağlı sağdan sola satır sırası | Yalnızca RightToLeft set edildiğinde |
Okuma yönü export'u kasıtlı olarak tembel çözülür; böylece o export olmadan derlenmiş bir DLL, soldan sağa her isteğe hizmet etmeye devam eder. Adaptör kütüphaneyi LoadLibraryEx ile, DLL'in kendi klasörünü ve varsayılan güvenli dizinleri kapsayan arama bayraklarıyla yükler; HotPDFRapidOCR.dll'in yanına konan ONNX Runtime veya OpenCV bağımlılıkları, PATH düzenlemeden bulunur. Model ve sözlük yolları UTF-8 olarak sınırı geçer ve DLL dosyaları wide-character API'lerle açmadan önce onları strict modda MultiByteToWideChar ile çevirir. C:\Users\Łukasz altında bir model dizini ya da Kiril bir kullanıcı adı normal açılır
Tek bir kural header'da değil build dosyalarında yaşar. DLL, ONNX Runtime ile OpenCV'yi statik bağlar ve CMake projesi statik release CRT'yi (/MT) varsayar. /MD ile derlenmiş statik kütüphaneleri karıştırırsanız şanslıysanız link hatası alırsınız, değilseniz iki bağımsız heap alırsınız. DLL ile aynı CRT modunda derlenmiş kütüphaneleri sağlayın
Bir TBitmap ile bir metin satırı arasında ne olur?
HotPDF, DLL'e render edilmiş sayfanın bağımsız, üstten alta bir BGR kopyasını verir; DLL de tanınan her satır için bir callback ile karşılık verir. O callback'teki metin ödünçtir: pointer yalnızca callback dönene kadar geçerlidir, adaptör bu yüzden onu yerinde kopyalar
Delphi'de anlık görüntü, pf24bit'e zorlanmış özel bir TBitmap'ten ve negatif biHeight ile GetDIBits üzerinden gelir; bu, dört bayta hizalanmış üstten alta satırlar verir ve stride, açık bir argüman olarak DLL'e gider. FPC'de adaptör CreateIntfImage üzerinden okur. Çağıranın bitmap'i asla değiştirilmez. Boyut kontrolleri kopya ayrılmadan önce çalışır: kenar başına en fazla 32.767 piksel ve toplamda MaxPixels'i aşmayan; o da varsayılanı 16.777.216 olup 67.108.864'e yükseltilebilir
DLL'in içinde görüntü 50 piksellik beyaz bir kenarlık alır, metin bölgeleri uzun kenarı en fazla 1.024 piksele ölçeklenmiş biçimde tespit edilir ve kutular yatay satırlara dizilir. Angle classifier açıkken bir kırpma yalnızca ters yüz puanı 0,9'u aşarsa 180 derece döndürülür; bu, zayıf bir tahminin kısa kelimeleri çevirmesini önler. Her satır sonra bir const char*, bir bayt sayısı, orijinal görüntü piksellerinde bir integer kutu ve ortalama karakter confidence'ı olarak gelir. Adaptör kabul ettiği şeyde katıdır:
- UTF-8,
MB_ERR_INVALID_CHARSile decode edilir; böylece bozuk bir bayt dizisi sayfayı düşürür, aranabilir bir katmana replacement karakterleri ekmez - C0 ve C1 kontrol karakterleri reddedilir; yalnızca boşluktan oluşan satırlar atlanır
- Kutu bitmap'in içinde bulunmalı ve confidence, 0 ile 1 arasında sonlu bir değer olmalı
- Metin, isteğin
MaxTextCodeUnitsine karşı sayılır; çağrı başına sert tavan 1.048.576 UTF-16 unit'tir ve Basic Multilingual Plane dışındaki karakterler iki unit'e mal olur - Callback içindeki bir Pascal istisnası orada yakalanır, saklanır ve 0 döndürüşüne çevrilir; bu DLL'i durdurur, saklanan mesaj
Info.Diagnosticolur
Bu ayrıntılardan ikisi çıktıyı ayarlarken önem taşır. Birim satırdır, kelime değil: her satır bir MaxWords slotu alır, Info.AcceptedWordCount ile Info.DroppedWordCount satır sayar ve bir arama isabeti bütün satır kutusunu vurgular. Ve MinimumConfidence, satırın ortalama karakter confidence'ı ile karşılaştırılır; yirmi temiz karakterin arasındaki tek lekeli karakter satırı pek batırmaz. Eşiği 0,7'ye ya da 0,8'e yükseltmek tek karakterleri değil bütün satırları düşürür. Boş bir sayfa sıfır satırla başarı döndürür ve herhangi bir başarısızlık kısmi sonuçları atar; çok sayfalı commit böylece ya hep ya hiç kalır
Tek engine, tek model kopyası, bir seferde tek çağıran
Her RapidOCR DLL engine'i, tüm ömrü boyunca tam olarak bir model örneğine sahiptir ve o engine üzerindeki Recognize çağrıları bir critical section ile serileştirilir. Modelleri bellekte tutan şey IHPDFOCREngine referansını elinde tutmaktır; toplu iş bu yüzden engine'i bir kez oluşturup her belgede yeniden kullanmalı
procedure OcrBatch(const Files: TStrings; const OutputDir: string);
var
Models: THPDFRapidOCRDLLOptions;
Engine: IHPDFOCREngine;
Doc: THotPDF;
Options: THPDFOCRTextLayerOptions;
Info: THPDFOCRTextLayerInfo;
I: Integer;
begin
Models := THPDFRapidOCRDLLOptions.ForLanguage('ru-RU');
Models.UseAngleClassifier := False; // dik taramalar: classifier modeli yüklenmez
Models.Threads := 4; // 1..64, aktif işlemci sayısına kırpılır
Models.TimeoutMilliseconds := 120000; // Recognize çağrısı başına, işbirlikçi
Engine := HPDFCreateRapidOCRDLLOCREngine(
'C:\OCR\Win64\HotPDFRapidOCR.dll', 'C:\OCR\models', Models);
Options := THPDFOCRTextLayerOptions.Default;
for I := 0 to Files.Count - 1 do
begin
Doc := THotPDF.Create(nil);
try
Doc.AutoLaunch := False;
if (Doc.LoadFromFile(Files[I]) > 0) and
Doc.ApplyLoadedOCRTextLayer([], Engine, Options, Info) then
Doc.SaveLoadedDocument(IncludeTrailingPathDelimiter(OutputDir) +
ExtractFileName(Files[I]))
else
Writeln(Files[I], ': ', string(Info.Diagnostic));
finally
Doc.Free;
end;
end;
end; // son referans serbest bırakılır: modeller yok edilir, sonra DLL unload edilir
Threads, engine'deki her ONNX session'ının hem intra-op hem inter-op thread sayısını set eder ve DLL bunu aktif işlemci sayısına kırpılır. Bir engine'i paylaşan iki thread inference'ı asla paralel koşturmaz; ikincisi bekler. O bekleyiş kör bir EnterCriticalSection değildir. Adaptör kilidi TryEnterCriticalSection ile dener, denemeler arasında 25 ms uyur ve her denemede cancellation token ile deadline'ı kontrol eder; böylece kuyruktaki bir istek yine de iptal edilebilir
Deadline saati, kilit alınmadan Recognize'a girildiğinde başlar. Başka bir sayfanın arkasında kuyrukta geçen süre, TimeoutMilliseconds'e yazılır. Tek engine üzerinde dört worker thread ve 60 saniyelik deadline ile dördüncü sayfa modele hiç ulaşmadan zaman aşımına uğrayabilir. Bunun yerine her worker'a kendi engine'ini verin. Bedeli, engine başına bellekte bir model kopyasıdır; o bellek öngörülebilir timeout'lar ve gerçek paralellik satın alır. Tek engine paylaşmak yalnızca istekler neredeyse hiç kuyruk oluşmayacak kadar seyrekse mantıklıdır
Native bir OCR çağrısı inference ortasında neden öldürülemez?
Native bir RapidOCR çağrısı inference ortasında öldürülemez; çağrı sizin thread'inizde, sizin process'inizde, çalışan bir Run için kesinti API'si bulunmayan bir ONNX Runtime session'ının ortasında koşar. DLL adaptöründe iptal işbirlikçidir. DLL, detection öncesi ve sonrası, her kırpmanın classification'ı sonrası ve tanınan her satırdan sonra bir abort callback çağırır ve callback 0 döndürdüğü ilk checkpoint'te durur. Başlamış tek bir Run önce bitmek zorundadır
Zorlamalı seçenekler beklemekten daha kötüdür. TerminateThread, CRT heap kilidini, ONNX Runtime'ın thread havuzunu ve herhangi bir OpenCV durumunu tam da o an bulundukları koşulda bırakır. Çağrı hâlâ yürürken FreeLibrary çağırmak, stack üzerindeki kodu bellekten düşürür. İkisi de güvenli hâle getirilemez; bu yüzden adaptör hiçbir zaman denemez. Dolan bir deadline otlsEngineError olarak zaman aşımı tanısıyla geri gelir; iptal edilen token otlsCancelled olarak:
// Token çağıran tarafından oluşturulur ve UI thread'iyle paylaşılır;
// kullanıcı Stop'a bastığında UI, Token.Cancel çağırır
function OcrWithStop(Doc: THotPDF; const Engine: IHPDFOCREngine;
Token: THPDFCancellationToken): Boolean;
var
Options: THPDFOCRTextLayerOptions;
Info: THPDFOCRTextLayerInfo;
begin
Options := THPDFOCRTextLayerOptions.Default;
Options.CancellationToken := Token;
Result := Doc.ApplyLoadedOCRTextLayer([], Engine, Options, Info);
if not Result then
case Info.Status of
otlsCancelled:
// bir sonraki aşama ya da satır checkpoint'inde durdu; belge değişmedi
Writeln('Cancelled');
otlsEngineError:
// işbirlikçi bir deadline dolmasını ve native tanıları içerir
Writeln('Engine: ', string(Info.Diagnostic));
otlsBudgetExceeded:
// Options'taki bir sayfa, piksel, kelime veya içerik limitine ulaşıldı
Writeln('Budget: ', string(Info.Diagnostic));
else
Writeln(string(Info.Diagnostic));
end;
end;
Process adaptörleri ile süreç içi DLL arasındaki gerçek takas budur ve hiçbir taraf her satırı kazanmaz:
- Açılış maliyeti: Tesseract ve Python RapidOCR adaptörleri her sayfa için bir process başlatır ve modelleri yükler; DLL modelleri engine başına bir kez yükler
- Durdurma: child process doğrudan sonlandırılabilir ve Python worker, kapanışta öldüren bir Job Object içinde koşar, bütün process ağacı onunla gider; DLL aşama ve satır checkpoint'lerinde durur
- Hata sınırlama:
tesseract.exeiçindeki bir çökme tek sayfayı düşürür; DLL'in içindeki bir access violation process'inizi götürür - Dağıtım: process adaptörleri kurulu bir program ya da Python ortamı ister; DLL kendisini, modellerini ve sözlüğünü, uygulamanın bit genişliğiyle eşleşmiş biçimde ister
- Bellek: process adaptörü child çıkarken her şeyi serbest bırakır; DLL engine'i, son interface referansı gidene kadar modellerini bellekte tutar
Sayfayı tek tek OCR eden, bir inference aşaması içinde dönen duyarlı bir Stop düğmesi isteyen etkileşimli masaüstü uygulaması için DLL'i seçin. Gündüz gece güvenilmeyen taramaları yutan bir sunucu için sayfa başına açılış maliyetini ödeyin ve process sınırını koruyun; bir tanıyıcıyı çökerten hazırlanmış bir görüntü tek sayfaya mal olmalı ve child process ile mal olur
HotPDFRapidOCR.dll'i derlemek ve model seçmek
HotPDFRapidOCR.dll, Native/RapidOCR altındaki C++ kaynaklarından MSVC, C++17, bir Windows SDK ve CMake 3.20 veya üstüyle derlenir. tools/Build-HotPDFRapidOCR.ps1 yardımcısı native kaynak, ONNX Runtime ve OpenCV dizinlerini artı -Platform Win32 ya da Win64 alır ve sonucu Lib/Native/RapidOCR/<Platform>/ altına yazar. İkisini de dağıtıyorsanız ikisini de derleyin. 32 bitlik bir Delphi uygulaması 64 bitlik bir DLL yükleyemez ve sağladığınız statik kütüphaneler hedef mimariye olduğu kadar CRT moduna da uymalı
Modellerin kendi uyumluluk kuralları vardır. Detector bir DB text detector'dır. Recognizer, NCHW düzeninde ve sabit input yüksekliği 32 ya da 48 olan CTC modellerini kabul eder; model dinamik yükseklik bildirirse 48 kullanır. Model formatı, statik bağlı ONNX Runtime'ın anladığı biçimlerden biri olmalı; PP-OCRv5 gibi daha yeni export'lar daha yeni bir runtime isteyebilir ve okunamayan bir model, tanıyla initialization'da başarısız olur. tools/Install-RapidOCRModels.ps1, sabitlenmiş SHA256 hash'lere karşı doğrulanmış PP-OCRv3 ve PP-OCRv4 paketlerini, Default'un beklediği dosya adları altında paylaşılan detector ve classifier ile kurar. Runtime derlemesinin kontrolü de sizde değilse o paketlerde kalın
Sözlük, BOM'suz UTF-8 olmalı, tam olarak modelin karakter sırasını taşımalı ve girdi sayısı modelin çıktı sınıflarına eşit olmalı. CRLF satır sonları sorun değil. Model kendi karakter listesini metadata'ya gömüyorsa, model initialization'ı her girdiyi ve konumunu sözlük dosyasıyla karşılaştırır; yalnızca doğru uzunlukta bir sözlük yine de başarısız olur. DLL eksik bir modeli asla indirmiyor
HotPDF, native RapidOCR adaptörünü process tabanlı OCR adaptörleriyle, onları besleyen sayfa renderer'ıyla ve görünmez Unicode metin katmanı yazıcıyla, Delphi ve C++Builder için tek bir native VCL component'inin içinde paketler. Python kurulu olmayan makinelerde aranabilir PDF üretmek zorunda olan capture ve arşiv yazılımı için HotPDF Delphi PDF component ile dağıtılacak yalnızca DLL ve model dosyaları kalır