Module Usage¶

Python ライブラリとして YomiToku を利用する場合の利用方法について説明します。

Document Analyzer の利用¶

Document Analyzer は OCR およびレイアウト解析を実行し、それらの結果を統合した解析結果を返却します。段落、表の構造解析、抽出、図表の検知など様々なユースケースにご利用いただけます。pdfファイルを読み込む場合はload_pdf、画像ファイルを読み込む場合はload_imageを使用してください。load_imageは内部でOpenCVを使用しています。チャンネルはBGRであることに注意してください。

以下の 4 つのモデルがモジュール内で使われます。

Text Recognizer (文字認識)
Text Detector (文字検出)
Layout Parser (レイアウト解析)
Table Structure Recognizer (表構造認識)

demo/simple_document_analysis.py

import cv2

from yomitoku import DocumentAnalyzer
from yomitoku.data.functions import load_pdf

PATH_IMGE = "demo/samples/sample.pdf"
analyzer = DocumentAnalyzer(visualize=True, device="cuda")
# PDFファイルを読み込み
imgs = load_pdf(PATH_IMGE)

# 画像を読み込む場合はload_imageを使用
# imgs = load_image(PATH_IMGE)

for i, img in enumerate(imgs):
    results, ocr_vis, layout_vis = analyzer(img)
    # HTML形式で解析結果をエクスポート
    results.to_html(f"output_{i}.html", img=img)
    # 可視化画像を保存
    cv2.imwrite(f"output_ocr_{i}.jpg", ocr_vis)
    cv2.imwrite(f"output_layout_{i}.jpg", layout_vis)

analyzer.close()

オプション名	型	説明	補足
`visualize`	`bool`	処理結果の可視化を行うかどうかを指定します。	デバッグ用途でない場合は `False` を推奨します。`True` の場合、第 2 戻り値に OCR 結果、第 3 戻り値にレイアウト解析結果を返却します。`False` の場合は `None` を返却します。
`device`	`str`	処理に用いるデバイスを指定します。	デフォルトは `"cuda"` です。GPU が利用できない場合は、自動で `"cpu"` に切り替わります。
`configs`	`dict`	モジュールの処理のより詳細なパラメータを設定するために利用します。	詳細はモデルの詳細設定をご確認ください。
`license_key`	`str`	ライセンスキーを格納して、引数の値を認証に利用できます。	環境変数よりもこちらの引数の値を優先的に参照します。格納しない場合は、環境変数のキーを参照します。
`secret_key`	`str`	シークレットキーを格納して、引数の値を認証に利用できます。	環境変数よりもこちらの引数の値を優先的に参照します。格納しない場合は、環境変数のキーを参照します。
`device_token`	`str`	デバイストークンを格納して、引数の値を認証に利用できます。	環境変数よりもこちらの引数の値を優先的に参照します。格納しない場合は、環境変数のキーを参照します。
`ignore_ruby`	`bool`	ふりがな（ルビ）テキストを出力から除外するかどうかを指定します。	デフォルトは `False` です。
`ruby_threshold`	`float`	ルビ判定の閾値を指定します。行高さの中央値に対する比率で、この閾値未満のひらがな・カタカナのみのテキストをルビとみなします。	デフォルトは `2.0` です。`ignore_ruby=True` の場合のみ有効です。

DocumentAnalyzer の処理結果のエクスポートは以下に対応しています。

メソッド	出力形式
`to_json()`	JSON 形式 (*.json)
`to_html()`	HTML 形式 (*.html)
`to_csv()`	カンマ区切り CSV 形式 (*.csv)
`to_markdown()`	マークダウン形式 (*.md)

AI-OCR のみの利用¶

AI-OCR では、テキスト検知と検知したテキストに対して、認識処理を実行し、画像内の文字の位置と読み取り結果を返却します。

以下の 2 つのモデルがモジュール内で使われます。

Text Recognizer (文字認識)
Text Detector (文字検出)

demo/simple_ocr.py

import cv2

from yomitoku import OCR
from yomitoku.data.functions import load_pdf

ocr = OCR(visualize=True, device="cuda")
# PDFファイルを読み込み
imgs = load_pdf("demo/samples/sample.pdf")
for i, img in enumerate(imgs):
    results, ocr_vis = ocr(img)

    # JSON形式で解析結果をエクスポート
    results.to_json(f"output_{i}.json")
    cv2.imwrite(f"output_ocr_{i}.jpg", ocr_vis)

ocr.close()

