このページの内容
30 秒でわかる要点:推論エンジンと PaddleOCR をインストールし(インストールガイド)、PaddleOCR().predict("image.png") を呼び出します。結果はそれぞれ辞書のように扱えるオブジェクトで、rec_texts・rec_scores・rec_boxes を読むか、save_to_json() や save_to_img() を呼び出します。Markdown・表・数式が必要な場合は、代わりに PPStructureV3 を使います。
クイックスタート:最初の OCR#
from paddleocr import PaddleOCR
ocr = PaddleOCR(
use_doc_orientation_classify=False, # skip page-rotation model (clean scans)
use_doc_unwarping=False, # skip page-flattening model (flat pages)
use_textline_orientation=False, # skip upside-down line detection
)
for res in ocr.predict("receipt.jpg"):
res.print() # pretty-print every field
res.save_to_img("output") # output/receipt_ocr_res_img.jpg with boxes drawn
res.save_to_json("output") # output/receipt_res.json最初の呼び出しで PP-OCRv6 medium(テキスト検出+文字認識)が ~/.paddlex/official_models にダウンロードされ、以降はすべてオフラインで動作します。ターミナルから同じことを行うには次のようにします。
paddleocr ocr -i receipt.jpg --use_doc_orientation_classify False --use_doc_unwarping False --use_textline_orientation False --save_path ./outputGPU がなくても問題ありません。4 コアのテスト機では、PaddlePaddle 3.2.0 でレシート 1 枚あたり約 3.2 秒(ONNX Runtime では 2.0 秒)でした。全モデルの結果はベンチマーク (EN) をご覧ください。
3 つのパイプラインの概要#
| パイプライン | Python クラス | CLI | 必要な extra | 得られるもの |
|---|---|---|---|---|
| テキスト OCR(PP-OCRv6) | PaddleOCR | paddleocr ocr | なし | テキスト行、検出枠、信頼度 |
| PP-StructureV3 | PPStructureV3 | paddleocr pp_structurev3 | [doc-parser] | レイアウト・表・数式を含む Markdown/JSON |
| PaddleOCR-VL | PaddleOCRVL | paddleocr doc_parser | [doc-parser] | 視覚言語モデルによる Markdown/JSON |
このほかにも、印影認識、表認識、数式認識、PP-ChatOCRv4 による重要情報抽出、PP-DocTranslation などのパイプラインや、TextDetection・TextRecognition といった単体モデルのクラスがあります。すべての一覧は CLI の節にあります。1
PaddleOCR() のパラメータ — 実際に適用される既定値#
PaddleOCR.__init__ の OCR 関連の引数はすべて既定値が None で、これは「PaddleX のパイプライン設定の値を使う」という意味です。つまり実際の既定値は PaddleOCR のシグネチャではなく PaddleX の OCR.yaml にあり、そのうち 3 か所は公式ドキュメントの記載と異なります。12
| パラメータ | 実際の既定値 | 役割 |
|---|---|---|
lang | None → PP-OCRv6 medium | 言語コード(例:"en"、"japan"、"korean")。文字認識モデルを選びます。全 112 コード。 |
ocr_version | None | "PP-OCRv6"、"PP-OCRv5"、"PP-OCRv4"、"PP-OCRv3"。それ以外は ValueError になります。 |
text_detection_model_name / text_recognition_model_name | PP-OCRv6_medium_det / _rec | モデルを直接指定します。small や tiny を使う唯一の方法です。lang/ocr_version より優先されます。 |
text_detection_model_dir / text_recognition_model_dir | None | ローカルのフォルダーからモデルを読み込みます(オフライン環境やファインチューニング済みモデル)。 |
use_doc_orientation_classify | True | 最初にページ全体を 0/90/180/270° 回転補正します。 |
use_doc_unwarping | True | 最初に UVDoc で、湾曲したページや撮影したページを平らに補正します。座標が変わります。 |
use_textline_orientation | True | 上下逆さのテキスト行(0°/180°)を検出します。 |
text_det_limit_side_len / text_det_limit_type | 64 / "min" | テキスト検出前のリサイズ規則。"max" にすると長辺の上限になります。 |
text_det_thresh | 0.3 | テキスト確率マップに対する画素単位のしきい値。 |
text_det_box_thresh | 0.6 | 検出枠の平均スコアがこの値を超えれば残します。薄い文字を拾うには下げます。 |
text_det_unclip_ratio | 1.5 ドキュメントでは 2.0 | 検出枠の拡張率。文字が欠ける場合は上げます。 |
text_rec_score_thresh | 0.0 | この信頼度未満の認識結果を除外します(この値以上なら残る)。 |
text_recognition_batch_size | 6 ドキュメントでは 1 | 1 バッチで認識する行数。 |
textline_orientation_batch_size | 6 ドキュメントでは 1 | 1 バッチで向きを分類する行数。 |
return_word_box | False | 単語ごとの検出枠(text_word、text_word_boxes)も返します。 |
device | None(GPU があれば GPU 0、なければ CPU) | "cpu"、"gpu"、"gpu:1"、"npu:0"… |
engine | None(ほとんどの場合 PaddlePaddle) | "paddle"、"paddle_static"、"paddle_dynamic"、"onnxruntime"、"transformers"。 |
enable_mkldnn / cpu_threads | True / 10 | PaddlePaddle の CPU 高速化(oneDNN)とスレッド数。 |
enable_hpi、use_tensorrt、precision | None、False、"fp32" | 高性能推論、TensorRT、"fp16"。 |
これ以外のキーワード引数は ValueError: Unknown argument: … になります。2.x の引数名のうち 11 個(use_angle_cls、det_db_thresh、rec_model_dir など)は、非推奨の警告付きで PaddleOCR が引き続き受け付けますが、use_gpu や show_log などは受け付けません。すべての一覧は移行ガイドにあります。1
3 つの前処理モデルは有効のままにすべきか#
PaddleOCR() は既定で、文字認識の前にページ単位のモデル 2 つ(向き補正と UVDoc による歪み補正)と行単位のモデル 1 つを実行します。撮影したページ、回転したページ、湾曲したページには効果がありますが、きれいなスキャンやスクリーンショットでは時間がかかるだけです。入力が平らで正しい向きなら(本サイトの例はすべてそうです)オフにし、そうでない場合は必要なものだけをオンにしてください。
| 入力の種類 | use_doc_orientation_classify | use_doc_unwarping | use_textline_orientation |
|---|---|---|---|
| スキャン、PDF、スクリーンショット | False | False | False |
| 平らなページをスマートフォンで撮影 | False | False | True |
| 横向きや上下逆の可能性があるページ | True | False | True |
| 反った本のページ、しわのあるレシート | True | True | True |
画像 1 枚あたりのミリ秒、高性能モード、Intel Xeon Gold 6271C。PaddleOCR のドキュメントでの公表値。短いほど低コスト。
| モデル | CPU ms |
|---|---|
| テキスト行の向き(PP-LCNet_x1_0_textline_ori) | 2.98 ms |
| ページの向き(PP-LCNet_x1_0_doc_ori) | 1.19 ms |
| ページの歪み補正(UVDoc) | 869.82 ms |
docs/version3.x/pipeline_usage/OCR.en.md)とモジュールのドキュメント。ベンダー公表値。2 つの向き分類モデルはほぼコストがかかりません。高コストなのは UVDoc による歪み補正で、公式の数値ではサーバー CPU で画像 1 枚あたり約 0.9 秒かかり、さらに座標も変わります(次の節)。1 つだけオフにするなら、use_doc_unwarping をオフにしてください。
注意:歪み補正で座標が変わる#
use_doc_unwarping=True(既定値)のとき、テキスト検出は平らに補正した後の画像に対して行われ、検出枠もすべてその画像の座標で返されます。同じレシートを両方の設定で処理したところ、最初の行は歪み補正ありで [[119, 11], [507, 8], [507, 46], [120, 49]]、なしで [[128, 55], [489, 55], [489, 82], [128, 82]] でした。前者を元の画像に描画すると、検出枠がずれた位置に表示されます。6
歪み補正をオフにするか、結果に含まれる前処理後の画像 res.img["preprocessed_img"] に描画してください(文書の前処理が実行された場合に存在します。私たちの確認では、その場合 res.img に ocr_res_img と preprocessed_img の 2 つのキーがありました)。46
predict():入力と呼び出しごとの上書き#
predict(input) は結果のリストを返し、predict_iter(input) は結果を 1 つずつ返します。後者なら、長い PDF や大きなフォルダーでもメモリ使用量が増えません。input に指定できるのは次のとおりです。3
- 画像(
.jpg、.pngなど)または PDF のパスや URL — PDF は 1 ページが 1 つの結果になり、page_indexが設定されます。 - 画像の入ったディレクトリ(ディレクトリ内の PDF には非対応)
- numpy 配列(
cv2.imreadと同じ BGR) - 上記のリスト
テキスト検出・文字認識のしきい値、3 つの前処理スイッチ、return_word_box は呼び出しごとに上書きできます。パイプラインを作り直さずに難しい画像を再処理したいときに便利です。
res = ocr.predict("faded_label.jpg", text_det_box_thresh=0.4, text_det_unclip_ratio=2.0)[0]コンストラクタで無効にしたモデルを、predict() の時点で有効にすることはできません。PaddleOCR(use_textline_orientation=False) で作成したインスタンスで predict(..., use_textline_orientation=True) を呼ぶと、エラーがログに出力され、結果の代わりに {"error": ...} が返ります。2
結果オブジェクト#
各結果は dict のサブクラス(OCRResult)なので res["rec_texts"] のようにアクセスでき、ヘルパーメソッドも備えています。以下は、PaddleOCR 3.7.0 が私たちのテスト用レシートに対して実際に書き出した JSON です(配列は省略)。
{
"input_path": "samples/receipt.png",
"page_index": null,
"model_settings": {"use_doc_preprocessor": true, "use_textline_orientation": true},
"doc_preprocessor_res": {"model_settings": {"use_doc_orientation_classify": true, "use_doc_unwarping": true}, "angle": 0},
"dt_polys": [[[119, 11], [507, 8], [507, 46], [120, 49]], "…"],
"text_det_params": {"limit_side_len": 64, "limit_type": "min", "thresh": 0.3,
"max_side_limit": 4000, "box_thresh": 0.6, "unclip_ratio": 1.5},
"text_type": "general",
"textline_orientation_angles": [0, 0, "…"],
"text_rec_score_thresh": 0.0,
"return_word_box": false,
"rec_texts": ["HARBOR STREET COFFEE", "214 Harbor Street, Portland ME", "…"],
"rec_scores": [0.9999498128890991, 0.9985201954841614, "…"],
"rec_polys": [[[119, 11], [507, 8], [507, 46], [120, 49]], "…"],
"rec_boxes": [[119, 8, 507, 49], [120, 57, 506, 87], "…"]
}| フィールド | 意味 |
|---|---|
rec_texts | 認識したテキスト。1 行につき 1 つの文字列(スコアが text_rec_score_thresh 以上の行のみ)。 |
rec_scores | 各行の信頼度スコア(0〜1)。 |
rec_polys | 残った各行の 4 点ポリゴン(回転したテキストにも対応)。 |
rec_boxes | 残った各行の軸平行な [x_min, y_min, x_max, y_max]。Python では形状 (n, 4) の numpy 配列。 |
dt_polys | スコアによる除外前の、検出されたすべてのポリゴン。 |
textline_orientation_angles | 各行の 0 または 1(180°)。分類器がオフのときは −1。 |
doc_preprocessor_res | 適用されたページの回転(angle は 0〜3 で 0/90/180/270°、オフのときは −1)。 |
page_index | PDF 入力のときはページ番号、それ以外は null。 |
text_word、text_word_boxes | return_word_box=True のときのみ。 |
メソッドは print(json_format=False, indent=4, ensure_ascii=False)、save_to_json(path)({name}_res.json を書き出し)、save_to_img(path)({name}_ocr_res_img.{ext} を書き出し)、save_all(path) で、プロパティとして json、str、img があります。なお、公式ドキュメントでは print の引数名が format_json となっていますが、コードでは json_format です。4
よく使うレシピ#
res = ocr.predict("invoice.png")[0]
for text, score, box in zip(res["rec_texts"], res["rec_scores"], res["rec_boxes"]):
if score >= 0.80:
x1, y1, x2, y2 = box.tolist()
print(f"{score:.2f} {text} @ ({x1},{y1})-({x2},{y2})")res = ocr.predict("page.png")[0]
lines = sorted(zip(res["rec_boxes"].tolist(), res["rec_texts"]), key=lambda t: (t[0][1], t[0][0]))
print("\n".join(text for _, text in lines))from paddleocr import PaddleOCR
ocr = PaddleOCR(use_doc_orientation_classify=False, use_doc_unwarping=False)
with open("report.txt", "w", encoding="utf-8") as f:
for res in ocr.predict_iter("report.pdf"): # one result per page
f.write(f"--- page {res['page_index'] + 1} ---\n")
f.write("\n".join(res["rec_texts"]) + "\n")import cv2
img = cv2.imread("photo.jpg") # BGR numpy array
res = ocr.predict(img)[0]「上から順に」の並べ替えは、1 段組みのテキスト向けの簡易的な方法です。複数段組みのページ、表、正確な読み順が必要な場合は、レイアウトから読み順を算出する PP-StructureV3 を使ってください。
バッチ処理、フォルダー、速度#
- インスタンスは使い回す。
PaddleOCR()の作成時にモデルが読み込まれます。作成は 1 回だけにして、predictを何度も呼び出してください。 - フォルダーやリストを渡す。Python でループするより効率的です。大量の入力には
predict_iterを使います。 - ハードウェアに合ったティアを選ぶ。私たちの CPU では small が medium より 3.3〜3.7 倍速く、誤りは 124 項目中 2 つ多いだけでした。モデルガイド。
- CPU では ONNX Runtime を試す(
engine="onnxruntime")。私たちのテストでは PP-OCRv6 で 1.4〜1.5 倍高速でした。 - 不要な前処理はオフにする(前述)。
ocr = PaddleOCR(
text_detection_model_name="PP-OCRv6_small_det",
text_recognition_model_name="PP-OCRv6_small_rec",
use_doc_orientation_classify=False, use_doc_unwarping=False, use_textline_orientation=False,
engine="onnxruntime",
)
for res in ocr.predict_iter("scans/"):
res.save_to_json("output")単体モデルのクラスとカスタムモデル#
3.x では各モデルが独立したクラスとして公開されています。2.x の ocr(img, det=False) や ocr(img, rec=False) の代わりになるものです。
from paddleocr import TextDetection, TextRecognition
det = TextDetection(model_name="PP-OCRv6_medium_det")
for res in det.predict("receipt.jpg"):
print(res["dt_polys"], res["dt_scores"]) # boxes and their scores
rec = TextRecognition(model_name="PP-OCRv6_medium_rec")
for res in rec.predict("cropped_line.png"):
print(res["rec_text"], res["rec_score"])ファインチューニングしたモデルやエクスポートしたモデルは、*_model_dir 引数で読み込みます。例:PaddleOCR(text_recognition_model_dir="./my_rec_model")。
コマンドラインリファレンス#
3.x の CLI はサブコマンド方式です。2.x の書き方(paddleocr --image_dir x.jpg --use_angle_cls true)はもう使えません。1
| 種類 | サブコマンド |
|---|---|
| パイプライン | ocr、pp_structurev3、doc_parser(PaddleOCR-VL)、doc_preprocessor、table_recognition_v2、seal_recognition、formula_recognition_pipeline、doc_understanding、pp_chatocrv4_doc、pp_doctranslation |
| 単体モデル | text_detection、text_recognition、textline_orientation_classification、doc_img_orientation_classification、text_image_unwarping、layout_detection、table_structure_recognition、table_cells_detection、table_classification、formula_recognition、seal_text_detection、chart_parsing、doc_vlm |
| ユーティリティ | install_hpi_deps {cpu,gpu,npu}、install_genai_server_deps {vllm,sglang,fastdeploy}、genai_server、doc2md、api |
パイプラインのフラグは Python のパラメータ名と同じで、真偽値は True/False と書きます。
# OCR a folder of scans on GPU 0 with the small tier, results to ./out
paddleocr ocr -i ./scans --device gpu:0 \
--text_detection_model_name PP-OCRv6_small_det \
--text_recognition_model_name PP-OCRv6_small_rec \
--use_doc_orientation_classify False --use_doc_unwarping False \
--save_path ./out
# Korean, CPU, ONNX Runtime engine
paddleocr ocr -i sign.jpg --lang korean --engine onnxruntime
# A PDF to Markdown with PP-StructureV3
paddleocr pp_structurev3 -i report.pdf --save_path ./out
# Help for any subcommand
paddleocr ocr --helpログ出力#
PaddleOCR のログは単一のロガー paddleocr.logger から出力され、既定のレベルは ERROR です。そのため、何かが失敗しない限り何も表示されません。レベルを上げたりファイルに出力したりするには、次のようにします。5
import logging
from paddleocr import logger
logger.setLevel(logging.INFO)
logger.addHandler(logging.FileHandler("paddleocr.log"))PaddleOCR にロガーをまったく設定させないようにするには、ドキュメントでは DISABLE_AUTO_LOGGING_CONFIG=1 を設定するとされていますが、コードが読むのは PADDLEOCR_DISABLE_AUTO_LOGGING_CONFIG=1 です。接頭辞付きの名前を使ってください。5 PaddleX が出力する緑色の「Creating model」メッセージは PaddleX 独自のロガーによるもので、この設定の影響を受けません。
次に読むページ#
PP-StructureV3#
PDF やスキャン画像を、表や数式を含む Markdown に変換。
サービングと API (EN)#
任意のパイプラインを HTTP で公開、またはホスト型 API を利用。
トラブルシューティング#
エラーメッセージを貼り付けて、検証済みの対処法を確認。
コード生成 (EN)#
必要なオプションだけを含むスクリプトを作成。
よくある質問#
ocr() と predict() の違いは何ですか?
ocr() は 2.x のメソッド名です。3.x でも非推奨のエイリアスとして残っており、predict() と同じ結果オブジェクトを返しますが、cls=、det=、rec= は受け付けません。私たちのテストでは、ocr(img, cls=True) が TypeError: PaddleOCR.predict() got an unexpected keyword argument 'cls' になりました。predict()(または predict_iter())を使い、結果オブジェクトからフィールドを読み出してください。
PaddleOCR の結果からテキストだけを取り出すには?
"\n".join(res["rec_texts"]) です。各要素が検出された 1 行で、検出順に並んでいます。
PaddleOCR は PDF を直接読めますか?
はい。PDF のパスを predict() または predict_iter() に渡すと、1 ページが 1 つの結果になり、page_index が設定されます。レイアウトや表を含む Markdown として出力したい場合は PP-StructureV3 を使ってください。
画像に描画すると検出枠の位置がずれるのはなぜですか?
おそらく use_doc_unwarping が有効(既定値)になっており、座標が平らに補正された画像を基準にしているためです。オフにするか、res.img["preprocessed_img"] に描画してください。
PP-OCRv6 の small や tiny を使うには?
text_detection_model_name="PP-OCRv6_small_det" と text_recognition_model_name="PP-OCRv6_small_rec" の両方を指定します。lang と ocr_version で選ばれるのは常に medium です。なお、tiny は日本語に対応していません。
すべてのパラメータを網羅した PaddleOCR の API リファレンスはありますか?
このページは OCR パイプラインを対象としています。paddleocr.ai の公式ガイドには、すべてのパイプラインとモジュールが記載されています。その既定値が実際に同梱されている設定と異なる箇所は、上記で注記しています。
出典
- PaddleOCR 3.7.0 のソースコード:
paddleocr/_pipelines/ocr.py(コンストラクタ、旧引数名の対応付け、ocr()の非推奨化)、paddleocr/_common_args.py(engine、device、未知の引数のエラー)、paddleocr/_cli.py(サブコマンド) — github.com/PaddlePaddle/PaddleOCR。 - 実際に適用される既定値:
pip install paddleocr==3.7.0でインストールされる PaddleX 3.7.2 のpaddlex/configs/pipelines/OCR.yamlとpaddlex/inference/pipelines/ocr/pipeline.py。 - 公式の OCR パイプラインガイド:docs/version3.x/pipeline_usage/OCR.en.md(パラメータの説明、受け付ける入力、出力ファイル)。
- 結果オブジェクトのメソッド:PaddleX の
paddlex/inference/common/result/mixin.pyとpaddlex/inference/pipelines/ocr/result.py。 - ログ出力:logging.en.md と
paddleocr/_env.pyの比較。 - 私たちのテスト(2026-10-27、PaddleOCR 3.7.0、Linux、4 vCPU):
save_to_jsonの実際の出力、use_doc_unwarping=Trueによる座標のずれ、前処理のコスト。スクリプトはベンチマーク (EN) に掲載。 - 前処理モデルのレイテンシ:公式 OCR パイプラインガイドの表(Intel Xeon Gold 6271C CPU / NVIDIA T4)。