PaddleOCR PP-Structure表格识别工具打包exe离线运行实现指南

简介：Windows系统下PaddleOCR表格识别工具PP-Structure已打包为exe离线运行版，专为没有安装Python环境的Windows用户设计，可在完全离线条件下直接完成表格OCR识别任务，适合企业内网、生产现场等受限环境使用。工具包内含约2000个文件，主要由Python源码、pyc编译文件、dll与pyd动态链接库、ttf字体文件及配置文件组成，完整打包了运行PP-Structure所需的全部依赖与字体资源，压缩包大小214.12MB。目前已吸引567人学习下载。通过该工具包，用户无需搭建Python开发环境，即可获得可执行的exe主程序，并配套全部运行库与静态资源；既可双击即用，也可将整个目录拷贝至其他Windows离线机器部署，极大降低了表格识别功能的落地门槛。 前阵子客户提了个挺现实的需求：他们有个业务系统，里面全是带边框的表格图片，需要自动识别成Excel表格，但客户现场是内网环境，机器上既没有Python，也不允许联网。项目本身我用的是PaddleOCR里的PP-Structure表格识别能力，但交付的时候总不能给客户发源码让人家自己配环境吧，于是就有了这个"Windows系统下PaddleOCR表格识别工具PP-Structure打包exe离线运行版"项目。

这篇文章就把整个打包过程和踩过的坑完整记录下来。内容包括为什么选PP-Structure、如何准备离线模型、核心识别代码怎么写、PyInstaller打包的关键配置，以及目标机器上无Python环境时的验证流程。适合正在用PaddleOCR做表格识别、需要交付exe给第三方、或者对Python打包paddle系列项目有困惑的同学参考。

1. 整体方案设计：为什么是PP-Structure + 离线exe

1.1 核心需求拆解

先把这个项目的需求拆明白。我当时拿到需求后，脑子里有三个关键约束，后面所有技术选型都围绕这三条展开：

• 输入是包含表格的图片（包括带框线的表格、发票、截图、扫描件），输出是结构化数据，最好是能直接拿来用的Excel文件。
• 目标机器没有Python环境，没有网络，也没有管理员权限保证（所以不能指望现场装环境）。
• 业务人员不关心模型、依赖这些东西，双击exe就能用，最多需要一个简单的界面。

基于这三个约束，"PaddleOCR + PP-Structure"几乎是当前开源方案里最合适的选择。PaddleOCR本身自带了完整的PP-Structure表格识别能力，能把表格图片直接解析成HTML结构，再配合pandas就能轻松转成Excel。而"打包成exe离线运行"则是满足分发约束的必然选择。

1.2 为什么选PP-Structure而不是纯OCR + 自研解析

我在方案设计阶段其实纠结过两条路：一条是只用PaddleOCR的文字检测识别，拿到所有文本框的坐标，然后自己写规则去推断行列关系；另一条就是直接用PP-Structure的表格识别能力。

自己写规则解析，听起来可控，实际做起来非常痛苦。表格的边框有没有、合并单元格怎么处理、跨行跨列怎么判断，这些规则的复杂度远超想象，而且换个表格样式就得改规则，几乎没法稳定交付。

PP-Structure里的表格识别模型（TableRec）是专门针对表格结构解析训练的，它不只识别文字，还识别单元格位置、合并关系、行列结构，最终直接输出HTML格式的表格结构。这个HTML里天然包含了行、列、合并单元格的信息，再用pandas的read_html一解析，转Excel就非常简单了。

这也是我在最终方案里选择PP-Structure的核心理由：不重复造轮子，把最复杂的表格结构解析交给专业模型，自己只处理结果转换和交付形态。

1.3 整体架构与运行流程

整个方案的运行流程可以描述为：用户选中表格图片或批量拖入文件夹，程序调用PP-Structure的表格方向引擎，完成后把每张图片的表格结果保存为Excel文件，并弹出完成提示。

离线exe的架构也不复杂：

用户操作界面（可选） -> 图片路径列表 -> PP-Structure表格识别引擎（离线模型） -> 结果解析 -> Excel文件输出

关键点在于"离线模型"。PaddleOCR首次运行时默认会从服务器下载模型，所以打包前必须把模型文件提前下载好，然后通过配置让程序在运行时直接加载本地模型，不再发起任何网络请求。这一步是"离线运行"的核心，后面我在第3部分详细演示。

2. 环境准备与依赖管理：这步踩的坑最多

2.1 Python和Paddle版本怎么搭配

环境准备是整个项目里最容易踩坑的地方，没有之一。PaddlePaddle对Python版本有严格限制，装错了轻则报错，重则装完直接无法import。

