用cv_resnet18_ocr-detection做了个文档扫描项目，全过程分享

1. 项目背景与目标

最近在做一个文档数字化的小项目，核心需求是把纸质文件、合同、发票这些材料拍照后自动提取文字区域，方便后续做OCR识别和归档。市面上虽然有不少现成的OCR工具，但要么太重，要么对复杂版式支持不好，而且很多还收费。

后来在CSDN星图镜像广场上发现了一个叫cv_resnet18_ocr-detection的模型镜像，名字看着就很“技术流”——基于ResNet-18的OCR文字检测模型，开发者署名“科哥”，还承诺永久开源。抱着试试看的心态部署了一下，结果出乎意料地好用：轻量、响应快、界面简洁，关键是支持微调和ONNX导出，非常适合二次开发。

这篇文章就来完整记录我从部署到应用的全过程，包括怎么上传图片、调整参数、批量处理，甚至用自己的数据重新训练模型。如果你也在做类似的文字检测或文档扫描类项目，这篇应该能帮你少走不少弯路。

2. 环境准备与快速部署

2.1 镜像简介

这个cv_resnet18_ocr-detection镜像是一个集成了OCR文字检测模型和WebUI的完整环境，基于PyTorch实现，使用ResNet-18作为骨干网络，适合在中低端GPU或高配CPU上运行。它最大的优点是开箱即用，自带图形界面，不需要写代码就能完成检测任务。

镜像由“科哥”构建并开源，提供了完整的用户手册和二次开发接口，支持单图检测、批量处理、模型微调和ONNX导出四大功能，非常适合个人开发者和小团队使用。

2.2 启动服务

我是在一台Ubuntu服务器上部署的，操作非常简单：

cd /root/cv_resnet18_ocr-detection bash start_app.sh

执行完脚本后，终端会输出类似这样的信息：

============================================================ WebUI 服务地址: http://0.0.0.0:7860 ============================================================

说明服务已经成功启动。接下来只需要在浏览器里访问http://你的服务器IP:7860就能看到Web界面了。

整个过程不到两分钟，连Docker都不用装，对新手极其友好。

3. WebUI界面功能详解

3.1 整体布局

打开页面后，第一眼就被它的设计吸引了：紫蓝渐变背景，现代感十足，顶部写着“OCR 文字检测服务”，右下角还有开发者的微信联系方式（312088415），看得出来是个实在人。

界面分为四个Tab页，分别是：

单图检测：上传一张图，查看文字检测结果
批量检测：一次处理多张图片
训练微调：用自定义数据集重新训练模型
ONNX 导出：把模型转成ONNX格式，方便跨平台部署

每个功能都独立成页，逻辑清晰，没有多余的功能堆砌。

3.2 单图检测实战

这是我用得最多的功能。操作流程特别直观：

点击“上传图片”区域，选择一张文档照片；
图片上传后会自动显示预览；
点击“开始检测”按钮，几秒钟后就能看到结果。

输出内容有三部分：

识别文本内容：按顺序列出检测到的文字，带编号，可以直接复制；
检测结果图：原图上叠加了绿色的检测框，清楚地标出每段文字的位置；
检测框坐标（JSON）：包含每个文本块的四点坐标、置信度和推理时间，方便程序调用。

比如我上传了一张产品说明书截图，模型准确圈出了标题、参数表和注意事项，连表格里的小字都没漏掉。

3.3 调整检测阈值的小技巧

界面上有个“检测阈值”滑块，默认值是0.2。这个参数很关键，直接影响检测的严格程度：

阈值越高（如0.4~0.5）：只保留高置信度的结果，适合文字清晰、背景干净的文档，能减少误检；
阈值越低（如0.1~0.2）：更宽松，能检测出模糊或小字号文字，但可能把噪点也当成文字；
一般建议设为0.2~0.3：平衡准确率和召回率。

我在测试手写笔记时就把阈值调到了0.15，成功识别出了潦草的批注；而在处理打印文件时则用0.3，避免把页眉页脚的细线误判为文字。

4. 批量处理与实际应用场景

