V
≡

HTR · 04

Příprava testovacího prostředí pro práci s HTR

Vydáno: Aktualizováno: Vydavatel: Vestigia Scriptorium

Úvod

Než začneme vytvářet vlastní Ground Truth a trénovat HTR model, je vhodné připravit oddělené testovací prostředí, ve kterém lze bezpečně experimentovat s digitalizovanými dokumenty, modely a nastavením jednotlivých nástrojů.

Pro první experiment není nutné budovat serverovou infrastrukturu ani pořizovat výkonnou pracovní stanici. Důležitější je zvolit prostředí, které odpovídá cíli projektu.

Pro práci s historickými rukopisy lze z praktického hlediska rozlišit tři základní možnosti:

  1. Transkribus – nejjednodušší cesta bez vlastní instalace HTR infrastruktury;
  2. eScriptorium – lokální nebo serverové grafické prostředí využívající mimo jiné systém Kraken;
  3. Kraken – samostatný nástroj ovládaný především z příkazové řádky.

Každá varianta je vhodná pro jiný způsob práce.

1. Nejdříve si určete účel testovacího prostředí

Před instalací jakéhokoli softwaru je vhodné odpovědět na několik základních otázek.

Chceme pouze:

  • vyzkoušet automatické rozpoznávání několika stran;
  • vytvořit vlastní Ground Truth;
  • natrénovat vlastní model;
  • experimentovat s různými modely;
  • zpracovávat dokumenty lokálně bez jejich odesílání do externí služby;
  • automatizovat zpracování stovek nebo tisíců obrazů;
  • propojit HTR s vlastním programovým nebo databázovým prostředím?

Pokud chceme pouze pochopit princip práce s HTR, je vlastní server zbytečnou komplikací.

Pokud však chceme experimentovat s datovými formáty, automatizací, vlastními modely a dávkovým zpracováním, lokální prostředí začne dávat smysl.

Varianta A: Transkribus – nejjednodušší cesta

2. Kdy použít Transkribus

Pro začátečníka je Transkribus obvykle nejrychlejší cestou k prvnímu experimentu.

Není nutné instalovat Python, databázi, Docker ani framework pro neuronové sítě. Uživatel si vytvoří účet, nahraje dokumenty a pracuje prostřednictvím webové aplikace.

Transkribus umožňuje například:

  • import digitalizovaných dokumentů;
  • automatickou analýzu layoutu;
  • vytváření a opravu transkripcí;
  • přípravu Ground Truth;
  • použití existujících HTR modelů;
  • trénování vlastních modelů;
  • vyhodnocování výsledků;
  • export přepisů.

Pro první seznámení s HTR je proto vhodné začít právě zde.

Co potřebujeme

Praktické minimum představuje:

  • běžný počítač;
  • moderní webový prohlížeč;
  • připojení k internetu;
  • účet Transkribus;
  • několik kvalitně digitalizovaných stran historického dokumentu.

Samotné výpočty není nutné provádět na vlastním počítači.

Co již není vhodné instalovat

Dříve existoval desktopový Transkribus eXpert Client. Ten je však nyní veden jako zastaralý a není dále rozvíjen; nové funkce jsou soustředěny do webové aplikace.[1]

Pro nový projekt proto nemá smysl stavět pracovní postup na desktopovém klientu.

Varianta B: eScriptorium – vlastní grafické HTR prostředí

3. Co je eScriptorium

eScriptorium je otevřené prostředí určené pro práci s historickými dokumenty. Poskytuje webové rozhraní pro import obrazů, segmentaci, transkripci, anotaci, trénování modelů a automatické rozpoznávání.

Pro samotné HTR využívá především systém Kraken.[2]

Výhodou eScriptoria je kombinace dvou vlastností:

  • uživatel pracuje v grafickém webovém rozhraní;
  • samotné prostředí lze provozovat na vlastním počítači nebo serveru.

To je vhodné například tam, kde chceme mít obrazová data, Ground Truth i modely pod vlastní kontrolou.

4. Doporučené prostředí pro první lokální instalaci

Nejjednodušší cestou k lokálnímu eScriptoriu je v současnosti Docker.

Oficiální dokumentace eScriptoria označuje Docker za doporučený způsob instalace.[3]

Pro testovací počítač je vhodná například tato konfigurace:

Operační systém

  • Linux;
  • macOS;
  • Windows s WSL 2.

Pro technické experimenty je obvykle nejpohodlnější Linux, například aktuální LTS vydání Ubuntu.

Základní software

Potřebujeme:

  • Git;
  • Docker Engine nebo Docker Desktop;
  • Docker Compose v2;
  • webový prohlížeč.

