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

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

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

• 方式一（推荐）：直接将本地图片文件拖入虚线框内，松手即上传
• 方式二：点击虚线框内'点击上传'文字，唤起系统文件选择器
• 支持格式：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 张（防内存溢出）

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

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

1. 调整检测阈值（同单图逻辑）
2. 点击'批量检测' → 启动队列式处理
3. 实时显示进度条：'已完成 7/23 张，平均耗时 2.8s/张'
4. 处理完毕，右侧以画廊形式展示所有结果图，每张图带：
   • 原始文件名标签
   • 检测框数量统计（如 共检测到 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 中只需填三项，其他由科哥预设最优值：

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

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

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

• 实时显示：当前 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 提供三档预设：

实测结论：对 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 打不开？先查这三件事

1. 服务是否活着：终端执行 ps aux | grep python，确认有 gradio 或 uvicorn 进程
2. 端口是否被占：执行 lsof -ti:7860，若无输出说明端口空闲；若有，kill -9 PID 杀掉占用进程
3. 防火墙是否拦截：云服务器需在安全组放行 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 云服务，而是成为你本地工作流中那个'永远在线、随时响应、绝不收费'的可靠伙伴。当你要快速验证一个想法、临时处理一批资料、或是为定制化需求打下第一块基石时，它就在那里，安静，高效，不打扰。