PaddleOCR 3.x 多功能 OCR 工作站部署与使用笔记

适用项目目录：C:PP-OCRv6

当前主程序：app_v6_upgraded.py

双击启动脚本：run_ocr_app.bat

访问地址：http://127.0.0.1:7860

1. 项目用途

这是基于 PaddleOCR 3.x + Gradio 的本地 OCR 工具，主要支持：

• 单张图片 OCR；
• 批量图片 OCR；
• PDF OCR；
• 输出 PDF / TXT / Markdown；
• PDF 原图层 + OCR 文字层分层输出；
• OCR 可见文字层字号倍率调整；
• 单张图片上传后可在页面内编辑。

2. 推荐目录结构

建议把项目固定放在：

<code class="language-text">C:PP-OCRv6</code>

主要文件说明：

<code class="language-text">C:PP-OCRv6
├─ app_v6_upgraded.py      主程序
├─ run_ocr_app.bat         双击启动脚本
├─ requirements.txt        Python 依赖
├─ .venv                 推荐的虚拟环境目录
└─ OCR_*.pdf / OCR_*.txt / OCR_*.md
                           OCR 输出文件</code>

3. 环境要求

建议使用：

• Windows 10 / Windows 11；
• Python 3.10 或 3.11；
• PaddleOCR 3.x；
• Gradio 5.x 或 6.x；
• PyMuPDF；
• ReportLab；
• OpenCV；
• 微软雅黑字体 C:WindowsFontsmsyh.ttc，用于中文 PDF 文字层。

不建议使用太新的未适配依赖版本，尤其 OpenCV 要控制在 5 以下。

4. 第一次部署步骤

打开 PowerShell，进入项目目录：

<code class="language-powershell">cd /d C:PP-OCRv6</code>

如果还没有虚拟环境，创建一个：

<code class="language-powershell">python -m venv .venv</code>

启用虚拟环境：

<code class="language-powershell">..venvScriptsactivate</code>

升级 pip：

<code class="language-powershell">python -m pip install --upgrade pip</code>

安装依赖：

<code class="language-powershell">python -m pip install -r requirements.txt</code>

当前 requirements.txt 推荐内容：

<code class="language-text">paddleocr>=3.0,<4
gradio>=5,<7
opencv-python>=4.8,<5
numpy>=1.24
PyMuPDF>=1.24
reportlab>=4.0</code>

5. 启动方法

方法一：双击启动

直接双击：

<code class="language-text">C:PP-OCRv6run_ocr_app.bat</code>

脚本会自动做这些事：

1. 切换到项目目录； 2. 优先使用 .venvScriptspython.exe； 3. 检查依赖是否齐全； 4. 如果缺依赖，会自动执行一次 pip install -r requirements.txt； 5. 启动 app_v6_upgraded.py； 6. 自动打开浏览器访问：

<code class="language-text">http://127.0.0.1:7860</code>

方法二：手动启动

<code class="language-powershell">cd /d C:PP-OCRv6
..venvScriptsactivate
python app_v6_upgraded.py</code>

浏览器打开：

<code class="language-text">http://127.0.0.1:7860</code>

6. 关闭方法

如果是双击 run_ocr_app.bat 启动的：

1. 回到黑色命令行窗口； 2. 按 Ctrl + C； 3. 如果提示是否终止批处理，输入：

<code class="language-text">Y</code>

然后回车。

如果没有反应，可以直接关闭黑色命令行窗口。

如果端口被占用，可以在 PowerShell 中查找：

<code class="language-powershell">netstat -ano | findstr :7860</code>

然后结束对应进程：

<code class="language-powershell">taskkill /PID 进程号 /F</code>

7. PDF 分层输出说明

界面里的 PDF 图层模式建议选择：

<code class="language-text">原图层 + OCR文字层 (OCR层默认关闭，可开关 PDF)</code>

这个模式会生成真正的 PDF 图层：

• 原图背景层
• OCR文字层

默认状态：

• 原图背景层：开启；
• OCR文字层：关闭。

打开 PDF 后，如果阅读器支持图层，可以在左侧图层面板里单独打开或关闭 OCR 文字层。

注意：不是所有 PDF 阅读器都支持图层面板。推荐使用：

• Adobe Acrobat Reader；
• PDF-XChange Editor；
• 福昕高级版等支持图层的阅读器。

浏览器自带 PDF 预览通常看不到图层面板，这是阅读器限制，不是程序没有分层。

8. OCR 文字层字号设置

界面里有 OCR 文字层字号倍率。

推荐：

• 默认：2.0；
• 如果文字太小：可以调到 2.2 或 2.5；
• 如果文字开始重叠：降到 1.5 到 1.8；
• 古籍竖排、密集小字：建议不要盲目调太大。

当前程序已经修复过“字号放大 2 倍后文字错位”的问题：

• 竖排文字按原字符槽中心放大；
• 横排文字按识别框中心放大；
• 识别框不是明显竖排时，不会强行按竖排拆字；
• 文本框放不下时，会按字符中心做 fallback，避免整句挤到一起。

9. 常见坑和避坑方法

坑 1：第一次运行时一直在下载

第一次启动可能会下载依赖或 PaddleOCR 模型，这是正常的。

如果看到类似：

<code class="language-text">Downloading opencv_python...
Downloading ...</code>

说明正在补依赖。网速慢时会等很久。

避坑：

