Техническая статья

In-process RapidOCR в HotPDF: нативный DLL OCR на Delphi

TerminateThread выглядит как очевидный способ остановить OCR-вызов, который молотит по одной отсканированной странице дольше, чем готов ждать ваш UI. Документация Windows объясняет, почему это не так: если целевой поток держит блокировку кучи процесса, эта блокировка не освободится никогда, и следующее выделение памяти в любом другом потоке может зависнуть навсегда. Когда OCR работает внутри вашего собственного процесса, единственная безопасная остановка — кооперативная, на чекпойнтах между стадиями инференса, и это цена загрузки ONNX-моделей один раз и удержания их тёплыми

Альтернатива, которую пробуют первой большинство Delphi-команд, — дочерний процесс. Python-воркер на страницу можно убить в любой момент, что заманчиво, но каждый вызов стартует интерпретатор, импортирует рантайм и грузит модели детекции и распознавания, прежде чем прочитает хоть один пиксель. Положим, архивное задание обрабатывает 500 страниц: эта стартовая работа выполнится 500 раз, а в развёртывании рядом с нативным исполняемым файлом теперь живёт окружение Python

Searchable PDF из сканов с HPDFCreateRapidOCRDLLOCREngine

HotPDF запускает RapidOCR in-process через HPDFCreateRapidOCRDLLOCREngine, объявленную в юните HPDFRapidOCRRecognition. Фабрика грузит HotPDFRapidOCR.dll, один раз инициализирует ONNX-модели детекции, опциональной классификации угла и распознавания и возвращает IHPDFOCREngine. Этот движок включается в THotPDF.ApplyLoadedOCRTextLayer точно так же, как остальные OCR-движки: документ рендерит каждую страницу, DLL гоняет по ней CPU-инференс, и результат фиксируется как невидимый Unicode-текстовый слой. Никакого Python, никакого дочернего процесса. Адаптер поставляется для сборок Delphi, C++Builder и Windows FPC/Lazarus

Валидация происходит в фабрике, до того как тронута хоть одна страница. Каждый файл модели и словаря должен найтись, HPDFRapidOCRAbiVersion должна вернуть 1, и нужные экспорты должны существовать, прежде чем HPDFRapidOCRCreate построит модели. Ошибки конфигурации поднимают EArgumentException; модель, отказывающаяся грузиться, поднимает EInvalidOperation с собственным диагностическим сообщением DLL — например, о словаре, не соответствующем модели распознавания

Последовательность валидации фабрики RapidOCR DLL в HotPDF для HPDFCreateRapidOCRDLLOCREngine: пути и файлы моделей обязаны существовать, HPDFRapidOCRAbiVersion обязана вернуть 1, нужные экспорты обязаны разрешиться, а HPDFRapidOCRCreate — инициализировать модели; EArgumentException или EInvalidOperation поднимаются заранее до любого распознавания, причём второй несёт нативный диагностический текст
валидация нарочно ранняя: проблемы конфигурации поднимаются до инициализации любой модели, так что битый путь или ABI никогда не доезжают до дедлайна распознавания
uses
  SysUtils, HPDFTypes, HPDFDoc, HPDFRapidOCRRecognition;

procedure MakeSearchable(const SourceFile, TargetFile: string);
var
  Doc: THotPDF;
  Engine: IHPDFOCREngine;
  Options: THPDFOCRTextLayerOptions;
  Info: THPDFOCRTextLayerInfo;
begin
  // Модели грузятся здесь, вне всякого дедлайна распознавания.
  // Относительные имена в THPDFRapidOCRDLLOptions.Default
  // разрешаются относительно каталога моделей
  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
    // пустой список страниц = все страницы; SkipPagesWithText по умолчанию 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 и ppocr_keys_v1.txt с одним CPU-потоком, лимитом входа в 16777216 пикселей и дедлайном 60000 мс на вызов распознавания. Для других письменностей THPDFRapidOCRDLLOptions.ForLanguage сохраняет эти дефолты и подставляет <profile>/recognition.onnx плюс <profile>/dictionary.txt для одного из девяти профилей — от традиционного китайского и кириллицы до арабского и деванагари. Каждый движок читает один язык; выбирайте профиль на страницу или на документ. Почему модель и словарь всегда путешествуют парой, разобрано в статье о мультиязычных моделях RapidOCR и CTC-словарях в HotPDF

Движок отчитывается как RapidOCR (native DLL) в Info.EngineName. Пишите эту строку в лог. Когда тот же сервис гоняет ещё и внешний процессный адаптер Tesseract OCR или встроенный template-matching OCR, это самый быстрый способ понять, какой распознаватель выдал плохую страницу

