Artykuł techniczny

HotPDF: RapidOCR w procesie, OCR z natywnej DLL w Delphi

TerminateThread wygląda jak oczywisty sposób na zatrzymanie wywołania OCR, które mieli jedną zeskanowaną stronę dłużej, niż UI jest gotów czekać. Dokumentacja Windows wyjaśnia, dlaczego to nie to: jeśli wątek docelowy trzyma lock sterty procesu, ten lock nigdy nie zostaje zwolniony, a następna alokacja na dowolnym innym wątku może zablokować się na zawsze. Skoro OCR działa w Twoim własnym procesie, jedynym bezpiecznym stopem jest kooperatywny, na punktach kontrolnych między etapami inferencji — i to jest cena za załadowanie modeli ONNX raz i utrzymanie ich ciepłymi

Alternatywa, którą większość zespołów Delphi próbuje najpierw, to proces potomny. Pythonowy worker na stronę można zabić w dowolnej chwili, co kusi, ale każde wywołanie startuje interpreter, importuje runtime i ładuje modele detekcji oraz rozpoznawania, zanim przeczyta pierwszy piksel. Załóżmy archiwizację 500 stron: ta praca startowa wykonuje się 500 razy, a deployment obejmuje teraz środowisko Python siedzące obok natywnego pliku wykonywalnego

Przeszukiwalny PDF ze skanów przez HPDFCreateRapidOCRDLLOCREngine

HotPDF puszcza RapidOCR w procesie przez HPDFCreateRapidOCRDLLOCREngine, zadeklarowane w jednostce HPDFRapidOCRRecognition. Fabryka ładuje HotPDFRapidOCR.dll, raz inicjalizuje modele detekcji ONNX, opcjonalnej klasyfikacji kąta i rozpoznawania, po czym zwraca IHPDFOCREngine. Ten silnik wpina się w THotPDF.ApplyLoadedOCRTextLayer dokładnie jak pozostałe silniki OCR: dokument renderuje każdą stronę, DLL odpala na niej inferencję na CPU, a wynik zostaje zatwierdzony jako niewidoczna warstwa tekstu Unicode. Bez Pythona, bez procesu potomnego. Adapter jest dostarczany dla buildów Delphi, C++Builder i FPC/Lazarus na Windows

Walidacja dzieje się w fabryce, zanim cokolwiek dotknie stronę. Każdy plik modelu i słownika musi się rozwiązać, HPDFRapidOCRAbiVersion musi zwrócić 1, a wymagane eksporty muszą istnieć, zanim HPDFRapidOCRCreate zbuduje modele. Błędy konfiguracji podnoszą EArgumentException; model, który odmawia załadowania, podnosi EInvalidOperation z własną diagnostyką DLL, na przykład ze słownikiem niepasującym do modelu rozpoznawania

Sekwencja walidacji fabryki DLL RapidOCR w HotPDF dla HPDFCreateRapidOCRDLLOCREngine: ścieżki i pliki modeli muszą istnieć, HPDFRapidOCRAbiVersion musi zwrócić 1, wymagane eksporty muszą się rozwiązać, a HPDFRapidOCRCreate musi zainicjalizować modele; EArgumentException albo EInvalidOperation podnoszone z góry, zanim jakiekolwiek rozpoznawanie ruszy, przy czym to drugie niesie natywny tekst diagnostyczny
walidacja jest z góry celowo: problemy konfiguracji podnoszą wyjątek, zanim jakikolwiek model się zainicjalizuje, więc zła ścieżka albo ABI nigdy nie dociera do deadline'u rozpoznawania
uses
  SysUtils, HPDFTypes, HPDFDoc, HPDFRapidOCRRecognition;

procedure MakeSearchable(const SourceFile, TargetFile: string);
var
  Doc: THotPDF;
  Engine: IHPDFOCREngine;
  Options: THPDFOCRTextLayerOptions;
  Info: THPDFOCRTextLayerInfo;
