简介：以百度开源PaddleOCR为内核搭建的本地离线识别工程包，把文字检测与识别能力封装成可直接运行的桌面环境，面向需要在 Python 与 VC++ 项目中集成 OCR 的开发者，以及重视数据隐私、网络条件不稳定的使用场景。包内共35个文件、约67.15MB，以 dll 动态库、exe 可执行程序、params 与 model 模型文件为主体，辅以 png 测试图、txt 配置说明和 VC++ 工程源码；其中动态库覆盖数学计算、图像处理与多核并行等运行依赖，命令行工具与测试控制台可直接跑通识别流程。已有22891人学习下载，可见其在离线 OCR 实践中的参考价值。读者可在断网环境下完成文字检测与识别，并借助 C++ 调用代码把能力嵌入自有程序；工程含 sln、vcxproj 等完整项目结构，便于编译调试，配合识别可视化输出理解处理流程，适用于从图片取字到文档处理系统的二次开发。

1. 断网机器上跑 PaddleOCR：本地离线识别装不好，多半栽在两个运行库

在内网、车间、机房这类不联网的机器上想把 PaddleOCR 的本地离线识别跑起来，最常见的结局是：pip 一顿装看起来全绿，脚本一执行就弹出DLL load failed，或者更难受的——不报错，但识别结果全是空列表。Python 版本对上了、PaddlePaddle 也装上了，偏偏 VC++ 运行库少一个、模型目录多写了一级、protobuf 版本没锁，这三个点任何一个翻车，识别率都能从 95% 掉到 0。

这篇按我实际装机的顺序来：先把版本和运行库固定下来，再建虚拟环境装包，然后手工把离线模型放到本地，最后一起看五条翻车记录和一套能复现的验证手法。适合第一次在 Windows CPU 机器上部署离线 OCR 的人，也适合换机器迁移、想少返工一遍的人。下面所有命令都能直接抄，路径按你自己的盘符改。

2. 装前把环境固定下来：Python 3.10、VC++ 运行库与 PaddlePaddle 2.6 的版本对照

装 OCR 这件事，八成的返工发生在敲第一条 pip 命令之前。PaddleOCR 不是那种pip install完就能用的纯 Python 包，它底下挂着一个 C++ 写的推理引擎，上面挂着一堆图像处理依赖，中间还夹着模型文件。这三层任何一层的版本对不上，报出来的错误都指向别处，很容易查偏。

2.1 Python 选 3.8 到 3.11，别追最新

PaddlePaddle 发布的 wheel 是按 CPython 版本和平台逐个编译的，不是纯 Python 包。3.13 这类刚出的版本放出来那会儿基本没有对应的 wheel，pip 会尝试从源码编译，Windows 上编译 Paddle 需要的工具链能把人劝退一整天。即便有 wheel，paddleocr依赖的shapely、pyclipper、lmdb这些带 C 扩展的包也可能缺轮子。

我一般把解释器锁在 3.10，理由很实际：3.8 太老，有些新依赖不给了；3.11 能用但个别包还在补轮子；3.10 是这一批 OCR 项目里兼容性最好的一档。装之前先确认位数，必须 64 位：

# 打印解释器版本和位数，必须是 64bit python -c "import sys, struct; print(sys.version); print(struct.calcsize('P') * 8, 'bit')"

输出里如果看到32bit，后面 paddle 的安装会直接失败或者装上跑不动。32 位解释器寻址受限，Paddle 的推理库根本没有对应构建。这种情况不要试图修，直接卸了装 64 位 Python。

另外提醒一句：机器上如果已经装了 Anaconda 或者别的 Python，python命令到底指向谁经常是玄学。用where python看清楚路径再动手，别在错误的解释器里装了一堆包，然后发现脚本用的是另一个。

2.2 VC++ 运行库：Windows 上最容易漏的一步

Paddle 的 wheel 里打包了 MKL、iomp 这些数学库的 DLL，它们依赖系统的 C 运行时，也就是vcruntime140.dll、msvcp140.dll、vcomp140.dll这一组。干净的 Windows Server 或者刚重装的系统上，这些文件往往不全，于是import paddle就炸在加载动态库那一步。

解决办法是安装 VC++ Redistributable 2015-2022 的 x64 版本。注意两个细节：一是必须装 x64，装成 x86 那版对 64 位解释器没用；二是名字里带 2015-2022 的那个包才是合集，单独装 2015 或 2017 有时会漏文件。