4.1 批量检测操作流程

当需要处理一整套文件时，“批量检测”功能就派上用场了。操作也很简单：

点击“上传多张图片”，支持Ctrl/Shift多选；
设置检测阈值；
点击“批量检测”按钮；
系统会依次处理所有图片，并在下方画廊展示结果；
可点击“下载全部结果”保存处理后的图像。

我试过一次性上传20张PDF截图，GTX 1060显卡大概花了不到10秒就全部处理完，速度相当可观。

4.2 典型应用场景推荐设置

根据官方文档和我的实测经验，不同场景下的最佳参数如下：

场景	推荐阈值	注意事项
证件/文档扫描	0.2 - 0.3	图片尽量清晰，避免反光
屏幕截图识别	0.15 - 0.25	避免压缩导致的模糊
手写文字检测	0.1 - 0.2	建议先增强对比度
复杂背景图片	0.3 - 0.4	可提前去噪或二值化

特别是处理发票、合同这类正式文档时，只要拍照光线充足，基本都能做到零遗漏。

5. 模型微调：让AI更懂你的数据

5.1 为什么需要微调？

虽然默认模型已经很强，但如果你的数据风格特殊——比如古籍扫描、医疗报告、特定字体的设计稿——通用模型可能表现不佳。这时候就需要用“训练微调”功能，让模型学会识别你自己的数据。

5.2 数据准备规范

微调需要准备符合ICDAR2015格式的数据集，结构如下：

custom_data/ ├── train_list.txt ├── train_images/ # 训练图片 ├── train_gts/ # 对应的标注文件 ├── test_list.txt ├── test_images/ └── test_gts/

每个标注文件（txt）的格式是：

x1,y1,x2,y2,x3,y3,x4,y4,文本内容

列表文件则是图片路径和标注路径的对应关系：

train_images/1.jpg train_gts/1.txt

我用了大约100张内部文档截图，标注了标题、表格和签名区域，花了半天时间整理成这个格式。

5.3 开始训练

在“训练微调”页面输入数据目录路径，比如/root/custom_data，然后可以调整以下参数：

Batch Size：默认8，显存不够可降到4；
训练轮数（Epoch）：一般5轮就够了，太多容易过拟合；
学习率：默认0.007，不建议轻易改动。

点击“开始训练”后，系统会在后台运行，训练完成后模型会保存在workdirs/目录下。我训练了5个epoch，总共耗时约12分钟（GTX 1060），重新加载模型后，对同类文档的检测准确率明显提升，连印章边缘的文字都能稳定识别了。

6. ONNX导出与跨平台部署

6.1 导出步骤

如果你想把这个模型集成到其他系统里，比如Android App、Windows软件或者嵌入式设备，就可以用“ONNX 导出”功能。

操作很简单：

设置输入尺寸（高度和宽度），支持320~1536之间的任意值；
点击“导出 ONNX”按钮；
等待片刻，系统会生成.onnx文件；
点击“下载 ONNX 模型”即可获取。

导出的模型包含了完整的预处理和后处理逻辑，拿来就能用。

6.2 输入尺寸选择建议

尺寸	特点	适用场景
640×640	速度快，内存占用低	实时检测、移动端
800×800	平衡精度与性能	通用场景
1024×1024	高精度，细节丰富	高分辨率文档

我导出了一个800×800的版本，在Python环境下用ONNX Runtime加载，推理速度比原始PyTorch模型还快了一点。

6.3 Python推理示例

import onnxruntime as ort import cv2 import numpy as np # 加载ONNX模型 session = ort.InferenceSession("model_800x800.onnx") # 读取并预处理图片 image = cv2.imread("test.jpg") input_blob = cv2.resize(image, (800, 800)) input_blob = input_blob.transpose(2, 0, 1)[np.newaxis, ...].astype(np.float32) / 255.0 # 推理 outputs = session.run(None, {"input": input_blob}) # 解析输出（boxes, scores等） # 后续可做NMS、可视化等处理

这段代码跑通后，意味着你已经可以把这个OCR检测能力嵌入到任何支持ONNX的平台上了。