PaddleOCR离线打包exe实战：模型内置与PyInstaller避坑指南

简介：这份资源面向需要在无 Python 环境下完成文字识别的开发者与运维人员，提供一套基于 PaddleOCR 的离线 exe 工具打包成品，解决现场部署时依赖缺失、无法直接调用 OCR 接口的问题，适合具备基础 Python 与打包经验的中级读者参考使用。压缩包共约 2000 个文件，体积 279.22MB，以 py 脚本、pyc 字节码与 pyd 扩展模块为主体，配合 dll 动态库、msg 提示信息、enc 编码资源及 tcl、txt、png 等运行时与说明文件，完整保留了 PyInstaller 打包后的目录结构，便于直接运行或二次裁剪。资源已有 3790 人学习下载，读者可从中获得可执行的离线识别工具、PaddleOCR 调用脚本示例，以及模型与依赖的打包组织方式，用于快速验证图片路径输入到 txt 结果输出的完整流程，并据此调整模型大小与性能平衡。

1. 把 PaddleOCR 塞进一个 exe：离线场景下最省心的落地方式

上周有个做档案数字化的朋友找我，说他们车间那批机器压根不联网，但每天要处理几千张扫描件，问我能不能把 PaddleOCR 做成一个双击就能跑的 exe。这个需求其实很典型——PaddleOCR 本身识别效果不错，但依赖链长、模型文件散、Python 环境一装就是几百兆，直接扔到没网的机器上基本跑不起来。所谓「paddleocr 打包 exe 离线工具」，核心就是把 PaddleOCR 的推理能力、模型权重和运行时依赖全部收进一个可执行文件里，让目标机器不需要装 Python、不需要联网下载模型，双击就能完成图片或 PDF 的文字识别。适合谁？做内网部署的、给客户交付桌面工具的、以及需要在隔离环境里批量处理票据证照的从业者。这篇不聊 OCR 算法原理，只讲怎么把它打包成一个真正能用的离线 exe，以及我在这个过程中翻过的车。

2. 打包前的选型：为什么是 PaddleOCR + PyInstaller 这套组合

2.1 离线 exe 的三个硬约束

在动手之前得先把约束想清楚，否则后面全是返工。第一个约束是模型必须内置。PaddleOCR 默认行为是首次运行时去下载检测、识别、方向分类三个模型，离线机器上这一步直接卡死。所以打包时必须把模型文件一起塞进去，并且改掉代码里的模型路径逻辑，让它从本地读而不是从缓存目录找。

第二个约束是依赖必须收敛。PaddleOCR 背后是 PaddlePaddle 推理库，加上 OpenCV、Shapely、PyMuPDF 等一堆包，全量打进去轻松超过 500MB。我的做法是只保留推理必需的模块，把训练相关的、可视化调试相关的依赖剔掉，体积能压到 300MB 左右，对 U 盘拷贝和邮件传输都友好得多。

第三个约束是路径必须动态解析。PyInstaller 打包后，程序运行在一个临时解压目录里，__file__的指向和开发环境完全不同。模型路径、配置文件路径如果写死绝对路径，换台机器就崩。常见做法是用sys._MEIPASS做基准，所有资源路径都相对它拼。

提示：这三个约束里，模型内置是最容易漏的。很多人本地测试通过，一到客户机器就报「模型下载失败」，八成是没处理这一层。

2.2 PyInstaller 与 PaddleOCR 的兼容性边界

选 PyInstaller 而不是 Nuitka 或 cx_Freeze，理由很实际：PaddleOCR 的依赖里有大量动态导入和 C 扩展，PyInstaller 的 hook 机制对这类包支持最成熟，社区里踩过的坑也最多，遇到问题能搜到答案。Nuitka 编译出来启动快、体积小，但对 Paddle 这种重型框架的兼容性还在打磨阶段，我试过两次都在推理库加载阶段翻车，后来就老实回到 PyInstaller。

