PaddleOCR 源码编译指南：从 pip 安装到自建 C++ 可执行文件的完整教程

PaddleOCR 源码编译指南从 pip 安装到自建 C 可执行文件的完整教程【免费下载链接】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 源码编译指南你要么得到一个可以逐行修改、断点调试的 Python 可编辑环境要么得到一个脱离 Python 运行时、在服务器上离线执行文字识别的独立 C 可执行文件。全文按选路线 → 开工前自查 → 主路线逐步走通 → 踩坑对照组织先定位你属于哪条路线再动手。该走哪条路线按需求对号入座路线 A直接用现成包只需要调 API 做识别pip install paddleocr就够不需要本文任何一步。路线 BPython 源码安装要改 Python 侧逻辑、验证自己的补丁或发布定制 wheel走deploy之外的paddleocr/目录安装。路线 CC 推理库编译交付一个无 Python 依赖的程序目标在deploy/cpp_infer/下编译出ppocr可执行文件。路线 DARM 交叉编译目标是开发板或嵌入式设备在 C 路线基础上换工具链、换依赖架构。为什么非源码编译不可pip 拿到的 wheel 是别人编译好的产物改不了行为、优化不到你的指令集、也搬不进 256MB 内存的设备。三条理由不占一条直接用路线 A。开工前自查Linux 环境 6 项核对清单组件下限推荐操作系统Ubuntu 18.04 / CentOS 7Ubuntu 20.04Python3.8pyproject.toml声明requires-python3.10CMake3.14deploy/cpp_infer/CMakeLists.txt声明3.18GCC8.29.x配合 GPU 版推理库需 11.2内存8 GB16 GB网络需下载 Paddle Inference 预编译包与第三方依赖建议挂代理白名单拉取代码并一次性核对版本git clone https://gitcode.com/paddlepaddle/PaddleOCR cd PaddleOCR python3 -V pip -V cmake --version | head -n1 g --version | head -n1四行版本号依次打印出来即通过哪条命令报错就先补哪个工具链。主路线Linux 上把 C 可执行文件跑起来主路线选Linux C它是最典型的源码编译场景产物ppocr内置文档预处理、文本检测、文本识别等模块。源码在 deploy/cpp_infer/入口是cli.cc。第一步拿到 Paddle Inference 预编译包PaddleOCR 的 C 程序不包含推理运行时模型计算由 Paddle Inference 库完成。去 Paddle Inference 官网按你的平台CPU 或 GPU 版本下载预编译包解压后应出现paddle/与third_party/两个子目录tar -xvf paddle_inference.tgz ls paddle_inference/version.txt paddle_inference/paddle/libversion.txt和libpaddle_inference.so或.a都在说明包结构完整记下这个目录它就是后面的PADDLE_LIB。第二步用现成脚本编译 OpenCV 4.xC 侧只兼容 OpenCV 4.x仓库自带构建脚本省掉手工配置打开deploy/cpp_infer/tools/build_opencv.sh把root_path改成 OpenCV 源码如 4.7.0的绝对路径install_path留默认${root_path}/opencv4执行sh tools/build_opencv.sh验证install_path下出现lib64/cmake/opencv4/目录它的上级路径就是下一步要传的OPENCV_DIR。第三步CMake 参数逐个说CMakeLists.txt靠PADDLE_LIB和OPENCV_DIR两个路径定位全部头文件与库缺一个就直接FATAL_ERROR终止configure 阶段还会自动下载 abseil-cpp、clipper、nlohmann 三个第三方包所以这步必须联网。cd deploy/cpp_infer mkdir -p build cd build cmake .. \ -DPADDLE_LIB$(realpath /path/to/paddle_inference) \ -DOPENCV_DIR/path/to/opencv4 \ -DWITH_GPUOFF -DWITH_MKLON终端最后打印Configuring done与Generating done即通过漏传路径时会看到please set PADDLE_LIB with -DPADDLE_LIB...这类提示。也可以改tools/build.sh里的OPENCV_DIR、LIB_DIR后执行sh tools/build.sh效果相同。第四步编译并验证 ppocr 可执行文件make -j$(nproc) find . -type f -name ppocrfind打印出ppocr文件路径即编译完成。运行前要准备文本检测、文本识别两个模块的推理模型下载入口见 model_list.md然后按--help输出的实际旗标名执行各版本旗标略有差异./ppocr --mode ocr \ --text_det_model_dir /path/to/det_infer \ --text_rec_model_dir /path/to/rec_infer \ --test_image_path /path/to/test.jpg终端打印出识别文本即整条链路跑通。测试输入可以直接用仓库里这张样图分支路线其他平台与安装方式Windows只改这三处工具链换成 Visual Studio 2022 CMake用 cmake-gui 指向deploy/cpp_infer目标平台选 x64OpenCV 用官方 Windows 预编译 exe解压后的build目录作OPENCV_DIRPaddle Inference 同样取 Windows 预编译包编译器标志/bigobj /MT等由 CMake 自动处理编译后还会自动拷贝mklml.dll、mkldnn.dll到输出目录。完整流程见 OCR_windows.md。Python 源码安装两条命令什么时候才值得放弃现成 wheel只有你要改paddleocr/里的代码或要打出自己的定制包python3 -m pip install -e . python3 -m pip show paddleocrLocation指向本地仓库路径即可编辑安装成功。需要打 wheel 时再执行python3 setup.py bdist_wheel然后安装dist/下生成的文件dist/里出现paddleocr-*.whl即构建成功。文档解析等信息抽取能力按 extras 追加如paddleocr[doc-parser]、paddleocr[all]。ARM 交叉编译只改这几行目标板上跑与主路线的差异集中在工具链与依赖架构cmake .. \ -DCMAKE_TOOLCHAIN_FILE../arm-toolchain.cmake \ -DPADDLE_LIB${SYSROOT}/usr/local/paddle_inference \ -DOPENCV_DIR${SYSROOT}/usr/local/opencv \ -DWITH_MKLOFFPaddle Inference 预编译包必须选 aarch64 版本与目标机架构一致ARM 上一般切 OpenBLAS所以关掉 MKL。选项速查CMake 参数开启后各有什么影响选项默认值开启后的影响WITH_MKLON使用 MKL 数学库Linux 下 configure 时向/usr/lib拷贝libmklmlOFF 改走 OpenBLASWITH_GPUOFF链接 CUDA/cuDNN需同时给出CUDA_LIB与CUDNN_LIBWITH_STATIC_LIBON静态链接libpaddle_inference.a交付时不随附运行时.soOFF 改动态链接USE_FREETYPEOFF启用 FreeType 字体渲染要求 OpenCV 带 freetype 模块否则直接报错CMAKE_BUILD_TYPE未显式设置Release 面向发布RelWithDebInfo 保留调试符号且不影响性能另外Linux 下默认附加-g -O3 -fopenmp语言标准固定 C11这两点写在CMakeLists.txt里一般不用动。踩坑记录按出现频率排序现象原因解决CMake 报FATAL_ERROR: please set PADDLE_LIB没传PADDLE_LIB/OPENCV_DIR用-D传两个路径OPENCV_DIR指向含lib64/cmake/opencv4的目录运行期找不到libmklml_intel.soWITH_MKLON时脚本向/usr/lib拷库非 root 无写权限sudo 重跑一次或把库目录加进LD_LIBRARY_PATH或改WITH_MKLOFFundefined reference to glog / protobufPADDLE_LIB指向残缺目录或推理库版本与代码不匹配确认包内paddle/与third_party/齐全换匹配版本OpenCV was not compiled with the freetype module开了USE_FREETYPE但 OpenCV 没编 freetype重编 OpenCV 时勾选BUILD_opencv_freetype且仅限 4.xmake 阶段内存不足、进程被杀并行线程过多调小-j数值分批编译pip 安装时报 paddlex 版本冲突Python 低于 3.8或 paddlex 不在 3.7.0 至 3.8.0 区间升级 Python 或装回区间内的版本进阶选项针对本机 CPU 的性能编译cmake .. -DCMAKE_CXX_FLAGS-marchnative -O3 -flto-marchnative只对编译机有效交付别的环境要单独出包验证方式是同一张图对比前后单张耗时。CI 里的构建验证只保留核心片段挂到任意流水线即可- name: Build C inference run: | cd deploy/cpp_infer mkdir build cd build cmake .. -DPADDLE_LIB/opt/paddle_inference -DOPENCV_DIR/opt/opencv4 make -j4任何一步失败都会让流水线变红防止依赖库版本悄悄漂移。收尾带走的 5 条要点先选路线再动手多数场景不需要源码编译改动、优化、嵌入式三条理由占一条才开工。PADDLE_LIB和OPENCV_DIR两个路径占掉大半故障先核对目录结构再进 cmake。每步留验证动作看version.txt、查cmake/opencv4目录、find出ppocr通过再走下一步。编译全程保留日志cmake 与 make 的输出存档排查时好比对。可执行文件只是前半程det/rec 推理模型齐了才能真正出识别结果。深入阅读C 构建入口deploy/cpp_infer/Linux 完整部署教程docs/version3.x/inference_deployment/local_inference/cpp/OCR.md模型清单docs/version3.x/model_list.md部署总览deploy/README.md【免费下载链接】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），仅供参考