企业官网建设流程全解析

PaddleOCR 3.5 安装完全指南：Python 分发包、可选依赖组、推理引擎与训练导出环境搭建

【免费下载链接】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

本指南以 docs/version3.x/installation.md 为骨架，结合仓库内 pyproject.toml、requirements.txt 等源码与配置展开，帮助你在本地完成 PaddleOCR 推理环境的搭建：既能通过paddleocrPython 分发包按需启用文档解析、信息抽取、文档翻译等能力，也能独立安装训练与模型导出所需的完整依赖，并在此基础上理解推理引擎与飞桨框架的安装前提。

PaddleOCR 3.x 提供两条彼此独立的安装路径：一是面向本地推理的paddleocrPython 分发包（含可选依赖组），安装后即可调用预训练产线完成 OCR、版面解析、表格识别、关键信息抽取等推理任务；二是面向模型训练与导出的完整仓库依赖，需要先安装飞桨框架，再安装仓库根目录的 requirements.txt。本文按此两条主线组织，并补充推理引擎选择、依赖组映射等底层细节，帮助你按需安装、避免依赖冲突。

1. 安装paddleocrPython 库：两条路径

1.1 Python 版本要求

• paddleocr本体与doc2md依赖组支持Python 3.8 及以上；
• 其他可选依赖组（doc-parser、ie、trans、all等）受上游依赖限制，需要Python 3.9 及以上。

这与仓库 pyproject.toml 中声明的requires-python = ">=3.8"以及lmdb; python_version >= "3.9"等条件依赖相互印证：基础包在 3.8 即可运行，但更重的可选能力对解释器版本有更高要求。

1.2 从 PyPI 安装最新版本

# 仅需要通用 OCR 与文档图像预处理等默认能力 python -m pip install paddleocr # 需要文档解析、文档理解、文档翻译、关键信息抽取等全部可选能力 # python -m pip install "paddleocr[all]"

执行后，pip会同时解析并安装 pyproject.toml 中声明的核心依赖：paddlex[ocr-core]>=3.7.0,<3.8.0、PyYAML>=6、requests、aiohttp>=3.8.0、typing-extensions>=4.12。也就是说，安装paddleocr时 PaddleX 会作为底层推理基础设施一并安装，但只安装 OCR 类任务所需的最小依赖子集，避免依赖体积过度膨胀（详见 PaddleOCR 与 PaddleX）。

1.3 从源码安装

# 仅需要通用 OCR 与文档图像预处理等默认能力 python -m pip install "paddleocr@git+https://github.com/PaddlePaddle/PaddleOCR.git" # 需要文档解析、文档理解、文档翻译、关键信息抽取等全部可选能力 # python -m pip install "paddleocr[all]@git+https://github.com/PaddlePaddle/PaddleOCR.git"

从源码安装默认跟踪仓库当前默认分支。仓库使用setuptools_scm动态生成版本号（见 pyproject.toml 的[tool.setuptools_scm]配置），因此安装的是与当前提交对应的开发版本。

2. 按功能选择依赖组（extras）

除all外，可通过指定依赖组启用部分可选能力。依赖组表示能力域（文档解析、信息抽取、文档翻译等）。各依赖组如下：

| 依赖组名称 | 对应的功能 | | - | - | |doc-parser| 文档解析，可用于提取文档中的表格、公式、印章、图片等版面元素，包含 PP-StructureV3 等模型方案 | |ie| 信息抽取，可用于从文档中提取关键信息，如姓名、日期、地址、金额等，包含 PP-ChatOCRv4 等模型方案 | |trans| 文档翻译，可用于将文档从一种语言翻译为另一种语言，包含 PP-DocTranslation 等模型方案 | |doc2md| 文档转 MarkDown，可用于将 Word、Excel、PowerPoint 文件快速转为可读文本 | |all| 完整功能 |

通用 OCR 产线与文档图像预处理产线无需额外依赖组；文档解析、信息抽取、文档翻译等按上表安装对应组。各产线所属依赖组见对应产线文档；单功能模块在任一包含该模块的依赖组安装后即可调用其基础能力。

2.1 依赖组在仓库中的真实映射

依赖组的实际内容定义在 pyproject.toml 的[project.optional-dependencies]段：