我当时用的是Python 3.9，搭配的是paddlepaddle 2.4.2 CPU版和paddleocr 2.6.x。这个组合实测下来比较稳。不建议用最新的Python 3.11或3.12，因为Paddle的预编译轮子对新版本Python的支持经常滞后，很容易出现"找不到合适的paddlepaddle版本"这种尴尬。

还要强调一个原则：只装CPU版。虽然标题里的热词有人提到GPU和cudnn 8.5，但如果你最终要打包成exe分发给别人，GPU版会把CUDA、cudnn、显卡驱动这些依赖全部牵扯进来，目标机器没有N卡或者驱动版本不对，程序直接跑不起来。而且PyInstaller对GPU版的DLL收集往往不完整，打包体积会飙升到好几个GB。离线交付场景，CPU版是最稳的选择，识别速度慢一点，但胜在兼容性极好。

2.2 安装依赖的完整清单

我用pip安装，完整命令如下：

pip install paddlepaddle==2.4.2 -i https://mirror.baidu.com/pypi/simple pip install paddleocr==2.6.1 pip install opencv-python-headless pip install pandas pip install openpyxl pip install pyinstaller

有几个细节要单独说明。opencv-python-headless和opencv-python不能同时存在，否则会有libGL相关的报错，打包阶段特别容易出现；openpyxl是pandas转Excel的引擎，必须装；shapely和pyclipper是PaddleOCR的强依赖，安装paddleocr时会自动带上，但后面打包时要注意它们需要额外的hidden-import处理，这个我放到第4部分讲。

这里还要特意提醒一句：不要用最新版的paddleocr。我试过直接装最新版，它内部对模型目录结构做了改动，导致老教程里的代码路径对不上。锁定2.6.x这个版本，教程多、资料全、踩坑经验也好找。

2.3 提前下载离线模型

离线模型这个操作非常关键。最简单的方法是在联网环境下先运行一次程序，让PaddleOCR自动下载并缓存模型。模型缓存目录通常在用户目录下：

C:\Users\你的用户名\.paddleocr\

如果你用的版本较新，模型的默认目录可能在：

C:\Users\你的用户名\.paddlex\

以paddleocr 2.6.x为例，模型文件会放在.paddleocr\whl\det\ch_PP-OCRv3_det_infer、.paddleocr\whl\rec\ch_PP-OCRv3_rec_infer、.paddleocr\whl\table\en_ppstructure_mobile_v2.0_SLANet_infer等目录下。这些目录就是打包时必须带上的关键内容。

注意：打包前一定要确认PP-Structure的表格模型（SLANet）已经下载成功。只跑过文字识别检测的话，.paddleocr里可能没有table模型目录，运行时会报找不到模型。

3. 表格识别核心代码实现与离线路径处理

3.1 核心识别代码

下面这段是PP-Structure表格识别的核心代码，也是整个exe的核心逻辑。我用的是PPStructure类，它在paddleocr 2.6.x里直接import就能用。

import os import sys import traceback from paddleocr import PPStructure def create_engine(): # 关键：指定模型存放目录，确保离线时能找到模型 model_dir = os.path.join(get_base_dir(), "models") try: engine = PPStructure( show_log=False, lang="ch", use_gpu=False, det_model_dir=os.path.join(model_dir, "det"), rec_model_dir=os.path.join(model_dir, "rec"), table_model_dir=os.path.join(model_dir, "table"), ) except TypeError: # 如果当前版本不支持直接传table_model_dir，退回到默认目录加载 engine = PPStructure(show_log=False, lang="ch", use_gpu=False) return engine def get_base_dir(): """兼容开发环境和PyInstaller打包后的路径获取""" if getattr(sys, "frozen", False): # 打包后的exe，资源文件在_MEIPASS目录 return sys._MEIPASS return os.path.dirname(os.path.abspath(__file__)) if __name__ == "__main__": engine = create_engine() result = engine("sample_table.jpg") for item in result: if item["type"] == "table": html = item["res"]["html"] print(html)

这里有个重要细节：det_model_dir、rec_model_dir、table_model_dir这三个参数，在不同版本里的支持情况不一样。我用的2.6.1版本是支持直接传table_model_dir的。如果某次运行报参数不认识的TypeError，就用代码里的try-except机制降级回去，让它从默认缓存目录加载，但前提是你已经提前把模型文件夹放到了正确位置。

3.2 表格结果解析与Excel导出

PP-Structure返回的结果是一个列表，每个元素都是dict。type为"table"的项，其res里有一个"html"字段，内容就是表格的HTML结构。接下来把HTML转成Excel：

