はじめに

クイックスタートと APIインストールオンライン OCRCode generator (EN)

モデルとパイプライン

PP-OCRv6 モデル対応言語PP-StructureV3PaddleOCR-VL

デプロイと連携

Serving & API (EN)PaddleOCR.js (EN)MCP server (EN)

トラブル対応と移行

トラブルシューティング2.x からの移行Releases (EN)

評価

Our benchmark (EN)Compare OCR tools (EN)License & cost (EN)

ツール

オンライン OCRインストールコマンド生成Code generator (EN)エラー解決ツール2.x → 3.x 変換言語コード検索

言語

English简体中文日本語オンラインで OCR
ドキュメント

PaddleOCR 3.7 クイックスタートと Python API

Python やコマンドラインから PaddleOCR を呼び出すのに必要な情報をまとめました。動作する最初のスクリプト、コンストラクタの全パラメータと実際に適用される既定値(ドキュメントとコードで食い違うものがあります)、結果オブジェクト、PDF、バッチ処理、CLI を解説します。

PaddleOCR 3.7.0 で確認済み更新日 14 分で読めます
このページの内容
  1. クイックスタート:最初の OCR
  2. 3 つのパイプラインの概要
  3. PaddleOCR() のパラメータ — 実際に適用される既定値
  4. predict():入力と呼び出しごとの上書き
  5. 結果オブジェクト
  6. バッチ処理、フォルダー、速度
  7. 単体モデルのクラスとカスタムモデル
  8. コマンドラインリファレンス
  9. ログ出力
  10. 次に読むページ
  11. よくある質問

30 秒でわかる要点:推論エンジンと PaddleOCR をインストールし(インストールガイド)、PaddleOCR().predict("image.png") を呼び出します。結果はそれぞれ辞書のように扱えるオブジェクトで、rec_texts・rec_scores・rec_boxes を読むか、save_to_json() や save_to_img() を呼び出します。Markdown・表・数式が必要な場合は、代わりに PPStructureV3 を使います。

クイックスタート:最初の OCR#

pythonfirst_ocr.py
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 ./output

GPU がなくても問題ありません。4 コアのテスト機では、PaddlePaddle 3.2.0 でレシート 1 枚あたり約 3.2 秒(ONNX Runtime では 2.0 秒)でした。全モデルの結果はベンチマーク (EN) をご覧ください。

3 つのパイプラインの概要#

パイプラインPython クラスCLI必要な extra得られるもの
テキスト OCR(PP-OCRv6)PaddleOCRpaddleocr ocrなしテキスト行、検出枠、信頼度
PP-StructureV3PPStructureV3paddleocr pp_structurev3[doc-parser]レイアウト・表・数式を含む Markdown/JSON
PaddleOCR-VLPaddleOCRVLpaddleocr 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

パラメータ実際の既定値役割
langNone → PP-OCRv6 medium言語コード(例:"en"、"japan"、"korean")。文字認識モデルを選びます。全 112 コード。
ocr_versionNone"PP-OCRv6"、"PP-OCRv5"、"PP-OCRv4"、"PP-OCRv3"。それ以外は ValueError になります。
text_detection_model_name / text_recognition_model_namePP-OCRv6_medium_det / _recモデルを直接指定します。small や tiny を使う唯一の方法です。lang/ocr_version より優先されます。
text_detection_model_dir / text_recognition_model_dirNoneローカルのフォルダーからモデルを読み込みます(オフライン環境やファインチューニング済みモデル)。
use_doc_orientation_classifyTrue最初にページ全体を 0/90/180/270° 回転補正します。
use_doc_unwarpingTrue最初に UVDoc で、湾曲したページや撮影したページを平らに補正します。座標が変わります。
use_textline_orientationTrue上下逆さのテキスト行(0°/180°)を検出します。
text_det_limit_side_len / text_det_limit_type64 / "min"テキスト検出前のリサイズ規則。"max" にすると長辺の上限になります。
text_det_thresh0.3テキスト確率マップに対する画素単位のしきい値。
text_det_box_thresh0.6検出枠の平均スコアがこの値を超えれば残します。薄い文字を拾うには下げます。
text_det_unclip_ratio1.5 ドキュメントでは 2.0検出枠の拡張率。文字が欠ける場合は上げます。
text_rec_score_thresh0.0この信頼度未満の認識結果を除外します(この値以上なら残る)。
text_recognition_batch_size6 ドキュメントでは 11 バッチで認識する行数。
textline_orientation_batch_size6 ドキュメントでは 11 バッチで向きを分類する行数。
return_word_boxFalse単語ごとの検出枠(text_word、text_word_boxes)も返します。
deviceNone(GPU があれば GPU 0、なければ CPU)"cpu"、"gpu"、"gpu:1"、"npu:0"…
engineNone(ほとんどの場合 PaddlePaddle)"paddle"、"paddle_static"、"paddle_dynamic"、"onnxruntime"、"transformers"。
enable_mkldnn / cpu_threadsTrue / 10PaddlePaddle の CPU 高速化(oneDNN)とスレッド数。
enable_hpi、use_tensorrt、precisionNone、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_classifyuse_doc_unwarpinguse_textline_orientation
スキャン、PDF、スクリーンショットFalseFalseFalse
平らなページをスマートフォンで撮影FalseFalseTrue
横向きや上下逆の可能性があるページTrueFalseTrue
反った本のページ、しわのあるレシートTrueTrueTrue
各前処理モデルの公式 CPU レイテンシ

画像 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
PaddleOCR の OCR パイプラインのドキュメント(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 は呼び出しごとに上書きできます。パイプラインを作り直さずに難しい画像を再処理したいときに便利です。

python
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 です(配列は省略)。

jsonoutput/receipt_res.json (from our run)
{
  "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_indexPDF 入力のときはページ番号、それ以外は null。
text_word、text_word_boxesreturn_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 倍高速でした。
  • 不要な前処理はオフにする(前述)。
python
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) の代わりになるものです。

python
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 と書きます。

bash
# 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

python
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 の公式ガイドには、すべてのパイプラインとモジュールが記載されています。その既定値が実際に同梱されている設定と異なる箇所は、上記で注記しています。

出典

  1. PaddleOCR 3.7.0 のソースコード:paddleocr/_pipelines/ocr.py(コンストラクタ、旧引数名の対応付け、ocr() の非推奨化)、paddleocr/_common_args.py(engine、device、未知の引数のエラー)、paddleocr/_cli.py(サブコマンド) — github.com/PaddlePaddle/PaddleOCR。
  2. 実際に適用される既定値:pip install paddleocr==3.7.0 でインストールされる PaddleX 3.7.2 の paddlex/configs/pipelines/OCR.yaml と paddlex/inference/pipelines/ocr/pipeline.py。
  3. 公式の OCR パイプラインガイド:docs/version3.x/pipeline_usage/OCR.en.md(パラメータの説明、受け付ける入力、出力ファイル)。
  4. 結果オブジェクトのメソッド:PaddleX の paddlex/inference/common/result/mixin.py と paddlex/inference/pipelines/ocr/result.py。
  5. ログ出力:logging.en.md と paddleocr/_env.py の比較。
  6. 私たちのテスト(2026-10-27、PaddleOCR 3.7.0、Linux、4 vCPU):save_to_json の実際の出力、use_doc_unwarping=True による座標のずれ、前処理のコスト。スクリプトはベンチマーク (EN) に掲載。
  7. 前処理モデルのレイテンシ:公式 OCR パイプラインガイドの表(Intel Xeon Gold 6271C CPU / NVIDIA T4)。
更新日 2026年10月27日·事実確認の方法