Przygotowanie środowiska testowego do pracy z HTR

Wstęp

Zanim zaczniemy tworzyć własne Ground Truth i trenować model HTR, warto przygotować osobne środowisko testowe, w którym będziemy mogli bezpiecznie eksperymentować ze zdigitalizowanymi dokumentami, modelami i indywidualnymi ustawieniami narzędzi.

Do pierwszego eksperymentu nie jest konieczne budowanie infrastruktury serwerowej ani nabywanie wydajnej stacji roboczej. Ważniejsze jest wybranie środowiska odpowiadającego celowi projektu.

Z praktycznego punktu widzenia pracy z rękopisami historycznymi można wyróżnić trzy podstawowe opcje:

1. Transkribus– najprostszy sposób bez konieczności instalowania własnej infrastruktury HTR;
2. eScriptorium– lokalne lub serwerowe środowisko graficzne wykorzystujące m.in. system Kraken;
3. Kraken– osobne narzędzie sterowane przede wszystkim z linii poleceń.

Każdy wariant nadaje się do innego sposobu pracy.

1. Najpierw określ cel środowiska testowego

Przed instalacją jakiegokolwiek oprogramowania warto odpowiedzieć sobie na kilka podstawowych pytań.

Chcemy tylko:

• spróbuj automatycznego rozpoznania kilku stron;
• utwórz własny Ground Truth;
• wytrenuj swój własny model;
• eksperymentuj z różnymi modelami;
• przetwarzaj dokumenty lokalnie, bez wysyłania ich do serwisu zewnętrznego;
• zautomatyzować przetwarzanie setek lub tysięcy obrazów;
• połączyć HTR z własnym programem lub środowiskiem bazodanowym?

Jeśli chcemy po prostu zrozumieć zasadę pracy z HTR, własny serwer to niepotrzebna komplikacja.

Jeśli jednak chcemy poeksperymentować z formatami danych, automatyzacją, niestandardowymi modelami i przetwarzaniem wsadowym, środowisko lokalne zaczyna mieć sens.

Opcja A: Transkribus - najprostszy sposób

2. Kiedy używać Transkribus

Dla początkującego Transkribus jest zwykle najszybszą drogą do pierwszego eksperymentu.

Nie ma potrzeby instalowania Pythona, bazy danych, Docker ani frameworka sieci neuronowej. Użytkownik zakłada konto, przesyła dokumenty i pracuje poprzez aplikację internetową.

Transkribus umożliwia na przykład:

• importować dokumenty cyfrowe;
• automatyczna analiza układu;
• tworzenie i poprawianie transkrypcji;
• przygotowanie Ground Truth;
• wykorzystanie istniejących modeli HTR;
• szkolenie własnych modeli;
• ocena wyników;
• transkrypcje eksportu.

Dlatego też należy rozpocząć tutaj pierwsze wprowadzenie do HTR.

Czego potrzebujemy

Praktyczne minimum składa się z:

• zwykły komputer;
• nowoczesna przeglądarka internetowa;
• połączenie internetowe;
• konto Transkribus;
• kilka wysokiej jakości zdigitalizowanych stron dokumentu historycznego.

Samych obliczeń nie trzeba wykonywać na własnym komputerze.

Co nie nadaje się już do montażu

Kiedyś istniał komputer stacjonarny Transkribus eXpert Client. Jednak obecnie jest on wymieniony jako przestarzały i nie jest dalej rozwijany; nowe funkcje skoncentrowane są w aplikacji webowej. [1]

Dlatego nie ma sensu budować przepływu pracy na kliencie stacjonarnym dla nowego projektu.

Wariant B: eScriptorium – własne środowisko graficzne HTR

3. Co to jest eScriptorium

eScriptorium to otwarte środowisko przeznaczone do pracy z dokumentami historycznymi. Zapewnia interfejs sieciowy do importowania obrazów, segmentacji, transkrypcji, adnotacji, uczenia modeli i automatycznego rozpoznawania.

W przypadku samego HTR wykorzystuje on przede wszystkim system Kraken. [2]

Zaletą eScriptorium jest połączenie dwóch cech:

• użytkownik pracuje w graficznym interfejsie WWW;
• samo środowisko można uruchomić na własnym komputerze lub serwerze.