装完不用猜，直接查注册表确认：

# 查 x64 版 VC++ 运行库是否注册，有 Version 值说明装了 reg query "HKLM\SOFTWARE\Microsoft\VisualStudio\14.0\VC\Runtimes\x64" /v Version

返回Installed REG_DWORD 0x1和一行版本号，说明这一层没问题。如果提示找不到项，那就是没装或者只装了 x86 版本，回去补。这一步看起来土，但比装完再看报错省时间——DLL load failed这个报错完全不会告诉你是缺运行库还是缺 MKL。

2.3 版本对照：PaddlePaddle 与 PaddleOCR 怎么配

PaddlePaddle 是推理引擎，PaddleOCR 是上层封装，两者的版本不能随便搭。我常用的一组是 PaddlePaddle 2.6.x 配 PaddleOCR 2.7.x，这一组的 API 稳定、社区里的报错帖也最多，遇到问题好查。写在这里的版本号以你能在 pip 索引里对上的为准，小版本号差一点通常没事，跨大版本就要小心了。

还有个容易被忽略的点：PaddleOCR 的版本决定了它默认找哪个模型。2.7 默认走 PP-OCRv4，如果你手工下载的是 v3 的模型目录，参数名能对上但效果会掉。所以模型版本和 PaddleOCR 版本最好一起定，别一个装新版一个拿旧模型。

3. 一步步装 PaddleOCR：虚拟环境、依赖与离线模型落位

环境定好之后，安装本身其实很快，慢的是两件事：一是依赖互相打架，二是离线机器上模型下载不下来。这一章把这两件事拆开做。

3.1 建虚拟环境，把 pip 源固定

不要往系统 Python 里装 PaddleOCR，它拖来的依赖里opencv、numpy、protobuf都是有版本脾气的，装进全局环境以后，别的项目大概率被连累。建独立环境，出问题直接删目录重来，这是我愿意为它付出的唯一成本。

# 在 D 盘建一个专门跑 OCR 的环境，路径别带中文和空格 python -m venv D:\envs\ocr310 # 激活（cmd 用这条，PowerShell 换成 .\Activate.ps1） D:\envs\ocr310\Scripts\activate # 确认当前 python 已经是虚拟环境里的那个 where python # 升级 pip，并指向国内源加速 python -m pip install -U pip -i https://pypi.tuna.tsinghua.edu.cn/simple

where python这一步别省。虚拟环境激活失败的场景特别多，PowerShell 的执行策略、cmd 的路径残留都会导致你以为激活了其实没激活，后面所有包装到了全局，排查起来很折磨。看到路径里带envs\ocr310才算数。

路径带中文和空格也是个坑源。Paddle 的推理库加载 DLL 时对非 ASCII 路径的处理不够稳，虽然新版好了很多，但把环境放在D:\envs\这种干净路径下，能省掉一类莫名其妙的加载失败。

3.2 装 PaddlePaddle：CPU 版和 GPU 版的取舍

离线识别大部分场景是 CPU 跑，尤其是那些没有独立显卡的工控机。CPU 版的包小、依赖少、装起来快，识别一张普通截图在几百毫秒量级，日常够用。有显卡的机器想快可以装 GPU 版，但要注意 CUDA 和 cuDNN 的版本必须和 paddle 的构建严格对应，装错了不是慢，是直接起不来。

这里只走 CPU 版这条主线：

# 安装 CPU 版推理引擎 pip install paddlepaddle==2.6.1 -i https://pypi.tuna.tsinghua.edu.cn/simple # 装完立刻验证，能打印版本号才算这一层通了 python -c "import paddle; print(paddle.__version__); paddle.utils.run_check()"

run_check()会做一次最小推理自检，输出里如果出现PaddlePaddle is installed successfully，说明引擎、运行库、指令集这一整条链路都正常。这一步失败，后面装 PaddleOCR 没有任何意义，先在引擎层解决。

如果机器是老 CPU，可能会看到Illegal instruction之类的报错。Paddle 的部分构建用到了 AVX 指令集，太老的处理器不支持。这种情况没有太多绕法，要么换机器，要么找不带 AVX 的构建版本，实际项目里我一般直接换机器。

3.3 装 PaddleOCR：盯住 protobuf 和 PyMuPDF 这两个麻烦点