Почему C ABI разговаривает только int32_t и байтами UTF-8?

Граница HotPDFRapidOCR.dll использует целые фиксированной ширины, сырые указатели и явные длины в байтах, потому что у Delphi, C++Builder и Free Pascal с MSVC общая только конвенция вызова C. std::string, std::vector или C++-исключение несут раскладку памяти и модель размотки, принадлежащие одному компилятору и одной рантайм-библиотеке, и если позволить любому из них пересечь границу в Pascal-код, дело кончится испорченным стеком или блоком кучи, освобождённым не тем аллокатором

ABI версии 1 — короткий список правил. Каждый экспорт — cdecl и возвращает статус int32_t: 1 при успехе, 0 при неудаче. Каждая функция, способная упасть, принимает буфер диагностики, принадлежащий вызывающему, и его размер в байтах, а DLL пишет туда NUL-терминированное UTF-8-сообщение, обрезанное по размеру. Внутри DLL тело каждого экспорта сидит в try с catch (const std::exception &) и catch (...). Ошибка ONNX Runtime, assert OpenCV или кривой словарь превращаются в статус 0 плюс текст

ЭкспортРольКогда адаптер его разрешает
HPDFRapidOCRAbiVersionВозвращает 1; любое другое значение отвергаетсяСразу после загрузки DLL
HPDFRapidOCRCreateГрузит модели детекции, опциональной классификации, распознавания и словарьВ фабрике
HPDFRapidOCRRecognizeПрогоняет один битмап и выдаёт один callback на строку текстаВ фабрике
HPDFRapidOCRDestroyОсвобождает экземпляр моделейВ фабрике
HPDFRapidOCRSetReadingDirectionОпциональный порядок строк справа налевоТолько когда задан RightToLeft

Экспорт направления чтения разрешается лениво намеренно, поэтому DLL, собранный без него, всё равно обслуживает любой запрос слева направо. Адаптер грузит библиотеку через LoadLibraryEx с флагами поиска, покрывающими собственную папку DLL плюс безопасные директории по умолчанию; зависимости ONNX Runtime или OpenCV, лежащие рядом с HotPDFRapidOCR.dll, находятся без правки PATH. Пути моделей и словаря пересекают границу как UTF-8, и DLL конвертирует их через MultiByteToWideChar в строгом режиме, прежде чем открывать файлы через wide-char API. Каталог моделей вроде C:\Users\Łukasz или кириллическое имя пользователя открываются нормально

Одно правило живёт в файлах сборки, а не в заголовке. DLL линкует ONNX Runtime и OpenCV статически, и CMake-проект по умолчанию берёт статический release CRT (/MT). Подмешаете статические библиотеки, собранные под /MD, — получите ошибки линковки, если повезёт, и две независимые кучи, если нет. Разворачивайте библиотеки, собранные в том же режиме CRT, что и DLL

Что происходит между TBitmap и строкой текста?

HotPDF передаёт в DLL независимую top-down BGR-копию отрендеренной страницы, а DLL возвращает по одному callback на распознанную строку. Текст в этом callback — заёмный: указатель действителен только до выхода из callback, поэтому адаптер копирует его на месте

В Delphi снимок берётся из приватного TBitmap, принудительно переведённого в pf24bit и прочитанного через GetDIBits с отрицательным biHeight. Это даёт top-down-строки, падденные до выравнивания в четыре байта, и шаг строк уходит в DLL явным аргументом. В FPC адаптер читает через CreateIntfImage. Битмап вызывающего никогда не модифицируется. Проверки размера идут до выделения копии: не более 32767 пикселей по стороне и не более MaxPixels суммарно — по умолчанию 16777216, поднимается до 67108864

Конвейер RapidOCR DLL в HotPDF от битмапа до текстового слоя: адаптер снимает страницу как top-down pf24bit BGR, DLL паддит, детектирует, упорядочивает и распознаёт кропы, доставляет по одному callback на строку с заёмным UTF-8-текстом, боксом и уверенностью, а адаптер валидирует каждую строку до фиксации текстового слоя
пиксели пересекают ABI один раз как снимок, строки возвращаются по одному callback за раз, и ничто не доходит до searchable-слоя, пока каждая проверка не пройдена

