模型训练失败怎么办？cv_resnet18_ocr-detection排错手册-开发者社区

模型训练失败怎么办？cv_resnet18_ocr-detection排错手册

1. 为什么训练会失败——先搞懂这个模型在做什么

在动手排查之前，得明白你正在调试的不是一个黑箱，而是一个有明确结构、有清晰数据流的OCR文字检测系统。cv_resnet18_ocr-detection镜像不是简单套了个ResNet18外壳的通用模型，它背后是DB（Differentiable Binarization）文本检测算法的工程化落地，专为中文场景优化过。

它的核心任务很纯粹：不识别文字内容，只圈出图片里所有文字出现的位置。就像一个视力极好的助手，你给它一张图，它立刻用红色方框把“发票”“价格”“型号”这些字块一一标出来，但不会告诉你框里写的是“¥99.00”还是“库存：23件”。

这个能力来自三个关键模块的协同：

Backbone（ResNet18）：负责“看清楚”。它把输入图片一层层拆解，提取出边缘、纹理、形状等基础视觉特征。ResNet18在这里不是追求最高精度，而是平衡了速度与表征能力，让整套流程能在普通GPU甚至高配CPU上跑起来。
FPN（特征金字塔网络）：负责“远近兼顾”。文字有大有小，标题可能占半张图，页脚小字可能只有几个像素高。FPN把Backbone不同深度的特征图融合起来，既保留了细节（小字），又抓住了整体（大标题），确保大小文字都能被“看见”。
Head（DB Head）：负责“精准画框”。它不直接输出坐标，而是生成两张关键的“热力图”：一张是文本区域概率图（哪里可能是文字），另一张是动态阈值图（每个位置判断“是/否”的标准线）。DB算法的精髓就在这里——它让模型自己学会“什么算清晰、什么算模糊”，而不是用一个死板的0.5阈值一刀切。

所以，当训练失败时，问题大概率不出在“模型太笨”，而是在数据没喂对、环境没配好、或者参数设得太激进。接下来，我们就按这个逻辑，一层层剥开问题。

2. 排错第一步：确认你的数据集是“合格”的ICDAR2015格式

训练失败，八成根子在数据上。cv_resnet18_ocr-detection的训练模块严格遵循ICDAR2015标准，任何格式偏差都会导致加载失败、维度报错，甚至静默崩溃。别跳过这一步，这是最常被忽略的“元凶”。

2.1 目录结构必须严丝合缝

你的自定义数据集目录（比如/root/custom_data）必须长这样，一个字符都不能错：

custom_data/ ├── train_list.txt # 必须存在，且路径正确 ├── train_images/ # 必须存在，文件夹名不能是 train_img 或 images │ ├── 1.jpg # 图片格式必须是 JPG/PNG/BMP，不能是 .jpeg 或 .JPG（Linux区分大小写！） │ └── 2.png # 建议统一用小写后缀 ├── train_gts/ # 必须存在，文件夹名不能是 gt 或 annotations │ ├── 1.txt # 文件名必须和图片名一一对应 │ └── 2.txt ├── test_list.txt # 即使不测试，也必须存在（可为空） ├── test_images/ # 同上，必须存在 │ └── 3.jpg └── test_gts/ # 同上，必须存在 └── 3.txt

致命陷阱排查清单：

train_list.txt和test_list.txt是纯文本文件，不是.txt~或.txt.bak这类隐藏备份。
train_list.txt里的每一行，格式必须是train_images/1.jpg train_gts/1.txt，前后不能有空格，路径不能用绝对路径（如/root/...），也不能漏掉train_images/和train_gts/前缀。
train_gts/1.txt里的坐标，必须是8个数字加一个文本，用英文逗号分隔，不能有空格、中文逗号、制表符或换行符。错误示例：10,20,100,20,100,80,10,80, 产品名称（末尾多了一个空格）；正确示例：10,20,100,20,100,80,10,80,产品名称。
所有图片文件，用file 1.jpg命令检查，确认是真正的JPEG/PNG文件，而不是一个重命名的PDF或网页截图。