import pandas as pd from io import StringIO def html_to_excel(html_str, output_path): tables = pd.read_html(StringIO(html_str)) if tables: df = tables[0] df.to_excel(output_path, index=False, engine="openpyxl")

这一段代码看似简单，但有几个细节要注意。pandas的read_html解析出来的可能有多张表格，取第0张是常见做法，但如果图片里有多个表格，你可能需要根据实际业务调整索引逻辑。另外，如果表格里包含图片里的非文本内容，比如印章、条码，PP-Structure会返回空单元格，这属于正常现象，识别结果以文字内容为主。

还有一个比较关键的技巧：如果要保留表格合并单元格的样式，pandas的to_excel做不到——它只保留行列布局，不保留合并单元格视觉样式。如果业务方要求完美还原表格样式，就需要用openpyxl手动遍历HTML的rowspan和colspan属性来重建合并单元格，工作量会大不少。对于大部分业务需求来说，数据不缺、行列不错位，就已经够用了。

3.3 离线模型目录的放置逻辑

离线运行的关键在于必须让程序知道"模型从哪里加载"。我在打包前把所有模型文件统一拷贝到项目根目录下的models文件夹中，结构如下：

项目根目录/ ├── app.py ├── models/ │ ├── det/ │ │ └── inference.pdmodel ...（检测模型） │ ├── rec/ │ │ └── inference.pdmodel ...（识别模型） │ └── table/ │ └── inference.pdmodel ...（表格模型）

然后通过create_engine函数里的det_model_dir参数直接指定路径。这样打包出来的exe完全不需要访问网络，也不需要依赖用户目录下的缓存。

刚才说的get_base_dir函数是专门为了兼容PyInstaller打包而写的。用PyInstaller打包后，如果使用--add-data把模型目录打进去，模型文件会被释放到临时目录，路径就是sys._MEIPASS。开发环境运行的时候，路径就是项目根目录。这个函数就是负责在两种场景下都找到正确的模型目录。

4. PyInstaller打包exe实操：从配置到避坑

4.1 打包前的工程组织

打包前把项目整理干净。我最终的项目结构是这样的：

table_tool/ ├── app.py # 主程序 ├── models/ # 离线模型目录（约200多MB） ├── output/ # 识别结果输出目录 ├── test_images/ # 测试图片 └── table_tool.spec # PyInstaller配置

主程序app.py里除了识别逻辑，还加了一个非常简单的命令行交互界面，让用户通过cmd启动后拖入图片路径。你说要做成图形界面也可以，PyQt或Tkinter都行，但我当时考虑到项目量级，先用命令行交互快速交付了。如果想做GUI，主程序逻辑不变，只把输入输出部分换成界面控件就行。

4.2 打包命令与spec文件关键配置

打包我强烈建议使用spec文件，而不是直接写一堆命令行参数。原因很简单：Paddle相关依赖多、隐藏导入多、需要添加的数据也多，每次都写命令太容易漏。spec文件把配置固化下来，也方便后续复现。

我的table_tool.spec文件关键内容如下：

# -*- mode: python ; coding: utf-8 -*- a = Analysis( ["app.py"], pathex=[], binaries=[], datas=[ ("models", "models"), ], hiddenimports=[ "shapely", "shapely.geometry", "pyclipper", "paddleocr", "paddlex", "skimage", "imghdr", "pandas", "openpyxl", ], hookspath=[], hooksconfig={}, runtime_hooks=[], excludes=[], noarchive=False, ) pyz = PYZ(a.pure) exe = EXE( pyz, a.scripts, a.binaries, a.datas, [], name="表格识别工具", debug=False, bootloader_ignore_signals=False, strip=False, upx=False, console=True, )

几个关键配置我逐一说明。

datas=("models", "models")这一行是把整个模型目录打包进exe，注意源路径和目标路径在Windows下用逗号分隔，目标路径指的是程序运行时的相对路径。在app.py里，get_base_dir返回sys._MEIPASS，然后os.path.join(base_dir, "models")就能找到这些文件。

hiddenimports是Paddle系列打包的命门。shapely、pyclipper这些库在被PyInstaller静态分析时往往检测不到，不手动加进去，运行时会报ModuleNotFoundError。skimage是paddlex底层要用的，imghdr也是paddleocr内部会import的模块，这些隐藏依赖都要显式写进去。

upx=False是个大坑的规避。UPX是个压缩工具，PyInstaller默认会在环境里有UPX时自动使用，但Paddle的DLL被UPX压缩后经常加载失败，表现为运行时崩溃或者直接说DLL损坏。所以spec里必须显式设置为False，同时确保环境变量里没有UPX配置。

