Addestra Tesseract su font
e dati personalizzati (tesstrain, v5).
Una guida collaudata e orientata alle decisioni per il fine-tuning e l'addestramento di modelli Tesseract 5 con tesstrain: compilare dai sorgenti, preparare il ground truth, eseguire make training, regolare le variabili importanti, misurare il CER con lstmeval e distribuire il tuo traineddata.
In breve — fine-tuning di un modello esistente
Se il tuo script è già supportato, il fine-tuning è la via più rapida a un modello migliore.
git clone https://github.com/tesseract-ocr/tesstrain.git
cd tesstrain && make tesseract-langdata
# metti immagini di riga + .gt.txt in data/myfont-ground-truth/
make training MODEL_NAME=myfont START_MODEL=itaL'addestramento non è disponibile tramite gli installer binari. Serve Linux o WSL2. Vedi l'installazione per compilare dai sorgenti.
Albero decisionale: fine-tuning vs taglio dello strato superiore vs da zero
Scegliere l'approccio giusto fa risparmiare giorni di addestramento sprecato.
| Approccio | Usalo quando | Dati necessari | Tempo |
|---|---|---|---|
Fine-tuning (FINETUNE_TYPE=1) | Stesso script, nuovo font o vocabolario di dominio | 1.000–5.000 righe | Ore |
Taglio strato superiore (FINETUNE_TYPE=2) | Stesso script, glifi nettamente diversi | 5.000–20.000 righe | Ore–giorni |
| Da zero | Nuovo script o alfabeto molto diverso | 50.000+ righe | Giorni |
Inizia con l'opzione più leggera che potrebbe funzionare, valuta e passa a soluzioni più pesanti solo se il CER è inaccettabile. La maggior parte dei problemi con font personalizzati si risolve con il fine-tuning.
Prerequisiti
L'addestramento richiede la compilazione dai sorgenti, non il binario preconfezionato.
- Un ambiente Linux — nativo o WSL2 su Windows. macOS non è supportato per l'addestramento.
git,make,pkg-config,automakee una toolchain C++.libtesseract-develibleptonica-dev(i binari di addestramento vi si collegano).- Il repository
tesstrain, piùlangdata_lstme un modello di partenza datessdata_best.
sudo apt update
sudo apt install -y git make automake pkg-config g++ \
libleptonica-dev libtesseract-dev tesseract-ocr
git clone https://github.com/tesseract-ocr/tesstrain.git
cd tesstrain
make tesseract-langdata # scarica langdata_lstm + tessdata_bestPreparare il ground truth
Il ground truth è costituito da immagini di riga abbinate al loro testo esatto.
tesstrain si aspetta un'immagine per riga di testo in data/<MODEL_NAME>-ground-truth/, ciascuna con un file .gt.txt contenente la trascrizione esatta. Genera le immagini da un file di testo e un font con text2image, e dividi i testi lunghi in righe con split_training_text.py di langdata_lstm.
# Genera immagini di riga da un corpus + un font
text2image --text=corpus.txt \
--outputbase=data/myfont-ground-truth/myfont \
--font='Mio Font Personalizzato' --fonts_dir=/usr/share/fonts \
--ptsize=14
# text2image genera anche file .box; convertili in .gt.txt
# (tesstrain/training/ contiene script di supporto, o rinomina dopo la verifica)Quanti dati: 100–500 righe per validare la pipeline, 1.000–5.000 per la produzione. La precisione deriva dalla varietà — font, dimensioni, spaziature e rumore diversi — più che dal volume grezzo.
Font e selezione dell'unicharset
Il set di caratteri deve coprire tutto ciò che il modello vedrà.
- Installa i font di addestramento nell'ambiente; passa il nome esatto della famiglia a
--font. - Nel fine-tuning, mantieni l'
unicharsetdel modello di partenza affinché lo strato di output corrisponda. - Per un nuovo script, deriva l'unicharset dal tuo ground truth affinché ogni glifo sia rappresentato.
- Includi punteggiatura, cifre e maiuscole/minuscole se i documenti reali le contengono; altrimenti il modello le scarterà.
Eseguire l'addestramento
Un solo comando guida l'intera pipeline del Makefile.
make training \
MODEL_NAME=myfont \
START_MODEL=ita \
TESSDATA_PREFIX=../tessdata_best \
MAX_ITERATIONS=10000| Variabile | Significato | Valore tipico |
|---|---|---|
START_MODEL | Modello da cui continuare (fine-tuning) | eng, ita… |
TESSDATA_PREFIX | Directory che contiene il modello di partenza | ../tessdata_best |
MAX_ITERATIONS | Limite massimo di passi di addestramento | 10000–100000 |
LEARNING_RATE | Ampiezza del passo; più piccola è più sicura nel fine-tuning | 0.0001–0.001 |
FINETUNE_TYPE | 0 da zero, 1 fine-tuning, 2 taglio strato superiore | 1 |
NET_SPEC | Specifica dell'architettura di rete | lasciare predefinito |
RATIO_TRAIN | Divisione addestramento/validazione | 0.9 |
TARGET_ERROR_RATE | Obiettivo CER per l'arresto anticipato | 0.01 |
Checkpoint, stop_training e best vs fast
- tesstrain scrive checkpoint periodici (ad es.
myfont_checkpoint) che puoi valutare o da cui riprendere. - Crea un file
stop_trainingnella directory di output per terminare l'esecuzione in modo pulito all'iterazione successiva. - Converti un checkpoint in un modello utilizzabile con
combine_tessdata -e/convert_to_intdegli strumenti di addestramento. - I modelli best sono i più precisi; i fast sono più piccoli e veloci. Fai fine-tuning da
tessdata_bestquando la precisione conta.
Valutazione: tasso di errore carattere con lstmeval
Giudica il modello su dati che non ha mai visto.
lstmeval --model data/myfont_checkpoint \
--traineddata ../tessdata_best/ita.traineddata \
--eval_listfile data/myfont-ground-truth/eval_files.txtMonitora il CER su un set riservato. Quando smette di scendere — o sale mentre la perdita di addestramento continua a calare — c'è overfitting; fermati e usa il checkpoint precedente.
Distribuire il modello addestrato
Copia il traineddata, punta il motore su di esso e prova.
# Copia in una directory tessdata
cp data/myfont.traineddata /usr/share/tesseract-ocr/5/tessdata/
# oppure imposta un prefisso personalizzato
export TESSDATA_PREFIX=/percorso/verso/tessdata
tesseract campione.png stdout -l myfontPuoi combinare il tuo modello con una lingua di base, ad es. -l myfont+ita. In Python, passa lo stesso valore a pytesseract; vedi la guida Python.
Risoluzione dei problemi
| Sintomo | Causa | Soluzione |
|---|---|---|
| Box errati / ground truth disallineato | Metriche del font errate o immagini di riga troppo grandi | Rigenera con il --font e --ptsize corretti; controlla alcune immagini a occhio. |
| Caratteri mancanti nell'output | Carattere assente dall'unicharset | Aggiungi i glifi al ground truth e ricostruisci l'unicharset. |
| La perdita diverge / NaN | Tasso di apprendimento troppo alto | Riduci LEARNING_RATE e riprendi da un checkpoint precedente. |
| Memoria esaurita (OOM) | Batch troppo grande per RAM/GPU | Riduci BATCH_SIZE/dimensione della rete, o usa una macchina con più memoria. |
| Il CER di validazione sale mentre la perdita scende | Overfitting | Fermati prima, aggiungi ground truth più vario o usa un tasso di apprendimento più basso. |
Domande frequenti sull'addestramento
Posso addestrare Tesseract senza compilarlo dai sorgenti?
No. Gli strumenti di addestramento non sono negli installer binari; usa Linux o WSL2 con libtesseract-dev e il repository tesstrain.
Quanti campioni servono?
Circa 100–500 righe per validare la pipeline e 1.000–5.000 per la produzione. Il fine-tuning richiede meno dati dell'addestramento da zero.
Fine-tuning o da zero?
Fine-tuning per un nuovo font o vocabolario in uno script esistente; da zero solo per uno script realmente nuovo.
Quando fermare l'addestramento?
Quando il CER di validazione smette di migliorare, non quando la perdita di addestramento si appiattisce. Quella differenza è overfitting.
Dove va il modello?
Copia <MODEL_NAME>.traineddata in una directory tessdata (o imposta TESSDATA_PREFIX) ed esegui tesseract image.png stdout -l myfont.