オプション名	型	説明	補足
`visualize`	`bool`	処理結果の可視化を行うかどうかを指定します。	デバッグ用途でない場合は `False` を推奨します。`True` の場合、第 2 戻り値に OCR 結果を返却します。`False` の場合は `None` を返却します。
`device`	`str`	処理に用いるデバイスを指定します。（指定値: `cuda` \| `cpu` \| `mps`）	デフォルトは `"cuda"` です。GPU が利用できない場合は、自動で `"cpu"` に切り替わります。
`configs`	`dict`	モジュールの処理のより詳細なパラメータを設定するために利用します。	詳細はモデルの詳細設定をご確認ください。
`license_key`	`str`	ライセンスキーを格納して、引数の値を認証に利用できます。	環境変数よりもこちらの引数の値を優先的に参照します。格納しない場合は、環境変数のキーを参照します。
`secret_key`	`str`	シークレットキーを格納して、引数の値を認証に利用できます。	環境変数よりもこちらの引数の値を優先的に参照します。格納しない場合は、環境変数のキーを参照します。
`device_token`	`str`	デバイストークンを格納して、引数の値を認証に利用できます。	環境変数よりもこちらの引数の値を優先的に参照します。格納しない場合は、環境変数のキーを参照します。

OCRの処理結果のエクスポートは JSON 系形式(to_json())のみサポートしています。

Layout Analyzer のみの利用¶

Layout Analyzer では、テキスト検知と検知したテキストに対して、段落、図表の検知および表の構造解析処理 AI を実行し、文書内のレイアウト構造を解析します。

以下の 2 つのモデルがモジュール内で使われます

Layout Parser (レイアウト解析)
Table Structure Recognizer (表構造認識)

demo/simple_layout.py

import cv2

from yomitoku import LayoutAnalyzer
from yomitoku.data.functions import load_pdf

analyzer = LayoutAnalyzer(visualize=True, device="cuda")
# PDFファイルを読み込み
imgs = load_pdf("demo/sample.pdf")
for i, img in enumerate(imgs):
    results, layout_vis = analyzer(img)
    # JSON形式で解析結果をエクスポート
    results.to_json(f"output_{i}.json")
    cv2.imwrite(f"output_layout_{i}.jpg", layout_vis)

analyzer.close()

オプション名	型	説明	補足
`visualize`	`bool`	処理結果の可視化を行うかどうかを指定します。	デバッグ用途でない場合は `False` を推奨します。`True` の場合、第 2 戻り値にレイアウト解析結果を返却します。`False` の場合は `None` を返却します。
`device`	`str`	処理に用いるデバイスを指定します。（指定値: `cuda` \| `cpu` \| `mps`）	デフォルトは `"cuda"` です。GPU が利用できない場合は、自動で `"cpu"` に切り替わります。
`configs`	`dict`	モジュールの処理のより詳細なパラメータを設定するために利用します。	詳細はモデルの詳細設定をご確認ください。
`license_key`	`str`	ライセンスキーを格納して、引数の値を認証に利用できます。	環境変数よりもこちらの引数の値を優先的に参照します。格納しない場合は、環境変数のキーを参照します。
`secret_key`	`str`	シークレットキーを格納して、引数の値を認証に利用できます。	環境変数よりもこちらの引数の値を優先的に参照します。格納しない場合は、環境変数のキーを参照します。
`device_token`	`str`	デバイストークンを格納して、引数の値を認証に利用できます。	環境変数よりもこちらの引数の値を優先的に参照します。格納しない場合は、環境変数のキーを参照します。

LayoutAnalyzerの処理結果のエクスポートは JSON 系形式(to_json())のみサポートしています。

モデルの詳細設定¶

Config を与えることで、より細かい振る舞いを調整できます。モデルに対して、以下のパラメータを設定可能です。

オプション名	型	説明
`model_name`	`str`	使用するモデルの名前を指定します。
`path_cfg`	`str`	ハイパーパラメータが記述された config ファイルのパスを入力します。
`device`	`str`	推論に使用するデバイスを指定します。（指定値: `cuda` \| `cpu` \| `mps`）
`visualize`	`bool`	可視化処理を実施するかどうかを指定します。
`from_pretrained`	`bool`	Pretrained モデル（学習済みモデル）を使用するかどうかを指定します。
`infer_onnx`	`bool`	PyTorch の代わりに ONNX Runtime を使用して推論するかどうかを指定します。

サポートされるモデル名(`model_name`)¶