Docker zde řeší důležitý problém: eScriptorium není jediný program, ale soustava několika služeb. Používá mimo jiné webovou aplikaci, databázi PostgreSQL, Redis a pracovní procesy Celery. Docker jednotlivé komponenty spouští v oddělených kontejnerech.[2]

Pro začátečníka je to výrazně jednodušší než instalovat všechny závislosti samostatně.

5. Kontrola Dockeru

Po instalaci Dockeru nejprve ověříme, zda funguje.

V terminálu:

docker --version
docker compose version

Druhá instrukce je důležitá. Současná dokumentace eScriptoria počítá s příkazem:

docker compose

tedy s Docker Compose v2.

Starší samostatný program:

docker-compose

je již zastaralý.[3]

Funkčnost Dockeru můžeme ověřit například:

docker run hello-world

Pokud se testovací kontejner úspěšně spustí, je základní prostředí připraveno.

6. Stažení eScriptoria

Zdrojové soubory stáhneme pomocí Gitu:

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

Poté vytvoříme konfigurační soubor:

cp variables.env_example variables.env

Soubor variables.env obsahuje nastavení lokální instance.

Před prvním spuštěním je vhodné upravit alespoň:

  • SECRET_KEY;
  • jméno administrátora;
  • heslo administrátora;
  • e-mail administrátora;
  • případně doménu a síťová nastavení.

Ani v testovacím prostředí není vhodné ponechávat výchozí heslo, pokud by byl systém dosažitelný z jiné části sítě.[3]

7. Spuštění eScriptoria

Aktuální obrazy kontejnerů lze stáhnout příkazem:

docker compose pull

Poté prostředí spustíme:

docker compose up -d

Parametr -d znamená, že kontejnery poběží na pozadí.

Stav ověříme:

docker compose ps

Lokální rozhraní je při standardním nastavení dostupné v prohlížeči na:

http://localhost:8080/

Přihlásíme se administrátorským účtem nastaveným v variables.env.[3]

8. Jak eScriptorium zastavit

Testovací prostředí můžeme zastavit:

docker compose down

Data přitom zůstávají zachována.

Velmi opatrně je třeba zacházet s příkazem:

docker compose down -v

Volba -v odstraní také Docker volumes, takže může smazat databázi a uložená data instance.[3]

Pro začátečníka je proto bezpečnější používat běžné:

docker compose down

Varianta C: Kraken – práce přímo s HTR enginem

9. Co je Kraken

Kraken je open-source systém pro automatické rozpoznávání textu, zaměřený zejména na historické dokumenty a různé druhy písem.

Podporuje mimo jiné:

  • segmentaci stránky;
  • detekci řádků;
  • rozpoznávání textu;
  • trénování vlastních modelů;
  • PAGE XML;
  • ALTO;
  • hOCR;
  • práci s předtrénovanými modely.[4]

Je vhodný zejména pro uživatele, kteří chtějí mít jednotlivé kroky HTR procesu pod kontrolou nebo je začlenit do vlastních skriptů.

10. Vytvoření samostatného Python prostředí

Kraken není vhodné bezmyšlenkovitě instalovat do systémového Pythonu.

Pro experimentální práci je lepší vytvořit samostatné virtuální prostředí.

Například:

python3 -m venv htr-env

Aktivace na Linuxu a macOS:

source htr-env/bin/activate

Poté aktualizujeme instalační nástroje:

python -m pip install --upgrade pip

a nainstalujeme Kraken:

pip install kraken

Současná dokumentace Krakenu uvádí instalaci prostřednictvím pip jako standardní podporovanou cestu.[4]

11. Ověření instalace Krakenu

Po instalaci:

kraken --help

Pokud se zobrazí nápověda, je základní instalace funkční.

Kraken má rovněž přístup k repozitáři existujících modelů. Dostupné modely lze zobrazit například:

kraken list

Informace o konkrétním modelu lze získat pomocí:

kraken show IDENTIFIKATOR_MODELU

Kraken tak umožňuje experimentovat nejen s vlastními modely, ale také s existujícími volně dostupnými modely.[4]

12. První test rozpoznávání

Před trénováním vlastního modelu je vhodné ověřit celý řetězec na jednom obrazu.

Princip zpracování je:

obraz → segmentace → rozpoznání → text/XML

Při vhodném modelu lze použít například:

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

Kraken nejprve určí strukturu řádků a následně provede rozpoznání pomocí zadaného modelu.[4]

Cílem tohoto prvního experimentu není získat dokonalý přepis.

Potřebujeme pouze ověřit, že:

  • Kraken lze spustit;
  • vstupní obraz lze načíst;
  • model lze načíst;
  • proběhne segmentace;
  • vznikne výstupní text.

Teprve potom má smysl řešit vlastní trénování.

13. CPU nebo GPU?

