十年匠心定制 · 商业建站与技术教学双线并行 咨询热线:400-886-1026 service@lmnt.cn
ARTICLE DETAIL

资讯详情

深耕网站建设与运营推广的一线实战洞察。

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

PaddleOCR 3.x 完整安装指南:Python 包、可选依赖组、推理引擎与训练环境 PaddleOCR 3.x 完整安装指南Python 包、可选依赖组、推理引擎与训练环境【免费下载链接】PaddleOCR飞桨多语言OCR工具包实用超轻量OCR系统支持80种语言识别提供数据标注与合成工具支持服务器、移动端、嵌入式及IoT设备端的训练与部署 Awesome multilingual OCR toolkits based on PaddlePaddle (practical ultra lightweight OCR system, support 80 languages recognition, provide data annotation and synthesis tools, support training and deployment among server, mobile, embedded and IoT devices)项目地址: https://gitcode.com/paddlepaddle/PaddleOCR本篇指南以 PaddleOCR 仓库中 docs/version3.x/installation.en.md 为骨架系统讲解 PaddleOCR 3.x 的两大独立安装维度其一为面向本地推理的paddleocrPython 分发包与按能力域拆分的可选依赖组doc-parser、ie、trans、doc2md、all以及按需安装的推理引擎其二为面向模型训练与导出的飞桨框架与训练依赖。读完本文你将能够根据仅做通用 OCR 推理、需要文档解析 / 关键信息抽取 / 文档翻译 / 文档转 Markdown、需要本地训练与导出模型等不同诉求选择最小化且正确的安装组合并理解 PaddleOCR 3.5 统一推理引擎配置engine/engine_config背后的安装与选型逻辑。1. 安装前需要理解的两个独立维度PaddleOCR 3.x 将运行预训练产线做推理与训练 / 导出模型拆分为两条互不干扰的安装路径推理路径第 1 节安装paddleocr分发包、按能力域选择可选依赖组、再按需安装推理引擎。适用于在本地调用预训练产线完成推理以及文档格式转换等辅助功能。训练 / 导出路径第 2 节单独安装飞桨框架与训练相关依赖。适用于模型训练与模型导出。两条路径可以在同一环境中共存无需强制隔离。原文档明确指出模型训练与模型导出与上述推理安装路径相互独立。从源码看这一设计直接体现在 pyproject.toml 中paddleocr项目的基础依赖dependencies只声明了paddlex[ocr-core]3.7.0,3.8.0、PyYAML、requests、aiohttp、typing-extensions等运行时必需的最小集合而训练依赖shapely、scikit-image、pyclipper、lmdb、albumentations等则独立维护在仓库根目录的 requirements.txt 中只有走训练路径才需要安装。Python 版本要求速查| 安装对象 | 最低 Python 版本 | 原因 | | - | - | - | |paddleocr本体 | 3.8 | 项目自身支持 | |doc2md依赖组 | 3.8 | 上游依赖兼容 | |doc-parser/ie/trans/all依赖组 | 3.9 | 受上游依赖限制 | | 训练与模型导出 | 3.8 | 文档明确声明 |这一点同样可以在 pyproject.toml 的 classifiers 中印证项目声明支持 Python 3.8 ~ 3.13。2. 安装paddleocr默认能力与全量能力2.1 从 PyPI 安装# 默认能力仅通用 OCR 与文档图像预处理 python -m pip install paddleocr # 全量可选能力文档解析、文档理解、文档翻译、关键信息抽取等 # python -m pip install paddleocr[all]默认安装只包含通用 OCR 与文档图像预处理所需的运行时依赖不会把全部 PaddleX 依赖一并带入。依据 paddleocr_and_paddlex.en.md 的说明得益于 PaddleX 的可选依赖安装机制安装paddleocr分发包并不会包含 PaddleX 的全部依赖只会安装 OCR 相关任务所需的那些用户无需担心依赖体积过度膨胀。2.2 从源码安装# 默认能力默认跟踪仓库当前默认分支 python -m pip install paddleocrgithttps://github.com/PaddlePaddle/PaddleOCR.git # 全量可选能力 # python -m pip install paddleocr[all]githttps://github.com/PaddlePaddle/PaddleOCR.git从源码安装适合需要紧跟仓库最新开发状态、或者需要本地二次开发的场景。安装完成后paddleocr命令行入口由 pyproject.toml 中的[project.scripts]声明paddleocr paddleocr.__main__:console_entry实际入口实现位于 paddleocr/main.py所有子命令ocr、text_detection、PP-StructureV3、PP-ChatOCRv4-doc等在 paddleocr/_cli.py 中统一注册。3. 按能力域选择可选依赖组除all之外PaddleOCR 提供按能力域拆分的可选依赖组实现按需安装、最小化依赖。各依赖组与功能的对应关系如下| 依赖组名称 | 对应的功能 | 包含的模型方案 | | - | - | - | |doc-parser| 文档解析提取文档中的表格、公式、印章、图片等版面元素 | PP-StructureV3 等 | |ie| 信息抽取从文档中提取姓名、日期、地址、金额等关键信息 | PP-ChatOCRv4 等 | |trans| 文档翻译将文档从一种语言翻译为另一种语言 | PP-DocTranslation 等 | |doc2md| 文档转 Markdown将 Word、Excel、PowerPoint 文件快速转为可读文本 | — | |all| 完整功能 | 上述全部 |依赖组的底层实现在 pyproject.toml 的[project.optional-dependencies]中有精确映射doc-parserpaddlex[ocr,genai-client]3.7.0,3.8.0iepaddlex[ie]3.7.0,3.8.0transpaddlex[trans]3.7.0,3.8.0doc2mdpython-docx0.8.11python-pptx0.6.21openpyxl3.0.0pylatexenc2.10,3allpaddlex[ocr,genai-client,ie,trans]3.7.0,3.8.0 doc2md 的四个包从这份声明可以看到一个关键事实doc2md依赖组不依赖 PaddleX仅由python-docx、python-pptx、openpyxl、pylatexenc组成这正是它能在 Python 3.8 上工作的原因而doc-parser、ie、trans等组通过 PaddleX 的可选 extra 引入对应能力受上游依赖限制需要 Python 3.9。依赖组选择建议通用 OCR 产线与文档图像预处理产线无需任何额外依赖组需要文档解析、信息抽取、文档翻译等能力时按上表安装对应组各产线所属依赖组见对应产线文档如 PP-StructureV3、PP-ChatOCRv4、PP-DocTranslation、doc2md对于单个功能模块安装任一包含该模块的依赖组后即可调用其基础能力。4. 安装推理引擎按需PaddleOCR 3.5 采用统一推理引擎配置机制通过engine选择底层推理引擎通过engine_config传入引擎专属设置。这一机制同时适用于单个模型和产线。若未显式指定engine默认行为与旧版本保持一致——除高性能推理、生成式 AI 客户端请求等少数场景外PaddleOCR 绝大多数情况下使用飞桨框架执行推理若显式指定了engine则初始化时优先遵循所选引擎。详细的安装与配置说明见 推理引擎与配置说明各引擎安装要点如下| 引擎类别 |engine取值 | 安装方式 | | - | - | - | | 飞桨框架 |paddle、paddle_static、paddle_dynamic| 安装 PaddlePaddle见下一节 | | Transformers |transformers|python -m pip install transformers5.10.0多数情况下还需安装底层推理框架 | | ONNX Runtime |onnxruntime| 例如python -m pip install onnxruntime-gpu适用于 CUDA 12.x 环境的 NVIDIA GPU |⚠️ 不同推理引擎之间可能存在依赖冲突建议每个环境只安装一种推理引擎。引擎选型要点paddle飞桨框架统一入口按模型类型与模型目录中的文件自动选择paddle_static或paddle_dynamic两者同时可用时优先静态图paddle_static静态图推理适合追求更优推理性能或更细粒度性能调优的场景paddle_dynamic动态图推理比静态图更灵活、更易调试transformersHugging Face Transformers 推理便于融入 HF 生态onnxruntimeONNX Runtime 推理用于加载和执行 ONNX 格式模型。5. 训练与导出路径飞桨框架 训练依赖5.1 安装飞桨框架若要进行模型训练或模型导出需要先安装飞桨框架详细步骤见 飞桨框架安装文档。其 pip 安装要点# CPU 版本 python -m pip install paddlepaddle3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cpu/ # GPU 版本要求驱动 450.80.02 (Linux) 或 452.39 (Windows) python -m pip install paddlepaddle-gpu3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu118/ # GPU 版本要求驱动 550.54.14 python -m pip install paddlepaddle-gpu3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu126/安装成功后验证python -c import paddle; print(paddle.__version__)文档特别提醒无需关注物理机 CUDA 版本只需关注 GPU 驱动版本。另外如果当前环境中已安装飞桨之外的推理引擎如 Transformers可能出现依赖冲突建议在全新环境中安装。关于 PaddleOCR 与 PaddlePaddle、PaddleX 的版本对应关系可参考 PaddleOCR 与 PaddleX 中的版本对照表例如 PaddleOCR3.5.x对应 PaddleX 3.5.0, 3.6.0、PaddlePaddle 3.0.0当前 pyproject.toml 声明paddlex[ocr-core]3.7.0,3.8.0即对应 PaddleOCR3.7.x。5.2 克隆仓库并安装训练依赖# 推荐方式 git clone https://github.com/PaddlePaddle/PaddleOCR # 可选切换到指定分支 git checkout release/3.5 # 如果因网络问题克隆失败也可使用码云仓库 git clone https://gitee.com/paddlepaddle/PaddleOCR # 注码云托管代码可能无法实时同步存在 3~5 天延时请优先使用推荐方式。克隆完成后安装其余训练依赖python -m pip install -r requirements.txtrequirements.txt 中声明的训练依赖包括shapely、scikit-image、pyclipper、lmdb按 Python 版本区分版本约束Python 3.9 装最新版 3.9 装lmdb1.5、tqdm、numpy、rapidfuzz、opencv-python、opencv-contrib-python、cython、Pillow、pyyaml、requests、albumentations、albucore、packaging等覆盖了数据加载LMDB 数据集、图像增强albumentations、后处理几何计算shapely / pyclipper、可视化与日志等训练全链路所需组件。6. 安装完成后的快速验证安装完成后可以通过 PaddleOCR 命令行快速验证环境是否可用。以通用 OCR 产线为例paddleocr ocr也可以在模型子命令中直接指定推理引擎# 使用飞桨静态图引擎执行通用 OCR paddleocr ocr -i general_ocr_001.png --engine paddle_static # 单个模型使用 Transformers 引擎 paddleocr text_detection -i general_ocr_001.png --engine transformers # 单个模型使用 ONNX Runtime 引擎 paddleocr text_detection -i general_ocr_001.png --engine onnxruntime在 Python API 中推理引擎的指定方式同样直观from 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)产线级的快速使用示例可进一步参考 quick_start.en.md。7. 常见问题与注意事项两条安装维度互不冲突paddleocr包 可选依赖组推理路径与飞桨框架 requirements.txt训练路径可在同一环境共存无需强制隔离。依赖冲突优先干净环境若环境已装 Transformers 等其他推理引擎再安装飞桨框架可能出现依赖冲突建议使用全新虚拟环境。推理引擎一环境一个不同推理引擎飞桨 / Transformers / ONNX Runtime依赖可能冲突每个环境只装一种。engine_config的两种形态同一层级上engine_config可以是扁平式键直接为解析后引擎所需字段如run_mode、cpu_threads或分桶式顶层键仅为引擎注册名如paddle_static、transformers各自映射到嵌套字典禁止在同一层级混用两种键。优先级规则产线通过 CLI 参数或 Python API 初始化参数传入的engine/engine_config优先于产线配置文件中的同名项配置文件中的全局设置可被子模块覆盖。版本对应关系安装前建议核对 PaddleOCR 与 PaddleX 版本对照表确保paddleocr、PaddleX 与飞桨框架的版本区间匹配避免因版本错配导致 API 或依赖异常。8. 相关资源安装文档英文原文 / 安装文档中文版推理引擎与配置说明飞桨框架安装PaddleOCR 与 PaddleX 的关系与协作doc2md 文档转 Markdown 说明pyproject.toml依赖组声明requirements.txt训练依赖【免费下载链接】PaddleOCR飞桨多语言OCR工具包实用超轻量OCR系统支持80种语言识别提供数据标注与合成工具支持服务器、移动端、嵌入式及IoT设备端的训练与部署 Awesome multilingual OCR toolkits based on PaddlePaddle (practical ultra lightweight OCR system, support 80 languages recognition, provide data annotation and synthesis tools, support training and deployment among server, mobile, embedded and IoT devices)项目地址: https://gitcode.com/paddlepaddle/PaddleOCR创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表