begin
  // Tu ładują się modele, poza każdym deadline'em rozpoznawania.
  // Nazwy względne z THPDFRapidOCRDLLOptions.Default rozwiązują się
  // względem katalogu modeli
  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
    // pusta lista stron = wszystkie strony; SkipPagesWithText domyślnie 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 wymienia ch_PP-OCRv3_det_infer.onnx, ch_PP-OCRv3_rec_infer.onnx, ch_ppocr_mobile_v2.0_cls_infer.onnx i ppocr_keys_v1.txt, z jednym wątkiem CPU, limitem wejścia 16 777 216 pikseli i deadline'em 60 000 ms na wywołanie rozpoznawania. Dla innych pism THPDFRapidOCRDLLOptions.ForLanguage zostawia te domyślne i podmienia <profile>/recognition.onnx plus <profile>/dictionary.txt dla jednego z dziewięciu profilów, od chińskiego tradycyjnego i cyrylicy po arabski i dewanagari. Każdy silnik czyta jeden język; dobierz profil per strona albo per dokument. Czemu model i słownik zawsze podróżują w parze, opisuje artykuł o wielojęzycznych modelach RapidOCR i słownikach CTC w HotPDF

Silnik przedstawia się jako RapidOCR (native DLL) w Info.EngineName. Loguj ten string. Gdy ten sam serwis puszcza też adapter zewnętrznego procesu Tesseract albo wbudowany silnik OCR z dopasowaniem szablonów, to najszybszy sposób, by powiedzieć, który rozpoznawacz wyprodukował złą stronę

Dlaczego ABI C mówi tylko int32_t i bajtami UTF-8?

Granica HotPDFRapidOCR.dll używa integerów o stałej szerokości, surowych wskaźników i jawnych długości w bajtach, bo Delphi, C++Builder i Free Pascal nie dzielą z MSVC niczego poza konwencją wywołań C. std::string, std::vector albo wyjątek C++ niesie układ pamięci i model unwindingu należące do jednego kompilatora i jednej biblioteki runtime, a przepuszczenie czegokolwiek z tego do kodu Pascala kończy się zepsutym stackiem albo blokiem sterty zwolnionym przez niewłaściwy alokator

ABI w wersji 1 to krótka lista reguł. Każdy eksport jest cdecl i zwraca status int32_t: 1 dla sukcesu, 0 dla porażki. Każda funkcja, która może się nie udać, bierze bufor diagnostyczny należący do wołającego i jego rozmiar w bajtach, a DLL zapisuje wiadomość UTF-8 zakończoną NUL, obciętą do rozmiaru. Wewnątrz DLL każde ciało eksportu siedzi w try z i catch (const std::exception &), i catch (...). Błąd ONNX Runtime, asercja OpenCV albo zniekształcony słownik staje się statusem 0 plus tekstem

EksportRolaKiedy adapter go rozwiązuje
HPDFRapidOCRAbiVersionZwraca 1; każda inna wartość jest odrzucanaZaraz po załadowaniu DLL
HPDFRapidOCRCreateŁaduje modele detekcji, opcjonalnej klasyfikacji i rozpoznawania oraz słownikW fabryce
HPDFRapidOCRRecognizePuszcza jedną bitmapę i wysyła jedno wywołanie zwrotne na linię tekstuW fabryce
HPDFRapidOCRDestroyZwalnia instancję modeliW fabryce
HPDFRapidOCRSetReadingDirectionOpcjonalna kolejność wierszy od prawej do lewejTylko gdy ustawiono RightToLeft

Eksport kierunku czytania jest rozwiązywany leniwie celowo, więc DLL zbudowana bez niego nadal obsługuje każde żądanie od lewej do prawej. Adapter ładuje bibliotekę przez LoadLibraryEx z flagami wyszukiwania obejmującymi własny folder DLL plus domyślne bezpieczne katalogi; zależności ONNX Runtime albo OpenCV położone obok HotPDFRapidOCR.dll zostają znalezione bez edycji PATH. Ścieżki modelu i słownika przechodzą granicę jako UTF-8, a DLL konwertuje je przez MultiByteToWideChar w trybie ścisłym, zanim otworzy pliki przez API szerokich znaków. Katalog modeli spod C:\Users\Łukasz albo cyrylicka nazwa użytkownika otwierają się normalnie

Jedna reguła mieszka w plikach budowania, nie w nagłówku. DLL linkuje ONNX Runtime i OpenCV statycznie, a projekt CMake domyślnie bierze statyczną release'ową CRT (/MT). Wmieszaj biblioteki statyczne skompilowane pod /MD i dostaniesz błędy linkera, jeśli masz szczęście, i dwie niezależne sterty, jeśli nie. Prowizjonuj biblioteki zbudowane w tym samym trybie CRT co DLL

