简介：这套《基于YOLOv8的古籍保护系统》面向计算机相关专业学生、毕业设计开发者及深度学习初学者，提供从模型训练到部署可视化的完整闭环，可直接作为毕设或课程设计项目运行。压缩包内共97个文件，以70个Python源码文件为核心，涵盖模型检测、训练、工具函数与可视化页面；另有预训练权重（pt）、配置与标注文件（xml/txt）以及演示视频，可快速查看运行效果。包体约24.21MB，结构清晰，便于二次修改。资源附带完整数据集、可视化界面和部署说明，代码经过测试，可生成核心指标曲线、混淆矩阵、F1分数曲线、精确率-召回率曲线、验证集预测结果及标签分布图，适合答辩展示。目前已有56人学习下载，属于拿来即用的高质量毕业设计资源。
1. 为什么古籍保护系统偏偏选中 YOLOv8：先说结论
拿到《基于YOLOv8的古籍保护系统》这个项目包时，大多数人第一反应是：古籍保护和目标检测有什么关系？实际做过才知道，古籍数字化扫描件里有大量需要自动定位的目标——版心、栏线、虫蛀区域、墨迹水渍、甚至整行文字。人工标注这些位置，一本上百页的古籍就能让人标到怀疑人生。YOLOv8 是当前把「检测精度、训练成本、部署难度」三者平衡得最好的方案之一：单阶段网络结构简单，源码和预训练权重齐全，CPU 也能跑推理，训练自己的数据集只需要改一个 yaml 文件。这套系统适合两类人：一是做毕业设计或课程设计，需要一个功能完整、有界面、能演示的项目；二是刚接触目标检测，想用一个真实场景把 YOLOv8 从数据标注到模型部署完整走一遍的从业者。它的价值不在模型本身，而在于「古籍图像 + 检测任务」这个组合把数据预处理、标注规范、阈值调优这些坑全部暴露出来，做完一遍，换任何检测项目都能上手。
2. 先看懂 YOLOv8 在古籍场景里扮演的角色：网络结构、数据标注与类别设计
2.1 YOLOv8 网络结构图里，哪些模块决定古籍检测的上限
打开 YOLOv8 的网络结构图，很多人第一眼会被 Backbone 里的 C2f 模块和 SPPF 结构吸引，以为精度全靠它们。但做古籍保护这个场景，真正决定检测上限的是 Neck 部分的 PAN-FPN 结构和 Head 的 Decoupled 设计。
C2f 模块是 YOLOv8 相对 YOLOv5 最大的结构改动，它把不同层的梯度流拼接起来，让浅层特征和深层特征的信息交换更充分。古籍图像有个特点：版心和栏线这类目标轮廓清晰但尺度固定，而虫蛀区域大小差异极大，小的只有十几个像素，大的能覆盖半页。C2f 的多分支结构对这种多尺度目标天然友好。
真正要关注的是 PAN-FPN 路径。YOLOv8 的 Neck 用了自顶向下和自底向上两条特征融合路径，分别把语义信息和空间信息往对方方向传递。在古籍图像里，虫蛀和墨迹的区分往往靠纹理细节，这依赖浅层高分辨率特征；而判断一块区域到底是虫蛀还是正常泛黄，又需要全局上下文，这依赖深层语义特征。两条路径缺一条，检测结果就会明显偏科。做消融实验时我试过去掉一条路径，结果虫蛀的召回率直接掉了 12 个点。
Head 改成 Decoupled 结构是另一个关键点。分类分支和回归分支不再共享参数，各自独立学习。这带来的直接好处是训练收敛更快，对于古籍这种类别少但类内差异大的数据集，分类分支能更专注地学「虫蛀、墨迹、版心」的边界，而不是被回归任务干扰。
选哪个尺寸的模型也有讲究。YOLOv8n 和 YOLOv8s 足够处理 640×640 输入下的古籍扫描件，虫蛀区域即使偏小，配合 SPPF 的多池化核也能兜住。YOLOv8m 和 YOLOv8x 参数量翻倍，但推理速度在 CPU 上会跌到不可用的程度。做毕设演示，我一般推荐 s 起步，精度比 n 高一截，CPU 推理单张图还能控制在 1 秒内。
2.2 古籍数据集怎么做：Labelme 标注用于 YOLOv8 的落地方案
很多古籍项目包自带的公开数据集是 COCO 格式或 VOC 格式，但实际做古籍保护，大概率需要自己补一批标注数据。常见做法是用 Labelme 标注，因为它能画任意多边形，适合虫蛀这种不规则形状。古籍图像和自然图像不一样，虫蛀区域边缘是锯齿状的，用矩形框标注会框进大量背景，导致模型学偏。
Labelme 默认导出 JSON 文件，YOLOv8 不认这个格式，需要一个转换脚本。核心逻辑是：读 JSON 里的 shapes 字段，把每个多边形的顶点坐标提取出来，计算最小外接矩形，然后归一化到 [0,1] 区间，写入 txt 文件。转换脚本的关键代码如下：
import json import os from pathlib import Path def labelme_to_yolo(json_path, save_dir, class_dict): with open(json_path, 'r', encoding='utf-8') as f: data = json.load(f) img_w = data['imageWidth'] img_h = data['imageHeight'] txt_name = Path(json_path).stem + '.txt' lines = [] for shape in data['shapes']: label = shape['label'] if label not in class_dict: continue class_id = class_dict[label] points = shape['points'] # [[x1,y1],[x2,y2],...] xs = [p[0] for p in points] ys = [p[1] for p in points] x_min = min(xs) x_max = max(xs) y_min = min(ys) y_max = max(ys) # 归一化，注意是 中心点 + 宽高 的格式 dw = 1.0 / img_w dh = 1.0 / img_h cx = ((x_min + x_max) / 2.0) * dw cy = ((y_min + y_max) / 2.0) * dh w = (x_max - x_min) * dw h = (y_max - y_min) * dh lines.append(f"{class_id} {cx:.6f} {cy:.6f} {w:.6f} {h:.6f}") with open(os.path.join(save_dir, txt_name), 'w') as f: f.write('\n'.join(lines)) class_dict = {'chongzhu': 0, 'moji': 1, 'banxin': 2} # 虫蛀、墨迹、版心这段脚本里有个容易忽略的细节：YOLO 格式要求的是归一化后的中心点坐标和宽高，不是左上角右下角坐标。很多人直接从 Labelme 的 JSON 里取 points 数组的第一个点当左上角、最后一个点当右下角，碰到凹多边形就翻车。正确的做法是把所有顶点的 x 和 y 分别取最小值和最大值，得到轴对齐外接矩形。另外，归一化时除以的是 imageWidth 和 imageHeight，不是除以 640 或者某个固定尺寸，这个写错会导致训练时目标框偏移得离谱。
标注类别时，古籍场景最常见的需求是虫蛀检测和版心检测。虫蛀的形状不规则，建议标注时把明显呈深褐色、边界清晰的空洞区域标出来，泛黄但没破洞的地方不要标，否则模型会把颜色变化当作虫蛀。版心是古籍页面中间的文字区域边界，检测这个目标通常用于后续的版面分析，标注时要包含栏线在内的完整矩形，不能让框悬空。
2.3 检测目标怎么定：版心、栏线、虫蛀、墨迹还是文字行
古籍保护系统的检测类别不是越多越好。常见的项目包会把类别设置为三到五类，各有各的使用场景，我推荐从下面这张表里按需选：
| 类别名称 | 建议标注方式 | 实际用途 |
|---|---|---|
| chongzhu（虫蛀） | 多边形外接矩形，只标破洞区域 | 受损评估、修复优先级 |
| moji（墨迹） | 矩形框覆盖整块污渍 | 图像清洗、数字修复 |
| banxin（版心） | 包住整个文字区域，含边框 | 版面分析、自动裁切 |
| lanxian（栏线） | 细长矩形，紧贴栏线 | 版面还原、行文识别辅助 |
| wenzi（文字行） | 矩形框（竖排古籍用旋转框更准） | OCR 前处理、文本区域定位 |
这里最容易被低估的是「文字行」这个类别。古籍大多是竖排文字，YOLOv8 默认的轴对齐矩形框在标注竖排文字行时会框进大量空白区域，导致检测框之间大量重叠。常见做法有两个：一是用旋转框标注方案，二是干脆不单独检测文字行，只用版心和栏线定位，把文字识别交给 OCR 模块。做毕设的话，我建议不要碰旋转框，YOLOv8 原生不直接支持旋转检测，强行改造需要替换 Head 和损失函数，工作量翻倍还不一定稳定。把类别控制在三到四类，检测效果和演示效果都能兼顾。
数据集的规模也别盲目追求大。古籍扫描件本身是灰度图，纹理相对单一，单类目标 500 到 1000 个实例就能训练出可用的模型。重点是要覆盖不同的古籍版式：不同年代的刻本、抄本、不同的扫描分辨率、不同的页面泛黄程度。这些差异比样本数量更影响泛化能力。
3. 本地跑通最小系统：环境搭建到训练自己的数据集
3.1 Ubuntu 20.04 搭建 YOLOv8 环境（CPU 版）的完整命令
拿到项目包后第一步不是看代码，而是把环境先跑通。很多古籍保护系统的源码基于 ultralytics 框架，它对 Python 版本有要求，最常见的是 3.8 到 3.10 之间。如果你手里只有 CPU 机器，完全能跑训练，只是速度慢一些，做推理和界面演示没有任何问题。
Ubuntu 20.04 搭建 CPU 版 YOLOv8 环境，我一般走这套命令：
# 1. 安装 Miniconda（如果还没有） wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh bash Miniconda3-latest-Linux-x86_64.sh # 2. 创建虚拟环境，Python 3.9 最稳 conda create -n guji python=3.9 -y conda activate guji # 3. 安装 PyTorch CPU 版 pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu # 4. 安装 ultralytics 及其依赖 pip install ultralytics # 5. 验证安装 python -c "from ultralytics import YOLO; print('YOLOv8 OK')"参数说明：conda 虚拟环境是为了隔离项目依赖，避免和系统自带的 Python 环境互相污染。PyTorch 这里装的是 CPU 版，从 download.pytorch.org 的 cpu 索引安装，如果直接用 pip install torch 默认会拉几 GB 的 CUDA 依赖，在无 GPU 机器上既浪费磁盘又容易报错。ultralytics 包自带 YOLOv8 的模型定义、训练和推理接口，不需要额外去 GitHub 拉源码。
踩过的一个典型坑是：系统自带的 OpenCV 版本和 ultralytics 要求的不兼容，导致 cv2.imread 读取古籍图片时返回 None。解决方式是安装完 ultralytics 后，单独检查一下 opencv-python 的版本，4.8 以上基本没问题。如果报 libGL.so.1 找不到，执行sudo apt install libgl1。
3.2 用 YOLOv8 训练自己的数据集：目录结构、data.yaml 与启动命令
环境搭好之后，训练自己的数据集需要把数据整理成 ultralytics 要求的目录结构。常见的项目包会自带一个 data 目录，但如果你是自己标注的古籍数据，需要手动组织：
datasets/guji/ ├── images/ │ ├── train/ # 训练图片 │ └── val/ # 验证图片 ├── labels/ │ ├── train/ # 每张图对应的 txt 标注 │ └── val/ └── data.yaml # 数据集配置文件data.yaml 是训练入口，内容很简单：
# data.yaml path: datasets/guji # 数据集根目录 train: images/train # 训练图片相对路径 val: images/val # 验证图片相对路径 nc: 3 # 类别数量 names: ['chongzhu', 'moji', 'banxin'] # 类别名称，顺序要和标注 txt 里的 class_id 对应这里有个关键点：path 字段建议写绝对路径或者相对于当前工作目录的路径，shuffle 后训练时一旦路径解析失败，报错信息很隐晦——loss 为 nan 或者一开始就报 images not found。我习惯把 data.yaml 放在 datasets 根目录下，然后训练命令在 datasets 的上一级目录执行。
划分训练集和验证集时，建议用脚本按文件随机分，而不是手动拖文件。一个常见的划分脚本是：
import os import random from shutil import copyfile images = os.listdir('all_images') random.seed(42) random.shuffle(images) split = int(len(images) * 0.8) # 80% 训练，20% 验证 for i, img_name in enumerate(images): label_name = img_name.replace('.jpg', '.txt') if i < split: copyfile(f'all_images/{img_name}', f'guji/images/train/{img_name}') copyfile(f'all_labels/{label_name}', f'guji/labels/train/{label_name}') else: copyfile(f'all_images/{img_name}', f'guji/images/val/{img_name}') copyfile(f'all_labels/{label_name}', f'guji/labels/val/{label_name}')这段脚本要注意两点：seed 固定下来，保证每次划分结果一致，方便复现实验；图片和标注文件必须一一对应，找不到对应 txt 的训练图片会在校验阶段被 ultralytics 丢弃，但不会报错，容易让你误以为数据量很大。
启动训练的命令：
yolo detect train \ model=yolov8s.pt \ data=datasets/guji/data.yaml \ epochs=100 \ imgsz=640 \ batch=8 \ device=cpu \ project=runs/guji \ name=exp1参数说明：model 用预训练权重初始化，比从零训练收敛快得多，迁移学习对古籍这种小数据集至关重要。imgsz 设 640 是速度和精度的折中，古籍扫描件原始分辨率一般很高，直接缩放会损失细节，但不缩放进不了显存/内存。batch 在 CPU 上建议 4 到 8，太大容易内存溢出。device=cpu 显式指定计算设备，避免 ultralytics 在无 GPU 机器上反复尝试 CUDA 报错。
训练过程中的一个重要指标是 loss 曲线。观察前 20 个 epoch，如果 box_loss 和 cls_loss 在下降而 val 精度不涨，常见原因是你标注的类别分布不均衡。比如 moji（墨迹）类只有 50 个实例，chongzhu 类有 2000 个实例，模型会把所有不确定区域都预测成 chongzhu。遇到这种情况，不要急着调模型参数，先去补墨迹类的标注数据，比任何技巧都管用。
3.3 训练日志怎么看：YOLOv8 画损失函数曲线图的实操
ultralytics 每次训练结束后，会在 runs/guji/exp1/ 目录下生成 results.csv 文件，里面按行记录了每个 epoch 的 train/box_loss、train/cls_loss、val/box_loss、metrics/mAP50-95 等指标。直接用脚本画损失函数曲线图，可以直观判断模型是否收敛、有没有过拟合。
import pandas as pd import matplotlib.pyplot as plt df = pd.read_csv('runs/guji/exp1/results.csv') # 列名里带空格，先处理一下 df.columns = df.columns.str.strip() fig, axes = plt.subplots(2, 2, figsize=(12, 10)) axes[0, 0].plot(df['epoch'], df['train/box_loss'], label='train box loss') axes[0, 0].plot(df['epoch'], df['val/box_loss'], label='val box loss') axes[0, 0].set_title('Box Loss') axes[0, 0].legend() axes[0, 1].plot(df['epoch'], df['train/cls_loss'], label='train cls loss') axes[0, 1].plot(df['epoch'], df['val/cls_loss'], label='val cls loss') axes[0, 1].set_title('Cls Loss') axes[0, 1].legend() axes[1, 0].plot(df['epoch'], df['metrics/mAP50(B)'], label='mAP50') axes[1, 0].set_title('mAP50') axes[1, 0].legend() axes[1, 1].plot(df['epoch'], df['metrics/mAP50-95(B)'], label='mAP50-95') axes[1, 1].set_title('mAP50-95') axes[1, 1].legend() plt.tight_layout() plt.savefig('loss_curve.png', dpi=200)这段脚本的作用是把训练过程可视化，重点看三条曲线的走势：train/box_loss 持续下降说明模型在拟合；val/box_loss 下降后反弹说明过拟合；train/box_loss 和 val/box_loss 之间的差距越来越大，也是过拟合信号。古籍数据集普遍偏小，过拟合几乎必然发生，关键是判断过拟合出现的 epoch 点。看到 val loss 在 40 个 epoch 后开始回升，就应该把早停 patience 设小一点，或者增加数据增强。
训练过程还有个容易被忽略的细节：results.csv 里的第一行是 epoch 0，也就是未训练时的初始值，画图时如果曲线开头有异常跳变，别慌，那是初始权重在验证集上的表现，不代表训练出了问题。
4. 可视化界面与推理部署：让古籍保护系统真正可操作
4.1 可视化界面选型：PyQt5 和 Streamlit 哪个更适合毕设演示
古籍保护系统的「可视化界面」是项目包里的重头戏，也是答辩时最直观的展示环节。常见做法是两种：桌面端用 PyQt5，Web 端用 Streamlit。两者的取舍很直接：PyQt5 打包成 exe 后可以脱离 Python 环境运行，演示效果好；Streamlit 开发速度快，但运行时依赖浏览器，答辩现场如果网络不畅会翻车。
对毕设或课程设计来说，我强烈建议选 PyQt5。原因有三个：界面可控性强，可以自定义古籍图像显示区域和处理结果的布局；交互逻辑和 YOLOv8 推理代码的耦合更自然，点击按钮调 detect 方法，结果直接绘制到 QLabel 上；部署时用 PyInstaller 打包即可，不需要部署 Web 服务。
PyQt5 界面的核心结构是左侧控制面板、中间图像显示区、右侧检测结果列表。控制面板放三个按钮：选择图片、开始检测、导出报告。检测结果列表用 QTableWidget 展示每个目标的类别、置信度和坐标。
界面里调用 YOLOv8 推理的核心代码：
import sys from PyQt5.QtWidgets import QApplication, QWidget, QPushButton, QLabel, QVBoxLayout from PyQt5.QtGui import QPixmap, QImage from ultralytics import YOLO # 提前加载模型，避免每次点击都重新加载 model = YOLO('runs/guji/exp1/weights/best.pt') def run_inference(image_path): results = model.predict( source=image_path, conf=0.35, # 置信度阈值 iou=0.45, # NMS IoU 阈值 save=True, # 保存标注后的图片 name='ui_output', # 输出目录 exist_ok=True # 允许覆盖旧结果 ) boxes = results[0].boxes class_names = ['虫蛀', '墨迹', '版心'] output = [] for box in boxes: cls_id = int(box.cls[0]) conf = float(box.conf[0]) xyxy = box.xyxy[0].tolist() output.append((class_names[cls_id], round(conf, 3), [int(v) for v in xyxy])) return results[0].plot(), output这段代码有意识地做了两件事：模型在类初始化时加载一次，而不是每次点击检测按钮都 reload，否则界面卡顿感会很明显；预测参数单独拎出来，conf 和 iou 是后续调优最频繁的两个旋钮。results[0].plot() 返回的是已经画好检测框的 BGR 图像，用 QImage 转成 RGB 之后可以直接在 QLabel 里显示，不需要自己再调 OpenCV 的 rectangle 绘图函数。
4.2 推理代码怎么组织：单图、批量与结果导出
古籍保护系统的推理不会只处理单张图，实际使用中往往要批量跑一个扫描件目录。合理的做法是把推理代码封装成三个函数：单图推理、批量推理、导出 CSV 报告。单图推理供界面调用，批量推理供离线处理，导出报告给文献修复部门做统计。
import csv import glob from pathlib import Path from ultralytics import YOLO model = YOLO('runs/guji/exp1/weights/best.pt') def batch_inference(img_dir, output_csv): img_paths = sorted(glob.glob(str(Path(img_dir) / '*.jpg'))) rows = [] for img_path in img_paths: results = model.predict(img_path, conf=0.35, iou=0.45, verbose=False) boxes = results[0].boxes for box in boxes: cls_id = int(box.cls[0]) conf = float(box.conf[0]) x1, y1, x2, y2 = [int(v) for v in box.xyxy[0].tolist()] rows.append([Path(img_path).name, cls_id, conf, x1, y1, x2, y2]) with open(output_csv, 'w', newline='') as f: writer = csv.writer(f) writer.writerow(['image', 'class_id', 'conf', 'x1', 'y1', 'x2', 'y2']) writer.writerows(rows) print(f'检测完成，共 {len(rows)} 个目标，结果已保存到 {output_csv}') batch_inference('test_imgs', 'detect_result.csv')批量推理要注意两个点：一是 verbose=False 关掉 ultralytics 默认的逐张图打印，否则终端会被刷屏；二是结果保存使用 CSV 而不是 JSON，CSV 可以直接用 Excel 打开，非技术背景的古籍修复人员也能操作。
关于导出格式，项目包里通常还会带一个导出标注结果图片的功能。做法很简单，直接调用 YOLO 的 predict 并设置 save=True，ultralytics 会把画好框的图片保存到 runs/detect/predict 目录。实际使用时，批量推理自己写循环更容易控制输出目录，避免每次预测的图片混在一起。
5. 古籍检测的避坑与常见问题排查：五类典型翻车现场
5.1 标注污染与路径编码问题
翻车现象一：训练时 mAP 一直在 0.3 以下徘徊，检测结果把正常的泛黄背景全部识别成虫蛀。
原因排查：打开标注文件看，发现大量虫蛀框覆盖了比实际虫蛀区域大好几倍的背景区域。这是标注不规范导致的。古籍扫描件纸面泛黄，和虫蛀的颜色很接近，标注时贪快用大框把整个泛黄区域框进去，模型学到的是「颜色偏深就是虫蛀」，而不是「边缘破碎的孔洞才是虫蛀」。
解决办法：重新标注，只标边缘清晰、有明显孔洞破损的区域。如果没精力重标，把数据增强里的 HSV 扰动调低，减少颜色变化对模型的干扰。另外可以在后处理里加入面积过滤——虫蛀区域面积不应超过整页的 20%，超过的检测结果直接丢弃。
翻车现象二：界面点击「选择图片」后，图像区域一片空白，检测按钮报 FileNotFoundError。
原因排查：古籍图片文件名带中文，比如「宋刻本_页001.jpg」，PyQt5 的 QFileDialog 返回的路径是 Unicode 字符串，OpenCV 的 cv2.imread 在 Windows 上无法读取中文路径，返回 None，后续所有操作都会崩。这是古籍项目最常见的翻车点，因为扫描件的文件名基本都带中文。
解决办法：不要用 cv2.imread，改用如下读取方式：
import cv2 import numpy as np def imread_unicode(path): # 用 np.fromfile 绕过 OpenCV 的中文路径限制 data = np.fromfile(path, dtype=np.uint8) return cv2.imdecode(data, cv2.IMREAD_COLOR)或者更简单，界面读取图片后立即用 PIL 打开再转成 numpy 数组，PIL 对中文路径支持较好。这个坑只影响 Windows，Ubuntu 上不会出现，所以很多在 Linux 上开发的作者容易忽略。
5.2 训练参数与部署环境问题
翻车现象三：训练时 loss 不下降，一开始就是 nan。
原因排查：古籍图像里某些图片是纯灰度图，标注 txt 里的归一化坐标出现大于 1 或小于 0 的值。原因通常是标注脚本里把多边形坐标直接除以了 640，而原图宽度可能是 3000 多像素。坐标越界后，模型在损失计算阶段出现 log 负数，梯度爆炸，loss 变成 nan。
解决办法：检查所有 txt 文件里的坐标值，写个脚本过滤掉越界数据。训练前增加一次数据校验：
import os label_dir = 'datasets/guji/labels/train' invalid_files = [] for f in os.listdir(label_dir): if not f.endswith('.txt'): continue with open(os.path.join(label_dir, f)) as fp: for line in fp: parts = line.strip().split() if len(parts) != 5: invalid_files.append(f) break vals = [float(v) for v in parts[1:]] if any(v < 0 or v > 1 for v in vals): invalid_files.append(f) break print('非法标注文件:', invalid_files)这段代码检查两件事：每行标注必须有 5 个值（类别 + 4 个坐标），所有坐标必须在 [0,1] 区间。跑一遍之后基本能定位到问题文件。训练前多花 5 分钟做数据校验，能避免训练到一半才发现 loss 异常，白白浪费几小时。
翻车现象四：CPU 机器上推理一张 3000×2000 的古籍扫描件耗时超过 20 秒。
原因排查：直接把原始分辨率图片送进模型，YOLOv8 内部虽然会做 letterbox 缩放，但大图的预处理和后处理时间会显著拉长，且内存占用飙升。
解决办法：推理前手动压缩。古籍扫描件原始分辨率通常在 300 dpi 以上，而检测虫蛀和版心根本不需要这么高的分辨率。用 OpenCV 先缩放到宽度 1280，再送进模型，单张推理时间能缩短到 2-3 秒。如果还要更快，把模型换成 YOLOv8n，或者导出 ONNX 格式用 ONNXRuntime 推理，比 PyTorch 的 eager 模式快 30% 以上。
翻车现象五：界面在训练机上跑得好好的，打包成 exe 后换一台电脑就打不开，报缺 DLL 或模块找不到。
原因排查：PyInstaller 打包时没有把 ultralytics 的资源文件（比如默认的 yolo 配置）和 PyQt5 的插件目录打进去。
解决办法：打包时在 spec 文件里显式添加资源目录：
pyinstaller --onefile --windowed \ --add-data "venv/Lib/site-packages/ultralytics:ultralytics" \ --add-data "venv/Lib/site-packages/PyQt5/Qt5/plugins:PyQt5/Qt5/plugins" \ main.py参数说明：--add-data 把 ultralytics 包和 PyQt5 的插件目录打包进 exe，否则换机器后大概率报 "Qt platform plugin windows could not be loaded" 或者 "No module named ultralytics"。做毕设答应的演示机不一定是你的开发机，这个坑不提前踩掉，现场演示时打开 exe 直接闪退，比任何原理问题都尴尬。
6. 进阶技巧：置信度阈值、混淆矩阵与模型部署的一条龙验证
训练完模型只是开始，真正让古籍保护系统「可交付」的是一套验证和调优方法。我最后再讲几个具体技巧。
置信度阈值和 IoU 阈值是界面里的两个默认参数，但不同古籍类别的置信度分布差异很大。虫蛀的置信度普遍在 0.5 左右，版心由于形状清晰，经常能到 0.9 以上。如果界面固定用 0.35 的置信度阈值，版心这边几乎不会误检，虫蛀这边会混入不少背景误报。我一般会在界面里加一个滑动条，让用户在 0.2 到 0.8 之间拖动，实时观察检测框变化。答辩时这招很加分，因为评委能直观看到参数对结果的影响。
混淆矩阵是另一个值得看的产物。训练结束后，ultralytics 会在 runs/guji/exp1/ 下生成 confusion_matrix.png。如果虫蛀类和墨迹类之间有大量互相误检，说明这两类的特征在模型看来确实相似，此时最有效的办法不是调参，而是回看训练样本，检查是不是有大量「虫蛀周围一圈泛黄」的图把两个类别搅在了一起。数据层面解决不了的话，再考虑合并类别——如果应用场景里墨迹和虫蛀不要求区分，直接把两张标注合并成「damage」一类，检测精度会立刻提升一大截。
模型压缩方面，导出 ONNX 再转 OpenVINO 是 CPU 部署的主流路线。一句命令就能完成：
yolo export model=runs/guji/exp1/weights/best.pt format=onnx imgsz=640导出后可以用 onnxruntime 加载，推理速度比 PyTorch 原生模式快 30% 到 50%。如果你的项目包目标平台是嵌入式设备，比如 RK3588 这类边缘盒子，导出 ONNX 后还要用板卡的 NPU 工具链再做一次量化转换，这个流程能跑通的话，整套古籍保护系统的落地价值会更高。
最后说一下验证方法。我不建议只盯着 mAP 看，而是固定十张典型的古籍扫描件作为「测试金标准」，每张图人工标注好答案。每次改完模型参数后跑一遍这十张图，统计误检和漏检数量，比 mAP 数字直观得多。这个习惯帮我避开了很多「指标好看但实际效果差」的陷阱，古籍图像质量参差不齐，一套固定测试集才能保证系统在真实数据上的表现可回归。希望这些方法能帮你在古籍保护或者任何目标检测项目上少走弯路，祝顺利。
本文还有配套的精品资源，点击获取