不过 PyInstaller 也不是万能。PaddlePaddle 的推理库里有几个.dll（Windows 下）是通过运行时动态加载的，PyInstaller 的静态分析扫不到，必须手动在 spec 文件里用binaries声明。另外 OpenCV 的cv2包在打包后经常出现ImportError: DLL load failed，这是因为它依赖的opencv_videoio_ffmpeg*.dll没被自动收集，得手动补。

版本搭配上，我一般锁定 PaddleOCR 2.x 系列配 PaddlePaddle 2.5 左右的 CPU 版，Python 用 3.9 或 3.10。太新的 Python 版本 PyInstaller 支持滞后，太老的又和 Paddle 的 wheel 对不上。这个组合不是唯一解，但在我经手的几个交付项目里最稳。

2.3 目录结构先定好，后面少改代码

动手写代码前，先把工程目录规划清楚。我习惯这么组织：

ocr_offline/ ├── main.py # 入口，含 GUI 或命令行逻辑 ├── ocr_engine.py # PaddleOCR 封装 ├── models/ # 内置模型 │ ├── det/ # 检测模型 │ ├── rec/ # 识别模型 │ └── cls/ # 方向分类模型 ├── config/ │ └── settings.json # 可调参数 └── build.spec # PyInstaller 配置

模型文件从 PaddleOCR 官方仓库下载后放models/下，每个子目录里是inference.pdmodel和inference.pdiparams两个文件。这样组织的好处是打包时一条datas规则就能把整个models目录带进去，代码里也只需要拼一个基准路径。

3. 核心实现：模型内置与推理封装

3.1 让 PaddleOCR 从本地模型目录加载

PaddleOCR 的PaddleOCR()构造函数接受det_model_dir、rec_model_dir、cls_model_dir三个参数，指向本地模型目录即可跳过下载。关键是把路径解析成打包后也能用的形式：

import sys import os def resource_path(relative_path): """兼容开发环境和 PyInstaller 打包后的资源路径解析""" if hasattr(sys, '_MEIPASS'): # 打包后，资源被解压到临时目录 sys._MEIPASS base_path = sys._MEIPASS else: # 开发环境，以当前文件所在目录为基准 base_path = os.path.dirname(os.path.abspath(__file__)) return os.path.join(base_path, relative_path) from paddleocr import PaddleOCR def build_ocr(): ocr = PaddleOCR( use_angle_cls=True, lang='ch', det_model_dir=resource_path('models/det'), rec_model_dir=resource_path('models/rec'), cls_model_dir=resource_path('models/cls'), use_gpu=False, # 离线交付机器通常无 GPU show_log=False # 关掉冗余日志，避免控制台刷屏 ) return ocr

这段代码的逻辑很直白：resource_path先判断是否处于打包环境，是则用sys._MEIPASS作为根，否则用源码目录。三个*_model_dir参数把模型锁定到本地，use_gpu=False是因为交付机器基本是办公本，show_log=False则是为了 exe 运行时界面干净——PaddleOCR 默认会打印一堆加载信息，客户看到会以为程序卡住了。

参数上还有两个值得调的：det_limit_side_len控制检测时图片缩放的长边上限，默认 960，处理高分辨率扫描件时可以提到 1280 提升小字检出率，但速度会降；rec_batch_num是识别阶段的批大小，CPU 上设 6 左右比较均衡，设太大内存吃不消。

3.2 封装一个能处理图片和 PDF 的识别入口

实际交付里，客户往往既要识别单张图片，也要处理多页 PDF。PaddleOCR 本身只吃图片数组，PDF 得先转图。我用 PyMuPDF 做转换，封装成一个统一入口：