カテゴリ	モデル名	バージョン	最大文字列長	対応文字種	特長・説明
テキスト認識	`parseqv3`	v1.3.0	100文字	活字 / 手書き	精度に最適化されたモデル。一般的な文書のOCRに高精度対応。
テキスト認識	`parseqv4`	v1.4.0	100文字	活字 / 手書き / 旧字 / 異体字	多様な日本語文字に対応した高精度モデル。旧字・異体字を含む文書に最適。（★ 標準）
テキスト認識	`parseqv4-short`	v1.4.0	75文字	活字 / 手書き / 旧字 / 異体字	処理速度と精度のバランスを重視したモデル。
テキスト認識	`parseqv4-tiny`	v1.4.0	50文字	活字 / 手書き / 旧字 / 異体字	CPU推論向けに最適化された高速モデル。軽量かつ高い汎用性。
テキスト認識	`parseqv4-large`	v1.6	100文字	活字 / 手書き / 旧字 / 異体字	大規模モデルによる高精度認識。言語モデルによる補正が強く、細部の文字・縦書き・記号の読み取り精度が向上。
テキスト検出	`dbnet`	v1.0.0	—	活字	活字文書の検出に最適化されたモデル。
テキスト検出	`dbnetv2`	v1.2.0	—	活字 / 手書き	活字と手書き文字の両方の検出に対応したモデル。
テキスト検出	`dbnetv2_1`	v1.6	—	活字 / 手書き	dbnetv2の改良版。細部の文字・縦書きテキスト・記号の検出精度を向上させたモデル。（★ 標準）

おすすめの組み合わせ

精度を最優先にしたい parseqv4-large + dbnetv2_1
活字のみの文書を効率と精度をバランスよく読み取りたい parseqv4-short + dbnetv2_1
CPUで効率的に手書きと活字が混在する文書を読み取りたい parseqv4-tiny + dbnetv2_1

Config の記述方法¶

Config は辞書形式で与えます。Config を与えることでモデルごとに異なるデバイスで処理を実行したり、詳細のパラメータの設定が可能です。

例えば以下のような Config を与えると、OCR 処理は GPU で実行し、レイアウト解析機能は CPU で実行します。

from yomitoku import DocumentAnalyzer

if __name__ == "__main__":
    configs = {
        "ocr": {
            "text_detector": {
                "device": "cuda",
            },
            "text_recognizer": {
                "device": "cuda",
            },
        },
        "layout_analyzer": {
            "layout_parser": {
                "device": "cpu",
            },
            "table_structure_recognizer": {
                "device": "cpu",
            },
        },
    }

    DocumentAnalyzer(configs=configs)

REST API サーバーとしての利用¶

Document Analyzer は REST API サーバーとして起動し、HTTP 経由で利用することも可能です。

uv pip install -e ".[server]"
yomitoku_server document_analyzer [--host 0.0.0.0] [--port 8000] [--device cuda]

サーバー起動後、POST /invocations エンドポイントに画像や PDF のバイナリデータを送信することで解析結果を取得できます。

curl -X POST http://localhost:8000/invocations \
     -H "Content-Type: image/jpeg" \
     --data-binary @sample.jpg

Docker を利用したデプロイにも対応しています。詳しくはサーバーページを参照してください。

YAML ファイルでのパラメータの定義¶

Config に YAML ファイルのパスを与えることで、推論時の細部のパラメータの調整が可能です。YAML ファイルの例はリポジトリ内のconfigsディレクトリ内にあります。モデルのネットワークのパラメータは変更できませんが、後処理のパラメータや入力画像のサイズなどは一部変更が可能です。変更可能なパラメータについてはModel Configをご確認ください。

例えば、以下のように Text Detector の後処理の閾値を YAML ファイルに定義し、Config にその YAML ファイルのパスを設定することができます。Config ファイルはすべてのパラメータを記載する必要はなく、変更が必要なパラメータのみの記載が可能です。

text_detector.yamlの記述

post_process:
  thresh: 0.1
  unclip_ratio: 2.5

以下のように YAML ファイルのパスを Config に格納可能です。

demo/setting_document_anaysis.py

from yomitoku import DocumentAnalyzer
from yomitoku.data.functions import load_pdf

# 設定ファイルを指定してDocumentAnalyzerを初期化
configs = {"ocr": {"text_detector": {"path_cfg": "demo/text_detector.yaml"}}}

analyzer = DocumentAnalyzer(configs=configs, visualize=True, device="cuda")

PATH_IMGE = "demo/samples/sample.pdf"

imgs = load_pdf(PATH_IMGE)

for i, img in enumerate(imgs):
    analyzer(img)