PaddleOCR 繁體中文完全指南：從場景 OCR 到文檔 AI 解析的開發者實戰手冊

PaddleOCR 是基於 PaddlePaddle 的開源 OCR 工具包與文檔 AI 引擎，核心能力是將 PDF 與圖像轉換為結構化、對 LLM 友好的 JSON/Markdown 數據。本文以官方 README（繁體中文版）為骨架，結合本倉庫源碼與產線使用文檔，系統講解其文檔解析 VLM、通用多語言文本識別、產線架構與快速上手路徑，讀者讀完可掌握從安裝、命令行調用、Python API 到模型選型與推理引擎切換的完整實戰方案。

項目定位：連接圖像/PDF 與大模型的中間層

PaddleOCR 的設計目標不僅是傳統意義上的「文字識別」，而是成為 RAG（檢索增強生成）與 Agentic 應用的核心基礎元件：將雜亂的文檔視覺信息轉化為結構化數據，供 Dify、RAGFlow、Cherry Studio 等 AI 智能體生態直接消費。從官方 README 的定位看，它覆蓋兩條主線：

• 文檔智能解析（面向大模型）：以 PaddleOCR-VL 系列視覺語言模型與 PP-StructureV3 產線為代表，輸出帶版面結構的 Markdown/JSON。
• 通用場景 OCR：以 PP-OCRv6 為代表的輕量級多語言文本檢測與識別流水線，覆蓋證件、街景、書籍、工業零部件等自然場景。

從倉庫源碼看，paddleocr/init.py 對外導出了一整套可直接使用的類：PaddleOCR、PaddleOCRVL、PPStructureV3、PPDocTranslation、DocUnderstanding、DocVLM、TextDetection、TextRecognition 等，並提供同步/異步 API 客戶端（PaddleOCRClient、AsyncPaddleOCRClient）與 doc2md_convert 辦公文檔轉換工具，可見其「產線 + 單模塊 + API 服務」三層能力布局。

核心特性一：智能文檔解析——面向大模型的結構化輸出

PaddleOCR-VL 系列：輕量級文檔解析視覺語言模型

官方 README 重點介紹了 PaddleOCR-VL-1.6（0.9B），這是一款面向文檔解析的輕量級 VLM，支持以 Markdown 和 JSON 格式輸出結構化結果，官方聲稱在 OmniDocBench v1.6 上達到 96.3% 精度，並在古籍、生僻字、印章、圖表等場景能力顯著增強。

源碼側，paddleocr/_pipelines/paddleocr_vl.py 中的 PaddleOCRVL 類給出了更精確的版本與配置信息：

• pipeline 版本：支持 v1、v1.5、v1.6，默認 v1.6，分別映射到 PaddleOCR-VL、PaddleOCR-VL-1.5、PaddleOCR-VL-1.6 產線；
• VL 推理後端：支持 native（本地原生推理）、vllm-server、sglang-server、fastdeploy-server、mlx-vlm-server、llama-cpp-server 六種後端，可通過 vl_rec_backend 與 vl_rec_server_url 配置，這與 README 中「基於定制版 vLLM 運行時，支持 OpenAI 兼容服務化調用」的 HPD-Parsing 描述相互印證；
• 佈局與識別開關：use_layout_detection、use_chart_recognition、use_seal_recognition、use_ocr_for_image_block 等參數控制產線行為；
• 解碼參數：temperature、top_p、repetition_penalty、max_new_tokens、min_pixels/max_pixels 等與主流 VLM 推理參數一致，便於精度與速度的平衡調節。

PP-StructureV3：帶細粒度坐標的版面結構分析

與端到端的 VLM 不同，PP-StructureV3 採用模塊化產線架構，官方文檔指出它能提供更細粒度的坐標信息（表格單元格坐標、文本坐標等）。從 paddleocr/_pipelines/pp_structurev3.py 的構造函數可以看出其模塊構成：

模塊組	參數前綴	作用
文檔預處理	doc_orientation_classify_*、doc_unwarping_*	方向分類、圖像矯正
版面與區域	layout_detection_*、region_detection_*	版面結構分析、區域檢測
文本識別	text_detection_*、textline_orientation_*、text_recognition_*	檢測、行方向分類、識別
表格識別	table_classification_*、wired/wireless_table_structure_recognition_*、wired/wireless_table_cells_detection_*	表格分類、有線/無線表格結構與單元格
公式與圖表	formula_recognition_*、chart_recognition_*	公式識別、圖表解析
印章識別	seal_text_detection_*、seal_text_recognition_*	印章文本檢測與識別