import fitz # PyMuPDF import numpy as np from PIL import Image import io def pdf_to_images(pdf_path, dpi=200): """把 PDF 每页渲染成 numpy 数组，供 OCR 使用""" doc = fitz.open(pdf_path) images = [] for page in doc: # 按 dpi 渲染，200 对文字类文档足够清晰 pix = page.get_pixmap(dpi=dpi) img_bytes = pix.tobytes("png") img = Image.open(io.BytesIO(img_bytes)).convert("RGB") images.append(np.array(img)) doc.close() return images def recognize(ocr, input_path): """统一入口：根据扩展名分流""" ext = os.path.splitext(input_path)[1].lower() if ext == '.pdf': pages = pdf_to_images(input_path) else: pages = [np.array(Image.open(input_path).convert("RGB"))] results = [] for page_img in pages: raw = ocr.ocr(page_img, cls=True) # raw 结构为 [[ [box, (text, score)], ... ]] lines = [] if raw and raw[0]: for item in raw[0]: box, (text, score) = item lines.append({"text": text, "score": round(score, 4)}) results.append(lines) return results

pdf_to_images里dpi=200是个经验值：低于 150 小字容易糊，高于 300 内存和耗时陡增，200 对 A4 文档是甜点。recognize里对raw的判断要小心，PaddleOCR 在没检测到文字时返回的可能是[None]而不是空列表，直接索引会抛异常，所以加了if raw and raw[0]的双重判断——这个坑我在一个票据项目里踩过，某张空白页直接把整个批处理干崩了。

3.3 用 spec 文件把模型和隐藏依赖打进去

PyInstaller 命令行参数一多就难维护，我习惯写 spec 文件。核心是datas带模型、binaries补动态库、hiddenimports兜住动态导入：

# build.spec # -*- mode: python ; coding: utf-8 -*- a = Analysis( ['main.py'], pathex=[], binaries=[ # 手动补 OpenCV 的 ffmpeg 动态库，避免 DLL load failed ('venv/Lib/site-packages/cv2/opencv_videoio_ffmpeg*.dll', 'cv2'), ], datas=[ ('models', 'models'), # 整个模型目录带进去 ('config', 'config'), ], hiddenimports=[ 'paddle', 'paddleocr', 'shapely', 'pyclipper', 'skimage', 'imgaug', 'fitz', ], hookspath=[], runtime_hooks=[], excludes=['matplotlib', 'tkinter.test', 'pytest'], noarchive=False, ) pyz = PYZ(a.pure) exe = EXE( pyz, a.scripts, a.binaries, a.datas, name='ocr_offline', console=False, # 有 GUI 时关控制台；纯命令行改 True upx=False, # UPX 压缩对 Paddle 的 dll 有副作用，关掉 )

datas里的('models', 'models')表示把源码目录的models整个复制到打包产物的models下，运行时resource_path('models/det')正好能对上。binaries那条是补 OpenCV 的 ffmpeg 库，通配符路径按自己虚拟环境实际位置改。excludes剔掉 matplotlib 和 pytest 能省几十兆，这两个包 PaddleOCR 推理时用不到，但会被间接依赖拉进来。

upx=False这条值得单独说。UPX 能把 exe 压小不少，但它对 Paddle 的某些 dll 做压缩后，运行时解压会出问题，表现为程序启动即闪退、无任何报错。我一开始为了压体积开了 UPX，排查了大半天才定位到，后来一律关掉。

打包命令就一句：

pyinstaller build.spec --clean --noconfirm

--clean清掉上次的缓存，--noconfirm跳过覆盖确认，适合反复迭代时用。

4. 避坑与排查：那些让我返工的细节

4.1 打包后启动闪退，控制台无输出

现象：双击 exe 窗口一闪而过，命令行运行也没有任何 traceback。

原因：最常见的是console=False把异常吞了，加上某个 dll 加载失败发生在 Python 层之前。我遇到的一次是 UPX 压缩破坏了paddle的推理库。

解决：先把 spec 里console改成True重新打包，让报错能打出来；同时关掉 UPX。如果还是无输出，用--debug=all打一版调试包，看warn-*.txt里有没有缺失模块的记录。

4.2 报「模型文件不存在」，但明明打进去了