2.2 用一个命令快速验证数据集

别靠肉眼数文件，用终端一行命令搞定：

cd /root/custom_data # 检查核心文件是否存在 ls -l train_list.txt test_list.txt train_images/ train_gts/ test_images/ test_gts/ # 检查 train_list.txt 内容是否规范（显示前3行） head -n 3 train_list.txt # 检查第一张标注文件是否格式正确 head -n 1 train_gts/$(head -n1 train_list.txt | awk '{print $2}' | cut -d'/' -f2) # 统计图片和标注数量是否一致 echo "图片数: $(ls train_images/*.jpg train_images/*.png 2>/dev/null | wc -l)" echo "标注数: $(ls train_gts/*.txt 2>/dev/null | wc -l)"

如果输出显示“No such file”或数量不一致，立刻停下，去修复数据集。这是最高效的投资时间的方式。

3. 排错第二步：检查训练启动时的实时日志

WebUI界面上的“训练失败”提示太笼统。真正的线索，藏在后台滚动的日志里。你需要亲自去看。

3.1 如何捕获第一手日志

当你在WebUI点击“开始训练”后，立刻在服务器终端执行：

# 切换到项目根目录 cd /root/cv_resnet18_ocr-detection # 实时追踪最新的训练日志（workdirs下最新创建的文件夹） tail -f $(ls -t workdirs/ | head -n1)/log.txt 2>/dev/null || echo "日志文件尚未生成，请稍等几秒"

关键观察点（看到这些，立刻停手）：

FileNotFoundError: [Errno 2] No such file or directory: 'xxx'
→ 数据集路径错了，或者train_list.txt里写的文件名和实际不符。回到第2节，重新核对。
ValueError: could not convert string to float: 'abc'
→ 标注文件1.txt里混入了非数字字符。打开那个文件，用cat -A 1.txt查看是否有不可见符号（如^M回车符），用dos2unix 1.txt修复。
RuntimeError: CUDA out of memory
→ GPU显存不够。这是常见问题，解决方案在第4节。
IndexError: list index out of range
→ 标注文件里某一行的坐标少于8个数字，或者文本内容为空导致解析失败。检查对应行。
日志卡在Starting training...后超过2分钟没动静
→ 很可能是数据集太大，模型在做预处理。耐心等待，或改用更小的子集测试。

3.2 日志里没有错误，但训练“假成功”

有时日志显示Training finished!，但workdirs/下没有生成.pdparams权重文件，或者log.txt末尾是Epoch 0/5, loss: nan。这说明训练过程本身崩溃了，但错误被静默吞掉了。

终极验证法：训练结束后，手动检查输出目录：

# 进入最新训练目录 cd $(ls -t workdirs/ | head -n1) # 查看是否有权重文件 ls -lh *.pdparams 2>/dev/null || echo " 警告：未生成权重文件！" # 查看loss曲线是否正常下降（不是nan或inf） grep "loss:" log.txt | tail -n 10

如果loss是nan，问题通常出在学习率过高、数据中有极端异常值（如超大坐标），或Batch Size设得太大。

4. 排错第三步：针对高频硬件与参数问题的速效方案

有些问题反复出现，我们整理了最有效的“一键式”解决方案，无需深究原理，直接套用。

4.1 GPU显存不足（CUDA out of memory）

这是新手最常遇到的拦路虎。ResNet18虽轻量，但DB算法的FPN和Head仍需大量显存。

三步速解：

立刻减小 Batch Size：在WebUI的训练参数中，将默认的8改为2或1。这是最快见效的方法。
降低输入分辨率：在ONNX导出页面，你看到的800x800是训练时的默认尺寸。在训练前，用图像处理工具（如convert命令）将你的train_images/里所有图片统一缩放到640x640以内。命令如下：
```
cd /root/custom_data/train_images mogrify -resize 640x640\> *.jpg *.png # \> 表示只在原图大于640时才缩放，避免小图被拉伸
```
启用CPU训练（万不得已）：如果连Batch Size=1都不行，说明GPU确实太小。编辑train.sh脚本（在项目根目录），找到python tools/train.py这一行，在后面加上--use_gpu False，然后在WebUI里用“自定义命令”运行它。