Jedna z nejčastějších otázek při vytváření HTR prostředí zní, zda je nutná grafická karta.

Pro samotné:

  • prohlížení dokumentů;
  • přípravu Ground Truth;
  • opravu transkripcí;
  • malé testy rozpoznávání;

není výkonná GPU nezbytnou podmínkou.

Při trénování neuronových modelů však může kompatibilní GPU celý proces výrazně urychlit.

eScriptorium umožňuje pro trénovací worker použít NVIDIA GPU prostřednictvím NVIDIA Container Toolkit. Současná dokumentace používá pro trénování nastavení zařízení typu:

KRAKEN_TRAINING_DEVICE=cuda:0

a konfiguraci GPU v Docker Compose.[3]

Pro první experiment ale není vhodné začínat instalací CUDA a ovladačů, pokud není jisté, že je budeme potřebovat.

Rozumnější postup je:

nejprve zprovoznit systém na CPU → vytvořit malý experiment → teprve potom řešit GPU.

Tím se výrazně zmenší počet možných zdrojů instalačních problémů.

14. Doporučená struktura projektových adresářů

Bez ohledu na zvolený nástroj je užitečné mít od začátku pořádek v datech.

Například:

htr-projekt/
│
├── images-original/
│   └── původní digitalizáty
│
├── images-working/
│   └── pracovní kopie obrazů
│
├── ground-truth/
│   └── ověřené transkripce
│
├── pagexml/
│   └── PAGE XML
│
├── models/
│   ├── model-001/
│   ├── model-002/
│   └── model-003/
│
├── test/
│   └── nezávislá testovací data
│
├── results/
│   └── výsledky experimentů
│
└── documentation/
    ├── transcription-rules.md
    └── experiment-log.md

Takové členění není technickou podmínkou HTR systému. Je to organizační opatření, které se začne vyplácet velmi rychle.

Zvlášť důležité je oddělit:

původní obrazy,
Ground Truth,
trénovací data,
nezávislá testovací data,
výsledky jednotlivých modelů.

Jinak může později snadno dojít k tomu, že nebudeme vědět, zda určitá stránka byla nebo nebyla součástí trénování.

15. Původní obrazy neupravujte

Originální digitalizáty je vhodné uchovávat v samostatném adresáři a nepřepisovat je.

Pokud potřebujeme změnit:

  • rozlišení;
  • kontrast;
  • barevnost;
  • ořez;
  • binarizaci;
  • orientaci obrazu;

vytvoříme pracovní kopii.

Původní soubor by měl zůstat zachován.

To je důležité nejen pro HTR experiment, ale také pro obecnou archivní reprodukovatelnost zpracování.

16. PAGE XML jako vhodný výměnný formát

Při dlouhodobější práci není vhodné uzamknout projekt pouze do interního formátu jednoho programu.

Jedním z významných formátů používaných pro historické dokumenty je PAGE XML.

Může obsahovat například:

  • rozměry stránky;
  • textové oblasti;
  • souřadnice řádků;
  • baselines;
  • pořadí čtení;
  • transkripce;
  • další strukturální informace.

Kraken PAGE XML podporuje a PAGE XML používá jako významný formát Ground Truth také ekosystém OCR-D.[4][5]

Pro archivní projekt je proto vhodné ověřit, zda lze Ground Truth a výsledky exportovat do standardizovaného formátu nezávislého na konkrétní aplikaci.

17. Udržujte si záznam o experimentech

Velmi snadno vznikne situace:

„Model číslo 7 byl lepší než model číslo 6, ale už nevíme proč.“

Proto je už od prvního experimentu vhodné vést jednoduchý protokol.

Například:

Model: statek-001
Datum: 2026-09-09

Training:
45 stran
8 742 slov

Validation:
5 stran
963 slov

Base model:
název / identifikátor

Nastavení:
...

CER validation:
7,4 %

Poznámka:
Problémy s písařem C.
Často zaměňuje r/n a e/c.

Další verze:

Model: statek-002

Změna:
+15 GT stran písaře C

CER validation:
5,8 %

Takový obyčejný textový soubor může mít později větší hodnotu než samotné automaticky ukládané logy.

18. Verzování

Pro konfigurační soubory, transkripční pravidla, skripty a dokumentaci je vhodný Git.

Například:

git init

Nemusíme však do Gitu ukládat tisíce velkých TIFF obrazů nebo několikagigabajtové modely.

Git je vhodný zejména pro:

  • transkripční pravidla;
  • skripty;
  • konfigurační soubory;
  • malé XML soubory;
  • dokumentaci experimentů.

Velká obrazová data je vhodnější archivovat jiným způsobem.

19. Zálohování

Ground Truth je zpravidla dražší než samotný HTR model.