同時，use_table_recognition、use_formula_recognition、use_chart_recognition、use_seal_recognition 等開關允許按需啟停子模塊。倉庫中還提供了對應的表格識別產線 paddleocr/_pipelines/table_recognition_v2.py 與公式識別產線 paddleocr/_pipelines/formula_recognition.py，與 PP-StructureV3 形成互補。

辦公文檔轉 Markdown 與 DOCX 導出

官方 3.5.0 更新說明提到支持將 Word、Excel、PowerPoint 等常見文檔格式轉換為 Markdown，且 PaddleOCR-VL、PP-StructureV3、PP-DocTranslation 可將解析結果導出為 DOCX。源碼側，paddleocr/_doc2md/init.py 暴露了 convert、supported_formats 兩個核心接口，以及可擴展的 BaseConverter 基類與 default_registry 註冊表，意味著文檔格式支持採用「轉換器註冊」模式，擴展新格式只需註冊新的轉換器實現。

核心特性二：通用文本識別——PP-OCRv6 與 100+ 語言

PP-OCRv6：單模型統一 50 種語言

官方 README 指出，PP-OCRv6 單模型統一支持 50 種語言（中、英、日及 46 種拉丁語系），無需切換模型即可應對多語言混合排版文檔，並提供 tiny（1.5M）/ small（7.7M）/ medium（34.5M）三檔模型，分別面向端側、移動端與服務端部署。

源碼驗證：在 paddleocr/_pipelines/ocr.py 中，_PPOCRV6_LANGS = {"ch", "chinese_cht", "en", "japan"} | (LATIN_LANGS - {"pi"})，即中文、繁體中文、英文、日文加上拉丁語系（排除 pi）共 50 種；_get_ocr_model_names() 在未指定任何模型時默認返回 PP-OCRv6_medium_det 與 PP-OCRv6_medium_rec。模型配置文件可在 configs/det/PP-OCRv6 下找到 tiny/small/medium 三檔檢測配置（如 PP-OCRv6_medium_det.yml）。

語言版本自動路由：從 v6 到 v3 的回退邏輯

對於 50 種語言之外的語種（如韓語、泰語、希臘語、阿拉伯語、西里爾語系、天城文語系等），PaddleOCR 產線的 _get_ocr_model_names() 實現了自動路由：

• 語言在 _PPOCRV6_LANGS 內 → 使用 PP-OCRv6；
• 韓語、泰語、希臘語及 ESLAV/ARABIC/CYRILLIC/DEVANAGARI 等語系 → 回退到 PP-OCRv5（如 en_PP-OCRv5_mobile_rec、latin_PP-OCRv5_mobile_rec）；
• ka（格魯吉亞語）→ 回退到 PP-OCRv3；
• 未知語言 → 返回空並拋出異常提示。

對應的語言分組定義位於 paddleocr/_utils/langs.py，其中 LATIN_LANGS、ARABIC_LANGS、CYRILLIC_LANGS、ESLAV_LANGS、DEVANAGARI_LANGS 等 frozenset 明確列舉了各語系代碼。開發者指定 lang 參數時，產線會自動匹配最合適的模型版本與語種模型，這與官方「支持 100+ 種語言」的承諾在代碼層面相互印證。

複雜場景與性能

官方 README 宣稱 PP-OCRv6 相比 PP-OCRv5 檢測精度提升 4.6%、識別精度提升 5.1%，並在數碼顯示屏、點陣字符、輪胎印字、工業字符等傳統 VLM 難以覆蓋的專業場景上能力大幅提升；推理方面 medium 檔 CPU OpenVINO 加速 5.2×，tiny 檔 Apple M4 加速 6.1×。這些數據來自官方版本說明，實際效果建議結合自身數據集在 docs/version3.x/pipeline_usage/OCR.md 提供的基準測試方式進行驗證。

核心特性三：以開發者為中心的生態系統

官方 README 從三個維度描述生態能力：

• 無縫集成：與 Dify、RAGFlow、Pathway、Cherry Studio 等 AI 智能體生態深度集成；
• 數據飛輪：提供構建高質量數據集的完整數據流水線，支撐大語言模型微調；
• 一鍵部署：支持 NVIDIA GPU、Intel CPU、崑崙芯 XPU 與多種 AI 加速器硬件後端。

從倉庫結構看，生態配套豐富：deploy/ 目錄下包含 C++ 推理（cpp_infer）、Android 原生（ppocr-android）、iOS（ios_demo）、ONNX 轉換（paddle2onnx）、服務化部署（hubserving）等方案；mcp_server/ 提供了將 PaddleOCR 能力暴露為 MCP（Model Context Protocol）服務的實現；paddleocr-js/ 是官方瀏覽器推理 SDK（支持在瀏覽器運行 PP-OCRv5）；langchain-paddleocr/ 則將 PaddleOCR 封裝為 LangChain 文檔加載器，可直接接入 RAG 鏈路。此外，api_sdk/ 提供 Go 與 TypeScript 兩種語言的 API SDK，便於異構系統集成。

