Introduction
Tesseract OCRで独自の学習モデルを作成しようとした時、誰もが一度は経験するであろう悪夢のようなシナリオがあります。それは、学習用の画像ファイルを読み込んだ後、ターミナルが沈黙し、プロセスが永遠に終わらない状態です。エラーメッセージは表示されず、ただ時間だけが過ぎていく…。この現象は、多くの開発者がTesseractの学習プロセスで経験する「通過儀礼」とも言えるものです。
この問題の原因は、ドキュメントに明記されていない、驚くほど直感に反する仕様や手順の欠落にあります。学習プロセスは非常に強力ですが、同時に unforgiving（容赦がない）な側面も持っており、一つの小さなミスが全体の失敗に繋がります。
この記事は、実際のトラブルシューティングセッションという「事件」を解決に導いた記録を基に、カスタムモデルの学習で99%の人がハマるであろう5つの大きな罠を特定し、その完全な解決策をステップ・バイ・ステップで解説するマニュアルです。このガイドを最後まで読めば、あなたはTesseract学習の最も厄介なハードルを乗り越え、確実に動作する自作モデルを手に入れることができるでしょう。
——————————————————————————–
1. 最大の罠：学習できない「fast」モデルを使っていませんか？
カスタムモデルの学習が失敗する最も一般的で、かつ最も気づきにくい原因は、ベースとして使用する公式モデルの選択ミスです。ここが多くの開発者が最初に躓くポイントです。多くのユーザーは、HomebrewなどでTesseractをインストールした際にデフォルトで入る軽量な「fast」モデルをそのまま使おうとしますが、これは推論（OCR実行）専用であり、学習には使えません。
この状態で学習を開始しようとすると、以下のような明確なエラーメッセージが表示されます。これは、あなたが学習不可能なモデルを使っているという動かぬ証拠です。
Error, jpn.lstm is an integer (fast) model, cannot continue training
なぜ「fast」モデルは学習できないのでしょうか？それは、「fast」モデルが推論速度を最大化するためにモデルの重みを整数に量子化（integer quantization）しているためです。この処理により精度情報の一部が失われるため、追加学習のベースとしては使用できません。学習には、浮動小数点数の重みを保持している「best」モデルが必須です。
解決策は非常にシンプルです。学習用に設計された、より高精度でサイズの大きい「best」モデルを明示的にダウンロードして使用します。
curl -L -o jpn.traineddata https://github.com/tesseract-ocr/tessdata_best/raw/main/jpn.traineddata
学習プロセスを開始する前に、必ずこの「best」モデルを使用しているか確認してください。これが、成功への第一歩であり、最も重要なチェック項目です。
2. 謎のエラー：「jpn.lstm」ファイルが見つからない問題
学習コマンドを実行したのに、今度は「.lstmファイルがない」というエラーに遭遇します。公式モデルをダウンロードしたはずなのになぜ？実は、これはTesseractの仕様に隠された巧妙な一手間が必要なサインです。
多くのチュートリアルではlstmtrainingコマンドの--continue_fromフラグで既存の.lstmファイルを指定するよう指示されていますが、公式の.traineddataファイルをダウンロードしても、その隣に.lstmファイルは存在しません。この問題の解決策は、直感に反するものです。実は、LSTMモデルのデータは.traineddataファイルの中に埋め込まれており、手動で抽出する必要があるのです。
なぜLSTMモデルが.traineddataに埋め込まれているのでしょうか？これは配布の便宜上のためです。OCRを実行するだけのユーザーは単一のファイルを扱えば済むからです。しかし、我々のようにモデルを学習する開発者にとっては、この一手間が必須となります。
以下のコマンドを実行することで、.traineddataファイルから.lstmファイルを生成できます。
combine_tessdata -e /path/to/your/jpn.traineddata jpn.lstm
Pro-Tip: 抽出が成功したかを確認するために、ls -lh jpn.lstm を実行してみましょう。ファイルサイズが10MB以上（bestモデルの場合）になっていれば成功です。
また、これに関連する落とし穴として、.traineddataファイルへのパス指定ミスがあります。特にApple Siliconを搭載した近年のmacOSでは、Homebrewでインストールした際のパスは/usr/local/share/tessdata/ではなく/opt/homebrew/share/tessdata/になっていることが多いため、注意が必要です。
3. 動かない原因はリストファイル？：「.png」と「.lstmf」の勘違い
学習用の中間ファイル（.lstmf）をすべて正常に生成できたにもかかわらず、lstmtrainingコマンドを実行しても学習が始まらない、という状況に陥ることがあります。このエラーは一見すると不可解ですが、原因は単純です。
そのミスとは、--train_listfileで指定するリストファイルが、本来指定すべき.lstmfファイルの一覧ではなく、元の画像ファイル（.png）の一覧になっていることです。Tesseractの学習プロセスは、.lstmfファイルが生成された後は、もはや元の画像ファイルやBoxファイルを必要としません。
学習フェーズでは、必ず.lstmfファイルへのパスが記述されたリストファイルを指定してください。以下のコマンドを使えば、カレントディレクトリ以下のすべての.lstmfファイルをリストアップしたテキストファイルを簡単に生成できます。
find "$(pwd)" -name "*.lstmf" > lstmf_files.txt
lstmtrainingコマンドを実行する前に、必ずリストファイルの中身を確認し、.lstmfファイルのパスが正しく記載されているかをチェックする習慣をつけましょう。
4. 学習完了、でも動かない：「Checkpoint」から最終モデルを生成する一手間
何時間もかかる学習プロセスが走り切り、ターミナルに「Finished!」の文字が表示された時、多くの人は「これで独自のOCRモデルが完成した」と安堵します。しかし、これは罠です。この時点で生成されているのは、OCRで直接使用できるモデルではなく、「チェックポイント」と呼ばれる学習の途中経過を保存したファイル群にすぎません。
これらのチェックポイントファイルを、Tesseractが実際に読み込んで使用できる最終的な.traineddataファイルに変換する、最後の仕上げ作業が必要です。この変換作業は、lstmtrainingコマンドに--stop_trainingフラグを追加して実行します。
ここで重要なのは、どのチェックポイントファイルを使うかです。学習プロセスでは複数のチェックポイントが生成され、ファイル名は <model_name>_<BCER>_<iteration>_<sample_count>.checkpoint という形式になっています。--continue_fromには、BCER（文字単位のエラー率）が最も低いファイルを選択してください。
この例では 0.667 が最小エラー率を示しているため、そのファイルから最終モデルを生成します。
lstmtraining \
--stop_training \
--continue_from output/jpn_from_existing_0.667_7_500.checkpoint \
--traineddata jpn.traineddata \
--model_output output/your_final_model.traineddata
この最後のステップを省略してしまうと、新しいモデルを使ってOCRを実行しようとしても、結果ファイルが0バイトになるなど、正常に動作しません。学習完了のメッセージに惑わされず、必ずこの最終モデル生成のプロセスを実行してください。
5. 地味だけど致命的：パス、フォルダ、入力ファイルの凡ミス集
最後に、上記4つの大きな罠ほど複雑ではありませんが、同じくらい致命的な結果を招く、よくある単純なミスをまとめました。
- 出力フォルダが存在しない:
lstmtrainingコマンドは、モデルの出力先フォルダを自動で作成してくれません。Error, model output cannot be written: No such file or directoryというエラーが出たら、単純に出力フォルダが存在しないだけです。コマンド実行前にmkdir outputを実行して、フォルダを作成しておきましょう。 - テスト画像が存在しない: 学習済みモデルをテストする際、
Error, cannot read input file test.pngというエラーが出ることがあります。これは文字通り、指定したテスト画像がカレントディレクトリに存在しないか、パスが間違っていることを示しています。入力画像には、必ず正しいフルパスを指定するようにしてください。 - 縦書きモデルの警告: OCRのテスト実行時に
Failed loading language 'jpn_vert'という警告が頻繁に表示されます。これはTesseractが内部的に縦書き用の日本語モデルを探そうとして見つからなかった、というだけの無害な警告です。横書きモデルを学習・使用している限り、このメッセージは無視して問題ありません。
——————————————————————————–
Conclusion
Tesseractの学習は、今回見てきたように、エラーメッセージが不親切な場面や、直感に反する手順が要求される場面の連続です。しかし、一つ一つの罠を理解し、その裏にあるTesseractの「作法」を学べば、それは非常に強力なツールに変わります。
このマニュアルが、あなたのモデル学習の旅を少しでもスムーズにする助けとなれば幸いです。さあ、独自の高精度OCRモデルが完成した今、あなたはその力でどんなユニークな文字認識の課題を解決しますか？