★ FEATURED ARTICLE 1. 为什么我建议你从源码编译而不是直接pip安装PaddleOCR 这个工具在中文 OCR 圈子里基本属于绕不开的存在轻量、模型丰富、对中文场景的适配做得相当到位。但很多人第一次上手就卡在安装这一步——pip 一行命令装完跑 demo 直接报错然后开始怀疑人生。我自己前前后后在不同机器上装过不下十次从 Windows 到 Linux从 CPU 到 GPU踩过的坑足够写一篇避雷指南。先说一个反直觉的结论如果你只是想在本地快速跑通一个识别 demopip 安装确实够用但只要你打算长期用、要改代码、要换模型、要部署到服务器源码编译安装才是正路。原因很简单pip 装的是打包好的 wheel里面绑定的依赖版本是固定的一旦你的环境里已经有其他版本的 numpy、opencv 或者 paddlepaddle冲突几乎是必然的。而源码安装可以让你清楚地看到每个依赖的版本要求出问题也能定位到具体环节。这篇文章我会把 PaddleOCR 的安装测试完整走一遍包括环境准备、依赖选择、安装方式对比、验证脚本、常见报错排查以及我自己总结的一套装完必测的检查清单。不管你是刚接触 OCR 的新手还是已经用过其他 OCR 工具想迁移过来的老手应该都能从里面找到有用的东西。1.1 先搞清楚 PaddleOCR 到底依赖哪些东西很多人安装失败的根本原因是没弄明白 PaddleOCR 的依赖分层。它不是一个大包把所有东西都塞进去而是分成了好几层底层推理框架PaddlePaddle飞桨这是核心所有模型推理都靠它。CPU 版和 GPU 版是两个不同的包装错了直接跑不起来。OCR 算法层PaddleOCR 本身包含检测、识别、方向分类三个模块的模型和推理逻辑。图像处理依赖opencv-python、Pillow、numpy 这些负责图片的读取、预处理和后处理。可选依赖比如 layoutparser版面分析、pyclipper文本框处理、shapely多边形计算等不装也能跑基础功能但某些高级功能会报错。这里最关键的是PaddlePaddle 和 PaddleOCR 的版本对应关系。我见过太多人装了最新版的 PaddlePaddle然后装了个老版本的 PaddleOCR结果 import 就报错。正确的做法是先确定你要用哪个版本的 PaddleOCR然后去查它要求的 PaddlePaddle 版本范围。提示PaddleOCR 的官方文档里有一张版本对应表安装前务必先看一眼。不要凭感觉装最新版最新版之间不一定兼容。1.2 CPU 版和 GPU 版的选择逻辑这个问题我被问过无数次。简单说CPU 版安装简单不需要 CUDA 和 cuDNN适合学习、测试、轻量级应用。缺点是推理速度慢尤其是检测模型一张图可能要好几秒。GPU 版需要匹配的 CUDA 和 cuDNN安装麻烦但速度快十倍以上适合生产环境和批量处理。我的建议是如果你只是学习或者做 demo先用 CPU 版跑通流程确认代码逻辑没问题了再考虑换 GPU 版。不要一上来就折腾 GPU 环境CUDA 版本、驱动版本、cuDNN 版本三者之间的匹配关系能把人逼疯。而且很多时候你以为是 PaddleOCR 的问题其实是 CUDA 环境没配好。另外提醒一点GPU 版的 PaddlePaddle 对显卡驱动有最低版本要求装之前先用nvidia-smi看一下驱动版本再去查对应的 CUDA 版本。这个顺序不能反。2. 手把手走一遍完整安装流程下面这套流程是我在 Linux 环境下反复验证过的Windows 下大同小异差异我会单独标注。假设你用的是 Python 3.8 到 3.10 之间的版本太老或太新的 Python 版本可能会有兼容性问题。2.1 创建独立的虚拟环境这一步千万别省。我见过太多人直接在系统 Python 里装结果把系统环境搞崩了其他项目也跟着遭殃。用 conda 或者 venv 都行我个人习惯用 conda因为管理多版本 Python 更方便。conda create -n paddleocr python3.9 conda activate paddleocr如果你不想装 conda用 venv 也可以python -m venv paddleocr_env source paddleocr_env/bin/activate # Linux/Mac # paddleocr_env\Scripts\activate # Windows创建完环境后先升级一下 pip避免因为 pip 版本太老导致某些包装不上python -m pip install --upgrade pip2.2 安装 PaddlePaddle这是整个流程里最容易出问题的一步。CPU 版相对简单python -m pip install paddlepaddle2.5.2 -i https://pypi.tuna.tsinghua.edu.cn/simple注意我指定了版本号 2.5.2这是为了和后面要装的 PaddleOCR 版本匹配。如果你不指定版本pip 会装最新的可能和 PaddleOCR 不兼容。GPU 版就复杂一些需要先确认 CUDA 版本。假设你的环境是 CUDA 11.2python -m pip install paddlepaddle-gpu2.5.2.post112 -f https://www.paddlepaddle.org.cn/whl/linux/mkl/avx/stable.html这里的post112就代表 CUDA 11.2。不同 CUDA 版本对应的后缀不一样装之前一定要去官网查清楚。装完之后验证一下import paddle paddle.utils.run_check()如果输出里出现 PaddlePaddle is installed successfully说明底层框架没问题。如果报错先别急着装 PaddleOCR把 PaddlePaddle 的问题解决了再说。2.3 安装 PaddleOCR有两种方式pip 和源码。先说你什么时候用 pippython -m pip install paddleocr2.7.0.3 -i https://pypi.tuna.tsinghua.edu.cn/simple这个方式适合快速验证但如前所述依赖冲突的风险较高。如果你要改代码或者长期使用建议源码安装git clone https://github.com/PaddlePaddle/PaddleOCR.git cd PaddleOCR git checkout release/2.7 # 切换到稳定分支 python -m pip install -r requirements.txt python -m pip install -e .-e参数是可编辑安装意思是你在源码目录里改代码直接生效不用重新安装。这对调试非常有用。源码安装时requirements.txt里列了一堆依赖其中有些是可选的。如果你只需要基础 OCR 功能可以手动精简一下只装核心的几个python -m pip install opencv-python pillow numpy pyclipper shapely imgaug pyyaml python-docx这样装出来的环境更干净出问题的概率也更低。2.4 下载推理模型PaddleOCR 的模型不是打包在代码里的需要单独下载。第一次运行的时候会自动下载但国内网络环境下自动下载经常失败。我的做法是手动下载好放到指定目录。模型分三类检测模型、识别模型、方向分类模型。基础中文场景用这几个就够了检测模型ch_PP-OCRv4_det_infer识别模型ch_PP-OCRv4_rec_infer方向分类模型ch_ppocr_mobile_v2.0_cls_infer下载地址在 PaddleOCR 的文档里有下载完解压到~/.paddleocr/whl/对应的子目录下。目录结构大概是这样的~/.paddleocr/whl/ ├── det/ │ └── ch/ │ └── ch_PP-OCRv4_det_infer/ ├── rec/ │ └── ch/ │ └── ch_PP-OCRv4_rec_infer/ └── cls/ └── ch_ppocr_mobile_v2.0_cls_infer/放对位置之后运行时就不会再去联网下载了。3. 跑通第一个识别脚本并验证结果装完之后最激动人心的时刻就是跑第一个脚本。但我要提醒你不要一上来就拿复杂的图片测试先用一张干净的、白底黑字的截图确认基础流程没问题再逐步增加难度。3.1 最简识别代码from paddleocr import PaddleOCR ocr PaddleOCR(use_angle_clsTrue, langch) result ocr.ocr(test.png, clsTrue) for line in result[0]: print(line[1][0], line[1][1])这段代码做了几件事初始化 OCR 对象开启方向分类指定中文模型然后对图片进行识别。result的结构是一个列表每个元素对应一行文本包含文本框坐标、识别文字和置信度。第一次运行会稍微慢一点因为要加载模型。如果一切正常你会看到识别出来的文字和对应的置信度分数。3.2 结果验证不能只看有没有输出很多人跑出结果就以为成功了其实不然。我总结了一套验证清单每次装完新环境都会走一遍检查项验证方法合格标准文字准确性用已知内容的图片测试识别结果与原文一致置信度查看输出的分数清晰文字应在 0.95 以上方向分类用旋转 180 度的图片测试能正确识别并纠正方向多行文本用段落截图测试每行独立识别顺序正确边界情况用空白图、纯色图测试不报错返回空结果特别是最后一项空白图测试经常被忽略。有些版本在遇到空白图时会抛异常如果你没测过上线后遇到用户传了张白图程序直接崩了。3.3 性能基准测试如果你打算用于生产还需要测一下速度。我的做法是准备 10 张不同复杂度的图片循环识别 10 次记录平均耗时import time times [] for i in range(10): start time.time() ocr.ocr(test.png, clsTrue) times.append(time.time() - start) print(f平均耗时: {sum(times)/len(times):.3f}秒)CPU 环境下一张 1080P 的图片检测加识别大概在 1 到 3 秒之间。GPU 环境下能降到 0.1 到 0.3 秒。如果你测出来慢得离谱先检查是不是用了 CPU 版却以为自己在用 GPU。4. 那些年我踩过的安装报错与排查思路这一节是整篇文章最有价值的部分。下面这些报错我几乎每个都遇到过至少一次有的还不止一次。4.1 ImportError: libGL.so.1: cannot open shared object file这是 Linux 环境下最常见的报错尤其是用 Docker 或者最小化安装的系统。原因是 opencv-python 依赖 libGL但系统里没装。解决方案有两个# 方案一安装系统依赖 apt-get update apt-get install -y libgl1-mesa-glx # 方案二换用 headless 版本的 opencv pip uninstall opencv-python pip install opencv-python-headless我一般推荐方案二因为 headless 版本不需要图形界面更适合服务器环境而且体积更小。4.2 AttributeError: module numpy has no attribute int这是 numpy 版本过高导致的。numpy 1.24 之后移除了np.int、np.float这些别名但很多老代码还在用。PaddleOCR 某些版本就有这个问题。解决方案是降级 numpypip install numpy1.23.5或者升级 PaddleOCR 到修复了这个问题的版本。我一般选择降级 numpy因为升级 PaddleOCR 可能引入其他不兼容。4.3 模型下载卡住或失败国内网络环境下自动下载模型经常超时。除了前面说的手动下载还有一个办法是设置代理环境变量。但更稳妥的做法还是手动下载一劳永逸。如果你发现程序卡在 Downloading... 不动直接 CtrlC 中断然后去手动下载。下载地址在 PaddleOCR 的tools/infer/utility.py里能找到搜索MODEL_URLS就能看到所有模型的下载链接。4.4 GPU 版装了但用不了这个问题的排查链路比较长我一般按这个顺序查nvidia-smi能不能正常输出不能的话是驱动问题。python -c import paddle; paddle.utils.run_check()输出里有没有 GPU 字样没有的话说明装的是 CPU 版。CUDA 版本和 PaddlePaddle 版本是否匹配post112对应 CUDA 11.2装错了用不了。cuDNN 是否安装版本是否匹配这四步走完基本能定位到问题。我遇到过最坑的一次是驱动版本太老nvidia-smi 能输出但 CUDA 版本不够升级驱动后解决。4.5 内存溢出批量处理大图时可能会遇到内存溢出。PaddleOCR 默认会把整张图加载到内存图片特别大的时候就爆了。解决方案是限制图片尺寸ocr PaddleOCR( det_limit_side_len960, # 限制检测输入尺寸 rec_image_shape3, 48, 320 # 限制识别输入尺寸 )或者自己先对图片做缩放再传给 OCR。我一般会把长边限制在 2000 像素以内既能保证识别精度又不会爆内存。5. 装完之后怎么持续维护这套环境安装只是开始后续的维护同样重要。我见过太多人装完就不管了结果过几个月想用的时候发现各种报错。5.1 锁定依赖版本装好之后第一件事是导出当前环境的依赖清单pip freeze requirements_lock.txt这个文件记录了你当前所有包的精确版本。以后环境出问题了照着这个文件重装就能恢复。我一般会把 PaddlePaddle、PaddleOCR、numpy、opencv 这几个关键包的版本单独记下来放在项目的 README 里。5.2 定期检查模型更新PaddleOCR 的模型迭代挺快的PP-OCRv4 之后可能还会有 v5。新模型通常在精度和速度上都有提升值得关注。但不要盲目升级升级前先在测试环境验证确认新模型在你的场景下确实更好再换。5.3 建立自己的测试用例集我建议每个用 PaddleOCR 的项目都建一个小的测试集包含各种典型场景的图片清晰文档、模糊照片、旋转文本、多语言混合、表格截图等。每次环境变动或者模型升级后跑一遍测试集对比识别结果确保没有退化。这个习惯帮我避免了好几次升级后精度反而下降的事故。有一次升级模型后通用场景精度提升了但我项目里特有的那种票据识别精度掉了好几个点幸好测试集发现了。5.4 关于 Docker 化的一点经验如果你的项目要部署到多台机器强烈建议做成 Docker 镜像。把 Python 版本、依赖、模型全部打包进去一次构建到处运行彻底告别在我机器上能跑的问题。Dockerfile 的核心部分大概是这样FROM python:3.9-slim RUN apt-get update apt-get install -y libgl1-mesa-glx libglib2.0-0 WORKDIR /app COPY requirements_lock.txt . RUN pip install -r requirements_lock.txt COPY . . CMD [python, app.py]注意基础镜像用 slim 版本体积小。系统依赖只装必要的libgl 和 libglib 这两个是 opencv 需要的不装会报错。我自己在实际操作中的体会是PaddleOCR 的安装测试看似简单但真正要做好需要把环境隔离、版本匹配、模型管理、性能验证这几件事都做到位。尤其是版本匹配这一环是绝大多数问题的根源。装之前多花十分钟查版本对应关系能省下后面几个小时的排查时间。另外测试用例集这个习惯越早建立越好它会在你后续每一次环境变动时帮你兜底。
阅读完成 · 觉得有帮助？