版本演進時間線：從 3.2.0 到 3.7.0

官方 README 的「最新動態」記錄了關鍵版本節點，整理如下：

版本	發布時間	核心亮點
3.7.0	2026.06.11	PP-OCRv6 發布：三檔模型、50 語言統一支持、專業場景增強、推理加速
3.6.0	2026.05.28	PaddleOCR-VL-1.6：OmniDocBench v1.6 突破 96.3%，表格/古籍/生僻字增強
3.5.0	2026.04.21	推理後端靈活切換（靜態圖/動態圖/Transformers）、Office 文檔轉 Markdown、DOCX 導出、瀏覽器推理 SDK PaddleOCR.js
3.4.0	2026.01.29	PaddleOCR-VL-1.5：OmniDocBench 94.5%、PP-DocLayoutV3 不規則形狀定位、印章/文本識別、111 種語言、跨頁表格合併
3.3.0	2025.10.16	發布 PaddleOCR-VL（0.9B VLM，NaViT 動態分辨率編碼器 + ERNIE-4.5-0.3B 語言模型，109 種語言）；PP-OCRv5 小語種識別模型
3.2.0	2025.08.21	PP-OCRv5 英文/泰文/希臘文模型、飛槳 3.1.x 支持、C++ 本地部署升級、CUDA 12 高性能推理、產線細粒度 benchmark

新增 HPD-Parsing（2026.07.22）

README 最新更新介紹了 HPD-Parsing：面向高吞吐文檔解析的輕量級視覺語言模型，採用層級並行解碼範式與漸進式多 token 預測（P-MTP），官方聲稱公開基準上峰值吞吐達 4,752 tokens/s，基於定制版 vLLM 運行時，支持 OpenAI 兼容服務化調用與本地推理。相應的產線文檔位於 docs/version3.x/pipeline_usage/HPD-Parsing.md。

3.2.0 的其他工程化改進

該版本還包含多項對開發者友好的改進：分離必要依賴與可選依賴（基礎文字識別僅需少量核心依賴）、PP-OCR 系列模型支持返回單文字坐標、支持 AIStudio/ModelScope 等下載源、PP-Chart2Table 圖表轉表單模塊推理等。從 paddleocr/_pipelines/ocr.py 的 PaddleOCR.__init__ 簽名可以看到 return_word_box 參數，正是「返回單文字坐標」的實現入口。

快速開始：三步上手

步驟 1：在線體驗

PaddleOCR 官方網站提供交互式體驗中心與 APIs，無需任何本地設置即可一鍵體驗各產線效果。適合在動手安裝前先驗證模型效果是否符合預期。

步驟 2：安裝與環境驗證

根據官方產線文檔 docs/version3.x/pipeline_usage/OCR.md，安裝方式如下：

# 安裝基礎版本
pip install paddleocr

# 安裝完整版本（包含文檔解析、信息抽取等全部功能）
pip install "paddleocr[all]"

安裝後可驗證環境：

import paddleocr
print(f"PaddleOCR版本: {paddleocr.__version__}")

# 若使用本地推理引擎 paddle_static，可驗證 PaddlePaddle 是否可用
import paddle
print(f"Paddle版本: {paddle.__version__}")
print(f"GPU可用: {paddle.is_compiled_with_cuda()}")

常見問題處理：依賴衝突時建議新建虛擬環境（conda create -n paddleocr python=3.8 && conda activate paddleocr）；GPU 環境需按 CUDA 版本安裝對應的 paddlepaddle-gpu；模型下載失敗時可設置下載源環境變量 PADDLE_PDX_MODEL_SOURCE。

步驟 3：命令行快速推理

paddleocr ocr -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/general_ocr_002.png \
    --use_doc_orientation_classify False \
    --use_doc_unwarping False \
    --use_textline_orientation False \
    --save_path ./output \
    --device gpu:0

# 通過 --ocr_version 指定 PP-OCR 其他版本
paddleocr ocr -i ./general_ocr_002.png --ocr_version PP-OCRv4

命令行子命令的註冊機制位於 paddleocr/_cli.py：_register_pipelines 將 PaddleOCR、PaddleOCRVL、PPStructureV3、PPDocTranslation 等產線註冊為 paddleocr 的子命令，_register_models 將 TextDetection、TextRecognition 等 13 個單模塊註冊為獨立子命令，install_hpi_deps 與 install_genai_server_deps 則負責按需安裝高性能推理與 vLLM/SGLang/FastDeploy 服務依賴。

Python API：產線對象化調用