Внутри DLL изображение получает белую рамку в 50 пикселей, текстовые регионы детектируются с масштабированием длинной стороны максимум до 1024 пикселей, а боксы сортируются в горизонтальные строки. При включённом классификаторе угла кроп переворачивается на 180 градусов, только если оценка «вверх ногами» превышает 0.9 — это не даёт слабому предсказанию переворачивать короткие слова. Затем каждая строка приходит как const char*, счётчик байтов, целочисленный бокс в пикселях исходного изображения и средняя уверенность по символам. Адаптер строг к тому, что принимает:

  • UTF-8 декодируется с MB_ERR_INVALID_CHARS, поэтому кривая байтовая последовательность валит страницу, а не подсаживает символы замены в searchable-слой
  • C0- и C1-управляющие символы отвергаются; строки из одних пробелов пропускаются
  • Бокс должен лежать внутри битмапа, а уверенность — быть конечным значением от 0 до 1
  • Текст учитывается в MaxTextCodeUnits запроса с жёстким потолком 1048576 UTF-16-единиц на вызов; символы вне базовой многоязычной плоскости стоят две единицы
  • Pascal-исключение внутри callback перехватывается там же, сохраняется и превращается в возврат 0, что заставляет DLL остановиться; сохранённое сообщение становится Info.Diagnostic

Две из этих деталей важны, когда вы подгоняете вывод. Единица — строка, а не слово: каждая строка занимает один слот MaxWords, Info.AcceptedWordCount и Info.DroppedWordCount считают строки, и попадание в поиске подсвечивает весь бокс строки. И MinimumConfidence сравнивается со средней уверенностью символов строки, так что один смазанный символ среди двадцати чистых редко топит строку. Порог 0.7 или 0.8 отбрасывает целые строки, но не отдельные символы. Пустая страница завершается успехом с нулём строк, а любая ошибка отбрасывает частичные результаты, так что мультистраничный коммит остаётся «всё или ничего»

Один движок, одна копия моделей, один вызывающий за раз

Каждый движок RapidOCR DLL владеет ровно одним экземпляром моделей на весь срок жизни, и вызовы Recognize на этом движке сериализуются критической секцией. Именно удержание ссылки IHPDFOCREngine держит модели в памяти, поэтому в пакетной работе движок стоит создать один раз и переиспользовать для всех документов

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;    // строго вертикальные сканы: модель классификатора не грузится
  Models.Threads := 4;                   // 1..64, зажимается до числа активных процессоров
  Models.TimeoutMilliseconds := 120000;  // на вызов Recognize, кооперативно
  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;  // последняя ссылка отпущена: модели уничтожены, затем DLL выгружен

Threads задаёт сразу число intra-op и inter-op потоков каждой ONNX-сессии в движке, а DLL зажимает его до числа активных процессоров. Два потока, делящие один движок, никогда не гоняют инференс параллельно; второй ждёт. Это ожидание — не слепой EnterCriticalSection. Адаптер пробует лок через TryEnterCriticalSection, спит по 25 мс между попытками и каждый раз проверяет токен отмены и дедлайн, так что стоящий в очереди запрос всё ещё можно отменить

Часы дедлайна стартуют при входе в Recognize, до захвата блокировки. Время в очереди за другой страницей тоже расходует TimeoutMilliseconds. С четырьмя воркерами на одном движке и дедлайном в 60 секунд четвёртая страница может уйти по таймауту, так и не доехав до модели. Вместо этого дайте каждому воркеру собственный движок. Это стоит одной копии моделей в памяти на движок, и эта память покупает предсказуемые таймауты и настоящий параллелизм; делить один движок имеет смысл, только когда запросы редки настолько, что очередь почти никогда не образуется

Почему нативный OCR-вызов нельзя убить посреди инференса?

Нативный вызов RapidOCR нельзя убить посреди инференса, потому что он идёт на вашем потоке, внутри вашего процесса, посреди ONNX Runtime-сессии, у которой нет API прерывания для уже запущенного Run. Отмена в DLL-адаптере кооперативная. DLL вызывает abort-callback до и после детекции, после классификации каждого кропа и после каждой распознанной строки и останавливается на первом чекпойнте, где callback вернул 0. Уже начатый одиночный Run сначала завершается

Насильственные варианты хуже ожидания. TerminateThread оставил бы блокировку кучи CRT, пул потоков ONNX Runtime и любое состояние OpenCV в том виде, в каком они застыли в момент убийства. Вызов FreeLibrary, пока вызов ещё исполняется, размапливает код, лежащий на стеке. Ни то, ни другое нельзя сделать безопасно, поэтому адаптер даже не пытается. Истёкший дедлайн возвращается как otlsEngineError с диагностикой о таймауте; отменённый токен — как otlsCancelled:

