Teknik Makale

HotPDF in-process RapidOCR: Delphi'de native DLL OCR

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

HPDFCreateRapidOCRDLLOCREngine için HotPDF RapidOCR DLL fabrika doğrulama dizisi: yollar ile model dosyaları var olmalı, HPDFRapidOCRAbiVersion 1 döndürmeli, zorunlu exportlar çözülmeli ve HPDFRapidOCRCreate modelleri başlatmalı; hiçbir tanıma koşmadan EArgumentException ya da EInvalidOperation istekli fırlatılır, ikincisi native teşhis metnini taşır
doğrulama kasıtlı olarak isteklidir: yapılandırma sorunları herhangi bir model başlamadan fırlatır; böylece kötü bir yol ya da ABI hiçbir zaman tanıma son teslimine ulaşmaz
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

ExportGörevAdaptör ne zaman çözer
HPDFRapidOCRAbiVersion1 döndürür; başka her değer reddedilirDLL yüklendikten hemen sonra
HPDFRapidOCRCreateDetection, isteğe bağlı classification, recognition modellerini ve sözlüğü yüklerFactory'de
HPDFRapidOCRRecognizeBir bitmap çalıştırır, metin satırı başına bir callback üretirFactory'de
HPDFRapidOCRDestroyModel örneğini serbest bırakırFactory'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

Bitmap'ten metin katmanına HotPDF RapidOCR DLL hattı: adaptör sayfayı üstten alta pf24bit BGR olarak anlık görüntüler; DLL pad eder, bölgeleri saptar, crop'ları sıralar ve tanır, satır başına ödünç UTF-8 metin, kutu ve güven taşıyan bir callback teslim eder ve adaptör metin katmanı işleminden önce her satırı doğrular
pixel'ler ABI'yi bir anlık görüntü olarak bir kez geçer, satırlar birer callback olarak geri döner ve her denetim geçmeden aranabilir katmana hiçbir şey ulaşmaz

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_CHARS ile 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.Diagnostic olur

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:

HotPDF OCR adaptör takasları: süreç adaptörleri her sayfada bir işçi başlatır ve modelleri yükler ama öldürülebilir ve çökmeleri içerir; süreç içi RapidOCR DLL'i modelleri bir kez yükler, yalnızca işbirlikçi kontrol noktalarında durur, adres uzayını paylaşır ve modelleriyle sözlüğüyle bir DLL olarak dağıtılır
iş yüküne göre seçin: sayfa başına çalışan bir masaüstü uygulaması sıcak DLL'den kazanır, güvenilmeyen taramaları yutan bir sunucu süreç duvarının bedelini ödemelidir
  • 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.exe iç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