[project.optional-dependencies] doc-parser = ["paddlex[ocr,genai-client]>=3.7.0,<3.8.0"] ie = ["paddlex[ie]>=3.7.0,<3.8.0"] trans = ["paddlex[trans]>=3.7.0,<3.8.0"] doc2md = ["python-docx>=0.8.11", "python-pptx>=0.6.21", "openpyxl>=3.0.0", "pylatexenc>=2.10,<3"] all = ["paddlex[ocr,genai-client,ie,trans]>=3.7.0,<3.8.0", "python-docx>=0.8.11", "python-pptx>=0.6.21", "openpyxl>=3.0.0"]

由此可以确认几个关键事实：

• doc-parser与ie、trans本质是 PaddleX 的 extras 透传：doc-parser对应paddlex[ocr,genai-client]，ie对应paddlex[ie]，trans对应paddlex[trans]；
• doc2md是纯办公文档转换依赖：python-docx（Word）、python-pptx（PowerPoint）、openpyxl（Excel）分别对应 Word、PPT、Excel 三种格式的解析转换，pylatexenc用于 LaTeX 公式编码处理；对应的转换实现位于 paddleocr/_doc2md，其convert(source, output=None, **kwargs)函数支持将办公文档转为 Markdown，可用paddleocr.doc2md_convert调用；
• all是前四者的并集，且不含pylatexenc（其被限定<3，属于doc2md的专属依赖）。

安装示例：

# 文档解析能力（版面、表格、公式、印章等） python -m pip install "paddleocr[doc-parser]" # 关键信息抽取能力（PP-ChatOCRv4 等） python -m pip install "paddleocr[ie]" # 文档翻译能力（PP-DocTranslation 等） python -m pip install "paddleocr[trans]" # 办公文档转 Markdown python -m pip install "paddleocr[doc2md]"

2.2 安装后的功能入口

安装完成后，paddleocr包对外暴露完整的能力面（见 paddleocr/init.py 的__all__）：

• 单功能模型：TextDetection、TextRecognition、FormulaRecognition、LayoutDetection、SealTextDetection、TableStructureRecognition、DocVLM等；
• 产线（Pipeline）：PaddleOCR（通用 OCR）、PPStructureV3（文档解析）、PPChatOCRv4Doc（关键信息抽取）、PPDocTranslation（文档翻译）、DocPreprocessor（文档图像预处理）等；
• 命令行入口：paddleocr命令由 pyproject.toml 的[project.scripts]注册（paddleocr = "paddleocr.__main__:console_entry"），可通过paddleocr --help查看可用子命令。

3. 安装推理引擎（按需）

PaddleOCR 3.5 采用统一推理引擎配置，底层可对接飞桨、Transformers 等。若要实际执行模型推理，请参考 推理引擎与配置说明 安装所选推理引擎。

当前支持的推理引擎及安装方式如下：

| 引擎类别 |engine取值 | 安装方式 | | - | - | - | | 飞桨框架 |paddle、paddle_static、paddle_dynamic| 参考 飞桨框架安装 | | Transformers |transformers|python -m pip install "transformers>=5.10.0"| | ONNX Runtime |onnxruntime|python -m pip install onnxruntime-gpu|

要点说明：

• 默认引擎行为：如果不显式指定engine，除高性能推理与生成式 AI 客户端请求等少数场景外，大多数情况下会优先使用飞桨框架推理；显式指定engine后则优先按指定引擎初始化；
• 依赖隔离建议：不同推理引擎之间可能存在依赖冲突，建议每个环境仅安装一种推理引擎；
• 引擎用法示例（摘自 inference_engine.md）：

# CLI 指定引擎 paddleocr text_detection -i general_ocr_001.png --engine transformers paddleocr ocr -i general_ocr_001.png --engine paddle_static

# Python API 指定引擎与引擎配置 from paddleocr import TextDetection model = TextDetection( model_name="PP-OCRv5_server_det", engine="paddle_static", engine_config={ "device_type": "cpu", "cpu_threads": 4, "run_mode": "mkldnn", }, ) result = model.predict("general_ocr_001.png")

3.1 飞桨框架安装要点

飞桨框架的安装细节参见 飞桨框架安装，关键信息如下：

• pip 安装（CPU）：python -m pip install paddlepaddle==3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cpu/
• pip 安装（GPU）：需显卡驱动版本满足要求，例如python -m pip install paddlepaddle-gpu==3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu118/；无需关注物理机上的 CUDA 版本，只需关注显卡驱动程序版本；
• Docker 安装：使用飞桨官方镜像并映射工作目录，GPU 场景加--gpus all参数，例如docker run --gpus all --name paddleocr -v $PWD:/paddle --shm-size=8G --network=host -it ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddle:3.0.0-gpu-cuda11.8-cudnn8.9-trt8.6 /bin/bash；
• 验证安装：python -c "import paddle; print(paddle.__version__)"，成功时输出版本号（如3.2.0）；
• 版本对应关系：PaddleOCR 与 PaddleX、飞桨存在版本对应表（见 PaddleOCR 与 PaddleX），例如 PaddleOCR3.5.x对应 PaddleX>=3.5.0,<3.6.0、飞桨>=3.0.0，安装时注意三者版本匹配。