Co się dzieje między TBitmap a linią tekstu?

HotPDF wręcza DLL niezależną, top-down kopię BGR wyrenderowanej strony, a DLL oddaje jedno wywołanie zwrotne na rozpoznaną linię. Tekst w tym wywołaniu jest pożyczony: wskaźnik jest ważny tylko do powrotu z callbacku, więc adapter kopiuje go na miejscu

W Delphi migawka pochodzi z prywatnego TBitmap wymuszonego na pf24bit i czytanego przez GetDIBits z ujemnym biHeight. To daje wiersze od góry do dołu, dopełnione do czterobajtowego wyrównania, a stride wędruje do DLL jako jawny argument. Na FPC adapter czyta przez CreateIntfImage. Bitmapa wołającego nie jest modyfikowana. Sprawdzenia rozmiaru biegną przed alokacją kopii: najwyżej 32 767 pikseli na bok i nie więcej niż MaxPixels łącznie, co domyślnie daje 16 777 216 i można podnieść do 67 108 864

Potok DLL RapidOCR w HotPDF od bitmapy do warstwy tekstu: adapter robi migawkę strony jako pf24bit BGR od góry do dołu, DLL dopełnia, wykrywa, porządkuje i rozpoznaje wycinki, doręcza jedno wywołanie zwrotne na linię z pożyczonym tekstem UTF-8, boxem i pewnością, a adapter waliduje każdą linię przed zatwierdzeniem warstwy tekstu
piksele przechodzą przez ABI raz, jako migawka, linie wracają po jednym wywołaniu zwrotnym, a nic nie dociera do warstwy przeszukiwalnej, dopóki każde sprawdzenie nie przejdzie

Wewnątrz DLL obraz dostaje 50-pikselową białą ramkę, regiony tekstu są wykrywane z dłuższym bokiem skalanym do najwyżej 1024 pikseli, a boxy są sortowane w poziome wiersze. Z włączonym klasyfikatorem kąta wycinek obraca się o 180 stopów tylko, gdy wynik do góry nogami przekroczy 0,9, co nie pozwala słabej predykcji przewrócić krótkich słów. Każda linia przychodzi potem jako const char*, liczba bajtów, integerowy box w pikselach oryginalnego obrazu i średnia pewność znaków. Adapter jest rygorystyczny co do tego, co przyjmuje:

  • UTF-8 jest dekodowane z MB_ERR_INVALID_CHARS, więc zniekształcona sekwencja bajtów wywala stronę zamiast sadzić znaki zastąpienia w przeszukiwalnej warstwie
  • Znaki kontrolne C0 i C1 są odrzucane; linie z samych białych znaków są pomijane
  • Box musi leżeć wewnątrz bitmapy, a pewność musi być skończoną wartością od 0 do 1
  • Tekst liczy się do MaxTextCodeUnits żądania, z twardym sufitem 1 048 576 jednostek UTF-16 na wywołanie; znaki spoza Basic Multilingual Plane kosztują dwie jednostki
  • Wyjątek Pascala wewnątrz callbacku jest tam łapany, przechowywany i zamieniany w zwrot 0, co każe DLL się zatrzymać; przechowana wiadomość staje się Info.Diagnostic

Dwa z tych szczegółów mają znaczenie, gdy stroisz wyjście. Jednostką jest linia, nie słowo: każda linia bierze jeden slot MaxWords, Info.AcceptedWordCount i Info.DroppedWordCount liczą linie, a trafienie w wyszukiwarce podświetla cały box linii. I MinimumConfidence jest porównywane ze średnią pewnością znaków linii, więc jeden rozmazany znak wśród dwudziestu czystych rzadko topi linię. Podniesienie progu do 0,7 albo 0,8 gubi całe linie, nigdy pojedyncze znaki. Pusta strona kończy się sukcesem z zerem linii, a każda porażka wyrzuca wyniki częściowe, więc wielostronicowe zatwierdzenie zostaje all-or-nothing

Jeden silnik, jedna kopia modeli, jeden wołający naraz

