PaddleOCR 3.x 安装完全指南：paddleocr 包、可选依赖组、推理引擎与训练环境

PaddleOCR 3.x 安装完全指南paddleocr 包、可选依赖组、推理引擎与训练环境【免费下载链接】PaddleOCRTurn any PDF or image document into structured data for your AI. A powerful, lightweight OCR toolkit that bridges the gap between images/PDFs and LLMs. Supports 100 languages.项目地址: https://gitcode.com/GitHub_Trending/pa/PaddleOCR导读本文以 PaddleOCR 官方安装文档docs/version3.x/installation.en.md为主线系统讲解 PaddleOCR 3.x 的两条独立安装路径一条用于本地推理安装paddleocr分发包、按能力域启用可选依赖组、按需安装推理引擎另一条用于模型训练与导出安装飞桨框架与仓库训练依赖。读完本文你将能根据自己的使用场景仅推理、文档解析、信息抽取、文档翻译、文档转 Markdown或训练/导出模型精准选择安装方案并理解paddleocr与 PaddleX、PaddlePaddle 三者之间的版本依赖关系。1. 安装前需要理解的两条独立路径PaddleOCR 3.x 的安装被明确划分为两个相互独立的维度第 1 条路径推理路径安装paddleocrPython 分发包并按能力域选择可选依赖组doc-parser、ie、trans、doc2md、all再按需安装推理引擎。适用于在本地运行预训练产线完成推理以及文档格式转换等辅助功能。第 2 条路径训练/导出路径克隆仓库并安装训练依赖requirements.txt依赖飞桨框架。适用于模型训练与模型导出。两条路径在同一环境中可以共存无需强制隔离。原文档特别强调模型训练与模型导出与推理安装路径相互独立。Python 版本要求| 目标 | Python 版本要求 | | - | - | |paddleocr本体与doc2md依赖组 | Python 3.8 及以上 | | 其他可选依赖组doc-parser、ie、trans、all等 | Python 3.9 及以上受上游依赖限制 | | 训练与模型导出 | Python 3.8 及以上 |从仓库 pyproject.toml 可以看到paddleocr包声明requires-python 3.8并在分类器中列出 Python 3.8 至 3.13 的支持范围而doc2md之外的依赖组之所以要求 Python 3.9是因为它们都依赖paddlex[ocr,genai-client,ie,trans]等上游组件这些组件的 Python 版本约束更高。2. 路径一安装 paddleocr 分发包2.1 从 PyPI 安装推荐# 仅需要通用 OCR 与文档图像预处理等默认能力 python -m pip install paddleocr # 需要文档解析、文档理解、文档翻译、关键信息抽取等全部可选能力 # python -m pip install paddleocr[all]2.2 从源码安装跟踪仓库最新代码# 默认跟踪仓库当前默认分支 python -m pip install paddleocrgithttps://github.com/PaddlePaddle/PaddleOCR.git # 安装全部可选能力 # python -m pip install paddleocr[all]githttps://github.com/PaddlePaddle/PaddleOCR.git从源码安装适合需要提前体验尚未发版的新特性或在本地二次开发时使用。2.3 源码级解读安装后获得了什么安装paddleocr后包的核心依赖在 pyproject.toml 中声明paddlex[ocr-core]3.7.0,3.8.0PaddleOCR 3.x 在推理部署阶段完全复用 PaddleX 的模型推理、前后处理与多模型组合能力详见 docs/version3.x/paddleocr_and_paddlex.en.mdPyYAML6解析 PaddleX 管道配置文件requests、aiohttp3.8.0同步/异步 HTTP 能力typing-extensions4.12类型标注兼容。安装完成后会注册paddleocr命令行入口见 pyproject.toml 中[project.scripts]的paddleocr paddleocr.__main__:console_entry。通过paddleocr --help可以查看可用的模型与产线子命令包括text_detection、text_recognition、ocr、PP-StructureV3、PP-ChatOCRv4-doc等子命令注册逻辑见 paddleocr/_cli.py。同时包顶层导出了TextDetection、TextRecognition、PaddleOCR、PPStructureV3等 Python 类见 paddleocr/init.py。2.4 特别说明PaddleOCR 与 PaddleX 的依赖关系虽然 PaddleOCR 底层依赖 PaddleX但得益于 PaddleX 的可选依赖安装机制安装paddleocr并不会引入 PaddleX 的全部依赖只会安装 OCR 相关任务所需的依赖因此无需担心依赖体积过度膨胀。官方文档中记录在 x86-64 Linux Python 3.10 环境下测试安装所需依赖的总体积仅从 717 MB 增加到 738 MB。3. 按能力域选择可选依赖组除all之外PaddleOCR 提供按能力域拆分的可选依赖组用户可以按需启用避免安装用不到的依赖| 依赖组名称 | 对应功能 | 底层依赖见 pyproject.toml | | - | - | - | |doc-parser| 文档解析提取文档中的表格、公式、印章、图片等版面元素包含 PP-StructureV3 等模型方案 |paddlex[ocr,genai-client]3.7.0,3.8.0| |ie| 信息抽取从文档中提取姓名、日期、地址、金额等关键信息包含 PP-ChatOCRv4 等模型方案 |paddlex[ie]3.7.0,3.8.0| |trans| 文档翻译将文档从一种语言翻译为另一种语言包含 PP-DocTranslation 等模型方案 |paddlex[trans]3.7.0,3.8.0| |doc2md| 文档转 Markdown将 Word、Excel、PowerPoint 文件快速转为可读文本 |python-docx0.8.11、python-pptx0.6.21、openpyxl3.0.0、pylatexenc2.10,3| |all| 完整功能 | 上述所有依赖的组合 |安装示例# 只需文档解析能力PP-StructureV3 等 python -m pip install paddleocr[doc-parser] # 只需关键信息抽取能力PP-ChatOCRv4 等 python -m pip install paddleocr[ie] # 只需文档翻译能力PP-DocTranslation 等 python -m pip install paddleocr[trans] # 只需文档转 Markdowndoc2md python -m pip install paddleocr[doc2md]使用要点原文档明确说明通用 OCR 产线与文档图像预处理产线无需任何额外依赖组安装默认的paddleocr即可使用文档解析、信息抽取、文档翻译等能力按上表安装对应依赖组各产线所属依赖组详见对应产线文档对于单功能模块安装任一包含该模块的依赖组后即可调用其基础能力。安装后doc2md能力在 Python 中通过paddleocr.doc2md_convert(source, **kwargs)调用见 paddleocr/init.py并可用paddleocr.doc2md_supported_formats()查询支持的文件格式。4. 安装推理引擎按需注意安装paddleocr分发包本身并不等于可以立即跑推理。PaddleOCR 3.5 起采用统一推理引擎配置机制底层可对接飞桨PaddlePaddle、Hugging Face Transformers、ONNX Runtime 等推理引擎。要实际执行模型推理必须按需安装所选的推理引擎。4.1 三种推理引擎一览| 引擎类别 |engine取值 | 说明 | | - | - | - | | 飞桨框架 |paddle、paddle_static、paddle_dynamic| 基于 PaddlePaddle 框架运行 | | Transformers |transformers| 基于 Hugging Face Transformers 运行 | | ONNX Runtime |onnxruntime| 基于 ONNX Runtime 加载执行 ONNX 格式模型 |4.2 各引擎安装方式由于不同推理引擎的依赖可能相互冲突官方建议每个环境只安装一种推理引擎。飞桨PaddlePaddle框架使用飞桨做推理时需要先安装飞桨框架详细步骤见 docs/version3.x/paddlepaddle_installation.en.md。该文档提供了 Docker 与 pip 两种安装方式例如 pip 安装 CPU 版python -m pip install paddlepaddle3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cpu/安装后可用python -c import paddle; print(paddle.__version__)验证。需要注意的是安装 GPU 版时只需关注本机 GPU 驱动版本无需关心物理机上的 CUDA 版本。Transformerspython -m pip install transformers5.10.0ONNX Runtime以 CUDA 12.x 环境下的 NVIDIA GPU 为例python -m pip install onnxruntime-gpu4.3 推理引擎配置示例engine与engine_config同时适用于单个模型和产线。例如用 Python API 指定飞桨静态图引擎并在 CPU 上启用 MKLDNNfrom paddleocr import TextDetection model TextDetection( model_namePP-OCRv5_server_det, enginepaddle_static, engine_config{ device_type: cpu, cpu_threads: 4, run_mode: mkldnn, }, ) result model.predict(general_ocr_001.png)命令行方式# 单模型指定引擎 paddleocr text_detection -i general_ocr_001.png --engine transformers # 产线指定引擎 paddleocr ocr -i general_ocr_001.png --engine paddle_staticengine未显式指定时行为与旧版本一致除高性能推理、生成式 AI 客户端请求等少数场景外多数情况默认使用飞桨框架推理。更完整的engine/engine_config取值与优先级规则参见 docs/version3.x/inference_deployment/local_inference/inference_engine.en.md。5. 路径二安装训练与导出依赖若要进行模型训练或模型导出需要走第二条独立安装路径。该路径与第 2、3 节的paddleocr包及可选依赖组属于不同安装维度两者可在同一环境共存。5.1 前置条件安装飞桨框架训练与导出依赖飞桨框架请先按 docs/version3.x/paddlepaddle_installation.en.md 安装。如果当前环境中已安装飞桨之外的推理引擎如 Transformers可能出现依赖冲突官方建议在全新环境中安装。5.2 克隆仓库并安装训练依赖# 推荐方式 git clone https://github.com/PaddlePaddle/PaddleOCR # 可选切换到指定分支 git checkout release/3.5 # 如果因网络问题克隆失败也可使用码云镜像仓库 git clone https://gitee.com/paddlepaddle/PaddleOCR # 注码云托管代码可能滞后于 GitHub 项目 3~5 天请优先使用推荐方式。然后安装其余训练依赖python -m pip install -r requirements.txt仓库根目录的 requirements.txt 包含训练所需的全部依赖核心项包括图像与几何处理shapely、scikit-image、pyclipper、opencv-python、opencv-contrib-python、Pillow、albumentations及兼容包albucore数据加载与序列化lmdbPython 3.9 使用lmdbPython 3.8 使用lmdb1.5、cython通用工具tqdm、numpy、rapidfuzz、pyyaml、requests、packaging。训练与模型导出支持 Python 3.8 及以上版本。6. 版本兼容性速查PaddleOCR、PaddleX 与飞桨框架存在严格的三方版本对应关系详见 docs/version3.x/paddleocr_and_paddlex.en.mdPaddleOCR 版本PaddleX 版本PaddlePaddle 版本3.0.03.0.0 3.0.03.1.x 3.1.0, 3.2.0 3.0.03.2.x 3.2.0, 3.3.0 3.0.03.3.x 3.3.0, 3.4.0 3.0.03.4.x 3.4.0, 3.5.0 3.0.03.5.x 3.5.0, 3.6.0 3.0.03.6.x 3.6.0, 3.7.0 3.0.03.7.x 3.7.0, 3.8.0 3.0.0安装时务必保持三者版本匹配。当前仓库 pyproject.toml 即声明了对paddlex[ocr-core]3.7.0,3.8.0的依赖与上表3.7.x行的约束一致。7. 安装后的快速验证安装完成后可以通过以下方式快速验证环境是否就绪# 查看 paddleocr 版本 python -c import paddleocr; print(paddleocr.__version__) # 查看 CLI 可用的模型与产线子命令 paddleocr --help # 验证飞桨框架仅训练/导出路径需要 python -c import paddle; print(paddle.__version__)PaddleOCR 3.x 的产线与 PaddleX 管道注册名存在一一对应关系例如通用 OCR 对应OCR、PP-StructureV3 对应PP-StructureV3、PP-ChatOCRv4 对应PP-ChatOCRv4-doc、PP-DocTranslation 对应PP-DocTranslation等完整对照表见 docs/version3.x/paddleocr_and_paddlex.en.md。了解这一对应关系有助于在高级配置、服务部署等场景中直接使用 PaddleX 的管道配置文件。8. 常见安装问题速查安装paddleocr后无法跑推理检查是否已按第 4 节安装所选推理引擎默认场景需要飞桨框架。Python 版本过低无法安装可选依赖组doc-parser、ie、trans、all依赖组要求 Python 3.9建议升级 Python 或仅使用doc2md/默认能力。训练环境与推理引擎冲突训练/导出依赖飞桨框架若环境中已有 Transformers 等其他推理引擎可能出现依赖冲突建议在全新虚拟环境中安装。不确定选哪个依赖组只做通用 OCR 用默认安装即可做版面解析/表格公式抽取装doc-parser做关键信息抽取装ie做文档翻译装trans做 Office 文档转 Markdown 装doc2md追求开箱即用直接装all。总结PaddleOCR 3.x 的安装体系可以概括为一个分发包、五个可选依赖组、两种独立路径、三类推理引擎默认的paddleocr包覆盖通用 OCR 与文档图像预处理doc-parser/ie/trans/doc2md/all按能力域扩展功能推理与训练/导出两条路径互不干扰、可共存推理引擎支持飞桨、Transformers、ONNX Runtime 三种选择。安装前确认 Python 版本要求安装时保持 PaddleOCR、PaddleX、PaddlePaddle 三方版本匹配即可快速搭建从推理到训练的完整开发环境。【免费下载链接】PaddleOCRTurn any PDF or image document into structured data for your AI. A powerful, lightweight OCR toolkit that bridges the gap between images/PDFs and LLMs. Supports 100 languages.项目地址: https://gitcode.com/GitHub_Trending/pa/PaddleOCR创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考