基于 ResNet18 的轻量级 OCR WebUI 实战指南

这不是又一个 OCR 工具，而是一次体验升级

你有没有过这样的经历：花半小时配环境、改路径、调参数，终于跑通一个 OCR 模型，结果打开网页——灰扑扑的 Gradio 默认界面，按钮挤在角落，上传框像上世纪的网页表单，检测完还得手动翻 JSON 看坐标？

科哥做的这个 cv_resnet18_ocr-detection WebUI，彻底改写了这个剧本。它没有堆砌炫技功能，却把'好用'刻进了每一处交互细节：紫蓝渐变的标题栏不刺眼、悬停有微光反馈、检测进度条带实时耗时显示、结果文本一键全选复制、坐标数据自动格式化为可读结构……这不是给工程师看的调试面板，而是为真实使用者设计的工作台。

更关键的是——它足够轻量。不用 GPU 也能跑，CPU 上单图检测 3 秒出结果；模型基于 ResNet18 轻量架构，显存占用低，连 GTX 1060 都能稳稳扛住批量处理；所有功能模块（单图/批量/训练/导出）都封装在同一个 Web 界面里，无需切终端、不用记命令，点几下就完成从前要写脚本才能做的事。

这篇文章不讲模型结构、不推公式、不比 benchmark。我们只做一件事：带你从零开始，用最自然的方式，把这张带文字的图片，变成你马上能复制、能下载、能集成进业务里的结构化结果。

三分钟启动：从镜像到可操作界面

一键拉起服务

镜像已预装全部依赖，无需编译、无需配置 Python 环境。只需两步：

cd /root/cv_resnet18_ocr-detection
bash start_app.sh

执行后你会看到清晰提示：

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

注意：如果你是远程服务器，把 0.0.0.0 换成你的服务器公网 IP，例如 http://123.45.67.89:7860

界面初印象：为什么说'紫蓝渐变'不是噱头？

打开链接，第一眼就能感受到差异——这不是 Gradio 默认皮肤的简单换色，而是一套完整视觉语言：

标题栏采用深紫到湛蓝的平滑渐变，文字用浅灰白确保高对比度，长时间使用不累眼
四个 Tab 页用圆角卡片 + 微妙阴影分隔，当前激活页有底部高亮条，切换时有 0.2 秒缓动动画
所有按钮悬停时背景加深、边框微扩，点击瞬间有 0.08 秒压感反馈
图片上传区是带虚线边框的拖拽区域，支持直接把文件从桌面拖进来

这种克制的动效和色彩控制，让整个工具既有专业感，又不显得冰冷。它不抢你注意力，但每次操作都给你确定的反馈。

首页四功能区：各司其职，不堆砌

界面顶部四个 Tab 页，对应四种高频需求，没有隐藏菜单、没有二级入口：

Tab 页	它解决什么问题	新手建议优先尝试
单图检测	'我有一张发票/截图/文档，现在就要提取文字'	强烈推荐从这里开始
批量检测	'我有 20 张产品说明书，不想一张张传'	处理 3 张以上就该用它
训练微调	'我的场景很特殊，通用模型识别不准'	建议先跑通单图再考虑
ONNX 导出	'我要把模型部署到手机/边缘设备'	导出后需额外开发集成

你会发现，每个 Tab 页的布局逻辑高度一致：左侧操作区（上传/参数）、右侧结果区（预览/输出），视线动线自然从左到右。这种一致性，比任何炫酷特效都更能提升效率。

单图检测：从上传到结果，一气呵成

上传图片：支持即拖即用，也兼容传统点击

方式一（推荐）：直接将本地图片文件拖入虚线框内，松手即上传
方式二：点击虚线框内'点击上传'文字，唤起系统文件选择器
支持格式：JPG、PNG、BMP（不支持 WebP、GIF 等）
小技巧：截图后按 Ctrl+V 可直接粘贴图片（部分浏览器支持）

上传成功后，左侧立刻显示原图缩略预览，尺寸自适应容器，保留原始宽高比。

检测过程：看得见的进度，算得清的时间

点击'开始检测'后，按钮变为禁用状态并显示加载动画，同时下方出现：

检测中... 当前耗时：0.8s | 预估剩余：1.2s

这个实时计时不是摆设。它基于模型实际推理耗时动态更新，让你对等待心里有数——而不是干等一个无响应的按钮。

结果呈现：三层信息，各取所需

检测完成后，右侧结果区展开为三个标签页，信息分层清晰：

文本内容（最常用）

每行文本带编号（1. 2. 3. …），方便口头指代
全选快捷键 Ctrl+A，复制快捷键 Ctrl+C，无需鼠标划选
中文、英文、数字、符号混合排版保持原顺序，不乱序、不断行

示例输出：

1. 100% 原装正品提供正规发票 2. 华航数码专营店 3. 正品 4. 保证 5. 天猫 6. 商城 7. 电子元器件提供 BOM 配单 8. HMOXIRR

