在 Ascend 310P 环境中使用 PyInstaller 打包 PaddleOCR

基于 PaddlePaddle 在昇腾 310P 上的部署实践，使用 PyInstaller 打包 PaddleOCR。

适用范围与前置条件

目标：为 Ascend 310P NPU 运行环境打包一个基于 PaddleOCR 的命令行程序。
系统/架构：Linux x86_64（示例路径基于 Conda + Python 3.11）。
关键版本：
- Python：3.11（如不同请调整路径）
- PyInstaller：6.x 或更高
- PaddlePaddle（Ascend 版本） 与 310P 运行时已正确安装
环境自检：

1
2
3


python -V
pyinstaller --version
python -c "import paddle, cv2; print(paddle.__version__, cv2.__version__)"

Spec 文件

通过以下 test_ocr.spec 文件进行打包：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56


# -*- mode: python ; coding: utf-8 -*-
from PyInstaller.utils.hooks import copy_metadata, collect_data_files

datas = [('/opt/PaddleX/paddlex', 'paddlex')] # PaddleX 项目源代码 Python 包所在目录
datas += [('/root/miniconda3/envs/asr_ocr_npu/lib/python3.11/site-packages/paddle', 'paddle')] # Paddle PyPI 包所在目录
datas += collect_data_files('lmdb')
datas += copy_metadata('ftfy')
datas += copy_metadata('lxml')
datas += copy_metadata('opencv-contrib-python')
datas += copy_metadata('pyclipper')
datas += copy_metadata('pypdfium2')
datas += copy_metadata('ultra-infer-npu-python')
datas += copy_metadata('scikit-learn')


a = Analysis(
    ['./test_ocr.py'], # 需要打包的入口文件
    pathex=[],
    binaries=[('/root/miniconda3/envs/asr_ocr_npu/lib/python3.11/site-packages/paddle/libs', '.')],  # Paddle 动态库所在目录
    datas=datas,
    hiddenimports=['cv2', 'pypdfium2', 'ultra_infer', 'paddle.cinn_config'],
    hookspath=[],
    hooksconfig={},
    runtime_hooks=[],
    excludes=[],
    noarchive=False,
    optimize=0,
)
pyz = PYZ(a.pure)

exe = EXE(
    pyz,
    a.scripts,
    [],
    exclude_binaries=True,
    name='test_ocr',
    debug=False,
    bootloader_ignore_signals=False,
    strip=False,
    upx=True,
    console=True,
    disable_windowed_traceback=False,
    argv_emulation=False,
    target_arch=None,
    codesign_identity=None,
    entitlements_file=None,
)
coll = COLLECT(
    exe,
    a.binaries,
    a.datas,
    strip=False,
    upx=True,
    upx_exclude=[],
    name='test_ocr',
)

构建

1

pyinstaller ./test_ocr.spec

各段含义说明

datas：打包运行期需要的包与数据文件（如 ftfy、lxml、opencv-contrib-python 的元数据/资源）。
binaries：打入 paddle/libs 下的共享库，以便目标机无需预装 Paddle 也可运行。
hiddenimports：显式声明 PyInstaller 可能漏掉的依赖（如 cv2、paddle.cinn_config、ultra_infer）。
UPX：用于压缩体积；若出现启动异常或被误报，尝试设置 upx=False。
单文件 vs 单目录：此方案构建为单目录（COLLECT），对大型框架更稳妥。