Jest to przydatne na przykład wtedy, gdy chcemy mieć pod własną kontrolą dane obrazu, Ground Truth i modele.

4. Zalecane środowisko dla pierwszej instalacji lokalnej

Najprostszym sposobem na lokalny eScriptorium jest obecnie Docker.

Oficjalna dokumentacja eScriptorium wymienia Docker jako zalecaną metodę instalacji. [3]

Na przykład następująca konfiguracja jest odpowiednia dla komputera testowego:

System operacyjny

• Linux;
• macOS;
• Windows z WSL2.

W przypadku eksperymentów technicznych Linux jest zwykle najwygodniejszy, na przykład bieżąca wersja Ubuntu LTS.

Podstawowe oprogramowanie

Potrzebujemy:

• Gita;
• Silnik Docker lub komputer stacjonarny Docker;
• Docker Compose v2;
• przeglądarka internetowa.

Docker rozwiązuje tutaj istotny problem: eScriptorium nie jest pojedynczym programem, ale zestawem kilku usług. Wykorzystuje między innymi aplikację internetową, bazę danych PostgreSQL, pracowników Redis i Seler. Docker uruchamia poszczególne komponenty w oddzielnych kontenerach. [2]

Dla początkującego jest to znacznie łatwiejsze niż instalowanie wszystkich zależności osobno.

5. Kontrola Docker

Po zainstalowaniu Docker najpierw sprawdzimy, czy to działa.

W terminalu:

docker --version
docker compose version

Drugie polecenie jest ważne. Aktualna dokumentacja eScriptorium wykorzystuje polecenie:

docker compose

czyli Docker Compose v2.

Starszy samodzielny program:

docker-compose

jest już przestarzały. [3]

Funkcjonalność Docker możemy sprawdzić na przykład:

docker run hello-world

Jeśli kontener testowy uruchomi się pomyślnie, środowisko podstawowe będzie gotowe.

6. Pobierz eScriptorium

Pliki źródłowe pobierzemy za pomocą Git:

git clone https://gitlab.com/scripta/escriptorium.git
cd escriptorium

Następnie tworzymy plik konfiguracyjny:

cp variables.env_example variables.env

Plik variables.env zawiera ustawienia instancji lokalnej.

Przed pierwszym uruchomieniem zaleca się modyfikację przynajmniej:

• SECRET_KEY;
• nazwa administratora;
• hasło administratora;
• e-mail administratora;
• ewentualnie ustawienia domeny i sieci.

Nawet w środowisku testowym nie zaleca się utrzymywania domyślnego hasła, jeśli system jest dostępny z innej części sieci. [3]

7. Uruchamianie eScriptorium

Aktualne obrazy kontenerów można pobrać za pomocą polecenia:

docker compose pull

Następnie uruchamiamy środowisko:

docker compose up -d

Parametr -d oznacza, że ​​kontenery będą działać w tle.

Sprawdzimy status:

docker compose ps

Domyślnie interfejs lokalny dostępny jest w przeglądarce pod adresem:

http://localhost:8080/

Logujemy się kontem administratora ustawionym w variables.env. [3]

8. Jak zatrzymać eScriptorium

Możemy zatrzymać środowisko testowe:

docker compose down

Dane zostaną zachowane.

Bądź bardzo ostrożny z poleceniem:

docker compose down -v

Opcja -v usuwa również woluminy Docker, dzięki czemu może usunąć bazę danych i przechowywane dane instancji. [3]

Dlatego dla początkującego bezpieczniej jest używać tego, co wspólne:

docker compose down

Wariant C: Kraken - praca bezpośrednio z silnikiem HTR

9. Co to jest Kraken

Kraken to system typu open source do automatycznego rozpoznawania tekstu, skupiający się głównie na dokumentach historycznych i różnego rodzaju pismach.

Obsługuje m.in.:

• segmentacja strony;
• wykrywanie linii;
• rozpoznawanie tekstu;
• trenowanie własnych modeli;
• PAGE XML;
• ALT;
• hOCR;
• pracować z wstępnie wytrenowanymi modelami. [4]

Jest szczególnie odpowiedni dla użytkowników, którzy chcą mieć pod kontrolą poszczególne kroki procesu HTR lub włączyć je do własnych skryptów.

10. Tworzenie izolowanego środowiska Python

Kraken nie należy instalować bezkrytycznie w systemie Python.

