OCR模型微调指南：cv_resnet18_ocr-detection自定义训练教程

1. 模型与工具简介

1.1 cv_resnet18_ocr-detection是什么

cv_resnet18_ocr-detection 是一个专为中文场景优化的文字检测模型，由科哥基于ResNet-18骨干网络构建。它不负责文字识别（OCR中的Recognition部分），只做文字区域定位（Detection部分）——也就是在图片中准确框出所有含文字的区域，为后续识别打下基础。

你可以把它理解成一个“找字高手”：不管文字是横排、竖排、倾斜、弯曲，甚至被遮挡了一半，它都能用矩形框把文字所在位置标出来。这个能力特别适合处理电商商品图、票据截图、文档扫描件等真实业务场景中的复杂图像。

和通用OCR模型不同，这个模型轻量、启动快、对中文排版友好，而且最关键的是——它支持你用自己的数据重新训练，让检测效果更贴合你的实际业务需求。

1.2 为什么需要微调文字检测模型

开箱即用的模型在标准测试集上表现不错，但一到真实业务中就容易“水土不服”。比如：

你公司商品图上的文字总是出现在右下角固定位置，而通用模型更习惯找居中文字；
你处理的发票图片背景复杂、印章干扰多，原模型容易把印章边框误判为文字框；
你扫描的古籍文档是竖排繁体字，通用模型对这类排版泛化能力弱。

这时候，微调（Fine-tuning）就是最直接有效的解法：用你手头几十张、上百张的真实样本，告诉模型“在我这儿，文字长这样”，它就能快速学会你的“业务语感”。

整个过程不需要从零训练，也不用懂反向传播，就像教一个实习生——给它看例子、指出对错、让它反复练习，几轮下来就能上岗。

2. WebUI环境准备与启动

2.1 环境要求与依赖确认

这个WebUI已在主流Linux服务器（Ubuntu/CentOS）上完成验证，最低配置建议：

CPU：4核以上
内存：8GB起（GPU训练建议16GB+）
显卡：NVIDIA GPU（可选，CPU也能训，只是慢些）
Python：3.8或3.9（已内置在镜像中）

无需手动安装PyTorch、OpenCV等依赖——所有环境都已打包进镜像，开箱即用。

2.2 启动服务三步走

进入项目根目录，执行以下命令：

cd /root/cv_resnet18_ocr-detection bash start_app.sh

你会看到类似这样的输出：

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

说明服务已成功启动。注意：0.0.0.0:7860表示服务监听所有网卡，外部可通过http://你的服务器IP:7860访问。

如果提示端口被占用，可临时修改start_app.sh中的--port参数，比如改成--port 7861。

3. 数据集准备：ICDAR2015格式详解

3.1 为什么必须用ICDAR2015格式

这不是为了“为难你”，而是因为模型训练脚本默认读取这种结构。它已被行业广泛采用，格式清晰、扩展性强，且能同时支持水平、倾斜、弯曲等多种文字形态标注。

好消息是：你不需要手写每行坐标。后面会介绍两种零代码转换方法。

3.2 目录结构与文件规范

你的自定义数据集必须严格按如下结构组织：

/root/custom_data/ ├── train_list.txt # 必填：训练图片与标注的映射关系 ├── train_images/ # 必填：存放所有训练图片 │ ├── invoice_001.jpg │ └── receipt_002.png ├── train_gts/ # 必填：对应图片的文本框标注 │ ├── invoice_001.txt │ └── receipt_002.txt ├── test_list.txt # 可选但强烈建议：用于验证训练效果 ├── test_images/ # 可选：测试图片 └── test_gts/ # 可选：测试标注

小贴士：train_images/和train_gts/下的文件名必须一一对应（如invoice_001.jpg对应invoice_001.txt），扩展名可不同。

3.3 标注文件（.txt）怎么写

每行代表一个文字区域，格式为：

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

其中(x1,y1)是左上角，(x2,y2)是右上角，(x3,y3)是右下角，(x4,y4)是左下角——按顺时针顺序排列。

举个真实例子（一张超市小票截图）：

120,85,320,85,320,105,120,105,商品名称：有机苹果 45,130,180,130,180,150,45,150,单价：12.80元

注意：最后一项“文本内容”可以为空（只检测位置不识别文字），此时写作x1,y1,x2,y2,x3,y3,x4,y4,（末尾逗号保留）。

3.4 列表文件（.txt）怎么写

每行一条记录，空格分隔图片路径和标注路径：

train_images/invoice_001.jpg train_gts/invoice_001.txt train_images/receipt_002.png train_gts/receipt_002.txt

路径是相对于数据集根目录（即/root/custom_data/）的相对路径。

4. 训练微调全流程实操

4.1 进入训练Tab页

打开浏览器访问http://你的服务器IP:7860→ 点击顶部Tab栏的“训练微调”。

界面简洁明了，只有三个输入区：

训练数据目录（必填）：填/root/custom_data（你的数据集根路径）
Batch Size（可选）：默认8。内存够就调大（16或24），训练更快；显存紧张就调小（4或2）
训练轮数（可选）：默认5。一般3~8轮足够，太多易过拟合
学习率（可选）：默认0.007。新数据差异大可略调高（0.01），差异小可略调低（0.005）

4.2 开始训练与状态观察

填好路径后，点击“开始训练”按钮。

界面会实时显示状态：