现象：开发环境正常，打包后运行提示det_model_dir路径下找不到inference.pdmodel。

原因：模型路径用了相对源码目录的写法，打包后工作目录变了。或者datas的目标路径层级写错，模型被放到了子目录里。

解决：统一走resource_path，并在启动时打印一次实际解析出的模型路径，对照打包产物目录结构核对。我现在的习惯是在build_ocr里加一行print(resource_path('models/det'))，打包后先跑一次确认路径对得上，再关掉。

4.3 OpenCV 报 DLL load failed

现象：ImportError: DLL load failed while importing cv2，只在打包后出现。

原因：cv2依赖的 ffmpeg 动态库没被 PyInstaller 自动收集，或者收集了但不在cv2模块能找到的目录下。

解决：在 spec 的binaries里显式声明 ffmpeg dll，目标目录设为cv2。路径用通配符匹配虚拟环境里的实际文件，不同 OpenCV 版本文件名略有差异，打包前先ls一下确认。

4.4 识别结果乱码或中文变问号

现象：英文数字正常，中文全变成?或方块。

原因：打包环境缺少中文字体，或者 PaddleOCR 的字典文件没带进去。识别模型依赖ppocr_keys_v1.txt这类字典文件做解码。

解决：确认models/rec目录下除了模型文件还有字典文件，datas规则覆盖到；如果输出到界面或文件时乱码，检查写入时的编码是否显式指定utf-8。Windows 下open()默认用 GBK，写中文结果文件必须加encoding='utf-8'。

4.5 首次运行特别慢，之后正常

现象：exe 第一次启动要等十几秒，第二次快很多。

原因：PyInstaller 的单文件模式每次运行都要把内容解压到临时目录，模型越大越慢。这是单文件模式的固有代价。

解决：如果对启动速度敏感，改用--onedir目录模式，把 exe 和依赖放一个文件夹里分发，启动快很多，代价是分发物是个文件夹而不是单个文件。我一般给客户交付用 onedir 打个压缩包，内部用还是单文件方便。

5. 进阶技巧：把识别质量和交付体验再往上提一档

打包跑通只是及格线，真正决定这个工具好不好用的是识别质量和交付细节。先说质量。PaddleOCR 默认的检测模型对倾斜、低对比度的扫描件表现一般，如果目标场景是老旧档案，可以在PaddleOCR()里把det_db_unclip_ratio从默认 1.5 调到 1.8 左右，让检测框稍微外扩，减少文字被截断的情况；drop_score默认 0.5，票据类场景可以降到 0.3 保留更多低置信结果，再由后处理规则过滤，比直接丢掉更可控。

再说交付体验。我习惯在 exe 同级放一个settings.json，把det_limit_side_len、drop_score、pdf_dpi这些参数暴露出来，客户现场遇到识别不准可以自己微调，不用回来找我重新打包。读取逻辑放在启动时，用resource_path找不到就回落到内置默认值，这样既灵活又不会因为配置文件丢失而崩。

验证方法上，我每次打包完会跑一个固定的回归集：五张不同场景的图（清晰打印件、倾斜拍照、低对比扫描、含表格票据、纯英文），加一个三页 PDF，逐项核对识别文本和置信度。这个回归集不追求覆盖所有情况，但能快速发现「模型没打进去」「字典丢了」「PDF 转换挂了」这类致命问题。下面是我常用的核对表：

最后说个血泪教训。早期我交付时只在自己机器上测，结果客户那边是 32 位系统，exe 直接跑不起来——PyInstaller 打出来的位数跟打包环境一致，必须用目标架构的 Python 环境打包。从那以后我每次交付前都强制确认目标机器的系统位数和是否有 VC++ 运行库，把这两项写进交付清单，再没在这上面翻过车。希望这些经验能帮你少走点弯路，把 PaddleOCR 顺顺当当塞进一个离线 exe 里。

本文还有配套的精品资源，点击获取