from paddleocr import PaddleOCR

# 默認使用 PP-OCRv6 模型
ocr = PaddleOCR(
    use_doc_orientation_classify=False,  # 不使用文檔方向分類模型
    use_doc_unwarping=False,             # 不使用文本圖像矯正模型
    use_textline_orientation=False,      # 不使用文本行方向分類模型
)
# ocr = PaddleOCR(lang="en")                        # 使用英文模型
# ocr = PaddleOCR(ocr_version="PP-OCRv5")           # 切換到 PP-OCRv5
# ocr = PaddleOCR(device="gpu")                     # 使用 GPU 推理
# ocr = PaddleOCR(engine="transformers")            # 切換推理引擎

result = ocr.predict("./general_ocr_002.png")
for res in result:
    res.print()              # 打印識別結果
    res.save_to_img("output")   # 保存可視化結果
    res.save_to_json("output")  # 保存 JSON 結果

推理引擎選擇

產線支持 paddle_static（默認，飛槳靜態圖）、transformers、onnxruntime 三種本地推理引擎，通過 --engine 參數切換。官方建議：默認的 paddle_static 通常具備更好的推理性能，優先使用；使用 transformers 引擎時，20 個主要模型可直接以 Transformers 為推理後端，深度適配 Hugging Face 生態。

模型選型與關鍵參數

以 OCR 產線為例，其 5 個模塊均可獨立訓練與推理：文檔圖像方向分類（可選）、文本圖像矯正（可選）、文本行方向分類（可選）、文本檢測、文本識別。常用的調節參數包括：

參數	作用
text_det_limit_side_len / text_det_limit_type	文本檢測輸入圖像縮放限制
text_det_thresh / text_det_box_thresh / text_det_unclip_ratio	檢測二值化閾值、框閾值、擴張比例
text_rec_score_thresh	識別結果置信度閾值
text_recognition_batch_size	識別批大小
return_word_box	是否返回單文字坐標

這些參數在 paddleocr/_pipelines/ocr.py 的 _get_paddlex_config_overrides() 中會被映射為產線配置結構（如 SubModules.TextDetection.thresh、SubModules.TextRecognition.score_thresh），並通過 create_config_from_structure 生成 PaddleX 配置。此外，源碼保留了 2.x 時代的舊參數名兼容映射（如 det_model_dir → text_detection_model_dir、use_angle_cls → use_textline_orientation），老用戶遷移時會收到棄用警告，但舊代碼仍可運行。

更多功能與部署選項

官方 README 的「更多功能」部分給出四條進階路徑，對應的倉庫文檔如下：

• ONNX 模型獲取與轉換：可參考 deploy/paddle2onnx 目錄下的轉換工具與說明；
• 高性能推理：使用 OpenVINO、ONNX Runtime、TensorRT 等引擎加速，或使用 ONNX 格式模型推理，見 docs/version3.x/pipeline_usage 下的推理部署系列文檔；
• 流水線並行推理：使用多 GPU 與多進程加速推理；
• 服務化部署：將 PaddleOCR 集成到 C++、C#、Java 等語言編寫的應用中，可參考 deploy/hubserving 下針對 ocr_det、ocr_rec、ocr_system、structure_system 等場景的服務模塊，以及 deploy/cpp_infer 的 C++ 推理實現。

許可證與引用

本項目採用 Apache 2.0 許可證發布，許可證全文見 LICENSE。若在學術或工程項目中使用 PaddleOCR，官方 README 提供了以下 BibTeX 引用格式：

@misc{cui2025paddleocr30technicalreport,
      title={PaddleOCR 3.0 Technical Report},
      author={Cheng Cui and Ting Sun and Manhui Lin and Tingquan Gao and Yubo Zhang and Jiaxuan Liu and Xueqing Wang and Zelun Zhang and Changda Zhou and Hongen Liu and Yue Zhang and Wenyu Lv and Kui Huang and Yichao Zhang and Jing Zhang and Jun Zhang and Yi Liu and Dianhai Yu and Yanjun Ma},
      year={2025},
      eprint={2507.05595},
      archivePrefix={arXiv},
      primaryClass={cs.CV},
}

小結

PaddleOCR 的技術路線可以概括為「兩條主線、一層生態」：以 PP-OCRv6 支撐通用場景多語言 OCR，以 PaddleOCR-VL 與 PP-StructureV3 支撐面向大模型的文檔結構化解析，並以產線化架構、多推理引擎、多語言 SDK 與 MCP/瀏覽器/LangChain 集成構成完整的開發者生態。無論是構建 RAG 數據管道、做文檔數字化，還是處理自然場景文字，都可以先從官方體驗中心驗證效果，再按本文的安裝與調用路徑在本地落地。