尧图网页设计 
简介面向计算机相关专业在校学生与毕业设计开发者这套基于YOLOv8的古籍保护系统是一份可直接运行的一站式项目资料包。资源涵盖完整源码、训练数据集、可视化操作界面及部署说明支持产出精确率-召回率曲线、混淆矩阵、F1分数曲线等核心评估结果功能完善、操作简单适合快速搭建毕设演示或课程设计原型。压缩包共97个文件以Python代码为主70个py文件另含模型权重pt、配置xml、文本说明及一个mp4演示视频整体约24.21MB结构清晰便于按需查阅。当前已有57人学习下载。使用者可依据README指引完成环境配置与推理借助可视化界面进行古籍检测还可参考训练脚本与best.pt权重复现模型效果并有视频演示辅助理解对答辩评审或实践学习均有较高参考价值。1. 古籍保护为什么值得用 YOLOv8从虫蛀检测到毕设落地的完整闭环古籍保护里最耗人力的环节是把馆藏古籍一页页翻出来检查虫蛀、霉变、水渍和破损。这些损伤往往面积小、对比度低人眼盯久了容易漏不同馆员对同一处损伤的判定标准也不一致。基于YOLOv8的古籍保护系统核心思路就是把“人工翻页盯损伤”变成“让模型框出损伤类别”用YOLOv8在带标注的古籍图像数据集上训练一个检测模型再配套可视化界面用来传图、调阈值、看结果并保存。压缩包里包含源码、完整数据集和部署教程环境配好后简单改几个路径就能运行。这套方案兼顾了算法深度与工程完整度适合做毕设或课程设计也很适合作为文物保护数字化入门的一次最小落地。2. 拆解 YOLOv8 古籍保护系统架构损伤类别、选型理由与工程目录古籍保护系统不是一个大而全的平台常见做法是把核心功能拆成三块模型训练、推理检测、界面展示。模型训练负责从带标注的古籍图像数据集中学习出各类损伤的位置和类别推理检测加载训练好的权重对单张图片、批量目录或摄像头画面输出带置信度的检测框界面展示则把检测结果可视化出来允许你调整置信度阈值、保存结果。三块各司其职替换任何一块都不影响另外两块比在一大坨脚本里来回改参数要省心得多。2.1 古籍损伤检测要识别哪些类别虫蛀、霉变、水渍、破损的视觉特征与难点一套能用于古籍保护的可复现方案标注类别和视觉特征设计先要想清楚。以常见做法为例最常出现的四类损伤是虫蛀、霉变、水渍和破损。虫蛀孔洞边缘清晰但尺度极小很多孔洞直径只有几十像素霉变区域颜色偏暗、边界模糊和纸张泛黄区域极易混在一起水渍通常是大面积、低对比度的色块与霉变的视觉特征在灰度图里几乎分不开破损在尺度上的差异最大小的裂口十几像素大的残缺可能占页面三分之一。这些特点对目标检测模型提出了两个硬要求第一是小目标敏感性第二是类间区分能力。如果仅仅做一个分类模型你只能知道“这张古籍页面有没有问题”却不知道“问题在哪里、属于哪一类损伤”。而YOLOv8这类目标检测模型输出的框和类别能让后续工作人员直接按区域核对。所以检测任务才成为这个系统的核心而不是简单套个图像分类网络。数据集标注环节在这里决定了整体上限。标注时我习惯只看两件事图像清晰度和边界约定。图像分辨率太低虫蛀孔在缩略图里根本看不见边界约定不统一同一个人标注的框大小也会前后不一致。比较稳妥的约定是损伤区域按外接矩形标注不刻意包住整片墨迹避免把前景和背景混在一起带进训练样本。如果你拿到的数据集标注里混着斜框或多边形还得先转成外接矩形框再进入格式转换流程。2.2 为什么是 YOLOv8 而不是 YOLOv5 或 RT-DETR小数据集、部署成本与生态的取舍选型这一步直接决定你后面训练和部署的顺畅程度。古籍保护系统往往不具备海量数据几百到两三千张带标注古籍图像才是常态。这个规模下候选模型其实只有YOLO系列和部分轻量检测器RT-DETR这类基于Transformer的检测器虽然精度天花板高但需要更大数据量来拟合小样本下反而容易欠拟合。YOLOv8和YOLOv5的取舍更能说明问题。YOLOv5的anchor-based机制需要针对数据集预设anchor超参数古籍损伤这种长宽比变化很大的场景默认anchor不一定匹配YOLOv8改成anchor-free之后少了这一层人工调参训练时通过任务对齐学习自动匹配正负样本对长宽比不规则的虫蛀孔、条状裂口更友好。另一个现实因素是生态Ultralytics官方库把训练、验证、导出、推理做成了一致的命令行和Python接口部署到PC或边缘设备都有成熟的转换路径这对一个要把Demo真正跑起来的系统很关键。对比维度YOLOv5YOLOv8RT-DETRanchor机制anchor-based需预设anchor-free无anchor小样本表现尚可良好自带预训练权重易欠拟合接口统一性分支多、版本杂官方库接口统一依赖第三方实现部署导出路径广泛但碎片化ONNX/TensorRT/RKNN全转换链略长从毕设或课程设计的角度看统一接口带来的好处是训练时报错能搜到大量现成答案导出成ONNX再转别的格式也有官方支持。即便你后面想做边缘端部署比如把模型装到RK3588这类带NPU的板卡上也能找到对应的导出适配不需要自己写转换工具。2.3 压缩包里的工程目录怎么用源码、数据集、模型与界面如何串起来拿到压缩包后第一件事不是跑代码而是看目录结构。一个合理的古籍保护工程包至少包含四块数据集目录、训练脚本、已训练模型、可视化界面。我一般先确认datasets下有没有标注文件再看models下有没有best.pt。如果有现成权重部署阶段完全不用重新训练直接跑推理即可。ancient_book_protection/ ├── datasets/ │ ├── ancient_book/ │ │ ├── images/train/ # 训练图像 │ │ ├── images/val/ # 验证图像 │ │ ├── labels/train/ # 训练标签txt │ │ └── labels/val/ # 验证标签txt │ └── ancient_book.yaml # 数据配置 ├── models/ │ └── best.pt # 训练好的权重 ├── src/ │ ├── train.py # 训练入口 │ ├── predict.py # 命令行推理 │ ├── voc2yolo.py # 标注格式转换 │ └── ui/ │ └── main_window.py # PyQt5 可视化界面 ├── requirements.txt └── README.md这一步最常见的坑是路径写死。很多压缩包里用的绝对路径是在作者机器上生成的解压到你的机器后路径不同会导致数据集载入失败。最稳妥的做法是解压后保持目录结构不变把工程包整体放到一个纯英文路径下跑之前打开ancient_book.yaml确认path字段和实际目录一致。跑通最小流程只需要两步先安装依赖再启动界面。如果models/best.pt存在训练步骤可以跳过pip install -r requirements.txt python src/ui/main_window.py安装依赖建议用虚拟环境不要直接装到系统Python里否则很容易和已有库冲突。界面启动后选择一张古籍页面图片模型会返回检测框、类别和置信度。整个工程的三块逻辑关系是数据集喂给训练脚本训练脚本产出权重权重和可视化界面共同组成推理程序。这个数据流不复杂但每一步都可能因为环境和格式问题卡住后面两章会对应展开。3. 用数据集训练 YOLOv8 古籍损伤检测模型标注转换、训练参数与损失曲线训练阶段决定了系统检测效果的上限。很多人在拿到压缩包后急着点“训练”结果损失曲线一路乱跳mAP低得没法看。问题往往不是模型不行而是数据没喂对。把数据集从原始标注整理成YOLOv8能吃的格式再按古籍损伤的小目标特性调整训练参数这一步值得多花时间。3.1 把 VOC 标注转成 YOLO 的 txt 格式转换脚本与类别映射古籍数据集的原始标注常见有两种格式VOC的XML和COCO的JSON。YOLOv8训练只认txt格式每张图片对应一个同名txt文件每行是一组目标信息格式为“类别索引 中心点x 中心点y 框宽 框高”坐标全部归一化到0到1之间。如果你拿到的数据集里是VOC标注第一步要做的就是把XML转成txt。import xml.etree.ElementTree as ET import os voc_dir datasets/annotations # 存放原始 xml 的目录 yolo_dir datasets/labels # 转换后 txt 输出目录 os.makedirs(yolo_dir, exist_okTrue) class_map { wormhole: 0, # 虫蛀 mildew: 1, # 霉变 stain: 2, # 水渍 damage: 3 # 破损 } def convert_one(xml_path): tree ET.parse(xml_path) root tree.getroot() img_w int(root.find(size/width).text) img_h int(root.find(size/height).text) out_name os.path.basename(xml_path).replace(.xml, .txt) with open(os.path.join(yolo_dir, out_name), w) as f: for obj in root.iter(object): cls obj.find(name).text.lower().strip() if cls not in class_map: continue bbox obj.find(bndbox) xmin float(bbox.find(xmin).text) ymin float(bbox.find(ymin).text) xmax float(bbox.find(xmax).text) ymax float(bbox.find(ymax).text) cx (xmin xmax) / 2 / img_w cy (ymin ymax) / 2 / img_h w (xmax - xmin) / img_w h (ymax - ymin) / img_h f.write(f{class_map[cls]} {cx:.6f} {cy:.6f} {w:.6f} {h:.6f}\n) for xml_file in os.listdir(voc_dir): if xml_file.endswith(.xml): convert_one(os.path.join(voc_dir, xml_file))这段脚本的逻辑很简单从XML里读出图像宽高和目标框的左上角、右下角坐标把绝对坐标换算成归一化的中心点坐标与宽高。转换完一定要检查txt文件的行数和XML里的object数量是否一致。常见翻车点是XML里存在size字段缺失的图片这种图片建议直接剔掉不要让它影响训练。另外类别名的匹配我用了lower().strip()是因为不同标注工具保存的类名大小写不一致这一步能避免“Wormhole”和“wormhole”被当成两个类别。3.2 yolov8 训练命令与关键参数epoch、batch、imgsz 怎么设才不翻车训练前先准备数据配置文件。YOLOv8用YAML描述数据集路径和类别列表古籍保护系统的配置文件大致长这样# ancient_book.yaml path: datasets/ancient_book # 数据集的根目录 train: images/train val: images/val nc: 4 names: [wormhole, mildew, stain, damage]注意path字段建议写相对路径目录层级要和你解压后的工程结构一致。nc必须和names的长度一致哪怕少一个类别都会导致训练时索引越界。配置好后训练命令如下yolo detect train datadatasets/ancient_book.yaml \ modelyolov8n.pt \ epochs100 \ imgsz640 \ batch16 \ device0 \ projectruns/detect \ nameancient_book这是最省心的起步配置。yolov8n.pt是官方预训练权重显存占用小GTX 1660 Ti这类6G显存的卡也能跑batch16在6G显存下通常够用如果报OOM就降到8但要记住batch减半后学习率最好也跟着降一点比如从0.01降到0.005否则收敛会不稳定。更关键的是imgsz这个参数。古籍扫描件通常分辨率很高虫蛀孔在640×640下可能只有十几个像素直接训练会让小目标漏检严重。我的习惯是显存够就上imgsz1024甚至imgsz1280小目标mAP提升非常明显显存不足则保持640同时依赖mosaic数据增强来增加小目标参与训练的机会。代价是训练时间变长一个100epoch的流程在单卡上可能要跑十几个小时要有心理预期。3.3 训练中盯着什么看损失函数曲线、mAP 指标与过拟合识别训练启动后Ultralytics会在runs/detect/ancient_book/下生成results.csv和results.png这两个文件是判断训练状态的主要依据。很多人只看mAP其实损失曲线更能反映问题。train/box_loss和val/box_loss两条曲线会随着epoch下降并逐渐靠近如果训练后期val/box_loss掉头往上走而train/box_loss还在降那就是过拟合的信号。用脚本把损失曲线画出来会更直观尤其适合放进毕设答辩材料import pandas as pd import matplotlib.pyplot as plt df pd.read_csv(runs/detect/ancient_book/results.csv) # 列名可能带空格读出来之后先做一次 strip df.columns [c.strip() for c in df.columns] plt.plot(df[train/box_loss], labeltrain box_loss) plt.plot(df[val/box_loss], labelval box_loss) plt.xlabel(epoch) plt.ylabel(loss) plt.legend() plt.title(box_loss curve) plt.show()曲线发散时先检查是不是学习率太大数据量本身就少的话可以把epochs减到50到80配合早停策略避免无效训练。另一个重要指标是metrics/mAP50(B)古籍保护这类任务里mAP50比mAP50-95更贴近实际使用感受因为损伤检测不需要像素级精确框能落在损伤区域内就算可用。训练结束后best.pt会根据验证集mAP自动保存推理阶段直接加载它就行。4. 古籍保护系统部署常见问题排查环境、数据与界面的三层踩坑记录训练跑通只是开始部署阶段才是劝退大多数人的地方。我把踩过的坑按环境、数据、界面三层拆开每一条都按“现象、原因、解决”写清楚。你在复现时如果卡住直接对着找。4.1 环境配置阶段PyTorch、CUDA 与 OpenCV 版本冲突现象按 requirements.txt 装完依赖后运行界面脚本直接报错要么是torch.cuda.is_available()返回False要么是cv2.error: Assertion failed之后进程退出。原因两个常见情况。其一pip默认装的是CPU版PyTorch根本用不了GPU其二环境里同时存在opencv-python和opencv-contrib-python两个包的部分文件互相覆盖导致cv2模块残缺。解决用虚拟环境重装先装PyTorch再装其它依赖conda create -n ancient_book python3.10 -y conda activate ancient_book pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118 pip install ultralytics pyqt5 opencv-python--index-url指定的是PyTorch官方CUDA 11.8版whl仓库装完用python -c import torch; print(torch.cuda.is_available())验证。OpenCV只装一个opencv-python就够了不要两个一起装。如果还需要图像处理的高级功能用opencv-contrib-python替代别混着装。4.2 数据与训练阶段空标签、类别错位与小目标漏检现象训练日志出现大量WARNING: images without labels或者训练完成后mAP为0检测结果完全不对。原因标签文件为空或者标签里的类别索引和YAML的names顺序对不上。比如VOC转换脚本里类名写错了一个导致某类目标全被跳过又或者某个标注工具从0开始编号而你配置文件里默认类别0是背景整体错位一位。解决训练前先扫一遍标签文件确认每张训练图都有对应标签import os label_dir datasets/ancient_book/labels/val for fn in os.listdir(label_dir): with open(os.path.join(label_dir, fn)) as f: lines f.read().strip().splitlines() if len(lines) 0: print(f{fn}: EMPTY) continue classes {int(line.split()[0]) for line in lines} if not classes.issubset({0, 1, 2, 3}): print(f{fn}: BAD class index {classes})这个小脚本能快速定位空标签和非法类别索引。小目标漏检的问题我在前面提过优先把imgsz调大。如果显存不够还可以关掉mosaic增强的末尾epoch避免小目标在拼接过程中被裁掉。4.3 可视化界面阶段PyQt5 卡死、路径读取失败与置信度阈值问题现象点击界面上的“开始检测”按钮后整个窗口白屏无响应过几秒甚至弹出“程序未响应”或者选择图片时路径带中文就直接读不出来。原因模型推理被放在了主线程里。YOLOv8推理一张高分辨率古籍扫描图可能要几秒甚至十几秒期间Qt事件循环被阻塞界面就表现为卡死。中文路径的问题是OpenCV的imread在Windows下默认不支持非ASCII路径它会直接返回None。解决推理放到后台线程用信号把结果传回主线程更新界面from PyQt5.QtCore import QThread, pyqtSignal from ultralytics import YOLO class DetectThread(QThread): result_ready pyqtSignal(object) # 信号传回检测结果 def __init__(self, model_path, image_path): super().__init__() self.model YOLO(model_path) self.image_path image_path def run(self): results self.model.predict( sourceself.image_path, conf0.25, iou0.45 ) self.result_ready.emit(results[0])主界面实例化这个线程连接result_ready信号到更新函数。这样推理在后台跑界面可以继续响应拖拽、缩放等操作。中文路径的解决也很简单绕过cv2.imread改用np.fromfile加cv2.imdecodeimport numpy as np import cv2 def imread_unicode(path): data np.fromfile(path, dtypenp.uint8) return cv2.imdecode(data, cv2.IMREAD_COLOR)置信度阈值的问题更多是使用层面。古籍损伤对比度低模型输出的置信度普遍不高界面上我建议把conf阈值做成滑杆默认0.25太低会有大量误检太高又会漏掉真实损伤。调阈值时要结合具体的扫描分辨率来试不要一上来追求高置信度。5. 让古籍保护系统更接近实用的进阶技巧模型导出、阈值后处理与大图切片系统能跑通之后接下来要做的是让它真正可用。古籍扫描件不是手机拍的照片动辄几千乘几千像素直接塞给YOLOv8推理有两个问题一是耗时太长二是下采样后小目标细节丢失。我的处理习惯是加一道切片推理逻辑。把大图按640像素大小切块相邻块之间保留128像素重叠避免损伤刚好落在切片边界上。每个切片独立推理再把检测框坐标映射回原图。重叠区域里同一个损伤可能被检出两次用置信度高的框保留、低的丢弃来去重。用低阈值推理比如0.1配合重叠去重比单张大图高阈值推理的漏检率低很多。如果想要更好的性能可以导出ONNX格式再推理。Ultralytics一句命令就能完成yolo export modelmodels/best.pt formatonnx opset12 simplifyTrue精度损失很小CPU上比PyTorch原版快不少也方便后续转成TensorRT或者RKNN部署到RK3588这类板子上。对课程设计来说导出ONNX在答辩现场也能成为一个加分项的演示点。最后把检测结果落成结构化记录。古籍保护系统如果只是弹窗展示结果实际价值有限把每次检测的类别、置信度、坐标和图片文件名写入CSV后续统计哪一类损伤占比高、哪一页需要重点修复就有了数据支撑。import csv csv_file open(detect_results.csv, w, newline, encodingutf-8) writer csv.writer(csv_file) writer.writerow([image, class, confidence, x1, y1, x2, y2]) for result in results: for box in result.boxes: cls_id int(box.cls[0]) conf float(box.conf[0]) x1, y1, x2, y2 [round(float(v), 1) for v in box.xyxy[0]] writer.writerow([result.path, class_names[cls_id], conf, x1, y1, x2, y2]) csv_file.close()我在做这类项目时有个习惯所有路径统一用相对路径所有类名统一小写所有阈值参数集中放在配置文件里而不是散落在代码各处。这样换机器、换数据集、换模型时动的只是配置文件代码一行都不用改。这些看似不起眼的习惯往往决定了方案能不能顺利复现。希望帮到你。本文还有配套的精品资源点击获取 YOLOv8助力古籍保护：损伤检测、模型训练与部署全解
简介面向计算机相关专业在校学生与毕业设计开发者这套基于YOLOv8的古籍保护系统是一份可直接运行的一站式项目资料包。资源涵盖完整源码、训练数据集、可视化操作界面及部署说明支持产出精确率-召回率曲线、混淆矩阵、F1分数曲线等核心评估结果功能完善、操作简单适合快速搭建毕设演示或课程设计原型。压缩包共97个文件以Python代码为主70个py文件另含模型权重pt、配置xml、文本说明及一个mp4演示视频整体约24.21MB结构清晰便于按需查阅。当前已有57人学习下载。使用者可依据README指引完成环境配置与推理借助可视化界面进行古籍检测还可参考训练脚本与best.pt权重复现模型效果并有视频演示辅助理解对答辩评审或实践学习均有较高参考价值。1. 古籍保护为什么值得用 YOLOv8从虫蛀检测到毕设落地的完整闭环古籍保护里最耗人力的环节是把馆藏古籍一页页翻出来检查虫蛀、霉变、水渍和破损。这些损伤往往面积小、对比度低人眼盯久了容易漏不同馆员对同一处损伤的判定标准也不一致。基于YOLOv8的古籍保护系统核心思路就是把“人工翻页盯损伤”变成“让模型框出损伤类别”用YOLOv8在带标注的古籍图像数据集上训练一个检测模型再配套可视化界面用来传图、调阈值、看结果并保存。压缩包里包含源码、完整数据集和部署教程环境配好后简单改几个路径就能运行。这套方案兼顾了算法深度与工程完整度适合做毕设或课程设计也很适合作为文物保护数字化入门的一次最小落地。2. 拆解 YOLOv8 古籍保护系统架构损伤类别、选型理由与工程目录古籍保护系统不是一个大而全的平台常见做法是把核心功能拆成三块模型训练、推理检测、界面展示。模型训练负责从带标注的古籍图像数据集中学习出各类损伤的位置和类别推理检测加载训练好的权重对单张图片、批量目录或摄像头画面输出带置信度的检测框界面展示则把检测结果可视化出来允许你调整置信度阈值、保存结果。三块各司其职替换任何一块都不影响另外两块比在一大坨脚本里来回改参数要省心得多。2.1 古籍损伤检测要识别哪些类别虫蛀、霉变、水渍、破损的视觉特征与难点一套能用于古籍保护的可复现方案标注类别和视觉特征设计先要想清楚。以常见做法为例最常出现的四类损伤是虫蛀、霉变、水渍和破损。虫蛀孔洞边缘清晰但尺度极小很多孔洞直径只有几十像素霉变区域颜色偏暗、边界模糊和纸张泛黄区域极易混在一起水渍通常是大面积、低对比度的色块与霉变的视觉特征在灰度图里几乎分不开破损在尺度上的差异最大小的裂口十几像素大的残缺可能占页面三分之一。这些特点对目标检测模型提出了两个硬要求第一是小目标敏感性第二是类间区分能力。如果仅仅做一个分类模型你只能知道“这张古籍页面有没有问题”却不知道“问题在哪里、属于哪一类损伤”。而YOLOv8这类目标检测模型输出的框和类别能让后续工作人员直接按区域核对。所以检测任务才成为这个系统的核心而不是简单套个图像分类网络。数据集标注环节在这里决定了整体上限。标注时我习惯只看两件事图像清晰度和边界约定。图像分辨率太低虫蛀孔在缩略图里根本看不见边界约定不统一同一个人标注的框大小也会前后不一致。比较稳妥的约定是损伤区域按外接矩形标注不刻意包住整片墨迹避免把前景和背景混在一起带进训练样本。如果你拿到的数据集标注里混着斜框或多边形还得先转成外接矩形框再进入格式转换流程。2.2 为什么是 YOLOv8 而不是 YOLOv5 或 RT-DETR小数据集、部署成本与生态的取舍选型这一步直接决定你后面训练和部署的顺畅程度。古籍保护系统往往不具备海量数据几百到两三千张带标注古籍图像才是常态。这个规模下候选模型其实只有YOLO系列和部分轻量检测器RT-DETR这类基于Transformer的检测器虽然精度天花板高但需要更大数据量来拟合小样本下反而容易欠拟合。YOLOv8和YOLOv5的取舍更能说明问题。YOLOv5的anchor-based机制需要针对数据集预设anchor超参数古籍损伤这种长宽比变化很大的场景默认anchor不一定匹配YOLOv8改成anchor-free之后少了这一层人工调参训练时通过任务对齐学习自动匹配正负样本对长宽比不规则的虫蛀孔、条状裂口更友好。另一个现实因素是生态Ultralytics官方库把训练、验证、导出、推理做成了一致的命令行和Python接口部署到PC或边缘设备都有成熟的转换路径这对一个要把Demo真正跑起来的系统很关键。对比维度YOLOv5YOLOv8RT-DETRanchor机制anchor-based需预设anchor-free无anchor小样本表现尚可良好自带预训练权重易欠拟合接口统一性分支多、版本杂官方库接口统一依赖第三方实现部署导出路径广泛但碎片化ONNX/TensorRT/RKNN全转换链略长从毕设或课程设计的角度看统一接口带来的好处是训练时报错能搜到大量现成答案导出成ONNX再转别的格式也有官方支持。即便你后面想做边缘端部署比如把模型装到RK3588这类带NPU的板卡上也能找到对应的导出适配不需要自己写转换工具。2.3 压缩包里的工程目录怎么用源码、数据集、模型与界面如何串起来拿到压缩包后第一件事不是跑代码而是看目录结构。一个合理的古籍保护工程包至少包含四块数据集目录、训练脚本、已训练模型、可视化界面。我一般先确认datasets下有没有标注文件再看models下有没有best.pt。如果有现成权重部署阶段完全不用重新训练直接跑推理即可。ancient_book_protection/ ├── datasets/ │ ├── ancient_book/ │ │ ├── images/train/ # 训练图像 │ │ ├── images/val/ # 验证图像 │ │ ├── labels/train/ # 训练标签txt │ │ └── labels/val/ # 验证标签txt │ └── ancient_book.yaml # 数据配置 ├── models/ │ └── best.pt # 训练好的权重 ├── src/ │ ├── train.py # 训练入口 │ ├── predict.py # 命令行推理 │ ├── voc2yolo.py # 标注格式转换 │ └── ui/ │ └── main_window.py # PyQt5 可视化界面 ├── requirements.txt └── README.md这一步最常见的坑是路径写死。很多压缩包里用的绝对路径是在作者机器上生成的解压到你的机器后路径不同会导致数据集载入失败。最稳妥的做法是解压后保持目录结构不变把工程包整体放到一个纯英文路径下跑之前打开ancient_book.yaml确认path字段和实际目录一致。跑通最小流程只需要两步先安装依赖再启动界面。如果models/best.pt存在训练步骤可以跳过pip install -r requirements.txt python src/ui/main_window.py安装依赖建议用虚拟环境不要直接装到系统Python里否则很容易和已有库冲突。界面启动后选择一张古籍页面图片模型会返回检测框、类别和置信度。整个工程的三块逻辑关系是数据集喂给训练脚本训练脚本产出权重权重和可视化界面共同组成推理程序。这个数据流不复杂但每一步都可能因为环境和格式问题卡住后面两章会对应展开。3. 用数据集训练 YOLOv8 古籍损伤检测模型标注转换、训练参数与损失曲线训练阶段决定了系统检测效果的上限。很多人在拿到压缩包后急着点“训练”结果损失曲线一路乱跳mAP低得没法看。问题往往不是模型不行而是数据没喂对。把数据集从原始标注整理成YOLOv8能吃的格式再按古籍损伤的小目标特性调整训练参数这一步值得多花时间。3.1 把 VOC 标注转成 YOLO 的 txt 格式转换脚本与类别映射古籍数据集的原始标注常见有两种格式VOC的XML和COCO的JSON。YOLOv8训练只认txt格式每张图片对应一个同名txt文件每行是一组目标信息格式为“类别索引 中心点x 中心点y 框宽 框高”坐标全部归一化到0到1之间。如果你拿到的数据集里是VOC标注第一步要做的就是把XML转成txt。import xml.etree.ElementTree as ET import os voc_dir datasets/annotations # 存放原始 xml 的目录 yolo_dir datasets/labels # 转换后 txt 输出目录 os.makedirs(yolo_dir, exist_okTrue) class_map { wormhole: 0, # 虫蛀 mildew: 1, # 霉变 stain: 2, # 水渍 damage: 3 # 破损 } def convert_one(xml_path): tree ET.parse(xml_path) root tree.getroot() img_w int(root.find(size/width).text) img_h int(root.find(size/height).text) out_name os.path.basename(xml_path).replace(.xml, .txt) with open(os.path.join(yolo_dir, out_name), w) as f: for obj in root.iter(object): cls obj.find(name).text.lower().strip() if cls not in class_map: continue bbox obj.find(bndbox) xmin float(bbox.find(xmin).text) ymin float(bbox.find(ymin).text) xmax float(bbox.find(xmax).text) ymax float(bbox.find(ymax).text) cx (xmin xmax) / 2 / img_w cy (ymin ymax) / 2 / img_h w (xmax - xmin) / img_w h (ymax - ymin) / img_h f.write(f{class_map[cls]} {cx:.6f} {cy:.6f} {w:.6f} {h:.6f}\n) for xml_file in os.listdir(voc_dir): if xml_file.endswith(.xml): convert_one(os.path.join(voc_dir, xml_file))这段脚本的逻辑很简单从XML里读出图像宽高和目标框的左上角、右下角坐标把绝对坐标换算成归一化的中心点坐标与宽高。转换完一定要检查txt文件的行数和XML里的object数量是否一致。常见翻车点是XML里存在size字段缺失的图片这种图片建议直接剔掉不要让它影响训练。另外类别名的匹配我用了lower().strip()是因为不同标注工具保存的类名大小写不一致这一步能避免“Wormhole”和“wormhole”被当成两个类别。3.2 yolov8 训练命令与关键参数epoch、batch、imgsz 怎么设才不翻车训练前先准备数据配置文件。YOLOv8用YAML描述数据集路径和类别列表古籍保护系统的配置文件大致长这样# ancient_book.yaml path: datasets/ancient_book # 数据集的根目录 train: images/train val: images/val nc: 4 names: [wormhole, mildew, stain, damage]注意path字段建议写相对路径目录层级要和你解压后的工程结构一致。nc必须和names的长度一致哪怕少一个类别都会导致训练时索引越界。配置好后训练命令如下yolo detect train datadatasets/ancient_book.yaml \ modelyolov8n.pt \ epochs100 \ imgsz640 \ batch16 \ device0 \ projectruns/detect \ nameancient_book这是最省心的起步配置。yolov8n.pt是官方预训练权重显存占用小GTX 1660 Ti这类6G显存的卡也能跑batch16在6G显存下通常够用如果报OOM就降到8但要记住batch减半后学习率最好也跟着降一点比如从0.01降到0.005否则收敛会不稳定。更关键的是imgsz这个参数。古籍扫描件通常分辨率很高虫蛀孔在640×640下可能只有十几个像素直接训练会让小目标漏检严重。我的习惯是显存够就上imgsz1024甚至imgsz1280小目标mAP提升非常明显显存不足则保持640同时依赖mosaic数据增强来增加小目标参与训练的机会。代价是训练时间变长一个100epoch的流程在单卡上可能要跑十几个小时要有心理预期。3.3 训练中盯着什么看损失函数曲线、mAP 指标与过拟合识别训练启动后Ultralytics会在runs/detect/ancient_book/下生成results.csv和results.png这两个文件是判断训练状态的主要依据。很多人只看mAP其实损失曲线更能反映问题。train/box_loss和val/box_loss两条曲线会随着epoch下降并逐渐靠近如果训练后期val/box_loss掉头往上走而train/box_loss还在降那就是过拟合的信号。用脚本把损失曲线画出来会更直观尤其适合放进毕设答辩材料import pandas as pd import matplotlib.pyplot as plt df pd.read_csv(runs/detect/ancient_book/results.csv) # 列名可能带空格读出来之后先做一次 strip df.columns [c.strip() for c in df.columns] plt.plot(df[train/box_loss], labeltrain box_loss) plt.plot(df[val/box_loss], labelval box_loss) plt.xlabel(epoch) plt.ylabel(loss) plt.legend() plt.title(box_loss curve) plt.show()曲线发散时先检查是不是学习率太大数据量本身就少的话可以把epochs减到50到80配合早停策略避免无效训练。另一个重要指标是metrics/mAP50(B)古籍保护这类任务里mAP50比mAP50-95更贴近实际使用感受因为损伤检测不需要像素级精确框能落在损伤区域内就算可用。训练结束后best.pt会根据验证集mAP自动保存推理阶段直接加载它就行。4. 古籍保护系统部署常见问题排查环境、数据与界面的三层踩坑记录训练跑通只是开始部署阶段才是劝退大多数人的地方。我把踩过的坑按环境、数据、界面三层拆开每一条都按“现象、原因、解决”写清楚。你在复现时如果卡住直接对着找。4.1 环境配置阶段PyTorch、CUDA 与 OpenCV 版本冲突现象按 requirements.txt 装完依赖后运行界面脚本直接报错要么是torch.cuda.is_available()返回False要么是cv2.error: Assertion failed之后进程退出。原因两个常见情况。其一pip默认装的是CPU版PyTorch根本用不了GPU其二环境里同时存在opencv-python和opencv-contrib-python两个包的部分文件互相覆盖导致cv2模块残缺。解决用虚拟环境重装先装PyTorch再装其它依赖conda create -n ancient_book python3.10 -y conda activate ancient_book pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118 pip install ultralytics pyqt5 opencv-python--index-url指定的是PyTorch官方CUDA 11.8版whl仓库装完用python -c import torch; print(torch.cuda.is_available())验证。OpenCV只装一个opencv-python就够了不要两个一起装。如果还需要图像处理的高级功能用opencv-contrib-python替代别混着装。4.2 数据与训练阶段空标签、类别错位与小目标漏检现象训练日志出现大量WARNING: images without labels或者训练完成后mAP为0检测结果完全不对。原因标签文件为空或者标签里的类别索引和YAML的names顺序对不上。比如VOC转换脚本里类名写错了一个导致某类目标全被跳过又或者某个标注工具从0开始编号而你配置文件里默认类别0是背景整体错位一位。解决训练前先扫一遍标签文件确认每张训练图都有对应标签import os label_dir datasets/ancient_book/labels/val for fn in os.listdir(label_dir): with open(os.path.join(label_dir, fn)) as f: lines f.read().strip().splitlines() if len(lines) 0: print(f{fn}: EMPTY) continue classes {int(line.split()[0]) for line in lines} if not classes.issubset({0, 1, 2, 3}): print(f{fn}: BAD class index {classes})这个小脚本能快速定位空标签和非法类别索引。小目标漏检的问题我在前面提过优先把imgsz调大。如果显存不够还可以关掉mosaic增强的末尾epoch避免小目标在拼接过程中被裁掉。4.3 可视化界面阶段PyQt5 卡死、路径读取失败与置信度阈值问题现象点击界面上的“开始检测”按钮后整个窗口白屏无响应过几秒甚至弹出“程序未响应”或者选择图片时路径带中文就直接读不出来。原因模型推理被放在了主线程里。YOLOv8推理一张高分辨率古籍扫描图可能要几秒甚至十几秒期间Qt事件循环被阻塞界面就表现为卡死。中文路径的问题是OpenCV的imread在Windows下默认不支持非ASCII路径它会直接返回None。解决推理放到后台线程用信号把结果传回主线程更新界面from PyQt5.QtCore import QThread, pyqtSignal from ultralytics import YOLO class DetectThread(QThread): result_ready pyqtSignal(object) # 信号传回检测结果 def __init__(self, model_path, image_path): super().__init__() self.model YOLO(model_path) self.image_path image_path def run(self): results self.model.predict( sourceself.image_path, conf0.25, iou0.45 ) self.result_ready.emit(results[0])主界面实例化这个线程连接result_ready信号到更新函数。这样推理在后台跑界面可以继续响应拖拽、缩放等操作。中文路径的解决也很简单绕过cv2.imread改用np.fromfile加cv2.imdecodeimport numpy as np import cv2 def imread_unicode(path): data np.fromfile(path, dtypenp.uint8) return cv2.imdecode(data, cv2.IMREAD_COLOR)置信度阈值的问题更多是使用层面。古籍损伤对比度低模型输出的置信度普遍不高界面上我建议把conf阈值做成滑杆默认0.25太低会有大量误检太高又会漏掉真实损伤。调阈值时要结合具体的扫描分辨率来试不要一上来追求高置信度。5. 让古籍保护系统更接近实用的进阶技巧模型导出、阈值后处理与大图切片系统能跑通之后接下来要做的是让它真正可用。古籍扫描件不是手机拍的照片动辄几千乘几千像素直接塞给YOLOv8推理有两个问题一是耗时太长二是下采样后小目标细节丢失。我的处理习惯是加一道切片推理逻辑。把大图按640像素大小切块相邻块之间保留128像素重叠避免损伤刚好落在切片边界上。每个切片独立推理再把检测框坐标映射回原图。重叠区域里同一个损伤可能被检出两次用置信度高的框保留、低的丢弃来去重。用低阈值推理比如0.1配合重叠去重比单张大图高阈值推理的漏检率低很多。如果想要更好的性能可以导出ONNX格式再推理。Ultralytics一句命令就能完成yolo export modelmodels/best.pt formatonnx opset12 simplifyTrue精度损失很小CPU上比PyTorch原版快不少也方便后续转成TensorRT或者RKNN部署到RK3588这类板子上。对课程设计来说导出ONNX在答辩现场也能成为一个加分项的演示点。最后把检测结果落成结构化记录。古籍保护系统如果只是弹窗展示结果实际价值有限把每次检测的类别、置信度、坐标和图片文件名写入CSV后续统计哪一类损伤占比高、哪一页需要重点修复就有了数据支撑。import csv csv_file open(detect_results.csv, w, newline, encodingutf-8) writer csv.writer(csv_file) writer.writerow([image, class, confidence, x1, y1, x2, y2]) for result in results: for box in result.boxes: cls_id int(box.cls[0]) conf float(box.conf[0]) x1, y1, x2, y2 [round(float(v), 1) for v in box.xyxy[0]] writer.writerow([result.path, class_names[cls_id], conf, x1, y1, x2, y2]) csv_file.close()我在做这类项目时有个习惯所有路径统一用相对路径所有类名统一小写所有阈值参数集中放在配置文件里而不是散落在代码各处。这样换机器、换数据集、换模型时动的只是配置文件代码一行都不用改。这些看似不起眼的习惯往往决定了方案能不能顺利复现。希望帮到你。本文还有配套的精品资源点击获取