Do prac eksperymentalnych lepiej jest stworzyć osobne środowisko wirtualne.

Na przykład:

python3 -m venv htr-env

Aktywacja w systemie Linux i macOS:

source htr-env/bin/activate

Następnie aktualizujemy instalatory:

python -m pip install --upgrade pip

i zainstaluj Kraken:

pip install kraken

Aktualna dokumentacja Kraken wymienia instalację poprzez pip jako standardowo obsługiwaną ścieżkę. [4]

11. Weryfikacja instalacji Kraken

Po instalacji:

kraken --help

Jeśli wyświetli się pomoc, instalacja podstawowa działa.

Kraken ma również dostęp do repozytorium istniejących modeli. Dostępne modele można obejrzeć np.:

kraken list

Informacje na temat konkretnego modelu można uzyskać korzystając z:

kraken show IDENTIFIKATOR_MODELU

Kraken umożliwia zatem eksperymentowanie nie tylko z własnymi modelami, ale także z istniejącymi, ogólnodostępnymi modelami. [4]

12. Pierwszy test rozpoznawczy

Przed wyszkoleniem własnego modelu warto zweryfikować cały proces przetwarzania na jednym obrazie.

Zasada przetwarzania jest następująca:

obraz → segmentacja → rozpoznawanie → tekst/XML

Mając odpowiedni model możesz zastosować np.:

kraken -i strana.tif vystup.txt segment -bl ocr -m model.mlmodel

Kraken najpierw określa strukturę linii, a następnie dokonuje rozpoznania na podstawie podanego modelu. [4]

Celem tego pierwszego eksperymentu nie jest uzyskanie doskonałego transkrypcji.

Musimy jedynie sprawdzić, czy:

• Można uruchomić Kraken;
• można załadować obraz wejściowy;
• można załadować model;
• nastąpi segmentacja;
• zostanie wygenerowany tekst wyjściowy.

Tylko wtedy ma sens zajmowanie się własnym treningiem.

13. Procesor czy GPU?

Jednym z najczęstszych pytań podczas tworzenia środowiska HTR jest to, czy wymagana jest karta graficzna.

Tylko dla następujących zadań:

• przeglądanie dokumentów;
• przygotowanie Ground Truth;
• korekta transkrypcji;
• małe testy rozpoznawcze;

Wydajny procesor graficzny nie jest warunkiem koniecznym.

Jednak podczas trenowania modeli neuronowych kompatybilny procesor graficzny może znacznie przyspieszyć proces.

eScriptorium umożliwia pracownikowi szkoleniowemu korzystanie z procesorów graficznych NVIDIA za pośrednictwem zestawu narzędzi NVIDIA Container Toolkit. W aktualnej dokumentacji stosowana jest konfiguracja urządzenia typu:

KRAKEN_TRAINING_DEVICE=cuda:0

i konfiguracja GPU w Docker Compose. [3]

W przypadku pierwszego eksperymentu nie zaleca się jednak rozpoczynania od instalacji CUDA i sterowników, jeśli nie jest pewne, czy będą nam one potrzebne.

Bardziej rozsądnym sposobem działania jest:

najpierw uruchom system na procesorze → utwórz mały eksperyment → dopiero potem skonfiguruj procesor graficzny.

To znacznie zmniejszy liczbę możliwych źródeł problemów z instalacją.

14. Zalecana struktura katalogów projektów

Niezależnie od tego, jakie narzędzie wybierzesz, warto od samego początku uporządkować dane.

Na przykład:

htr-projekt/
│
├── images-lubiginal/
│   └── lubyginalne skany
│
├── images-wlubking/
│   └── robocze kopie obrazów
│
├── ground-truth/
│   └── zweryfikowane transkrypcje
│
├── pagexml/
│   └── PAGE XML
│
├── models/
│   ├── model-001/
│   ├── model-002/
│   └── model-003/
│
├── test/
│   └── niezależne dane testowe
│
├── results/
│   └── wyniki eksperymentów
│
└── documentation/
    ├── transcription-rules.md
    └── experiment-log.md

Podział taki nie jest stanem technicznym systemu HTR. Jest to zabieg organizacyjny, który bardzo szybko zacznie procentować.

Szczególnie ważne jest oddzielenie:

oryginalne obrazy,
Ground Truth,
dane treningowe,
niezależne dane testowe,
wyniki poszczególnych modeli.

W przeciwnym razie może się później zdarzyć, że nie będziemy wiedzieć, czy dana strona była, czy nie, częścią szkolenia.

15. Nie modyfikuj oryginalnych obrazów

Zaleca się przechowywanie oryginalnych, zdigitalizowanych plików w oddzielnym katalogu i nie nadpisywanie ich.

Jeśli musimy zmienić:

• rezolucja;
• kontrast;
• kolor;
• przycięcie obrazu;
• binaryzacja;
• orientacja obrazu;

stworzymy kopię roboczą.

Należy zachować oryginalny plik.

Ma to znaczenie nie tylko dla eksperymentu HTR, ale także dla ogólnej powtarzalności archiwalnej przetwarzania.

16. PAGE XML jako odpowiedni format wymiany

W przypadku dłuższej pracy nie zaleca się zamykania projektu wyłącznie na wewnętrzny format jednego programu.

Jednym z najważniejszych formatów używanych w dokumentach historycznych jest PAGE XML.

Może zawierać na przykład:

• wymiary strony;
• regiony tekstowe;
• współrzędne wierszy;
• linie bazowe;
• kolejność czytania;
• transkrypcja;
• dodatkowe informacje strukturalne.

Kraken obsługuje PAGE XML, a ekosystem OCR-D wykorzystuje również PAGE XML jako główny format Ground Truth. [4] [5]

W przypadku projektu archiwalnego zaleca się zatem sprawdzenie, czy Ground Truth i wyniki można wyeksportować do znormalizowanego formatu, niezależnego od konkretnej aplikacji.

17. Prowadź rejestr eksperymentów

Sytuacja powstaje bardzo łatwo:

„Model nr 7 był lepszy od modelu nr 6, ale nie wiemy już dlaczego”.

Dlatego wskazane jest zachowanie prostego protokołu już od pierwszego eksperymentu.

Na przykład:

Model: statek-001
Data: 2026-09-09

Training:
45 stron
8 742 słowa

Validation:
5 stron
963 słowa

Base model:
nazwa / identyfikatlub

Ustawienia:
...

CER validation:
7,4 %

Uwaga:
Problemy z pisarzem C.
Często myli r/n lubaz e/c.

Następna wersja:

Model: statek-002

Zmiana:
+15 stron GT pisarza C

CER validation:
5,8 %

Taki zwykły plik tekstowy może być później cenniejszy niż same dzienniki automatycznego zapisywania.

18. Wersjonowanie

Git nadaje się do plików konfiguracyjnych, reguł transkrypcji, skryptów i dokumentacji.

Na przykład:

git init

Nie musimy jednak przechowywać w Git tysięcy dużych obrazów TIFF ani wielogigabajtowych modeli.

Git szczególnie nadaje się do:

• zasady transkrypcji;
• skrypty;
• pliki konfiguracyjne;
• małe pliki XML;
• dokumentacja eksperymentów.

Lepiej jest archiwizować duże dane obrazowe w inny sposób.

19. Kopia zapasowa

Ground Truth jest zwykle droższy niż sam model HTR.

Możemy ponownie trenować model.

Ręcznie utworzona i sprawdzona transkrypcja setek lub tysięcy wierszy może oznaczać dziesiątki, a nawet setki godzin ludzkiej pracy.

Dlatego Ground Truth należy regularnie tworzyć kopie zapasowe w co najmniej dwóch niezależnych kopiach.

Praktyczna hierarchia wartości danych wygląda następująco:

oryginalny zdigitalizowany obraz → Ground Truth → metadane i dokumentacja → model → automatycznie wygenerowany wynik

Utrata modelu jest denerwująca.

Utrata jakości Ground Truth może oznaczać konieczność ponownego wykonania znacznej części całego projektu.

20. Zalecane środowisko testowe dla początkującego

W pierwszym eksperymencie można zalecić dwie fazy.

Faza 1 – bez instalacji

Użyjemy:

Transkribus + 10 do 20 stron jednego dokumentu

Celem jest zrozumienie:

• segmentacja;
• linie bazowe;
• transkrypcja;
• Ground Truth;
• istniejące modele;
• CER;
• zasada treningu.