• 尽量保持网络稳定；
• 不要频繁关闭窗口；
• 如果依赖已经装好，后续启动脚本会跳过安装，不会每次下载。

坑 2：OpenCV 版本太新导致不兼容

避免安装 OpenCV 5.x。

requirements.txt 已经限制：

<code class="language-text">opencv-python>=4.8,<5</code>

如果出现 OpenCV 相关错误，可以重新执行：

<code class="language-powershell">..venvScriptspython.exe -m pip install "opencv-python>=4.8,<5" --force-reinstall</code>

坑 3：PDF 看不到图层

很多浏览器 PDF 预览器不支持图层面板。

避坑：

• 用 Adobe Acrobat Reader 或 PDF-XChange Editor 打开；
• 不要只用 Chrome / Edge 的内置 PDF 预览判断是否有图层。

坑 4：PDF 只有文字，没有原图

这通常是 PDF 生成逻辑退回到了纯文字模式，或选择了错误的 PDF 图层模式。

避坑：

• PDF 图层模式选择：

<code class="language-text">原图层 + OCR文字层 (OCR层默认关闭，可开关 PDF)</code>

• 不要选择纯文字 PDF。

坑 5：原图颜色变了

OpenCV 使用 BGR，PIL / PDF 渲染常用 RGB，混用时会导致红蓝通道反掉。

当前程序已经处理：

• PDF 页面渲染统一转 RGB；
• 图像写入 PDF 前保持正确颜色；
• 原图层使用 PNG 流写入，避免 JPEG 压缩和颜色偏移。

如果再次出现变色，优先检查最近有没有改动图像转换代码。

坑 6：OCR 文字缩成一团

常见原因：

• 识别框很密；
• 字号倍率太大；
• 横排/竖排方向选择不对；
• 古籍页面本身有弯曲、阴影、扫描变形。

避坑：

• 竖排古籍选择“竖排文字”；
• 横排文档选择“横排文字”；
• 字号倍率先用 2.0，不合适再微调；
• 对扫描质量差的图片，先裁剪、转正、去边框再 OCR。

坑 7：古籍 OCR 结果有点乱

古籍、繁体、竖排、异体字、雕版书会明显增加识别难度。

避坑：

• 语言选择繁体中文；
• 排版方向选择竖排；
• 图片尽量清晰，不要歪斜；
• 对双页扫描图，建议先裁成单页；
• 对有大面积空白或印章的页面，必要时先裁掉干扰区域。

坑 8：端口 7860 被占用

如果浏览器打不开，或者程序提示端口占用：

<code class="language-powershell">netstat -ano | findstr :7860</code>

找到 PID 后：

<code class="language-powershell">taskkill /PID 进程号 /F</code>

然后重新启动。

坑 9：路径里有中文或空格

有些依赖或命令对路径比较敏感。

避坑：

• 推荐固定放在 C:PP-OCRv6；
• 不建议放在很深的中文路径、桌面、下载目录里；
• 文件名可以中文，但如果出错，先换成简单英文文件名测试。

坑 10：修改代码后旧程序没变化

如果程序已经在运行，改代码不会自动生效。

避坑：

1. 关闭当前黑色命令行窗口； 2. 重新双击 run_ocr_app.bat； 3. 重新生成 OCR 输出。

旧 PDF 不会自动更新，必须重新导出。

10. 推荐使用流程

图片 OCR

1. 启动程序； 2. 进入“图片 OCR”； 3. 上传单张图片或多张图片； 4. 如需编辑单图，使用页面内编辑工具； 5. 选择识别语言； 6. 选择横排或竖排； 7. 勾选输出格式：PDF / TXT / Markdown； 8. 点击开始 OCR； 9. 下载输出文件。

PDF OCR

1. 启动程序； 2. 进入“PDF OCR”； 3. 上传 PDF； 4. 设置页码范围，全部页可填 all； 5. 选择识别语言； 6. 选择横排或竖排； 7. PDF 图层模式选择“原图层 + OCR文字层”； 8. 设置 OCR 文字层字号倍率； 9. 点击开始 PDF OCR； 10. 下载 PDF / TXT / Markdown。

11. 排错顺序

如果程序有问题，建议按这个顺序查：

1. 确认是否从 C:PP-OCRv6 启动； 2. 确认是否使用 .venvScriptspython.exe； 3. 运行：

<code class="language-powershell">..venvScriptspython.exe -m pip install -r requirements.txt</code>

4. 检查端口：

<code class="language-powershell">netstat -ano | findstr :7860</code>

5. 重新运行：

<code class="language-powershell">..venvScriptspython.exe app_v6_upgraded.py</code>

6. 如果 PDF 图层不显示，换支持图层的 PDF 阅读器； 7. 如果 OCR 文字错位，先把字号倍率降到 1.5 测试； 8. 如果 OCR 结果乱，先确认横排/竖排和语言选项是否正确。

12. 最简启动/关闭备忘

启动：

<code class="language-text">双击 C:PP-OCRv6run_ocr_app.bat</code>

访问：

<code class="language-text">http://127.0.0.1:7860</code>

关闭：

<code class="language-text">黑色命令行窗口按 Ctrl + C，然后输入 Y 回车</code>

如果关不掉：

<code class="language-text">直接关闭黑色命令行窗口</code>

如果端口占用：

<code class="language-powershell">netstat -ano | findstr :7860
taskkill /PID 进程号 /F</code>