# 装上层封装 pip install "paddleocr==2.7.3" -i https://pypi.tuna.tsinghua.edu.cn/simple # protobuf 单独钉住，这是最高频的报错来源 pip install "protobuf==3.20.3" -i https://pypi.tuna.tsinghua.edu.cn/simple # 确认关键依赖的版本 pip list | findstr /I "paddle protobuf opencv numpy"

为什么要单独把 protobuf 钉住？Paddle 2.6 的推理库是用 protobuf 3.20 之前的接口生成的，环境里如果留着 protobuf 4.x，import paddle时会抛TypeError: Descriptors cannot not be created directly。这个报错的字面意思跟 OCR 毫无关系，新手很容易以为是模型坏了。

PyMuPDF是另一个钉子，PaddleOCR 用它处理 PDF，某些版本约束写得很死，在新 Python 上装不上。如果 pip 卡在它那里报编译错误，先跳过它装完主包，PDF 相关的功能用不到就不影响图片识别。

opencv的问题相对温和。PaddleOCR 依赖opencv-python和opencv-contrib-python，两个都装有时候会互相覆盖，出现cv2找不到某个函数。装完跑一次python -c "import cv2; print(cv2.__version__)"确认能导入就行。

3.4 离线模型手工下载与目录摆放

这是离线部署的核心步骤。PaddleOCR 默认行为是首次运行自动联网下载模型，断网机器上这一步会卡住，然后超时，最后报一个urlopen error。正确做法是在能联网的机器上把三个推理模型下下来，拷到目标机。

需要三个目录：检测模型（det）、识别模型（rec）、方向分类模型（cls）。下载的是推理模型包，解压后目录里应该是inference.pdmodel、inference.pdiparams、inference.pdiparams.info这三个文件，缺一个是解压错了包——注意别下成训练模型，训练模型的目录结构完全不一样。

# 目标机上的模型目录，路径自己定，别带中文 mkdir D:\ocr_models mkdir D:\ocr_models\det mkdir D:\ocr_models\rec mkdir D:\ocr_models\cls # 解压后确认三层结构，每个目录下必须有这三个文件 dir D:\ocr_models\det\ch_PP-OCRv4_det_infer

最终放好之后的结构是这样：

D:\ocr_models\ ├── det\ch_PP-OCRv4_det_infer\ │ ├── inference.pdmodel │ ├── inference.pdiparams │ └── inference.pdiparams.info ├── rec\ch_PP-OCRv4_rec_infer\ └── cls\ch_ppocr_mobile_v2.0_cls_infer\

一个很常见的错误是路径多指或者少指一层。PaddleOCR 的参数要的是「包含 inference 那三个文件的目录」，不是它的上一层，也不是那三个文件本身的路径。指错了不会报错，只会回到自动下载，然后超时。判断方法后面第 4 章会讲。

3.5 第一次跑通：一条最小命令

模型放好之后，用命令行先跑一次，这一步能排除掉一半的代码问题。

# 用本地模型跑一张图，注意 --det_model_dir 等三个参数指向具体目录 paddleocr --image_dir D:\samples\demo.png ^ --det_model_dir D:\ocr_models\det\ch_PP-OCRv4_det_infer ^ --rec_model_dir D:\ocr_models\rec\ch_PP-OCRv4_rec_infer ^ --cls_model_dir D:\ocr_models\cls\ch_ppocr_mobile_v2.0_cls_infer ^ --use_angle_cls true ^ --use_gpu false

命令跑完会在控制台直接打印识别出的文字和置信度。能看到中文和分数，说明引擎、依赖、模型三层全通了。cmd 里的^是续行符，PowerShell 里要换成反引号，或者干脆写成一行。

如果这一步打印出结果但文字是乱的，通常是模型语言对不上，中英文模型混用了；如果打印空结果，先看第 5 章第 4 条。

4. 配置离线识别：三个最容易写错的开关

命令行能跑通，不代表代码里能跑通。PaddleOCR 的构造函数参数很多，其中三个直接决定「是不是真离线」和「识别结果准不准」。参数写错不报错，只是默默走默认值，这是最坑的地方。

4.1 模型路径三个参数必须明确指向本地

