简介这份《基于YOLOv8的古籍保护系统》资源包专为毕业设计、课程设计或相关深度学习项目开发而整理面向计算机、人工智能等专业的学生与初学者。内容涵盖完整的YOLOv8目标检测源码、古籍标注数据集、可视化交互界面及部署说明可用于快速搭建一套可演示、可扩展的古籍保护检测系统。压缩包共包含97个文件以70个Python源码文件为核心辅以模型权重文件pt、配置文件xml、说明文档txt和演示视频mp4整体大小24.21MB结构清晰便于按模块查阅和二次开发。系统界面支持直观展示检测结果并能生成精确率-召回率曲线、混淆矩阵、F1分数曲线等核心指标图表方便用于答辩或项目汇报。资源中的代码均已测试通过下载后按README指引即可运行已有56人学习下载值得作为实战项目参考。1. 古籍保护系统为什么选择 YOLOv8先看清这套系统在检测什么「古籍保护系统」听起来像博物馆里的高精尖项目拆开看核心任务其实很朴素把古籍扫描件上的文字行、印章、批注、污损区域自动框出来。YOLOv8 在这套系统里承担的就是这个目标检测任务框完之后再交给后续的 OCR 识别、留档和检索环节。选 YOLOv8 而不是更复杂的二阶段模型是因为古籍页面的检测目标尺寸相对固定、类别少、对推理速度有要求而且部署链路最成熟。这套方案把源码、数据集、可视化界面和部署教程打包在一起简单部署即可运行特别适合拿来当毕设或课程设计的完整项目练手。2. 构建古籍检测数据集标注类别怎么定、JSON 怎么转 YOLO 格式2.1 古籍检测任务拆解与数据选型古籍扫描件和现代文档的版面差异很大竖排文字、繁体字形、栏线、版框、渗墨、虫蛀痕迹这些在目标检测里都是可以被建模的视觉特征。做古籍保护系统最常见的检测任务有三个方向文字行检测为 OCR 做前置、印章检测、污损区域检测水渍、霉斑、破损。毕设或课程设计不建议一上来做七八个类别2 到 4 类最稳既能体现系统完整度又不至于让数据集标注量失控。我自己做过一次这类项目踩过最大的坑是「想做单字检测」。单字框数量大、标注累、而且竖排繁体字的单字框外接矩形不稳定换一页扫描件就可能对不齐。后来改回文字行检测整页扫描件一张图标注的框数从几百降到三四十训练质量反而上去了。古籍左上角的竖排题签、卷首的牌记、正文里的双行小注这些用行级框都能覆盖后续 OCR 再按行去切分识别链路是通的。数据来源方面常见做法是去公开数字馆藏找公版古籍的扫描图优先选明清民国时期的刻本和抄本页面干净、版权风险低。先挑 30 到 50 张整页扫描件人工标注训一个小模型然后用这个小模型对剩下的扫描件做预标注人工修正后回填数据集迭代效率能提升很多。这个「半自动标注」流程比纯手标节省至少一半时间是古籍这类密集版面场景最实用的开工方式。2.2 LabelMe 标注与 Label 映射规则LabelMe 是古籍数据集标注最常用的工具因为它的 JSON 结构里保留的是多边形点坐标后处理自由度大。如果你的项目也包含界面端展示LabelMe 的原生格式还方便做可视化校验。LabelImg 当然也能用但矩形框在竖排文字行的细长形状上经常框不紧所以我一般优先教同学用 LabelMe。标注前先定好类别与 id 的映射表这一步指定了后面所有脚本都不用改。类别名label id含义标注要求text_line0竖排文字行外接矩形紧贴文字高度可以略大于文字本身seal1红色印章只框印面不框题跋墨迹stain2渗墨、水渍、破损边缘模糊时按肉眼可见区域框标注完成后每个图片文件对应一个同名 JSON 文件例如page_001.jpg对应page_001.json。JSON 里记录的是多边形点坐标下一步必须统一转换成 YOLO 训练需要的 txt 格式。2.3 LabelMe JSON 转 YOLO txt 转换脚本YOLO 的标注格式是每行class_id x_center y_center width height坐标全部归一化到 0 到 1 之间。转换的核心是读取多边形的外接矩形然后做归一化。下面是完整的转换脚本。import json import os from pathlib import Path def labelme_to_yolo(json_path, out_dir, class_map): 将 LabelMe 的 JSON 标注转换为 YOLO 格式的 txt 标注 json_path: LabelMe 输出的 JSON 文件路径 out_dir: 输出 txt 的目录 class_map: 类别名到数字 id 的映射例如 {text_line: 0, seal: 1, stain: 2} with open(json_path, r, encodingutf-8) as f: data json.load(f) # 读取图像宽高LabelMe 在 JSON 里存的是 imageWidth / imageHeight img_w data.get(imageWidth, 0) img_h data.get(imageHeight, 0) if img_w 0 or img_h 0: print(f[跳过] {json_path} 缺少图像尺寸信息) return lines [] for shape in data[shapes]: label shape[label] if label not in class_map: # 宁可报错也不要静默跳过否则类别错乱很难排查 raise ValueError(f{json_path} 中出现未定义类别: {label}) # points 是多边形顶点取所有顶点中最小/最大的 x、y 作为外接矩形 pts shape[points] xs [p[0] for p in pts] ys [p[1] for p in pts] x_min, x_max min(xs), max(xs) y_min, y_max min(ys), max(ys) # 过滤掉宽或高小于 1 像素的框这类框训练时会被忽略 if x_max - x_min 1 or y_max - y_min 1: continue # 归一化并裁剪到 [0, 1] 区间防止坐标越界 x_center ((x_min x_max) / 2) / img_w y_center ((y_min y_max) / 2) / img_h w (x_max - x_min) / img_w h (y_max - y_min) / img_h x_center min(max(x_center, 0.0), 1.0) y_center min(max(y_center, 0.0), 1.0) w min(max(w, 0.0), 1.0) h min(max(h, 0.0), 1.0) lines.append(f{class_map[label]} {x_center:.6f} {y_center:.6f} {w:.6f} {h:.6f}) # 输出 txt 文件文件名与 JSON 同名 out_path Path(out_dir) / (Path(json_path).stem .txt) with open(out_path, w, encodingutf-8) as f: f.write(\n.join(lines)) if __name__ __main__: class_map {text_line: 0, seal: 1, stain: 2} json_dir datasets/annotations txt_dir datasets/labels os.makedirs(txt_dir, exist_okTrue) for json_file in Path(json_dir).glob(*.json): labelme_to_yolo(str(json_file), txt_dir, class_map)脚本的逻辑分三步先读 JSON 里的图像宽高和多边形点再求外接矩形并归一化最后按 YOLO 格式写入 txt。几个参数值得注意class_map必须和后面训练时data.yaml里的类别顺序完全一致坐标裁剪到 [0,1] 区间是为了防止某些标注工具偶尔产生越界点宽度或高度小于 1 像素的框直接丢弃因为这类框在训练时根本不会贡献损失留着反而可能让 loss 崩掉。转换完成后建议随手统计一下每个 txt 的行数如果发现某张图的框数异常偏少多半是 JSON 读取出了问题。2.4 数据增强与划分别把缺样本全押在增强上古籍扫描件有两个天然难题页面明暗不均、纸张纹理干扰多。YOLOv8 自带的 HSV 增强和 Mosaic 已经能覆盖一部分但针对古籍我还建议额外加两种增强亮度对比度抖动和局部高斯模糊。前者模拟不同扫描仪和翻拍设备的效果差异后者模拟页面污损区域对文字行的边缘干扰。数据增强的开源库很多常见做法是把它做成离线增强脚本在训练前把样本量扩到原来的 2 到 3 倍再走正常的训练流程。需要特别记住的一条「血泪经验」是古籍竖排文字行不要做左右翻转。通用目标检测里翻转是标配增强但文字是带方向的左右翻转之后文字行方向反了等于强行把模型往错误方向训练。我见过有同学加了翻转增强后 mAP 涨了几个点结果拿到真实古籍页面上检测框位置全偏到栏线外就是这个原因。如果确实想引入翻转只做小幅度的旋转和裁剪不要做镜像。数据集划分上我习惯按「整页图片」划分而不是按「标注框」划分。同一页扫描件的内容是连贯的如果训练集和验证集里出现同一页的不同区域mAP 会虚高最后换到全新页面上立刻现原形。train / val / test 按 8:1:1 切分即可测试集留出来最后统一评估不要提前参与任何调参决策。这个划分比例对古籍这种样本量几百张的小数据集来说是够用的样本量真的特别少时先把增强力度提上去而不是急着加更多网络结构。3. 训练古籍检测模型环境、参数与训练日志判读3.1 环境搭建CPU 与 GPU 两条路怎么选拿到项目源码后第一件事不是跑训练而是把环境搭好。我接触过不少同学卡在第一步这里按 GPU 和 CPU 两条线分别说。GPU 环境适合有独立显卡的机器GTX 1660 Ti 这类 6G 显存的卡也能跑只要别用大模型就行。# GPU 路线创建 conda 环境并安装 PyTorchCUDA 11.8 版本 conda create -n guji_yolo python3.10 -y conda activate guji_yolo # 安装 PyTorch注意这里安装的是 CUDA 11.8 版本下什么版本看显卡驱动 pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118 # 安装 ultralyticsYOLOv8 的训练、验证、导出都靠这个库 pip install ultralytics # 验证安装是否成功能打印出模型结构说明环境没问题 python -c from ultralytics import YOLO; print(YOLO(yolov8n.pt))CPU 路线就是把 PyTorch 换成本身自带的 CPU 版本pip install torch torchvision不加--index-url即可ultralytics 的安装完全一致。在 Ubuntu 20.04 上搭建 YOLOv8 的 CPU 环境很多同学会遇到libGL.so.1缺失的问题这是 OpenCV 依赖的系统库没装后面避坑章节会专门讲。CPU 环境跑训练确实慢但跑推理和界面演示完全够用做毕设答辩演示不必非得有 GPU。环境搭好后建议顺手固定依赖版本把pip freeze requirements.txt的结果提交到项目里这样换机器部署时能一键还原环境。这是「简单部署即可运行」最容易被忽略的一部分。3.2 数据配置与最小训练命令训练前需要先写一个data.yaml告诉 YOLOv8 训练集、验证集、类别信息放在哪。古籍数据集的项目里一般都有一个datasets/目录里面按 images 和 labels 分开存放结构如下。# data.yaml古籍检测数据集配置 path: ../datasets/guji # 数据集根目录相对于该 yaml 文件所在位置 train: images/train # 训练集图片目录 val: images/val # 验证集图片目录 test: images/test # 测试集图片目录训练时用不到但评估时有用 nc: 3 # 类别总数 names: 0: text_line # 竖排文字行 1: seal # 印章 2: stain # 污损区域写data.yaml最容易翻车的是path用了绝对路径换一台机器就得改一遍。这里建议用相对于 yaml 文件所在位置的相对路径这样整个数据集目录拷到哪里都能直接训。类别顺序必须和 2.3 节转换脚本里的class_map保持一致否则模型学到的和标注对不上训练过程看起来正常但结果完全错乱。训练命令本身很短但参数组合有讲究。我第一次跑古籍数据时用的就是下面这条命令。# 最小可用的训练命令 yolo detect train \ datadatasets/guji/data.yaml \ modelyolov8s.pt \ epochs100 \ imgsz640 \ batch8 \ device0 \ patience20 \ workers2 \ projectruns/train \ nameguji_v1参数含义拆开看modelyolov8s.pt表示在 COCO 预训练权重基础上微调比从头训练收敛快得多epochs100是常规起步值古籍数据量小一般 80 到 120 轮就能收敛imgsz640是 YOLOv8 的默认输入尺寸但如果你的扫描件分辨率很高且文字行偏细建议提到 960patience20表示连续 20 轮验证集指标没提升就早停这个参数能避免周末没看训练导致过拟合白跑workers2是数据加载线程数Windows 上太高容易报错Linux 上可以到 4 到 8。batch主要看显存6G 显存跑s模型用 8 颗没事想稳一点就降到 4。先别急着追求指标我第一次拿到项目源码时习惯先用yolov8n.pt小模型训 20 个 epoch目的是确认数据路径、标注格式、类别数量全部正确。这一步能跑通再换s或m模型跑正式训练能省下大量排查问题的时间。3.3 训练日志怎么读从 loss 到 mAP 的完整链路训练开始后很多同学只看每轮打印的 mAP50这是最常见的误区。mAP 是结果不是原因训练过程中真正需要盯的是 loss 曲线的趋势。YOLOv8 会在runs/train/guji_v1/目录下生成results.csv和results.png里面记录了每一轮的 box_loss、cls_loss、dfl_loss 以及验证集上的 precision、recall、mAP50、mAP50-95。判断模型状态有一套很实用的经验规则如果train/box_loss持续下降而val/box_loss先降后升说明开始过拟合了应该提前停止或加大数据增强如果两个 loss 都降不下去且 mAP 在低位抖动说明模型容量不够或者标注噪声太大这时候换更大的模型不如回头清洗数据。古籍数据的标注质量参差不齐尤其污损区域边界模糊标注不一致导致的 loss 波动很常见不用过度紧张。YOLOv8 自带的results.png已经画好了曲线但如果你想单独画损失函数曲线图放进论文或答辩 PPT可以用下面的脚本自己画。import pandas as pd import matplotlib.pyplot as plt # 读取训练日志YOLOv8 会把每轮的指标写入 results.csv df pd.read_csv(runs/train/guji_v1/results.csv) # 去掉列名首尾空格方便按列名取数 df.columns df.columns.str.strip() plt.figure(figsize(10, 6)) # train_loss 画在左边子图注意 YOLOv8 的列名格式 plt.subplot(1, 2, 1) plt.plot(df[epoch], df[train/box_loss], labeltrain_box_loss) plt.plot(df[epoch], df[val/box_loss], labelval_box_loss) plt.xlabel(epoch) plt.ylabel(loss) plt.legend() plt.title(Box Loss Curve) # mAP 画在右边子图量纲和 loss 不同所以要分开画 plt.subplot(1, 2, 2) plt.plot(df[epoch], df[metrics/mAP50(B)], labelmAP50) plt.plot(df[epoch], df[metrics/mAP50-95(B)], labelmAP50-95) plt.xlabel(epoch) plt.ylabel(mAP) plt.legend() plt.title(mAP Curve) plt.tight_layout() plt.savefig(loss_curve.png, dpi200)画图脚本的逻辑很简单但有两个参数细节值得注意。第一results.csv是逗号分隔且列名包含空格读取后必须 strip 列名否则取数时报 KeyError第二loss 曲线和 mAP 曲线量纲不同不要画在同一个纵轴上否则 loss 的数值变化会被 mAP 的 0 到 1 区间压扁看起来像一条直线。训练结束后best.pt是验证集指标最好的权重last.pt是最后一轮权重调参阶段用 best.pt继续训练则用 last.pt。3.4 模型选择与性能边界n、s、m、l 怎么选YOLOv8 系列从 n 到 x 共有五个规模古籍保护系统完全用不到 x 级别重点在 n、s、m 三个之间选择。选择依据就两条标注框的细腻程度和推理设备的能力。古籍扫描件上的文字行通常是细长形状竖排文字行在 640 × 640 输入下大约只有 10 到 30 像素宽。yolov8n的 backbone 比较浅对这种细条状目标的特征提取能力偏弱容易漏检yolov8m特征表达能力更强但在 CPU 上推理速度会明显下降。我的实际选择建议是数据量在 300 张以下用s数据量充足做最终版用mn只用来验证流程是否跑通。GTX 1660 Ti这类 6G 显存显卡跑s模型训练毫无压力推理速度也是毫秒级不用过度焦虑硬件配置。输入尺寸imgsz对古籍这类小目标的影响比换模型更大。用 640 训练时如果发现文字行漏检率偏高可以把imgsz提到 960 或 1024 重新训练。代价是显存占用和训练时间约翻一倍但古籍文字行的检测效果提升非常明显。这一步可以配合 YOLOv8 的网络结构图去理解小目标在浅层特征图上的信息更丰富输入图越大浅层的特征保留越完整检测头越容易捕捉到细长目标。4. 把模型封装成可视化界面推理逻辑与 PySide6 实现4.1 可视化界面功能拆解先想清楚用户操作什么古籍保护系统的可视化界面不只是「显示一张图画几个框」那么简单。站在使用者的角度打开界面后需要完成这些操作加载训练好的模型权重、选择单张图片或一个文件夹、执行检测、调节置信度阈值过滤误检、查看检测结果并导出。导出的内容又分为带标注框的图片和结构化的坐标数据后者会对接后续的 OCR 识别和档案录入。功能拆解做得越细界面代码越不容易返工。我把界面拆成三个区域左侧是控制面板包含模型选择、图片选择、置信度滑块、检测按钮中间是图像显示区实时渲染检测框和标签底部是日志栏显示当前识别的图片路径、检测到的目标数量、每类目标的分布。这个布局对汉字竖排的检测结果展示很友好左侧参数调整后中间画面立刻刷新答辩演示的观感也好。4.2 推理模块单图预测与批量预测的差异推理模块是界面和模型之间的桥梁建议单独抽成一个 Python 文件UI 层只负责调用不要在控件事件里直接写模型代码。这样以后换模型、换推理框架都不需要改动界面。# inference.py封装 YOLOv8 推理逻辑 from ultralytics import YOLO class GujiDetector: def __init__(self, weights_path: str, device: str 0): weights_path: 训练得到的 best.pt 路径 device: 0 表示第一个 GPUCPU 环境传 cpu self.model YOLO(weights_path) self.device device def predict(self, image_path: str, conf: float 0.25, imgsz: int 640): 对单张图片执行检测返回标准化后的结果 results self.model.predict( sourceimage_path, confconf, imgszimgsz, deviceself.device, verboseFalse, ) # results[0] 是单张图片的检测结果boxes 里包含所有目标框 boxes results[0].boxes detections [] for box in boxes: x1, y1, x2, y2 box.xyxy[0].tolist() # 框的绝对坐标 conf_val float(box.conf[0]) cls_id int(box.cls[0]) detections.append({ bbox: [x1, y1, x2, y2], confidence: conf_val, class_id: cls_id, }) return detections这个模块里有几个关键选择。verboseFalse必须加上否则每次推理都会往控制台刷一条日志界面跑久了会显著卡顿。box.xyxy返回的是像素绝对坐标不是归一化坐标在界面上画框时直接用方便得很。批量预测不需要自己写循环ultralytics 的predict支持source传文件夹路径它会自动遍历目录下所有图片但返回的results是一个列表遍历时要按图片顺序对应起来这个细节在界面里尤其容易踩坑。我习惯在predict方法里只处理单张图片批量逻辑放在 UI 层用循环驱动这样单条进度能实时反馈到界面底部的日志栏。4.3 核心问题把推理放进子线程界面才不卡死可视化界面最典型的翻车现场是点击「开始检测」按钮后整个窗口白屏无响应鼠标转圈几秒钟后系统提示「程序未响应」。原因几乎可以锁定——推理跑在了 UI 主线程里。YOLOv8 的推理虽然只有几百毫秒但在主线程里执行期间Qt 的事件循环被阻塞窗口自然就冻结了。解决办法是把推理放到 QThread 子线程完成后通过信号把结果传回主线程更新界面。# worker.py在子线程中执行推理避免界面卡死 from PySide6.QtCore import QThread, Signal class DetectWorker(QThread): # 定义两个信号finished 传检测结果error 传错误信息 finished Signal(list) error Signal(str) def __init__(self, detector, image_path: str, conf: float): super().__init__() self.detector detector self.image_path image_path self.conf conf def run(self): # run 方法在子线程中执行不会阻塞主线程的界面刷新 try: detections self.detector.predict(self.image_path, confself.conf) self.finished.emit(detections) except Exception as e: self.error.emit(str(e))对应的主窗口里按钮点击事件只做三件事创建 Worker、连接信号、启动线程。不要在按钮回调里写任何模型推理代码。# main_window.py主窗口核心代码节选 from PySide6.QtWidgets import QMainWindow, QPushButton, QSlider, QLabel, QFileDialog from PySide6.QtCore import Qt class MainWindow(QMainWindow): def __init__(self, detector): super().__init__() self.detector detector self.worker None # 保存 worker 引用防止被垃圾回收 self.btn_detect QPushButton(开始检测, self) self.btn_detect.clicked.connect(self.on_detect) self.slider_conf QSlider(Qt.Horizontal, self) self.slider_conf.setRange(5, 95) # 置信度阈值 5% ~ 95% self.slider_conf.setValue(25) # 默认 25% def on_detect(self): # 选择图片然后启动子线程 path, _ QFileDialog.getOpenFileName(self, 选择古籍扫描件, , Images (*.png *.jpg *.jpeg)) if not path: return # 清空上一次的 worker避免重复点击时线程冲突 if self.worker is not None and self.worker.isRunning(): return conf self.slider_conf.value() / 100.0 self.worker DetectWorker(self.detector, path, conf) self.worker.finished.connect(self.on_detect_finished) self.worker.error.connect(self.on_detect_error) self.worker.start() # start 之后 run 方法在子线程中执行 def on_detect_finished(self, detections): # 主线程中收到结果此时可以安全地更新界面 self.draw_boxes(detections) def on_detect_error(self, message): print(f检测出错: {message})信号槽机制是 PySide6 让界面不卡死的关键子线程算完结果通过finished信号发回主线程主线程在事件循环里收到信号后才去更新界面。两个参数细节值得注意self.worker必须作为实例属性保存否则 Python 的垃圾回收会在函数返回后把 worker 销毁导致线程异常终止滑块的值是整数除以 100 转成浮点数后才能作为置信度阈值传给模型。这套线程模型同样适用于批量检测时逐张展示进度条的场景。4.4 从界面到系统目录规划与源码组织一个能交付的毕设项目源码组织比模型本身更能决定答辩效果。古籍保护系统的项目结构我建议按下面的方式组织训练代码、推理代码、界面代码、数据配置互不干扰。guji_protect/ ├── README.md # 部署教程环境安装 启动命令 ├── requirements.txt # 依赖清单一键安装 ├── data.yaml # 数据配置 ├── datasets/ │ ├── images/ # 古籍扫描件 │ └── labels/ # YOLO 格式标注 ├── weights/ │ └── best.pt # 训练好的模型权重 ├── scripts/ │ ├── convert_json_to_yolo.py │ ├── train.py │ └── eval.py ├── ui/ │ ├── main_window.py │ └── worker.py ├── inference.py # 推理模块封装 └── app.py # 程序入口双击运行README.md里部署教程的写法要遵循一个「陌生机器验证」原则在另一台干净电脑上照着 README 从头执行一遍命令能跑通才算数。我见过很多项目的 README 是答辩前两小时赶出来的漏掉了libGL.so.1这种系统依赖最后只能在评委面前翻车。requirements.txt里建议把ultralytics、torch、PySide6、pandas、matplotlib这几个核心包列全版本号可以不用锁死但 Python 版本最好在 README 里标明。5. 部署与跑通避坑清单环境、数据、界面三类常见问题5.1 环境与依赖的坑现象pip install ultralytics之后运行程序报错ImportError: libGL.so.1: cannot open shared object file。原因ultralytics 会依赖 OpenCV而 OpenCV 在 Linux 上需要系统的libgl1库。很多新装的 Ubuntu 20.04 系统没有预装这个库Python 层面装再多包也解决不了。解决在终端执行sudo apt-get update sudo apt-get install -y libgl1 libglib2.0-0装完再运行程序就正常了。如果这台机器连编译工具都没有顺手把build-essential也装上避免后续装其他包时再踩一遍。现象CPU 环境下运行界面点击检测后转圈三五秒才出结果答辩演示体验很差。原因CPU 推理本身就慢如果还用yolov8m或yolov8l模型加上没有做任何推理优化单张图 3 到 5 秒是常态。解决答辩演示换yolov8s甚至yolov8n权重imgsz降到 480延迟能压到 1 秒以内。也可以把模型导出成 ONNX 格式用 ONNX Runtime 跑推理CPU 上提速非常明显这个后面章节会讲。5.2 训练与数据集格式的坑现象训练刚跑几个 step 就报CUDA out of memory把batch从 8 降到 2 还是崩。原因imgsz设得太大或者模型用了m级别以上显存占用超出显卡容量。6G 显存跑yolov8m加imgsz960崩是很正常的不是代码问题。解决先按「s模型 imgsz640batch4」跑通整个流程确认数据没问题后再逐步加大。另外 YOLOv8 默认开启 Mosaic 增强Mosaic 会把 4 张图拼在一起显存占用大概是普通训练的 2 倍batch调小是合理的应对手段。现象训练正常结束mAP50 看着还行但拿到完整古籍扫描页面上检测文字行大量漏检只检出一些碎片。原因训练时输入图片是 640 × 640 的缩放图完整扫描件缩到 640 后竖排文字行的宽度只剩几个像素模型特征提取阶段就把这些小目标过滤掉了。解决一是训练时把imgsz提到 960 甚至 1024二是做滑窗推理把完整扫描页切成 640 × 640 的重叠块分别检测再合并结果。后者更稳定但对界面代码要求高一些适合作为进阶优化。现象新增了一个类别重新训练后所有旧类别的框都识别成新类别或者预测结果类别错乱。原因data.yaml里类别顺序改了但标注文件的 label id 没同步改模型输出层的类别映射和实际标注对不上。还有一种情况是旧标注缓存没有清掉YOLOv8 用.cache文件缓存标注信息改了标注后缓存还在用旧数据。解决以data.yaml的names顺序为唯一标准重跑一遍 JSON 转 YOLO 脚本生成新的 txt同时删除数据集目录下所有.cache文件再训练。这条坑排查起来非常隐蔽我花了半天才定位到缓存上。5.3 界面与推理的坑现象点击「开始检测」后窗口立刻白了不停转圈过几秒弹出「未响应」。原因推理直接写在按钮点击事件里跑在了 Qt 主线程上阻塞了界面事件循环。模型推理时间越长白屏时间越久。解决按第 4 章的做法把推理逻辑拆到QThread子线程中通过信号把结果回传主线程。如果项目用了 Flask 或 FastAPI 做 Web 界面则对应地使用异步任务队列思路是一样的。现象程序在 Windows 上能跑拷到 Linux 上打开图片时报错提示图片路径不存在。原因项目中写死了 Windows 的路径分隔符\或者图片路径里带中文Ultralytics 与 OpenCV 在部分 Linux 环境下对非 ASCII 路径处理不稳定。解决项目所有路径统一用pathlib.Path拼接迁移到 Linux 后自动适配/分隔符训练数据和项目整体约定用英文目录避免中文路径带来的未知问题。在程序入口处打印当前工作目录排查路径问题时能省一半时间。6. 交付前最后一步验证指标、ONNX 导出与 OCR 联动扩展6.1 验证指标检查清单训练完不是直接交差先用测试集做一轮完整验证再谈部署。测试集是训练阶段完全没见过的图片在这上面跑的指标才有说服力。我习惯对照下面这张表逐项检查缺一项就回去补。检查项工具通过标准逐类 APyolo detect val或脚本读取 val 结果每个类别的 AP50 都高于 80% 视为及格置信度阈值选择PR 曲线或 F1-confidence 曲线在 F1 最高点附近取阈值不要直接用默认 0.25小目标漏检在测试集上可视化预测结果竖排文字行连续完整无断行漏检误检查看标注框与预测框的 IoU 分布印章误检成文字行、栏线误检成文字行的比例需低于 5%6.2 导出 ONNX 与 OCR 联动部署到没有 GPU 的机器时把模型导出成 ONNX 格式是性价比最高的加速手段。Ultralytics 自带导出功能一条命令就能搞定。# 导出 ONNX 格式模型opset 12 兼容性好 yolo export modelweights/best.pt formatonnx imgsz640 opset12导出后的.onnx文件可以用 ONNX Runtime 加载CPU 上推理速度比原生 PyTorch 快不少而且完全不依赖 PyTorch 环境部署时少装一堆依赖。古籍保护系统的最终价值在识别而不只是检测。检测框拿到之后把每个文字行区域裁剪下来交给开源 OCR 引擎识别成文本再连同坐标一起写入 JSON 或 CSV就形成了完整的古籍数字化档案。这一步做进系统里毕设的功能深度立刻拉开差距。我自己交付这类项目前有个固定习惯找一台没装过任何 Python 包的干净机器照着 README 从零执行一遍部署教程全部命令复制粘贴能跑通才敢说「简单部署即可运行」。这套系统的价值不在于模型结构多先进而在于把数据标注、训练、界面、部署整条链路完整走通了一次往里再补 YOLOv8 结构改进或小目标检测头也都是顺手的事。希望帮到你。本文还有配套的精品资源点击获取