Każdy silnik DLL RapidOCR posiada dokładnie jedną instancję modeli przez całe swoje życie, a wywołania Recognize na tym silniku są szeregowane sekcją krytyczną. To trzymanie referencji IHPDFOCREngine utrzymuje modele w pamięci, więc praca wsadowa powinna stworzyć silnik raz i używać go ponownie przy każdym dokumencie

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;    // proste skany: bez modelu klasyfikatora
  Models.Threads := 4;                   // 1..64, przycinane do aktywnych procesorów
  Models.TimeoutMilliseconds := 120000;  // na wywołanie Recognize, kooperatywnie
  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;  // ostatnia referencja zwolniona: modele zniszczone, potem DLL wyładowana

Threads ustawia jednocześnie licznik wątków intra-op i inter-op każdej sesji ONNX w silniku, a DLL przycina go do liczby aktywnych procesorów. Dwa wątki dzielące jeden silnik nigdy nie puszczają inferencji równolegle; drugi czeka. To czekanie nie jest ślepym EnterCriticalSection. Adapter próbuje locka przez TryEnterCriticalSection, śpi 25 ms między próbami i przy każdej sprawdza token anulowania oraz deadline, więc żądanie w kolejce nadal da się anulować

Zegar deadline'u startuje z wejściem w Recognize, przed wzięciem locka. Czas w kolejce za inną stroną liczy się do TimeoutMilliseconds. Z czterema wątkami roboczymi na jednym silniku i deadline'em 60 sekund czwarta strona może wypaść na timeout, nie docierając nigdy do modelu. Daj zamiast tego każdemu workerowi własny silnik. Kosztuje jedną kopię modeli w pamięci na silnik, a ta pamięć kupuje przewidywalne timeouty i realną równoległość; dzielenie jednego silnika ma sens tylko, gdy żądania są tak rzadkie, że prawie nigdy się nie kolejkują

Dlaczego natywnego wywołania OCR nie da się zabić w środku inferencji?

Natywnego wywołania RapidOCR nie da się zabić w środku inferencji, bo biegnie ono na Twoim wątku, w Twoim procesie, w środku sesji ONNX Runtime, która nie ma API przerwania dla działającego Run. Anulowanie w adapterze DLL jest kooperatywne. DLL woła callback przerwania przed i po detekcji, po sklasyfikowaniu każdego wycinka i po każdej rozpoznanej linii, i zatrzymuje się na pierwszym punkcie kontrolnym, gdzie callback zwróci 0. Pojedynczy Run, który już wystartował, kończy się najpierw

Siłowe opcje są gorsze niż czekanie. TerminateThread zostawiłby lock sterty CRT, pulę wątków ONNX Runtime i stan OpenCV w tym, w czym akurat były. Wywołanie FreeLibrary, gdy wywołanie wciąż się wykonuje, odmapowuje kod siedzący na stacku. Niczego z tego nie da się uczynić bezpiecznym, więc adapter nigdy nie próbuje. Przekroczony deadline wraca jako otlsEngineError z diagnostyką timeoutu; anulowany token wraca jako otlsCancelled:

// Token tworzy wołający i dzieli go z wątkiem UI,
// który woła Token.Cancel, gdy użytkownik naciśnie Stop
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:
        // zatrzymano na następnym etapie albo punkcie kontrolnym linii; dokument bez zmian
        Writeln('Cancelled');
      otlsEngineError:
        // obejmuje kooperatywne przekroczenie deadline'u i natywne diagnostyki
        Writeln('Engine: ', string(Info.Diagnostic));
      otlsBudgetExceeded:
        // osiągnięto limit strony, pikseli, słów albo treści w Options
        Writeln('Budget: ', string(Info.Diagnostic));
    else
      Writeln(string(Info.Diagnostic));
    end;
end;

To jest prawdziwy kompromis między adapterami procesowymi a DLL w procesie, i żadna ze stron nie wygrywa każdego wiersza:

Kompromisy adapterów OCR w HotPDF: adaptery procesowe odpalają pracownika i ładują modele przy każdej stronie, ale można je zabić i izolują crashe, podczas gdy DLL RapidOCR w procesie ładuje modele raz, zatrzymuje się tylko na kooperatywnych punktach kontrolnych, dzieli przestrzeń adresową i wdraża się jako DLL z modelami i słownikiem
wybieraj per obciążenie: desktopowa aplikacja strona-po-stronie korzysta z ciepłej DLL, a serwer połykający niezaufane skany powinien zapłacić za ścianę procesu
  • Koszt startu: adaptery Tesseract i Python RapidOCR odpalają proces i ładują modele przy każdej stronie; DLL ładuje modele raz na silnik
  • Zatrzymywanie: proces potomny da się zabić wprost, a pythonowy worker biegnie wewnątrz Job Object z kill-on-close, więc całe jego drzewo procesów idzie z nim; DLL zatrzymuje się na punktach kontrolnych etapów i linii
  • Izolacja awarii: crash w tesseract.exe gubi jedną stronę; access violation wewnątrz DLL zabiera Twój proces ze sobą
  • Deployment: adaptery procesowe wymagają zainstalowanego programu albo środowiska Python; DLL potrzebuje samej siebie, swoich modeli i słownika, dopasowanych do bitowości aplikacji
  • Pamięć: adapter procesowy zwalnia wszystko, gdy potomek wychodzi; silnik DLL trzyma modele rezydentne, dopóki ostatnia referencja interfejsu nie zniknie

Wybierz DLL dla interaktywnej aplikacji desktopowej, która OCR-uje stronę po stronie i potrzebuje responsywnego przycisku Stop wracającego w ciągu jednego etapu inferencji. Dla serwera połykającego niezaufane skany o każdej porze zapłać koszt startu na stronę i trzymaj granicę procesu; zmyślony obraz, który kładzie rozpoznawacz, powinien kosztować jedną stronę — i przy procesie potomnym kosztuje

Budowanie HotPDFRapidOCR.dll i wybór modeli

HotPDFRapidOCR.dll buduje się ze źródeł C++ w Native/RapidOCR przez MSVC, C++17, Windows SDK i CMake 3.20 lub nowszy. Helper tools/Build-HotPDFRapidOCR.ps1 bierze katalogi źródeł natywnych, ONNX Runtime i OpenCV plus -Platform Win32 albo Win64 i zapisuje wynik do Lib/Native/RapidOCR/<Platform>/. Buduj obie, jeśli wysyłasz obie. 32-bitowa aplikacja Delphi nie załaduje 64-bitowej DLL, a biblioteki statyczne, które prowizjonujesz, muszą pasować i do architektury docelowej, i do trybu CRT

Modele mają własne reguły kompatybilności. Detektor to DB text detector. Rozpoznawacz przyjmuje modele CTC w układzie NCHW o stałej wysokości wejścia 32 albo 48 i używa 48, gdy model deklaruje wysokość dynamiczną. Format modelu musi być taki, który statycznie linkowany ONNX Runtime rozumie; nowsze eksporty jak PP-OCRv5 mogą wymagać nowszego runtime'u i nieczytelny model wywala się przy inicjalizacji z diagnostyką. tools/Install-RapidOCRModels.ps1 instaluje pakiety PP-OCRv3 i PP-OCRv4 zweryfikowane względem przypiętych hashy SHA256, ze współdzielonym detektorem i klasyfikatorem pod nazwami plików, których oczekuje Default. Zostań przy tych pakietach, chyba że kontrolujesz też build runtime'u

Słownik musi być UTF-8 bez BOM, dokładnie w kolejności znaków modelu, a liczba jego wpisów musi pasować do klas wyjścia modelu. Końce linii CRLF są w porządku. Gdy model osadza własną listę znaków w metadanych, inicjalizacja modelu porównuje każdy wpis i jego pozycję z plikiem słownika, więc słownik, który ma jedynie właściwą długość, i tak wywali. DLL nigdy nie pobiera brakującego modelu

HotPDF pakuje natywny adapter RapidOCR razem z adapterami OCR opartymi o procesy, rendererem stron, który je karmi, i pisarzem niewidocznej warstwy tekstu Unicode, wszystko wewnątrz jednego natywnego komponentu VCL dla Delphi i C++Builder. Dla oprogramowania do akwizycji i archiwizacji, które musi produkować przeszukiwalny PDF na maszynach bez zainstalowanego Pythona, komponent HotPDF Delphi PDF zostawia do wdrożenia tylko DLL i jej pliki modeli