Dopiero gdy okaże się, że chcemy systematycznie korzystać z HTR, przełączymy się na środowisko lokalne.

Faza 2 – Laboratorium lokalne

Na zwykłym komputerze przygotujemy:

Windows + WSL 2
lub
Linux

+
Git
+
Docker
+
eScriptlubium
+
Kraken
+
source code editlub
+
Git repositluby flub configuration and documentation

Daje nam to środowisko, w którym możemy eksperymentować zarówno poprzez GUI eScriptorium, jak i bezpośrednio z Kraken.

21. Zalecany pierwszy eksperyment techniczny

Nie zaleca się natychmiastowego przesyłania 300-stronicowego tomu archiwalnego po instalacji.

Na przykład wystarczy pięć do dziesięciu stron.

Procedura:

1. Skopiuj obrazy do katalogu roboczego.

2. Zaimportuj je do eScriptorium lub Transkribus.

3. Wykonaj segmentację.

4. Sprawdź wartości bazowe.

5. Wypróbuj istniejący model HTR.

6. Ręcznie napraw kilka stron.

7. Eksportuj Ground Truth.

8. Sprawdź, czy możemy ponownie załadować Ground Truth.

9. Jeśli używamy Kraken, uruchom rozpoznawanie pojedynczego obrazu z wiersza poleceń.

10. Zapisz użyte oprogramowanie, model i uzyskany wynik.

Dopiero gdy ta mała pętla zadziała od początku do końca, rozszerzymy eksperyment na dziesiątki stron.

22. Co wybrałbym do własnego projektu archiwum

Jeśli celem jest przede wszystkim przetwarzanie dokumentów historycznych, a nie studiowanie zarządzania serwerem, zacząłbym od Transkribus.

Jeśli okaże się, że potrzebujemy:

• pełna kontrola nad danymi;
• przetwarzanie lokalne;
• niestandardowa automatyzacja;
• eksperymentowanie z modelami otwartymi;
• połączenie z niestandardowym oprogramowaniem;

Następnie zbudowałbym drugie środowisko testowe w oparciu o:

Docker + eScriptorium + Kraken.

Osobnej instalacji Kraken użyłbym głównie do eksperymentów, automatycznych skryptów i bardziej szczegółowej pracy z modelami.

Spowoduje to utworzenie trzech poziomów:

Transkribus
│
│  najprostsze użycie
│
eScriptlubium
│
│  własne środowisko + interfejs graficzny
│
Kraken
│
│  command line and direct wlubk with HTR
│
own scripts and data wlubkflows

W przypadku eksperymentów dydaktycznych i archiwalnych taki układ jest bardziej praktyczny niż próba stworzenia od pierwszego dnia kompletnej, niestandardowej infrastruktury HTR.

Wykorzystane notatki i źródła

[1]CZYTAJ-COOP. How to use Transkribus eXpert (deprecated). Dokumentacja Transkribus. Klient stacjonarny Transkribus eXpert nie jest już aktualizowany, a nowe funkcje są kierowane do aplikacji internetowej.
https://help.transkribus.org/downloading-and-installing-transkribus-expert-deprecated

[2]Skrypt. eScriptorium. Repozytorium źródłowe i opis architektury projektu. eScriptorium integruje narzędzia do transkrypcji, adnotacji, uczenia i rozpoznawania dokumentów historycznych i wykorzystuje Kraken.
https://gitlab.com/scripta/escriptorium

[3]Skrypt. eScriptorium – Install with Docker. Aktualna dokumentacja montażowa. Zaleca Docker, Docker Compose v2, a także opisuje konfigurację procesora graficznego za pomocą NVIDIA Container Toolkit.
https://gitlab.com/scripta/escriptorium/-/wikis/docker-install

[4]KIESSLING, Benjamin. Kraken 5.3 Documentation. Dokumentacja instalacji, segmentacja, rozpoznawanie, modele i obsługiwane formaty wyjściowe.
https://kraken.re/5.3.0/

[5]OCR-D. The Ground Truth Guidelines. Dokumentacja Ground Truth i PAGE XML.
https://ocr-d.de/en/gt-guidelines/trans/

[6]OCR-D. OCR-D Quick Start Guide. Przykład przygotowania środowiska kontenerowego przy użyciu Docker i pracy z dokumentami historycznymi.
https://ocr-d.de/en/start