检测可视化（最直观）

在原图上叠加半透明彩色检测框，框线宽度适中，不遮挡文字
每个框右上角标注置信度（如 0.98），数值越接近 1 表示模型越确信
支持鼠标悬停查看该框对应文本，避免来回切换标签页

坐标 JSON（最结构化）

输出标准 JSON 格式，字段名直白易懂：texts、boxes、scores
boxes 是 8 维数组 [x1,y1,x2,y2,x3,y3,x4,y4]，对应文本框四个顶点坐标
inference_time 字段精确到毫秒，方便你评估性能瓶颈

{
  "image_path": "/tmp/test_ocr.jpg",
  "texts": [["100% 原装正品提供正规发票"], ["华航数码专营店"]],
  "boxes": [[21, 732, 782, 735, 780, 786, 20, 783]],
  "scores": [0.98, 0.95],
  "success": true,
  "inference_time": 3.147
}

阈值调节：不是玄学，是精准控制

检测阈值滑块（0.0–1.0）是影响结果质量的关键旋钮，但它不是越低越好、也不是越高越好：

阈值=0.2（默认）：平衡点，适合大多数清晰文档
阈值=0.1：对付模糊截图、低分辨率照片，宁可多检几个错字，也不错漏
阈值=0.4：用于干净白底证件照，大幅减少边框误检（如纸张边缘、印章轮廓）

实测建议：先用默认值跑一次，如果结果偏少，往左滑 0.05；如果结果杂乱，往右滑 0.1。通常 2–3 次微调就能找到最佳值。

批量检测：告别重复劳动，效率提升 10 倍

一次上传，智能分组

点击'上传多张图片'，支持：

Windows：Ctrl+ 单击 选不连续文件，Shift+ 首尾单击 选连续文件
macOS：Command+ 单击 同上
无数量硬限制，但单次建议≤50 张（防内存溢出）

上传后，界面自动按文件名排序，并在缩略图下方显示原始文件名，避免传错图自己没发现。

批量处理流程：所见即所得

调整检测阈值（同单图逻辑）
点击'批量检测' → 启动队列式处理
实时显示进度条：'已完成 7/23 张，平均耗时 2.8s/张'
处理完毕，右侧以画廊形式展示所有结果图，每张图带：
- 原始文件名标签
- 检测框数量统计（如 共检测到 12 处文本）
- 置信度均值（如 平均得分：0.93）

结果导出：不止于下载一张图

单张下载：点击任意结果图，弹出大图预览，右下角有'下载'按钮
全部打包：点击'下载全部结果'，生成 ZIP 包，内含：
- /visualization/：所有带检测框的图片（命名规则：原文件名_result.png）
- /json/：对应 JSON 文件（命名规则：原文件名_result.json）
- /summary.txt：汇总报告，列出每张图的检测数量、平均置信度、总耗时

这个 ZIP 包可直接发给同事或导入下游系统，省去手动整理时间。

训练微调：把通用模型，变成你的专属 OCR

数据准备：不求多，但求准

你不需要从零标注几千张图。科哥的 WebUI 对训练数据要求极简：

最小可行集：10 张高质量样本图 + 对应标注，就能明显改善特定场景识别率
标注格式：纯文本 .txt 文件，每行一个文本框，格式为：
x1,y1,x2,y2,x3,y3,x4,y4，文本内容
目录结构：严格遵循 ICDAR2015 标准，但 WebUI 会校验并给出明确错误提示

示例标注文件 1.txt：

120,45,380,45,380,75,120,75，订单号：20240528-001
45,120,220,120,220,150,45,150，收货人：张三

训练配置：三参数决定效果上限

在 WebUI 中只需填三项，其他由科哥预设最优值：

参数	你该填什么	为什么这样设
训练数据目录	例如 `/root/my_invoice_data`	必须是绝对路径，WebUI 会自动扫描子目录
Batch Size	默认 8，若显存充足可调至 16	太大会 OOM，太小收敛慢，8 是安全起点
训练轮数	默认 5，复杂场景可加到 10	过多轮数易过拟合，5 轮通常足够捕捉关键特征

小技巧：首次训练建议用默认值。若效果不佳，再尝试增加轮数，而非盲目调大学习率。

训练过程：全程可视，失败可溯

点击'开始训练'后，界面切换为训练监控页：

实时显示：当前 Epoch、Batch ID、Loss 值（下降趋势清晰可见）
完成后自动跳转至输出目录 workdirs/，列出：
- best.pth：最优权重文件
- train.log：完整日志，含每轮指标
- val_results/：验证集检测样例图

训练好的模型会自动加载进 WebUI，下次检测即生效，无需重启服务。

ONNX 导出：跨平台部署，一步到位

导出即用：告别环境依赖

ONNX 是工业界事实标准，导出后可直接在：

