Entrena Tesseract con fuentes
y datos personalizados (tesstrain, v5).
Una guía probada y orientada a decisiones para ajustar y entrenar modelos de Tesseract 5 con tesstrain: compilar desde el código fuente, preparar el ground truth, ejecutar make training, ajustar las variables importantes, medir el CER con lstmeval y desplegar tu traineddata.
TL;DR — ajuste fino de un modelo existente
Si tu escritura ya está soportada, el ajuste fino es la vía más rápida a un modelo mejor.
git clone https://github.com/tesseract-ocr/tesstrain.git
cd tesstrain && make tesseract-langdata
# coloca imágenes de línea + .gt.txt en data/myfont-ground-truth/
make training MODEL_NAME=myfont START_MODEL=spaEl entrenamiento no está disponible a través de los instaladores binarios. Necesitas Linux o WSL2. Consulta la instalación para compilar desde el código fuente.
Árbol de decisión: ajuste fino vs cortar la capa superior vs desde cero
Elegir el enfoque correcto ahorra días de entrenamiento desperdiciado.
| Enfoque | Úsalo cuando | Datos necesarios | Tiempo |
|---|---|---|---|
Ajuste fino (FINETUNE_TYPE=1) | Misma escritura, nueva fuente o vocabulario de dominio | 1.000–5.000 líneas | Horas |
Cortar capa superior (FINETUNE_TYPE=2) | Misma escritura, glifos claramente distintos | 5.000–20.000 líneas | Horas–días |
| Desde cero | Nueva escritura o alfabeto muy distinto | 50.000+ líneas | Días |
Empieza por la opción más ligera que pueda funcionar, evalúa y escala solo si el CER es inaceptable. La mayoría de los problemas de fuentes personalizadas se resuelven con ajuste fino.
Requisitos previos
El entrenamiento requiere compilar desde el código fuente, no el binario empaquetado.
- Un entorno Linux —nativo o WSL2 en Windows—. macOS no es compatible con el entrenamiento.
git,make,pkg-config,automakey una cadena de herramientas C++.libtesseract-devylibleptonica-dev(los binarios de entrenamiento enlazan con estas).- El repositorio
tesstrain, máslangdata_lstmy un modelo inicial detessdata_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 # obtiene langdata_lstm + tessdata_bestPreparar el ground truth
El ground truth son imágenes de línea emparejadas con su texto exacto.
tesstrain espera una imagen por línea de texto en data/<MODEL_NAME>-ground-truth/, cada una con un archivo .gt.txt que contiene la transcripción exacta. Genera imágenes a partir de un archivo de texto y una fuente con text2image, y divide el texto largo en líneas con split_training_text.py de langdata_lstm.
# Genera imágenes de línea desde un corpus + una fuente
text2image --text=corpus.txt \
--outputbase=data/myfont-ground-truth/myfont \
--font='Mi Fuente Personalizada' --fonts_dir=/usr/share/fonts \
--ptsize=14
# text2image también genera archivos .box; conviértelos a .gt.txt
# (tesstrain/training/ tiene scripts auxiliares, o renómbralos tras verificarlos)Cuántos datos: 100–500 líneas para validar la canalización, 1.000–5.000 para producción. La precisión proviene de la variedad —distintas fuentes, tamaños, espaciado y ruido— más que del volumen bruto.
Fuentes y selección de unicharset
El conjunto de caracteres debe cubrir todo lo que el modelo verá.
- Instala las fuentes de entrenamiento en el entorno; pasa el nombre exacto de la familia a
--font. - Al hacer ajuste fino, conserva el
unicharsetdel modelo inicial para que la capa de salida coincida. - Para una escritura nueva, deriva el unicharset de tu ground truth para que todos los glifos estén representados.
- Incluye puntuación, dígitos y mayúsculas/minúsculas si los documentos reales los contienen; de lo contrario el modelo los descartará.
Ejecutar el entrenamiento
Un solo comando impulsa toda la canalización del Makefile.
make training \
MODEL_NAME=myfont \
START_MODEL=spa \
TESSDATA_PREFIX=../tessdata_best \
MAX_ITERATIONS=10000| Variable | Significado | Valor típico |
|---|---|---|
START_MODEL | Modelo desde el que continuar (ajuste fino) | eng, spa… |
TESSDATA_PREFIX | Directorio que contiene el modelo inicial | ../tessdata_best |
MAX_ITERATIONS | Límite superior de pasos de entrenamiento | 10000–100000 |
LEARNING_RATE | Tamaño del paso; menor es más seguro para ajuste fino | 0.0001–0.001 |
FINETUNE_TYPE | 0 desde cero, 1 ajuste fino, 2 cortar capa superior | 1 |
NET_SPEC | Especificación de la arquitectura de red | dejar por defecto |
RATIO_TRAIN | División entrenamiento/validación | 0.9 |
TARGET_ERROR_RATE | Objetivo de CER para parada temprana | 0.01 |
Checkpoints, stop_training y best vs fast
- tesstrain escribe checkpoints periódicos (por ejemplo
myfont_checkpoint) desde los que puedes evaluar o reanudar. - Crea un archivo
stop_trainingen el directorio de salida para terminar la ejecución limpiamente en la siguiente iteración. - Convierte un checkpoint en un modelo utilizable con
combine_tessdata -e/convert_to_intde las herramientas de entrenamiento. - Los modelos best son los más precisos; los fast son más pequeños y rápidos. Haz ajuste fino desde
tessdata_bestcuando la precisión importe.
Evaluación: tasa de error de caracteres con lstmeval
Juzga el modelo con datos que nunca vio en entrenamiento.
lstmeval --model data/myfont_checkpoint \
--traineddata ../tessdata_best/spa.traineddata \
--eval_listfile data/myfont-ground-truth/eval_files.txtVigila el CER en un conjunto reservado. Cuando deja de bajar —o empieza a subir mientras la pérdida de entrenamiento sigue cayendo— hay sobreajuste; detente y usa el checkpoint anterior.
Desplegar el modelo entrenado
Copia el traineddata, apunta el motor a él y prueba.
# Copia en un directorio tessdata
cp data/myfont.traineddata /usr/share/tesseract-ocr/5/tessdata/
# o define un prefijo personalizado
export TESSDATA_PREFIX=/ruta/a/tessdata
tesseract muestra.png stdout -l myfontPuedes combinar tu modelo con un idioma base, p. ej. -l myfont+spa. En Python, pasa el mismo valor a pytesseract; consulta la guía de Python.
Solución de problemas
| Síntoma | Causa | Solución |
|---|---|---|
| Cajas malas / ground truth desalineado | Métricas de fuente incorrectas o imágenes de línea demasiado grandes | Regenera con el --font y --ptsize correctos; revisa algunas imágenes a ojo. |
| Caracteres faltantes en la salida | Carácter ausente del unicharset | Añade los glifos a tu ground truth y reconstruye el unicharset. |
| La pérdida diverge / NaN | Tasa de aprendizaje demasiado alta | Baja LEARNING_RATE y reanuda desde un checkpoint anterior. |
| Sin memoria (OOM) | Lote demasiado grande para la RAM/GPU | Reduce BATCH_SIZE/el tamaño de red, o usa una máquina con más memoria. |
| El CER de validación sube mientras baja la pérdida | Sobreajuste | Detente antes, añade ground truth más variado o usa una tasa de aprendizaje menor. |
Preguntas frecuentes sobre entrenamiento
¿Puedo entrenar Tesseract sin compilarlo desde el código fuente?
No. Las herramientas de entrenamiento no están en los instaladores binarios; usa Linux o WSL2 con libtesseract-dev y el repositorio tesstrain.
¿Cuántas muestras necesito?
Unas 100–500 líneas para validar la canalización y 1.000–5.000 para producción. El ajuste fino necesita menos que entrenar desde cero.
¿Ajuste fino o desde cero?
Ajuste fino para una nueva fuente o vocabulario en una escritura existente; desde cero solo para una escritura genuinamente nueva.
¿Cuándo debo detener el entrenamiento?
Cuando el CER en validación deja de mejorar, no cuando la pérdida de entrenamiento se aplana. Esa brecha es sobreajuste.
¿Dónde va el modelo?
Copia <MODEL_NAME>.traineddata a un directorio tessdata (o define TESSDATA_PREFIX) y ejecuta tesseract image.png stdout -l myfont.