from paddleocr import PaddleOCR ocr = PaddleOCR( use_angle_cls=True, lang="ch", # 三个路径都指向本地目录，只要有一个为 None 就会触发联网下载 det_model_dir=r"D:\ocr_models\det\ch_PP-OCRv4_det_infer", rec_model_dir=r"D:\ocr_models\rec\ch_PP-OCRv4_rec_infer", cls_model_dir=r"D:\ocr_models\cls\ch_ppocr_mobile_v2.0_cls_infer", use_gpu=False, show_log=False, ) result = ocr.ocr(r"D:\samples\demo.png", cls=True) # 2.x 的返回结构：result[0] 是行列表，每行 [框坐标, (文字, 置信度)] for line in result[0]: text, score = line[1] print(f"{score:.3f}\t{text}")

关键在det_model_dir、rec_model_dir、cls_model_dir这三个参数。任何一个留空，PaddleOCR 都会按lang去默认目录找，找不到就下载。断网机器上表现为卡住十几秒然后抛异常。

用r"..."原始字符串是个人习惯，Windows 路径里的反斜杠不是转义符，不加r的时候\n、\t这种会被解释成换行和制表符，路径就废了。这个坑在含\new、\temp目录名的机器上特别容易中。

show_log=False关掉的是 paddle 引擎的调试日志，识别本身不受影响，但批量处理时这些日志会把控制台刷满，也影响速度。第一次排查问题的时候建议打开，看到Detection model loaded之类的字样，能确认模型确实从本地加载了。

4.2 use_angle_cls 与 det/rec 的取舍

方向分类器（cls）负责判断文本是不是倒着的、竖着的，倒了就转 180 度再识别。文档扫描件、手机拍的票据这类场景必须开，开了才能识别倒置文字；但它是额外一次推理，每张图多几十毫秒。

我一般的判断标准是：图源固定、方向统一的（比如截图、扫描仪正面进纸）关掉，能省 15% 左右的时间；图源不可控的（用户手机拍、快递单）开着，别省这一点。

lang参数只影响默认模型选择，一旦三个路径都指死了，它的作用就很小了。但要注意lang="ch"用的是中英文混合模型，识别英文没问题；如果只认英文，专门的英文模型体积更小、速度更快。

还有两个参数值得单独提：det_limit_side_len控制检测阶段把图缩放到的长边尺寸，默认 960。小图放大会变慢，大图缩小会丢字，票据类的长图把长边设到 1280 到 1600 之间通常更稳。drop_score是置信度过滤阈值，默认 0.5，把低于这个分数的结果丢掉——它对「输出全是空」这个现象影响很大，排查时先把它调到 0.1 看看有没有东西出来。

4.3 CPU 线程、批大小与显存

CPU 机器上最容易被忽略的是线程数。Paddle 默认会自己探测，但在容器里或者 CPU 核数很多的服务器上，探测结果经常偏保守或者偏激进。

ocr = PaddleOCR( use_angle_cls=True, lang="ch", det_model_dir=r"D:\ocr_models\det\ch_PP-OCRv4_det_infer", rec_model_dir=r"D:\ocr_models\rec\ch_PP-OCRv4_rec_infer", cls_model_dir=r"D:\ocr_models\cls\ch_ppocr_mobile_v2.0_cls_infer", use_gpu=False, cpu_threads=4, # 一般设成物理核数的 1/2 到 2/3 enable_mkldnn=True, # CPU 推理加速，多数情况下能快 20%~40% rec_batch_num=6, # 识别阶段一批送几张，显存/内存紧就调小 show_log=False, )

cpu_threads不是越大越好。设成全部核数时，多个线程抢同一批缓存，实测反而比 4 线程慢。我一般在 8 核机器上设 4，16 核设 6，靠一次简单压测定下来。

enable_mkldnn是 CPU 推理的加速开关，绝大多数 x86 机器上都能开，开了之后首次推理会慢一点（要做算子融合），之后稳定变快。个别很老的 CPU 上开了反而报错，那就关掉。

rec_batch_num只在一次传多张图或者一张图有很多文本行时起作用。内存紧张的工控机上把它从默认值往下调，能避免峰值内存打满被系统杀掉进程——这个现象很隐蔽，表现为「跑着跑着进程没了」，日志里什么都没有。

5. 避坑与排查：五条翻车记录，现象、原因、解决

下面这五条是我在不同机器上真实碰到过的，按出现频率排。每条都按「现象 → 原因 → 解决」写，遇到问题可以直接对号。

5.1 现象：ImportError: DLL load failed while importing libpaddle

原因：三种可能，按概率排是缺 VC++ 运行库、解释器是 32 位、环境里混进了另一个 paddle 版本。最常见的是第一种，尤其是 Windows Server 上。

解决：先跑第 2 章那条reg query确认 x64 运行库在不在；再python -c "import struct; print(struct.calcsize('P')*8)"确认位数；最后pip list | findstr paddle看是不是装了两份。三条都排除还报错，就在虚拟环境里pip uninstall paddlepaddle后重装，别在全局环境里折腾。

5.2 现象：启动时卡住十几秒，然后报urlopen error或Connection refused

原因：模型路径没指对或者压根没传，PaddleOCR 回退到自动下载。断网机器上必然失败，能联网的机器上则是慢，容易被误判成程序卡死。

解决：把三个*_model_dir全部传上，并且用os.path.exists()打一遍日志确认目录存在。判断路径对不对的土办法是看目录里有没有inference.pdmodel，没有就是多指或少指了一层。另外，能联网的机器上第一次运行会下载模型到用户目录，之后即使不传路径也能跑，这会造成「我这边好好的」的错觉，迁移到离线机器就炸——所以路径从一开始就写死，别依赖缓存。

5.3 现象：TypeError: Descriptors cannot not be created directly

原因：protobuf 版本过高。Paddle 2.6 的推理库是按 protobuf 3.20 之前的接口生成的，环境里如果是 4.x，导入阶段就崩。

解决：pip install "protobuf==3.20.3"，装完重启解释器再试。注意有些包会在安装时把 protobuf 又升上去，所以这一步放在所有安装的最后做，做完pip list确认版本没被改回去。如果环境里已经有别的服务依赖高版本 protobuf，那就是环境冲突，老老实实给它单独建一个虚拟环境。

5.4 现象：程序不报错，但识别结果是空列表或None

原因：按概率排是置信度阈值太高把结果全过滤了、图片本身没读到（cv2.imread返回None）、检测阶段把图缩得太小导致文字糊掉。中文路径也是高频原因，OpenCV 在 Windows 上对非 ASCII 路径支持不好，读图直接返回None，后续一切静默失败。

解决：先把drop_score调到 0.1 看有没有结果浮出来；再用python -c "import cv2; print(cv2.imread(r'D:\samples\demo.png').shape)"确认图片读得到；路径带中文的话，改用numpy.fromfile加cv2.imdecode的方式读图绕过去。这三步走完基本能定位。

5.5 现象：单张图正常，批量跑到一半进程直接消失

原因：内存峰值打满被系统杀掉，或者rec_batch_num设得太大。批量处理时图片对象没及时释放，内存会一路涨上去，日志里什么都看不到，因为进程是被系统终止的。

解决：把rec_batch_num降到 4 以下，批处理循环里手动del掉不再用的大图对象，别把所有图先读进一个列表再统一处理，改成一张一张流式处理。工控机内存小的话，这一步比调任何参数都有效。

6. 装完怎么验证：三条自检和一次准确率对照

装完能跑一张图不算数，得能证明它在断网状态下、在真实样本上、成批跑的时候都稳。我习惯做完三步自检再交付，缺一步都不敢说这环境装好了。

第一步是环境自检，一条命令把所有关键版本打出来存档，以后换机器或者出问题时有对照：

# 一次性打印环境快照，建议存成文本随项目一起归档 python -c "import sys, paddle, cv2, numpy, google.protobuf as pb; print('py', sys.version.split()[0]); print('paddle', paddle.__version__); print('cv2', cv2.__version__); print('numpy', numpy.__version__); print('protobuf', pb.__version__)"

第二步是离线自检，把网卡禁用或者拔掉网线再跑一次识别。这一步是必须的——很多「离线部署」其实一直在偷偷走缓存或者回源下载，只有真断网才能暴露模型路径没指死的问题。断网后如果启动明显变慢，说明哪里还在尝试联网。

第三步是准确率对照，拿 20 到 50 张真实业务样张跑一遍，把置信度分布和人工核对结果记下来：

跑完对照表，如果置信度均值明显偏低，先别怀疑模型，去看det_limit_side_len是不是把长图缩得太狠，以及样张本身的分辨率。我见过好几次识别率上不去的根因，是上游把 3000 像素的扫描件压成了 800 像素的缩略图。

从那以后我每次装完 PaddleOCR，都强制走一遍「断网 + 批量 + 置信度分布」这套流程，哪怕只是给同事的测试机装一份。血泪经验是：能跑一张图的环境和能上生产的环境，中间隔着的就是这三步。希望帮到你。

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