Model můžeme natrénovat znovu.

Ručně vytvořený a zkontrolovaný přepis stovek nebo tisíců řádků může představovat desítky až stovky hodin lidské práce.

Proto by měl být Ground Truth pravidelně zálohován minimálně ve dvou nezávislých kopiích.

Praktická hierarchie hodnoty dat bývá:

originální digitalizát → Ground Truth → metadata a dokumentace → model → automaticky generovaný výstup

Ztráta modelu je nepříjemná.

Ztráta kvalitního Ground Truth může znamenat nutnost zopakovat podstatnou část celého projektu.

20. Doporučené testovací prostředí pro začátečníka

Pro první experiment lze doporučit dvě fáze.

Fáze 1 – bez instalace

Použijeme:

Transkribus + 10 až 20 stran jednoho dokumentu

Cílem je pochopit:

  • segmentaci;
  • baselines;
  • transkripci;
  • Ground Truth;
  • existující modely;
  • CER;
  • princip trénování.

Teprve pokud zjistíme, že chceme HTR používat systematicky, přejdeme k lokálnímu prostředí.

Fáze 2 – lokální laboratoř

Na běžném počítači připravíme:

Windows + WSL 2
nebo
Linux

+
Git
+
Docker
+
eScriptorium
+
Kraken
+
editor zdrojových textů
+
Git repozitář pro konfiguraci a dokumentaci

Tím získáme prostředí, v němž můžeme experimentovat jak prostřednictvím grafického rozhraní eScriptoria, tak přímo s Krakenem.

21. Doporučený první technický experiment

Po instalaci není vhodné ihned nahrát 300stránkovou archivní knihu.

Stačí například pět až deset stran.

Postup:

1. Zkopírovat obrazy do pracovního adresáře.

2. Importovat je do eScriptoria nebo Transkribusu.

3. Provést segmentaci.

4. Zkontrolovat baselines.

5. Vyzkoušet existující HTR model.

6. Ručně opravit několik stran.

7. Exportovat Ground Truth.

8. Ověřit, že Ground Truth dokážeme znovu načíst.

9. Pokud používáme Kraken, spustit rozpoznávání jednoho obrazu z příkazové řádky.

10. Zaznamenat použitý software, model a dosažený výsledek.

Teprve když tento malý cyklus funguje od začátku do konce, rozšíříme experiment na desítky stran.

22. Co bych zvolil pro vlastní archivní projekt

Pokud je cílem především zpracovávat historické dokumenty, nikoli studovat správu serverů, začal bych Transkribusem.

Pokud se ukáže, že potřebujeme:

  • plnou kontrolu nad daty;
  • lokální zpracování;
  • vlastní automatizaci;
  • experimentování s otevřenými modely;
  • napojení na vlastní software;

pak bych vybudoval druhé testovací prostředí založené na:

Docker + eScriptorium + Kraken.

Samostatnou instalaci Krakenu bych používal především pro experimenty, automatizované skripty a detailnější práci s modely.

Tím vzniknou tři úrovně:

Transkribus
│
│  nejjednodušší použití
│
eScriptorium
│
│  vlastní prostředí + grafické rozhraní
│
Kraken
│
│  příkazová řádka a přímá práce s HTR
│
vlastní skripty a datové workflow

Pro výuku a archivní experimenty je takové uspořádání praktičtější než snažit se od prvního dne vytvořit kompletní vlastní HTR infrastrukturu.

Poznámky a použité zdroje

[1] READ-COOP. How to use Transkribus eXpert (deprecated). Dokumentace Transkribus. Desktopový klient Transkribus eXpert již není aktualizován a nové funkce jsou směrovány do webové aplikace.
https://help.transkribus.org/downloading-and-installing-transkribus-expert-deprecated

[2] Scripta. eScriptorium. Zdrojový repozitář a popis architektury projektu. eScriptorium integruje nástroje pro transkripci, anotaci, trénování a rozpoznávání historických dokumentů a využívá Kraken.
https://gitlab.com/scripta/escriptorium

[3] Scripta. eScriptorium – Install with Docker. Aktuální instalační dokumentace. Doporučuje Docker, Docker Compose v2 a popisuje také konfiguraci GPU pomocí NVIDIA Container Toolkit.
https://gitlab.com/scripta/escriptorium/-/wikis/docker-install

[4] KIESSLING, Benjamin. Kraken 5.3 Documentation. Dokumentace instalace, segmentace, rozpoznávání, modelů a podporovaných výstupních formátů.
https://kraken.re/5.3.0/

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

[6] OCR-D. OCR-D Quick Start Guide. Příklad přípravy kontejnerového prostředí pomocí Dockeru a práce s historickými dokumenty.
https://ocr-d.de/en/start