Windows/Linux/macOS（用 ONNX Runtime）
Android/iOS（用 ONNX Mobile）
嵌入式设备（如 Jetson Nano、树莓派）
浏览器（用 ONNX.js）

无需 Python、无需 PyTorch，只要支持 ONNX 的运行时，就能跑 OCR。

尺寸选择：不是越大越好，而是恰到好处

输入尺寸直接影响速度与精度，WebUI 提供三档预设：

尺寸	适用场景	推理速度（RTX 3090）	内存占用	推荐指数
640×640	手机截图、网页内容	18 FPS	<1GB
800×800	通用文档、发票	12 FPS	~1.2GB	☆
1024×1024	高清扫描件、工程图纸	7 FPS	~1.8GB	☆☆

实测结论：对 A4 纸扫描件，800×800 是黄金平衡点——精度损失<1%，速度提升 40%。

Python 调用示例：5 行代码搞定推理

导出的 ONNX 模型，开箱即用：

import onnxruntime as ort
import cv2
import numpy as np

# 1. 加载模型
session = ort.InferenceSession("model_800x800.onnx")

# 2. 读取并预处理图片
image = cv2.imread("invoice.jpg")
input_blob = cv2.resize(image, (800, 800))
input_blob = input_blob.transpose(2, 0, 1)[np.newaxis, ...].astype(np.float32) / 255.0

# 3. 执行推理
outputs = session.run(None, {"input": input_blob})

# 4. 解析结果（outputs[0] 为检测框，outputs[1] 为置信度）
# 5. 后处理（NMS、坐标还原）——科哥已提供参考脚本

WebUI 文档中附带完整后处理代码，你只需专注业务逻辑。

真实场景调优指南：不同图片，不同策略

证件/合同类（高精度刚需）

推荐设置：检测阈值 0.35，输入尺寸 800×800
预处理建议：上传前用手机 APP（如'白描'）做自动裁剪 + 二值化
避坑提示：避免反光区域，强光下拍摄的身份证，OCR 易在反光处生成伪框

手机截图（小字体、抗锯齿）

推荐设置：检测阈值 0.15，关闭'增强对比度'（WebUI 未内置，但可在上传前用 Photoshop 调整）
关键观察：检查 JSON 中的scores，若普遍低于 0.7，说明截图压缩过度，换原图重试

商品包装（复杂背景、艺术字）

推荐设置：检测阈值 0.25，启用'仅检测水平文本'（WebUI 高级选项，需勾选）
为什么有效：包装上 Logo、标语多为水平排布，排除倾斜检测可大幅减少误报

手写笔记（低对比度、连笔）

现实提醒：ResNet18 检测模型非专为手写优化，识别率有限
务实方案：先用 WebUI 检测出文本区域坐标，再将这些 ROI 图送入专用手写识别 API（如百度 OCR）
效率提升：WebUI 帮你省去 90% 的手动框选时间

故障排查：常见问题，三步定位

WebUI 打不开？先查这三件事

服务是否活着：终端执行 ps aux | grep python，确认有 gradio 或 uvicorn 进程
端口是否被占：执行 lsof -ti:7860，若无输出说明端口空闲；若有，kill -9 PID 杀掉占用进程
防火墙是否拦截：云服务器需在安全组放行 7860 端口

检测结果为空？别急着调参

第一步：上传一张纯白底 + 黑体字的测试图（如用 Word 新建一页，打'测试 OCR'），确认基础功能正常
第二步：若测试图 OK，原图失败 → 检查原图是否为扫描 PDF 转的 JPG（常含隐藏图层，需用 Adobe Acrobat 重新导出）
第三步：降低阈值至 0.05，若出现大量乱框 → 原图质量差，需预处理

批量检测卡死？内存是元凶

症状：上传 30 张图后，界面无响应，服务器free -h显示内存 100%
解法：
- 立即刷新页面（不关服务）
- 下次批量时，单次≤15 张
- 编辑 start_app.sh，在启动命令末尾加 --no-gradio-queue 参数，启用流式处理

总结：为什么值得你花 10 分钟试试

科哥的这个 OCR WebUI，不是又一个'能跑就行'的 Demo 项目。它把工程师的严谨，藏在了使用者的流畅体验之下：

对新手：3 分钟启动，5 分钟上手，无需懂模型、不碰代码，上传→检测→复制，闭环完成
对开发者：ONNX 导出开箱即用，训练微调路径清晰，JSON 输出结构规范，可直接对接业务系统
对团队：紫蓝渐变 UI 降低学习成本，批量处理节省重复劳动，版权开源承诺消除合规顾虑

它不试图取代专业 OCR 云服务，而是成为你本地工作流中那个'永远在线、随时响应、绝不收费'的可靠伙伴。当你要快速验证一个想法、临时处理一批资料、或是为定制化需求打下第一块基石时，它就在那里，安静，高效，不打扰。