4. 安装训练与导出依赖

4.1 与推理安装路径的关系

训练与导出路径与第 1 节的paddleocr包及可选依赖组属于不同安装维度，同一环境中可同时存在，无需强制隔离。但训练与导出依赖飞桨框架，且若环境中已安装飞桨之外的推理引擎（如 Transformers），可能出现依赖冲突，建议在全新的环境中进行安装。

Python 版本要求：训练与模型导出支持 Python 3.8 及以上。

4.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

4.3 训练依赖清单解读

仓库根目录 requirements.txt 是训练与导出路径的完整依赖清单，主要包括：

| 依赖 | 用途 | | - | - | |shapely、pyclipper| 多边形几何运算，用于检测框的生成、裁剪与后处理 | |scikit-image| 图像处理与评价指标计算 | |lmdb| LMDB 数据集（OCR 训练数据常以 LMDB 格式存储）的读取，Python 3.9+ 与 <3.9 分别有版本约束 | |tqdm、numpy| 训练进度展示与数值计算基础库 | |rapidfuzz| 文本相似度计算，用于识别结果评估 | |opencv-python、opencv-contrib-python| 图像读取与数据增强 | |cython| 编译加速算子（如部分后处理扩展模块） | |Pillow、pyyaml、requests| 图像 I/O、配置解析、网络请求 | |albumentations、albucore| 数据增强（albucore用于兼容 albumentations 新版本） | |packaging| 版本号解析与比较 |

安装完成后，即可使用仓库 tools/train.py、tools/export_model.py 等脚本进行模型训练与导出。

5. 安装验证与常见问题

5.1 快速验证安装

# 验证 paddleocr 包与版本 python -c "import paddleocr; print(paddleocr.__version__)" # 验证飞桨框架（训练/导出路径必需） python -c "import paddle; print(paddle.__version__)" # 查看 CLI 可用子命令 paddleocr --help

paddleocr.__version__通过importlib.metadata读取分发包元数据（见 paddleocr/_version.py），未正常安装时返回0.0.0，可据此判断包是否安装成功。

5.2 常见问题排查

• 依赖冲突（Transformers 与飞桨共存）：推理引擎间可能存在依赖冲突，建议每个环境只保留一种推理引擎；训练与导出路径同样建议在全新环境安装；
• Python 版本不符：安装doc-parser、ie、trans、all等依赖组需要 Python 3.9+，基础 OCR 能力与doc2md支持 3.8+；
• GPU 无法使用：优先核对显卡驱动版本而非物理机 CUDA 版本；驱动版本要求参见 飞桨框架安装；
• 产线依赖组不确定：各产线所属依赖组见对应产线文档（例如 PP-StructureV3、PP-ChatOCRv4、PP-DocTranslation），按表安装对应组即可。

6. 两种安装路径速查表

| 场景 | 安装方式 | Python 版本 | 是否需飞桨 | | - | - | - | - | | 通用 OCR / 文档图像预处理推理 |python -m pip install paddleocr| ≥ 3.8 | 按所选推理引擎（默认飞桨） | | 文档解析（PP-StructureV3 等） |python -m pip install "paddleocr[doc-parser]"| ≥ 3.9 | 按所选推理引擎 | | 关键信息抽取（PP-ChatOCRv4 等） |python -m pip install "paddleocr[ie]"| ≥ 3.9 | 按所选推理引擎 | | 文档翻译（PP-DocTranslation 等） |python -m pip install "paddleocr[trans]"| ≥ 3.9 | 按所选推理引擎 | | 办公文档转 Markdown |python -m pip install "paddleocr[doc2md]"| ≥ 3.8 | 否 | | 全部推理能力 |python -m pip install "paddleocr[all]"| ≥ 3.9 | 按所选推理引擎 | | 模型训练 / 导出 | 克隆仓库 +pip install -r requirements.txt| ≥ 3.8 | 必须（先装飞桨框架） |

按需选择、按表安装，即可在最小依赖体积下获得完整的 PaddleOCR 3.5 推理与训练能力。

【免费下载链接】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