4.2 训练loss为nan或剧烈震荡

这表明模型在“胡学”，学不到稳定规律。

针对性调整：

学习率（Learning Rate）：默认0.007对大多数自定义数据集来说太高了。强烈建议改为0.001。这是一个更安全、更通用的起点。
训练轮数（Epochs）：默认5轮对于新数据集往往不够。建议设为20，让模型有足够时间收敛。
数据增强（Data Augmentation）：镜像内置了基础增强，但如果你的数据集非常单一（比如全是白底黑字的发票），可以临时关闭它来稳定训练。编辑configs/det_db.yml文件，将use_tps: True改为False，并注释掉tps相关的配置块。

4.3 训练完成后，模型在WebUI里“检测无效果”

权重文件生成了，但上传图片后，检测框要么全空，要么满屏乱飘。这说明模型学到了，但学得不好。

这不是训练失败，而是训练“不到位”。请执行：

检查检测阈值：在单图检测页，把滑块从默认0.2拉到0.05，看看是否能检出更多框。如果能，说明模型置信度普遍偏低，需要继续训练。
用训练集图片做“回测”：上传一张train_images/里的原图，看它能否准确框出train_gts/里标注的位置。如果回测都失败，说明数据集或标注有根本性问题。
查看训练日志中的mAP：在log.txt末尾，搜索best metric。一个健康的训练，hmean（F1-score）应该在0.7以上。如果低于0.5，果断重训，并采用第4.2节的保守参数。

5. 排错第四步：利用WebUI的“批量检测”功能做快速验证

与其等一轮训练（可能半小时）再验证，不如用现成的、已验证过的模型，走一遍完整的数据流，确认整个链路是通的。

5.1 创建一个“黄金测试集”

准备3张图片，放在一个独立文件夹，比如/root/test_ocr/：

invoice.jpg：一张清晰的电子发票截图（文字规整）
menu.png：一张餐厅菜单照片（文字有角度、背景复杂）
handwritten.jpg：一张手写笔记（挑战极限）

5.2 执行端到端验证

在WebUI的“批量检测”Tab页，上传这3张图。
将检测阈值调至0.1（最宽松）。
点击“批量检测”。
观察结果：
- 如果3张图都返回了合理的检测框（哪怕不完美），说明模型、WebUI、GPU驱动、OpenCV库全部正常，问题100%出在你的训练数据或参数上。
- 如果其中一张（比如handwritten.jpg）完全失败，而另外两张OK，那说明模型对你的“手写”场景泛化能力弱，需要在训练数据里加入更多类似样本。
- 如果3张图都失败，或者返回空白JSON，说明底层环境有严重问题，此时应重启服务bash start_app.sh并重试。

这个验证过程只需1分钟，却能帮你把问题域从“整个系统”精准缩小到“我的训练数据”。

6. 总结：一份可立即执行的排错清单

训练失败不是终点，而是模型在向你发出清晰的信号。把它当作一次与AI协作的深度对话，而非一场对抗。以下清单，就是你下次点击“开始训练”前，应该逐项打钩的动作：

□ 数据集格式复查：用第2.2节的ls和head命令，100%确认train_list.txt路径、train_gts/*.txt坐标格式、图片文件名三者严丝合缝。
□ 启动实时日志监控：在点击训练按钮的同一秒，就在终端执行tail -f workdirs/latest/log.txt，眼睛盯着屏幕，捕捉第一个错误信号。
□ 参数保守开局：首次训练，Batch Size 设为2，学习率设为0.001，Epochs 设为20。宁可多训几轮，也不要一步到位。
□ 硬件兜底方案：如果GPU报错，立刻执行mogrify -resize 640x640\>缩放图片，这是比换卡更快的解决方案。
□ 用批量检测反向验证：在训练前，先用3张自己的图走一遍检测流程，确认“路是通的”，再把精力聚焦在数据上。