4.3 打包执行与体积优化

执行打包命令：

pyinstaller table_tool.spec --clean --noconfirm

打包过程在普通配置的电脑上大概需要5到10分钟，期间CPU会跑满，这是正常的。打包完成后，dist目录下会生成一个"表格识别工具.exe"文件，同时还有相关的DLL目录（PyInstaller默认不是单文件模式，会把Python运行时和依赖DLL都放在exe旁边）。

这里要解释一下为什么我没有用-F单文件模式。对于Paddle这种几百MB的依赖库，单文件模式运行时会先把所有内容解压到临时目录再执行，启动速度极慢，有时甚至要几十秒才出界面。目录模式下依赖文件就在exe旁边，启动快得多，缺点是要分发整个目录。实际交付时，压缩成一个zip发给客户就行，客户解压后双击exe就能用。

整个dist目录的体量大概在700MB到1GB之间。PaddlePaddle CPU版和模型文件是大头。如果想压体积，可以通过excludes排除不需要的paddle子模块，但收益不大而且容易引发未知问题，我建议就保持全量，接受体积。这年头U盘都32GB起步了，1GB的交付物不算夸张。

5. 目标机器离线运行验证与问题排查

5.1 无Python环境机器上的验证流程

打包成功只是第一步，真正考验人的是拿到一台干净Windows机器上跑通。我当时验证流程是这样的：

1. 在一台没有安装Python、没有安装任何Paddle相关组件的Windows 10虚拟机里测试。
2. 把dist目录整个拷贝过去，先不急着双击，用cmd打开命令行，运行exe。
3. 用控制台模式的好处是能看到所有报错输出。如果直接双击GUI程序，窗口一闪而过，根本不知道问题出在哪。

第一次运行如果弹出Windows安全提示"已保护你的电脑"，这是SmartScreen在拦截未签名的exe，选"更多信息"然后"仍要运行"即可。企业级交付时，如果你想要消除这个提示，需要花钱买代码签名证书对exe签名，大部分内部工具场景可以不管。

验证时输入一张测试表格图片路径，程序正常输出识别结果并生成Excel，说明打包成功。这个流程必须在多台干净机器上跑一遍，因为不同机器缺失的DLL可能不一样。

5.2 高频报错与解决方案速查

我在这套方案上可没少折腾，把实战中遇到的问题整理成了速查表，方便你对照排查。

还有一个经验分享：如果用的是Windows Server类系统，可能会因为系统缺少字体导致Paddle的绘图模块报错，到时候把"中文字体"装上就行，或者干脆在代码里禁用可视化输出，反正我们要的是结构化数据，不需要画框的图片。

5.3 关于"GPU模式"的一个补充说明

热词里有人搜"paddleocr如何用GPU模式 cudnn 8.5"，这里我补充一个个人观点。如果你开发机上有NVIDIA显卡，用来做模型调试和性能测试，GPU模式完全合理。但在"打包exe离线分发"这件事上，GPU模式是灾难性的。你需要带着CUDA runtime、cudnn 8.x、TensorRT等一堆DLL，体积轻松超过3GB，而且目标机器必须恰好有兼容的NVIDIA驱动。这也是我最终交付CPU版exe的原因。如果你确有必要用GPU模式，建议先跑通CPU版分发，再单独研究GPU版，别把两条线混在一起。

使用GPU模式时，如果确实需要，可以在代码里设置use_gpu=True，并在打包时添加相应的CUDA和cuDNN DLL文件，但这些DLL必须与目标机器的显卡驱动版本兼容，否则运行时会报CUDA初始化失败的错误。这种兼容性工作量相当大，除非你有很明确的理由，否则第一条路——CPU版离线exe——永远是性价比最高的选择。

写在最后的实操体会

我自己在这套方案上跑了不下十轮，最大的体会是：PaddleOCR这个框架识别能力本身很强，真正的门槛不在算法，而在工程交付。离线模型的固化、PyInstaller的依赖收集、目标机器环境的兼容性验证，这三件事占了整个项目八成的时间。

最后分享一个脚本技巧。在开发阶段，我习惯在app.py里加一个--check-deps参数，程序启动时会打印所有关键依赖的版本和模型文件是否存在。这一手在排查客户现场问题时特别有用——你远程指导客户双击exe并回传一段打印信息，就能快速定位是缺DLL还是模型没加载对，不用来回试错。

如果后续你有更多需求，比如把拖拽批量识别、日志持久化、界面进度条这些都加上，那就可以在这个基础上扩展。架构已经保证了，剩下的就是往里面加功能了。

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