等待开始训练...→ 后台正在加载数据集、初始化模型
Epoch 1/5 | Loss: 0.421 | Val_IoU: 0.78→ 正在训练，显示当前轮次、损失值、验证集IoU（交并比，越高越好）
训练完成！模型已保存至 workdirs/20260105143022/→ 成功！

IoU小知识：它是检测框和真实框重叠程度的指标，0.7以上算优秀，0.5以上基本可用。WebUI会在训练日志里持续打印，你不用刷新页面就能看到进展。

4.3 训练输出物说明

训练完成后，所有产出都在workdirs/目录下，以时间戳命名，例如：

workdirs/20260105143022/ ├── best.pth # 最佳权重（验证IoU最高时保存） ├── last.pth # 最终权重（最后一轮保存） ├── train.log # 完整训练日志（含每轮Loss/IoU） ├── val_results/ # 验证集检测可视化图（可直观看效果） │ ├── invoice_001_result.png │ └── receipt_002_result.png └── config.yaml # 当前训练参数快照

你只需关注best.pth—— 这就是微调后的新模型，下一步就能直接替换原模型使用。

5. 效果验证与模型替换

5.1 用验证图快速看效果

打开workdirs/20260105143022/val_results/目录，用图片查看器打开invoice_001_result.png。

你会看到原图上叠加了绿色检测框，旁边还标注了置信度（如0.92）。对比原始标注文件，快速判断：

框是否完整覆盖文字？（漏检）
是否框到了非文字区域？（误检）
倾斜文字是否被正确框出？（角度鲁棒性）

如果大部分都准，说明微调成功；如果仍有明显问题，可尝试：

增加训练轮数（改到8~10）
降低学习率（改到0.005）
补充几类典型难样本重新训练

5.2 替换模型并生效

WebUI默认使用内置模型。要让新模型生效，只需两步：

将best.pth复制到模型目录：

cp workdirs/20260105143022/best.pth models/det_model.pth

重启WebUI服务：
```
bash start_app.sh
```

再次进入“单图检测”，上传同一张图，你会发现检测框更贴合你的业务图片了——这就是微调的价值。

验证技巧：准备3张典型图（清晰文档、模糊截图、复杂背景），分别用原模型和新模型跑一遍，对比检测框数量、位置、置信度，一目了然。

6. ONNX导出与跨平台部署

6.1 为什么要导出ONNX

ONNX（Open Neural Network Exchange）是一种开放模型格式，好处是：

一次训练，到处推理：导出后可在Windows、Mac、嵌入式设备、甚至手机App里运行，不依赖Python环境；
性能更稳：ONNX Runtime针对CPU/GPU做了深度优化，推理速度通常比PyTorch原生快20%~50%；
便于集成：C++、Java、C#等语言都有成熟ONNX接口，方便嵌入现有系统。

6.2 导出操作与尺寸选择

回到WebUI → 点击“ONNX 导出”Tab页：

设置输入尺寸：推荐800×800（平衡精度与速度）
点击“导出 ONNX”→ 等待提示“导出成功”
点击“下载 ONNX 模型”，得到model_800x800.onnx

尺寸建议：
640×640：适合边缘设备、实时性要求极高场景（如扫码枪集成）
800×800：通用首选，兼顾精度与速度
1024×1024：仅当处理超高清图纸、需极致细节时使用（内存翻倍）

6.3 Python端简单推理示例

下载后的.onnx文件，用几行Python就能跑起来：

import onnxruntime as ort import cv2 import numpy as np # 加载ONNX模型 session = ort.InferenceSession("model_800x800.onnx") # 读取并预处理图片 image = cv2.imread("test.jpg") h, w = image.shape[:2] # 缩放并归一化 input_blob = cv2.resize(image, (800, 800)) input_blob = input_blob.astype(np.float32) / 255.0 input_blob = input_blob.transpose(2, 0, 1)[np.newaxis, ...] # (1,3,800,800) # 推理 outputs = session.run(None, {"input": input_blob}) boxes, scores = outputs[0], outputs[1] # 假设输出为[boxes, scores] # 过滤低置信度框（阈值0.2） valid_idx = scores > 0.2 boxes = boxes[valid_idx] print(f"检测到 {len(boxes)} 个文字区域")

这段代码不依赖PyTorch，只要装了onnxruntime和opencv-python就能运行，真正实现“拿来即用”。

7. 实用技巧与避坑指南

7.1 数据准备省力三招

招一：用LabelImg半自动标注
下载开源工具 LabelImg，设置为YOLO格式，画完框后用脚本一键转ICDAR格式（网上有现成转换脚本，搜“labelimg to icdar”即可）。
招二：从PDF截图生成训练图
用Adobe Acrobat或WPS将PDF转为高清PNG，再用PPT批量添加模拟印章、水印、阴影等干扰，快速构造“带噪声”的训练样本。
招三：用旧OCR结果反哺标注
先用百度OCR、腾讯OCR等API跑一遍你的图片，把返回的坐标+文本整理成ICDAR格式，再人工校对修正——比从零标注快5倍。

7.2 训练不收敛？先查这三点

现象	最可能原因	快速检查法
Loss不下降，始终在0.8左右	数据集路径填错，模型在训空数据	查`train.log`第一行是否报“no images found”
Val_IoU忽高忽低，波动剧烈	Batch Size太大，梯度不稳定	改小一半（如8→4），重训
训练中途崩溃	图片损坏或标注格式错误	用`head -n 5 train_gts/*.txt`检查前5行是否符合`x1,y1,...,text`格式