// Токен создаёт вызывающий и отдаёт UI-потоку,
// который зовёт Token.Cancel, когда пользователь жмёт 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:
        // останов на следующем чекпойнте стадии или строки; документ не тронут
        Writeln('Cancelled');
      otlsEngineError:
        // включает кооперативное истечение дедлайна и нативные диагностики
        Writeln('Engine: ', string(Info.Diagnostic));
      otlsBudgetExceeded:
        // достигнут лимит страницы, пикселей, слов или контента в Options
        Writeln('Budget: ', string(Info.Diagnostic));
    else
      Writeln(string(Info.Diagnostic));
    end;
end;

Это настоящий компромисс между процессными адаптерами и in-process DLL, и ни одна сторона не выигрывает каждую строку:

Компромиссы OCR-адаптеров HotPDF: процессные адаптеры стартуют воркера и грузят модели на каждую страницу, но их можно убить и они содержат падения, тогда как in-process RapidOCR DLL грузит модели однажды, останавливается только на кооперативных чекпойнтах, делит адресное пространство и деплоится как DLL с моделями и словарём
выбирайте по нагрузке: десктопному приложению со страницей за раз выгодна тёплая DLL, а серверу, глотающему недоверенные сканы, стоит платить за процессную стену
  • Стартовая цена: адаптеры Tesseract и Python RapidOCR на каждой странице запускают процесс и грузят модели; DLL грузит модели один раз на движок
  • Остановка: дочерний процесс можно завершить принудительно, причём Python-воркер живёт внутри kill-on-close Job Object, так что с ним уходит всё дерево процессов; DLL останавливается на чекпойнтах стадий и строк
  • Изоляция сбоев: падение tesseract.exe валит одну страницу; access violation внутри DLL валит ваш процесс
  • Развёртывание: процессным адаптерам нужна установленная программа или окружение Python; DLL нужна сама, её модели и словарь, под разрядность приложения
  • Память: процессный адаптер освобождает всё при выходе дочернего процесса; DLL-движок держит модели резидентно, пока не уйдёт последняя ссылка на интерфейс

Берите DLL для интерактивного десктопного приложения, которое распознаёт по странице за раз и нуждается в отзывчивой кнопке Stop, возвращающейся в пределах одной стадии инференса. Для сервера, круглосуточно глотающего недоверенные сканы, заплатите стартовую цену на страницу и оставьте процессную границу: специально собранное изображение, валящее распознаватель, должно стоить одну страницу — и с дочерним процессом так и есть

Сборка HotPDFRapidOCR.dll и выбор моделей

HotPDFRapidOCR.dll собирается из C++-исходников в Native/RapidOCR с помощью MSVC, C++17, Windows SDK и CMake 3.20 или новее. Хелпер tools/Build-HotPDFRapidOCR.ps1 принимает каталоги нативных исходников, ONNX Runtime и OpenCV плюс -Platform Win32 или Win64 и пишет результат в Lib/Native/RapidOCR/<Platform>/. Поставляете обе разрядности — собирайте обе. 32-битное Delphi-приложение не может загрузить 64-битный DLL, и статические библиотеки, которые вы разворачиваете, должны совпадать и по целевой архитектуре, и по режиму CRT

У моделей свои правила совместимости. Детектор — это DB text detector. Распознаватель принимает CTC-модели в раскладке NCHW с фиксированной высотой входа 32 или 48, а при объявленной динамической высоте использует 48. Формат модели должен быть понятен статически слинкованному ONNX Runtime; более новые экспорты вроде PP-OCRv5 могут требовать более новый рантайм, и нечитаемая модель валит инициализацию с диагностикой. tools/Install-RapidOCRModels.ps1 ставит пакеты PP-OCRv3 и PP-OCRv4, проверенные по закреплённым хешам SHA256, с общими детектором и классификатором под именами файлов, которых ждёт Default. Оставайтесь на этих пакетах, если только не контролируете и сборку рантайма тоже

Словарь должен быть UTF-8 без BOM, ровно в порядке символов модели, и число его записей должно совпадать с числом выходных классов модели. CRLF-концы строк допустимы. Когда модель несёт собственный список символов в метаданных, инициализация модели сверяет каждую запись и её позицию с файлом словаря, так что словарь одной лишь правильной длины всё равно провалится. DLL никогда не скачивает отсутствующую модель

HotPDF поставляет нативный RapidOCR-адаптер вместе с процессными OCR-адаптерами, страничным рендерером, который их кормит, и писателем невидимого Unicode-текстового слоя — всё внутри одного нативного VCL-компонента для Delphi и C++Builder. Для софта захвата и архивации, который должен выдавать searchable PDF на машинах без установленного Python, HotPDF Delphi PDF component оставляет для развёртывания только DLL и её файлы моделей