開発者ガイド

カスタムフォントとデータで
Tesseractを学習する（tesstrain、v5）。

tesstrainでTesseract 5モデルをファインチューニング・学習するための、実証済みで意思決定志向のガイド：ソースからのビルド、正解データの準備、make trainingの実行、重要変数の調整、lstmevalによるCER測定、traineddataのデプロイ。

TL;DR — 既存モデルのファインチューニング

対象の文字体系が既にサポートされているなら、ファインチューニングが最速の改善手段です。

bash
git clone https://github.com/tesseract-ocr/tesstrain.git
cd tesstrain && make tesseract-langdata
# 行画像 + .gt.txt を data/myfont-ground-truth/ に配置
make training MODEL_NAME=myfont START_MODEL=jpn

学習はバイナリインストーラーでは利用できません。LinuxまたはWSL2が必要です。ソースからのビルドはインストールをご覧ください。

意思決定ツリー：ファインチューニング vs 上位層のカット vs ゼロからの学習

適切な手法を選ぶことで、無駄な学習時間を何日も節約できます。

手法使う場面必要なデータ所要時間
ファインチューニング（FINETUNE_TYPE=1）同じ文字体系で、新しいフォントや専門用語1,000～5,000行数時間
上位層のカット（FINETUNE_TYPE=2）同じ文字体系で、字形が大きく異なる5,000～20,000行数時間～数日
ゼロから学習新しい文字体系や大きく異なるアルファベット50,000行以上数日

まず最も軽い手法から試し、評価し、CERが許容できない場合にのみ段階を上げてください。カスタムフォントの問題のほとんどはファインチューニングで解決します。

前提条件

学習にはパッケージ版バイナリではなく、ソースからのビルドが必要です。

bash
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   # langdata_lstm + tessdata_best を取得

正解データの準備

正解データとは、正確なテキストと対になる行画像のことです。

tesstrainはdata/<MODEL_NAME>-ground-truth/に1行1画像を期待し、それぞれに正確な転記を含む.gt.txtファイルが必要です。text2imageでテキストファイルとフォントから画像を生成し、langdata_lstmのsplit_training_text.pyで長いテキストを行に分割します。

bash
# コーパス + フォントから行画像を生成
text2image --text=corpus.txt \
  --outputbase=data/myfont-ground-truth/myfont \
  --font='My Custom Font' --fonts_dir=/usr/share/fonts \
  --ptsize=14

# text2image は .box ファイルも生成します。.gt.txt に変換してください
# （tesstrain/training/ に補助スクリプトあり。確認後にリネームでも可）

データ量の目安：パイプラインの検証に100～500行、本番用に1,000～5,000行。精度は生の量よりも、フォント・サイズ・字間・ノイズの多様性から生まれます。

フォントとunicharsetの選択

文字セットはモデルが見るすべてを網羅する必要があります。

学習の実行

1つのコマンドでMakefileパイプライン全体が動きます。

bash
make training \
  MODEL_NAME=myfont \
  START_MODEL=jpn \
  TESSDATA_PREFIX=../tessdata_best \
  MAX_ITERATIONS=10000
変数意味一般的な値
START_MODEL継続元のモデル（ファインチューニング）eng、jpn…
TESSDATA_PREFIX開始モデルを含むディレクトリ../tessdata_best
MAX_ITERATIONS学習ステップの上限10000～100000
LEARNING_RATEステップ幅。ファインチューニングでは小さいほど安全0.0001～0.001
FINETUNE_TYPE0 ゼロから、1 ファインチューニング、2 上位層カット1
NET_SPECネットワークアーキテクチャの指定既定のまま
RATIO_TRAIN学習／検証の分割比0.9
TARGET_ERROR_RATE早期終了のCER目標0.01

チェックポイント、stop_training、best と fast

評価：lstmevalによる文字誤り率

学習で一度も見ていないデータでモデルを評価します。

bash
lstmeval --model data/myfont_checkpoint \
  --traineddata ../tessdata_best/jpn.traineddata \
  --eval_listfile data/myfont-ground-truth/eval_files.txt

ホールドアウトセットのCERを監視します。下降が止まったとき、あるいは学習損失が下がり続けているのに上昇し始めたときは過学習です。停止して以前のチェックポイントを使います。

学習済みモデルのデプロイ

traineddataをコピーし、エンジンをそこに向けてテストします。

bash
# tessdata ディレクトリにコピー
cp data/myfont.traineddata /usr/share/tesseract-ocr/5/tessdata/
# または独自のプレフィックスを設定
export TESSDATA_PREFIX=/path/to/tessdata
tesseract sample.png stdout -l myfont

モデルをベース言語と組み合わせられます（例：-l myfont+jpn）。Pythonではpytesseractに同じ値を渡します。Pythonガイドをご覧ください。

トラブルシューティング

症状原因対処
ボックスがずれる／正解データの位置ずれフォントメトリクスが誤っている、または行画像が大きすぎる正しい--fontと--ptsizeで再生成し、いくつかの画像を目視確認します。
出力に文字が欠けるunicharsetに文字がない正解データに字形を追加し、unicharsetを再構築します。
損失が発散／NaN学習率が高すぎるLEARNING_RATEを下げ、以前のチェックポイントから再開します。
メモリ不足（OOM）バッチがRAM/GPUに対して大きすぎるBATCH_SIZEやネットワークサイズを減らすか、メモリの多いマシンを使います。
損失が下がるのに検証CERが上昇過学習早めに停止し、より多様な正解データを追加するか、学習率を下げます。

学習に関するFAQ

ソースからビルドせずにTesseractを学習できますか？

いいえ。学習ツールはバイナリインストーラーに含まれていません。libtesseract-devとtesstrainリポジトリを備えたLinuxまたはWSL2を使用してください。

サンプルはどれくらい必要ですか？

パイプラインの検証に約100～500行、本番に1,000～5,000行が目安です。ファインチューニングはゼロからの学習より少ないデータで済みます。

ファインチューニングとゼロからの学習、どちらを選ぶべきですか？

既存の文字体系で新しいフォントや専門用語が必要ならファインチューニングを。まったく新しい文字体系の場合のみゼロから学習します。

いつ学習を止めればよいですか？

学習損失が横ばいになったときではなく、ホールドアウト検証CERが改善しなくなったときです。その差が過学習です。

モデルはどこに置きますか？

<MODEL_NAME>.traineddataをtessdataディレクトリにコピー（またはTESSDATA_PREFIXを設定）し、tesseract image.png stdout -l myfontを実行します。