只跑过 YOLOv11 官方 demo 的人脑子里很容易形成一种错觉检测框画得又准又快项目好像就已经成功一半。但等你真拿一批自己的图片进来需要自建数据、训练、导出、部署、批量运行的时候才会发现所谓“demo”只是把别人训练好的权重调用了一下模型本身、数据处理、输出管理、异常处理全都是空的。这篇要拆解的是一个围绕 YOLOv11 搭建完整 CV 系统的项目应用场景是古籍上色。这里先把概念说清楚YOLOv11 不是上色模型它是目标检测和分割器上色由额外的条件生成模块完成。但在真实项目里检测精度决定上色范围上色质量又依赖后续处理你必须把整个流程串起来。这篇重点想说明三件事怎么从零准备环境、怎么把数据和标注整理成训练集、以及怎么把单张图片脚本改造成可批量推理和部署的完整系统。写这篇的目的很简单就是希望你能从“会调包跑 demo”走到“能自己搭一套完整 CV 流水线”哪怕项目不大过程也是完整的。1. 先搞清楚为什么是 YOLOv11为什么是古籍上色为什么不是 Demo1.1 YOLOv11 在项目中实际负责哪一环YOLOv11 属于目标检测模型它的工作是在图片里定位物体并告诉你是哪一类。在古籍上色项目里它可以负责检测人脸、衣服、花鸟、山水、印章、文字区域等等。检测结果是一个个带类别和坐标的框或者是更精细的分割掩码。上色并不是 YOLOv11 直接输出的。常见的做法是先用 YOLOv11 把需要上色的区域框出来再把框内区域送去上色模型比如基于生成对抗网络或扩散模型的图像翻译网络最终得到一张彩色结果。YOLOv11 在这里起到“区域定位”和“语义引导”的作用。很多人一开始会把项目理解成“用 YOLOv11 自动给黑白古籍上色”这是错的。如果按这个错误理解去搜代码最后只会找到一堆目标检测的官方 demo完全不知道上色模块应该往哪里接。正确理解是YOLOv11 负责提供区域限制上色负责提供颜色生成。两者协作才是一条完整的 CV 链路。1.2 判断一个 CV 项目是不是“玩具”的三个标准我判断一个 CV 项目能不能拿得出手就看三个问题能不能改源码和训练策略而不只是调用推理接口。能不能用自己的数据重新训练模型。能不能脱离 Notebook做批量推理和模型部署。如果三个都是否那它就是典型的玩具项目。你只是在别人的权重上做了一次预测和你写一段“读取显示图片”的入门代码没有本质区别。所以这篇文章的实践目标不是“跑出彩色图”而是把这三个问题全部打通。哪怕最终效果还达不到商用水平你至少知道每一步怎么走。1.3 古籍上色为什么适合当练习项目古籍上色这个场景非常有练习价值。它不是普通自然图像通常包含大量风格化元素工笔画、水墨画、版画、手写文字、红色印章。类别多样甚至很多类别在公开数据集里根本找不到所以你必须自己做数据。这个特点带来了真实业务中常见的挑战数据量少、类别不均衡、标注噪声高、图像尺寸大、细节多。这些问题在工业项目里非常常见但在官方 demo 里几乎遇不到。拿它练手你练的不是“调包”而是数据处理和模型选型的综合能力。2. 环境准备从 Python 虚拟环境到显存精度选型2.1 Python、CUDA、PyTorch、Ultralytics 的最小版本组合不管在 Windows 还是 Linux 上我都不建议直接在系统全局环境里配深度学习环境。第一次装环境最容易出的问题就是依赖冲突比如 PyTorch 版本和 CUDA 版本对不上或者 opencv 版本干扰其他库。建议从这个组合开始Python 3.10 或 3.11。独立虚拟环境可以使用 venv 或 conda。PyTorch 版本根据本机 CUDA 版本选择CPU 版本和 GPU 版本分开装。Ultralytics 提供 YOLOv11 的模型定义和训练推理接口安装方式通常就是 pip 安装 ultralytics。需要额外确认 opencv-python、numpy、pandas、matplotlib 等依赖是否正常。环境安装完成后第一件事不是跑大模型而是跑一个小样例确认 GPU 可用、显存能分配、图片能正常读写。在 Windows 上有一个常见坑路径分隔符。Windows 默认路径用反斜杠很多代码在 Linux 上能跑到 Windows 就报文件找不到。建议在代码里统一用 pathlib 或正斜杠拼接路径避免这种低级错误。2.2 显存占用和浮点数精度FP32、FP16、TF32、BF16 怎么选在训练和推理时你一定会遇到浮点数格式的选择问题。这里不展开讲底层原理只说你实际会碰到的判断逻辑。精度格式主要用途优点需要注意的地方FP32常规训练、常规推理精度最稳妥显存占用高速度相对慢FP16混合精度训练、GPU 推理显存占用减半速度提升明显可能出现数值溢出需要动态缩放BF16部分新一代 GPU 训练数值范围大比 FP16 更稳低比特位下精度下降老显卡不支持TF32部分 NVIDIA GPU 的矩阵运算兼顾速度和精度对最终结果的影响需要实测确认判断标准很简单如果你的显存不够先把训练推理改为 FP16如果你的检测框出现大量消失或 loss 不稳定再换回 FP32 或改用 BF16。实际项目里我会先用 FP16 跑一个短训练确认 loss 能正常下降再继续。不要一上来就把所有精度参数都调成最低那样省了显存但可能换来一堆莫名其妙的错检。2.3 跑通环境后先做什么检查环境装好以后不要直接训练。先跑一个最小脚本from ultralytics import YOLO model YOLO(yolo11n.pt) results model.predict(test.jpg, saveTrue) print(results[0].boxes.cls)如果能看到类别编号和结果图说明安装链路基本是通的。这一步看似简单但能帮你区分“模型问题”和“环境问题”。以后再出任何错先回来跑这个最小脚本如果最小脚本正常说明问题大概率出在你的数据、路径或参数上。3. 数据与标注把古籍图片变成模型能学的结构化数据3.1 古籍图像的收集、筛选与预处理古籍图片的来源通常很杂可能是扫描件、拍照件、公开数字图书馆资源、私人收藏翻拍图。采集之后第一件事不是标注而是清洗。清洗包括去掉有水印、模糊、严重变形、内容重复的图片。把超大扫描件切成小图或者统一缩放否则训练时占用显存太高。去除纯文字页除非你确实要检测文字区域。对所有图片做一遍直方图检查过亮过暗的图要么做增强要么先人工筛一遍。预处理不要过度。很多人一上来就做各种滤镜、锐化、自动对比度结果模型学到的不是古籍本身特征而是你制造的图像风格。建议先做最小预处理统一尺寸、统一色彩模式、保持原始语义不变。3.2 标注目标检测框还是分割掩码YOLOv11 支持检测框也支持实例分割。在古籍上色项目里不同上色需求对标注的要求不一样。如果你只负责定位人物、花鸟、远景、近景检测框足够。框的优点是标注快缺点是边界不精细上色时容易把背景颜色溢出到物体上。如果你的上色模型需要知道物体边界那就得用分割掩码。标一个多边形的成本高于拉一个矩形框但对后续上色效果帮助很大。我的建议是第一次做项目时先用检测框把类别跑通整个链路稳定后再考虑升级为分割标注。不要一开始就追求全分割否则你会被标注工作累死还没跑到训练就放弃了。标注工具可以使用常见的开源标注软件导出为 YOLO 格式的 txt 文件。每个图片对应一个同名 txt每行是类别编号 中心点 x 中心点 y 框宽 框高。3.3 样本数量少时的数据增强策略古籍数据量通常很少。样本少不是不能训练而是要控制方法。第一优先使用预训练权重。YOLOv11 官方权重在 COCO 等大型数据集上训练过虽然古籍不是它的主要应用场景但它的基础特征提取能力是可用的。你只需要微调后面的分类头。第二使用数据增强。YOLO 训练框架自带很多增强选项比如随机翻转、颜色扰动、缩放、平移、马赛克增强。但古籍图片不建议做过度旋转因为很多古籍里的文字方向是固定的旋转后语义会出错。第三如果样本实在少用半自动标注。先用预训练模型跑一遍把置信度高的结果过滤出来人工修正再进入训练集。这个方法能明显减少人工标注量但前提是你有一个还算靠谱的初始模型。样本数量少的时候最忌讳的是盲目加大训练轮数。数据量不够轮数越多过拟合越快。4. 最小闭环检测、上色、保存先跑通一条完整链路4.1 单张图片预训练推理这一步是为了验证数据通路。先准备一张古籍图片用预训练模型推理看看能不能得到正常的检测框。from ultralytics import YOLO model YOLO(yolo11n.pt) # nano 版本显存要求最低 results model.predict( book_001.jpg, saveTrue, conf0.25, iou0.45, projectruns/predict, namecheck ) print(len(results[0].boxes))这里有几个参数值得理解conf 是置信度阈值低于阈值的框会被过滤。第一次跑可以设低一点比如 0.2看看模型到底检测出什么。iou 是 NMS 去重阈值值越大越容易保留重叠框值越小越容易只留一个。project 和 name 控制输出目录不要把结果都丢到默认目录里否则后面批量跑会乱。4.2 从检测结果生成上色任务拿到检测框后有两个方向。一种是把检测框内的区域裁剪出来逐个送入上色模型再把结果贴回原图。这种方法简单但训练出的模型看不到全局结构颜色可能不统一。另一种是生成一张“区域 mask”把不同类别的区域标上不同编号然后送入条件上色模型。条件上色模型不仅看灰度图还看区域 mask让模型知道哪些区域属于人物、哪些属于山水、哪些属于背景。这样上色时有全局语义颜色过渡会更自然。第一次实验我建议你先用裁剪法。代码逻辑简单排查问题方便。等整条链路稳定后再升级成 mask 引导法。项目是一步一步长出来的不是一上来就设计成完美架构。4.3 保存结果的规范路径、命名、覆盖策略Demo 阶段直接把结果保存到当前目录没问题。但一旦你要跑几十张、几百张图片就必须提前规范结果保存。最少要规定三件事输入图片按原始文件名读取。输出结果放到独立目录比如 output/det 和 output/colorized。同一张图片重复运行时不要直接覆盖建议加时间戳或者批次号。这样做的原因是如果后面发现某个参数出了问题你想回溯哪些图片是用旧参数生成的、哪些是新参数生成的会发现当时保存的路径和批次信息决定一切。没有组织好输出排查成本会翻几倍。注意第一次跑通最小闭环时先不要追求效果也不要马上改模型结构。只要检测框正常、上色模块能跑、结果能保存这个阶段就算完成。5. 训练一个属于古籍场景的 YOLOv11 模型5.1 选择模型规模和预训练权重YOLOv11 有一系列不同规模的型号常见的是 n、s、m、l、x。规模越大参数量越多推理越慢显存占用越高。模型规模推荐场景显存参考判断思路n快速验证、低显存设备小适合先跑通流程s入门项目、中等数据量中比较均衡m数据量较大、精度需求高较大适合正式训练尝试l / x高精度研究或宽裕部署环境大需要较强算力第一次训练建议直接从 n 或 s 开始。先用小规模模型验证数据标注是否合理如果小模型已经能大致框出目标再考虑换大模型。不要一开始就选最大模型然后卡在显存不足的报错里。5.2 训练参数图像大小、批次、训练轮数、学习率训练参数里最常被问的就是训练轮数。这个没有固定答案但有一个通用判断思路。从 100 轮开始比较稳妥。每跑完一定轮数看验证集 loss 和 mAP 变化。如果训练 loss 持续下降验证 loss 开始上升说明已经过拟合要提前停止。如果训练轮数已经很高但验证效果还没到预期问题往往不在轮数而在数据量或标注质量。图像大小也很关键。古籍图片大且细节多但直接输入 1280 尺寸会很吃显存。先用 640 尺寸跑一版看检测效果。如果小目标、印章、细纹没检出来再提高到 960 或 1280并同步减小 batch size。batch size 决定了每次迭代看多少张图。显存大就调大显存小就调小。两个原则batch size 不要小到让 loss 震荡剧烈也不要大到训练一个 epoch 要等太久。学习率一般不用手动调整太多先用框架默认值。出现问题后再按十倍阶梯微调。5.3 验证指标和过拟合判断训练过程中不要只盯着一两张图的检测效果。要看的硬指标包括Precision预测出来的框里有多少是对的。Recall真实的目标里有多少被检测出来。mAP50 和 mAP50-95综合衡量检测精度。训练 loss 和验证 loss 的曲线。判断过拟合最简单的办法训练 loss 很低但验证 mAP 很低或者验证 loss 开始回升基本就是过拟合。此时不要继续加训练轮数正确做法是增加样本、加强数据增强、缩小模型、或在训练中加正则化。哪怕只是简单调整输入图像尺寸也可能让过拟合延迟出现。6. 批量推理、ONNX 导出和 C 部署真正脱离 Notebook6.1 批量处理目录图片能单张出图不代表能做批量处理。批量处理要考虑三件事目录遍历、失败重试、结果命名。一个简单的批量推理逻辑如下from pathlib import Path from ultralytics import YOLO model YOLO(runs/train/exp/best.pt) input_dir Path(data/input) output_dir Path(data/output) output_dir.mkdir(exist_okTrue) for img_path in sorted(input_dir.glob(*.jpg)): try: result model.predict( str(img_path), saveTrue, projectstr(output_dir / det), nameimg_path.stem ) except Exception as e: print(ffailed: {img_path.name} - {e})不要一上来就搞多线程并发。先按单线程跑一批确认所有图片都能正常处理。如果单线程在中间某一张卡住你要能定位到具体图片再检查那张图是不是分辨率异常、文件名特殊、内容缺失。6.2 ONNX 导出和精度转换训练完成后如果只在 Python 脚本里调用还能接受。但真实部署环境常常要求用 C 调用或者不能安装完整 PyTorch 环境。这时就需要导出模型。导出 ONNX 的通用思路如下from ultralytics import YOLO model YOLO(runs/train/exp/best.pt) model.export(formatonnx, opset12, halfTrue, simplifyTrue)导出时要考虑推理平台是否支持 FP16。如果部署设备对 FP16 支持不好就把 half 关掉使用 FP32。显存紧张再考虑量化到 INT8。但 INT8 量化对精度影响明显古籍这类细节密集的图像量化前一定要做对比验证。ONNX 的导出成功不代表部署没有问题。常见问题是动态输入尺寸、opset 版本、自定义模块不被转换。一个比较稳的办法是导出后先使用 ONNX Runtime 跑一遍单张图确认结果和 PyTorch 推理结果接近再进入 C 环节。6.3 C 部署中的常见坑C 部署不是简单调一个库。它会用到 ONNX Runtime 的 C API或者 OpenCV 的 DNN 模块。这里面的核心坑有三类。第一预处理不一致。PyTorch 推理和 C 推理如果对图像 resize、归一化、通道顺序的处理不一致检测结果会差很多。建议固定一套预处理代码两边完全一致。第二内存管理。C 里要自己处理 cv::Mat 的释放如果循环推理时内存不断增长很可能是有 Mat 没有释放。第三动态尺寸问题。有些模型导出时是固定尺寸那 C 端必须先把输入图片 resize 到相同尺寸再进行推理。不要认为推理框架会自动帮你处理任意尺寸。建议第一次做 C 部署时先把“单张图片从读取到输出检测框”按最小步骤写通再谈批量和高并发。C 的调试成本比 Python 高步子越小越好。7. 落地排查从“能出图”到“能稳定出图”7.1 小目标检测优化古籍里的小目标很多比如印章、人物面部、衣纹细节。小目标检测效果差最先要检查的是图像输入尺寸。如果输入尺寸只有 320小目标直接丢失特征换成 640 或 960 会立刻改善。第二个要检查的是数据集标注。小目标的真实框如果标注不准确模型学不到正确位置。建议把标注结果可视化叠在图片上人工抽查不要只看数字指标。第三个方向是增强策略。马赛克增强、随机裁剪、复制粘贴增强对小目标逻辑有帮助。但古籍图像涉及完整语义裁剪太碎会丢失上下文。应该做一些局部放大和随机平移而不是粗暴地切掉大块区域。7.2 日志、输出一致性与失败重试批量跑的时候稳定比速度重要。打开日志记录每张图片的输入路径、开始时间、结束时间、是否成功。尤其要把失败图片单独写到日志里方便统一复查。输出一致性也要注意。多测试几轮之后如果发现同一张图每次输出的检测结果数量不同大多是随机增强或推理时没有固定随机种子。训练时保证数据增强可复现推理时不加载训练增强输出就会稳定很多。失败重试要设置上限。不要遇到一张坏图就无限重试。比如最多重试三次三次都不行就跳过并且写入日志最后统一生成失败清单。7.3 排查链路输入、环境、参数、数据很多问题看起来像模型能力不足实际是前置条件没做好。我给自己的排查顺序一般是先看输入图片是否完整、格式是否支持、路径是否正确。再看环境依赖比如 CUDA、PyTorch、ONNX Runtime 的版本兼容性。接着看参数比如 conf、iou、batch size、图片尺寸。最后才怀疑数据和模型本身。这个顺序能避免很多浪费时间的事。比如图片路径里带了中文Windows 下很容易读取失败比如某个依赖版本不匹配导致 GPU 推理报错你以为自己模型写错了折腾半天才发现是环境问题。把排查顺序固定下来你就不会在第一次遇到报错时手忙脚乱。结语这个项目真正做完以后你收获的绝不仅仅是一张能自动上色的古籍图。你会在整个过程里把检测、分割、数据标注、训练、验证、导出、C 部署、批量处理、问题排查全部走一遍。这套流程放到任何其他 CV 场景里都是通用的骨架。如果你只跑官方 demo永远只能看到那几行优美的输出只有自己把脏活累活干一遍才知道深度学习项目里真正决定成败的往往不是模型结构而是数据、路径、日志和参数边界。我个人更建议先把单张流程跑稳再谈批量先把小模型跑通再换大模型先把检测主线做好再优化上色效果。这样一步步推进比一开始就要“完美方案”要靠谱得多。 从YOLOv11 Demo到完整CV流水线：古籍上色项目实战拆解
只跑过 YOLOv11 官方 demo 的人脑子里很容易形成一种错觉检测框画得又准又快项目好像就已经成功一半。但等你真拿一批自己的图片进来需要自建数据、训练、导出、部署、批量运行的时候才会发现所谓“demo”只是把别人训练好的权重调用了一下模型本身、数据处理、输出管理、异常处理全都是空的。这篇要拆解的是一个围绕 YOLOv11 搭建完整 CV 系统的项目应用场景是古籍上色。这里先把概念说清楚YOLOv11 不是上色模型它是目标检测和分割器上色由额外的条件生成模块完成。但在真实项目里检测精度决定上色范围上色质量又依赖后续处理你必须把整个流程串起来。这篇重点想说明三件事怎么从零准备环境、怎么把数据和标注整理成训练集、以及怎么把单张图片脚本改造成可批量推理和部署的完整系统。写这篇的目的很简单就是希望你能从“会调包跑 demo”走到“能自己搭一套完整 CV 流水线”哪怕项目不大过程也是完整的。1. 先搞清楚为什么是 YOLOv11为什么是古籍上色为什么不是 Demo1.1 YOLOv11 在项目中实际负责哪一环YOLOv11 属于目标检测模型它的工作是在图片里定位物体并告诉你是哪一类。在古籍上色项目里它可以负责检测人脸、衣服、花鸟、山水、印章、文字区域等等。检测结果是一个个带类别和坐标的框或者是更精细的分割掩码。上色并不是 YOLOv11 直接输出的。常见的做法是先用 YOLOv11 把需要上色的区域框出来再把框内区域送去上色模型比如基于生成对抗网络或扩散模型的图像翻译网络最终得到一张彩色结果。YOLOv11 在这里起到“区域定位”和“语义引导”的作用。很多人一开始会把项目理解成“用 YOLOv11 自动给黑白古籍上色”这是错的。如果按这个错误理解去搜代码最后只会找到一堆目标检测的官方 demo完全不知道上色模块应该往哪里接。正确理解是YOLOv11 负责提供区域限制上色负责提供颜色生成。两者协作才是一条完整的 CV 链路。1.2 判断一个 CV 项目是不是“玩具”的三个标准我判断一个 CV 项目能不能拿得出手就看三个问题能不能改源码和训练策略而不只是调用推理接口。能不能用自己的数据重新训练模型。能不能脱离 Notebook做批量推理和模型部署。如果三个都是否那它就是典型的玩具项目。你只是在别人的权重上做了一次预测和你写一段“读取显示图片”的入门代码没有本质区别。所以这篇文章的实践目标不是“跑出彩色图”而是把这三个问题全部打通。哪怕最终效果还达不到商用水平你至少知道每一步怎么走。1.3 古籍上色为什么适合当练习项目古籍上色这个场景非常有练习价值。它不是普通自然图像通常包含大量风格化元素工笔画、水墨画、版画、手写文字、红色印章。类别多样甚至很多类别在公开数据集里根本找不到所以你必须自己做数据。这个特点带来了真实业务中常见的挑战数据量少、类别不均衡、标注噪声高、图像尺寸大、细节多。这些问题在工业项目里非常常见但在官方 demo 里几乎遇不到。拿它练手你练的不是“调包”而是数据处理和模型选型的综合能力。2. 环境准备从 Python 虚拟环境到显存精度选型2.1 Python、CUDA、PyTorch、Ultralytics 的最小版本组合不管在 Windows 还是 Linux 上我都不建议直接在系统全局环境里配深度学习环境。第一次装环境最容易出的问题就是依赖冲突比如 PyTorch 版本和 CUDA 版本对不上或者 opencv 版本干扰其他库。建议从这个组合开始Python 3.10 或 3.11。独立虚拟环境可以使用 venv 或 conda。PyTorch 版本根据本机 CUDA 版本选择CPU 版本和 GPU 版本分开装。Ultralytics 提供 YOLOv11 的模型定义和训练推理接口安装方式通常就是 pip 安装 ultralytics。需要额外确认 opencv-python、numpy、pandas、matplotlib 等依赖是否正常。环境安装完成后第一件事不是跑大模型而是跑一个小样例确认 GPU 可用、显存能分配、图片能正常读写。在 Windows 上有一个常见坑路径分隔符。Windows 默认路径用反斜杠很多代码在 Linux 上能跑到 Windows 就报文件找不到。建议在代码里统一用 pathlib 或正斜杠拼接路径避免这种低级错误。2.2 显存占用和浮点数精度FP32、FP16、TF32、BF16 怎么选在训练和推理时你一定会遇到浮点数格式的选择问题。这里不展开讲底层原理只说你实际会碰到的判断逻辑。精度格式主要用途优点需要注意的地方FP32常规训练、常规推理精度最稳妥显存占用高速度相对慢FP16混合精度训练、GPU 推理显存占用减半速度提升明显可能出现数值溢出需要动态缩放BF16部分新一代 GPU 训练数值范围大比 FP16 更稳低比特位下精度下降老显卡不支持TF32部分 NVIDIA GPU 的矩阵运算兼顾速度和精度对最终结果的影响需要实测确认判断标准很简单如果你的显存不够先把训练推理改为 FP16如果你的检测框出现大量消失或 loss 不稳定再换回 FP32 或改用 BF16。实际项目里我会先用 FP16 跑一个短训练确认 loss 能正常下降再继续。不要一上来就把所有精度参数都调成最低那样省了显存但可能换来一堆莫名其妙的错检。2.3 跑通环境后先做什么检查环境装好以后不要直接训练。先跑一个最小脚本from ultralytics import YOLO model YOLO(yolo11n.pt) results model.predict(test.jpg, saveTrue) print(results[0].boxes.cls)如果能看到类别编号和结果图说明安装链路基本是通的。这一步看似简单但能帮你区分“模型问题”和“环境问题”。以后再出任何错先回来跑这个最小脚本如果最小脚本正常说明问题大概率出在你的数据、路径或参数上。3. 数据与标注把古籍图片变成模型能学的结构化数据3.1 古籍图像的收集、筛选与预处理古籍图片的来源通常很杂可能是扫描件、拍照件、公开数字图书馆资源、私人收藏翻拍图。采集之后第一件事不是标注而是清洗。清洗包括去掉有水印、模糊、严重变形、内容重复的图片。把超大扫描件切成小图或者统一缩放否则训练时占用显存太高。去除纯文字页除非你确实要检测文字区域。对所有图片做一遍直方图检查过亮过暗的图要么做增强要么先人工筛一遍。预处理不要过度。很多人一上来就做各种滤镜、锐化、自动对比度结果模型学到的不是古籍本身特征而是你制造的图像风格。建议先做最小预处理统一尺寸、统一色彩模式、保持原始语义不变。3.2 标注目标检测框还是分割掩码YOLOv11 支持检测框也支持实例分割。在古籍上色项目里不同上色需求对标注的要求不一样。如果你只负责定位人物、花鸟、远景、近景检测框足够。框的优点是标注快缺点是边界不精细上色时容易把背景颜色溢出到物体上。如果你的上色模型需要知道物体边界那就得用分割掩码。标一个多边形的成本高于拉一个矩形框但对后续上色效果帮助很大。我的建议是第一次做项目时先用检测框把类别跑通整个链路稳定后再考虑升级为分割标注。不要一开始就追求全分割否则你会被标注工作累死还没跑到训练就放弃了。标注工具可以使用常见的开源标注软件导出为 YOLO 格式的 txt 文件。每个图片对应一个同名 txt每行是类别编号 中心点 x 中心点 y 框宽 框高。3.3 样本数量少时的数据增强策略古籍数据量通常很少。样本少不是不能训练而是要控制方法。第一优先使用预训练权重。YOLOv11 官方权重在 COCO 等大型数据集上训练过虽然古籍不是它的主要应用场景但它的基础特征提取能力是可用的。你只需要微调后面的分类头。第二使用数据增强。YOLO 训练框架自带很多增强选项比如随机翻转、颜色扰动、缩放、平移、马赛克增强。但古籍图片不建议做过度旋转因为很多古籍里的文字方向是固定的旋转后语义会出错。第三如果样本实在少用半自动标注。先用预训练模型跑一遍把置信度高的结果过滤出来人工修正再进入训练集。这个方法能明显减少人工标注量但前提是你有一个还算靠谱的初始模型。样本数量少的时候最忌讳的是盲目加大训练轮数。数据量不够轮数越多过拟合越快。4. 最小闭环检测、上色、保存先跑通一条完整链路4.1 单张图片预训练推理这一步是为了验证数据通路。先准备一张古籍图片用预训练模型推理看看能不能得到正常的检测框。from ultralytics import YOLO model YOLO(yolo11n.pt) # nano 版本显存要求最低 results model.predict( book_001.jpg, saveTrue, conf0.25, iou0.45, projectruns/predict, namecheck ) print(len(results[0].boxes))这里有几个参数值得理解conf 是置信度阈值低于阈值的框会被过滤。第一次跑可以设低一点比如 0.2看看模型到底检测出什么。iou 是 NMS 去重阈值值越大越容易保留重叠框值越小越容易只留一个。project 和 name 控制输出目录不要把结果都丢到默认目录里否则后面批量跑会乱。4.2 从检测结果生成上色任务拿到检测框后有两个方向。一种是把检测框内的区域裁剪出来逐个送入上色模型再把结果贴回原图。这种方法简单但训练出的模型看不到全局结构颜色可能不统一。另一种是生成一张“区域 mask”把不同类别的区域标上不同编号然后送入条件上色模型。条件上色模型不仅看灰度图还看区域 mask让模型知道哪些区域属于人物、哪些属于山水、哪些属于背景。这样上色时有全局语义颜色过渡会更自然。第一次实验我建议你先用裁剪法。代码逻辑简单排查问题方便。等整条链路稳定后再升级成 mask 引导法。项目是一步一步长出来的不是一上来就设计成完美架构。4.3 保存结果的规范路径、命名、覆盖策略Demo 阶段直接把结果保存到当前目录没问题。但一旦你要跑几十张、几百张图片就必须提前规范结果保存。最少要规定三件事输入图片按原始文件名读取。输出结果放到独立目录比如 output/det 和 output/colorized。同一张图片重复运行时不要直接覆盖建议加时间戳或者批次号。这样做的原因是如果后面发现某个参数出了问题你想回溯哪些图片是用旧参数生成的、哪些是新参数生成的会发现当时保存的路径和批次信息决定一切。没有组织好输出排查成本会翻几倍。注意第一次跑通最小闭环时先不要追求效果也不要马上改模型结构。只要检测框正常、上色模块能跑、结果能保存这个阶段就算完成。5. 训练一个属于古籍场景的 YOLOv11 模型5.1 选择模型规模和预训练权重YOLOv11 有一系列不同规模的型号常见的是 n、s、m、l、x。规模越大参数量越多推理越慢显存占用越高。模型规模推荐场景显存参考判断思路n快速验证、低显存设备小适合先跑通流程s入门项目、中等数据量中比较均衡m数据量较大、精度需求高较大适合正式训练尝试l / x高精度研究或宽裕部署环境大需要较强算力第一次训练建议直接从 n 或 s 开始。先用小规模模型验证数据标注是否合理如果小模型已经能大致框出目标再考虑换大模型。不要一开始就选最大模型然后卡在显存不足的报错里。5.2 训练参数图像大小、批次、训练轮数、学习率训练参数里最常被问的就是训练轮数。这个没有固定答案但有一个通用判断思路。从 100 轮开始比较稳妥。每跑完一定轮数看验证集 loss 和 mAP 变化。如果训练 loss 持续下降验证 loss 开始上升说明已经过拟合要提前停止。如果训练轮数已经很高但验证效果还没到预期问题往往不在轮数而在数据量或标注质量。图像大小也很关键。古籍图片大且细节多但直接输入 1280 尺寸会很吃显存。先用 640 尺寸跑一版看检测效果。如果小目标、印章、细纹没检出来再提高到 960 或 1280并同步减小 batch size。batch size 决定了每次迭代看多少张图。显存大就调大显存小就调小。两个原则batch size 不要小到让 loss 震荡剧烈也不要大到训练一个 epoch 要等太久。学习率一般不用手动调整太多先用框架默认值。出现问题后再按十倍阶梯微调。5.3 验证指标和过拟合判断训练过程中不要只盯着一两张图的检测效果。要看的硬指标包括Precision预测出来的框里有多少是对的。Recall真实的目标里有多少被检测出来。mAP50 和 mAP50-95综合衡量检测精度。训练 loss 和验证 loss 的曲线。判断过拟合最简单的办法训练 loss 很低但验证 mAP 很低或者验证 loss 开始回升基本就是过拟合。此时不要继续加训练轮数正确做法是增加样本、加强数据增强、缩小模型、或在训练中加正则化。哪怕只是简单调整输入图像尺寸也可能让过拟合延迟出现。6. 批量推理、ONNX 导出和 C 部署真正脱离 Notebook6.1 批量处理目录图片能单张出图不代表能做批量处理。批量处理要考虑三件事目录遍历、失败重试、结果命名。一个简单的批量推理逻辑如下from pathlib import Path from ultralytics import YOLO model YOLO(runs/train/exp/best.pt) input_dir Path(data/input) output_dir Path(data/output) output_dir.mkdir(exist_okTrue) for img_path in sorted(input_dir.glob(*.jpg)): try: result model.predict( str(img_path), saveTrue, projectstr(output_dir / det), nameimg_path.stem ) except Exception as e: print(ffailed: {img_path.name} - {e})不要一上来就搞多线程并发。先按单线程跑一批确认所有图片都能正常处理。如果单线程在中间某一张卡住你要能定位到具体图片再检查那张图是不是分辨率异常、文件名特殊、内容缺失。6.2 ONNX 导出和精度转换训练完成后如果只在 Python 脚本里调用还能接受。但真实部署环境常常要求用 C 调用或者不能安装完整 PyTorch 环境。这时就需要导出模型。导出 ONNX 的通用思路如下from ultralytics import YOLO model YOLO(runs/train/exp/best.pt) model.export(formatonnx, opset12, halfTrue, simplifyTrue)导出时要考虑推理平台是否支持 FP16。如果部署设备对 FP16 支持不好就把 half 关掉使用 FP32。显存紧张再考虑量化到 INT8。但 INT8 量化对精度影响明显古籍这类细节密集的图像量化前一定要做对比验证。ONNX 的导出成功不代表部署没有问题。常见问题是动态输入尺寸、opset 版本、自定义模块不被转换。一个比较稳的办法是导出后先使用 ONNX Runtime 跑一遍单张图确认结果和 PyTorch 推理结果接近再进入 C 环节。6.3 C 部署中的常见坑C 部署不是简单调一个库。它会用到 ONNX Runtime 的 C API或者 OpenCV 的 DNN 模块。这里面的核心坑有三类。第一预处理不一致。PyTorch 推理和 C 推理如果对图像 resize、归一化、通道顺序的处理不一致检测结果会差很多。建议固定一套预处理代码两边完全一致。第二内存管理。C 里要自己处理 cv::Mat 的释放如果循环推理时内存不断增长很可能是有 Mat 没有释放。第三动态尺寸问题。有些模型导出时是固定尺寸那 C 端必须先把输入图片 resize 到相同尺寸再进行推理。不要认为推理框架会自动帮你处理任意尺寸。建议第一次做 C 部署时先把“单张图片从读取到输出检测框”按最小步骤写通再谈批量和高并发。C 的调试成本比 Python 高步子越小越好。7. 落地排查从“能出图”到“能稳定出图”7.1 小目标检测优化古籍里的小目标很多比如印章、人物面部、衣纹细节。小目标检测效果差最先要检查的是图像输入尺寸。如果输入尺寸只有 320小目标直接丢失特征换成 640 或 960 会立刻改善。第二个要检查的是数据集标注。小目标的真实框如果标注不准确模型学不到正确位置。建议把标注结果可视化叠在图片上人工抽查不要只看数字指标。第三个方向是增强策略。马赛克增强、随机裁剪、复制粘贴增强对小目标逻辑有帮助。但古籍图像涉及完整语义裁剪太碎会丢失上下文。应该做一些局部放大和随机平移而不是粗暴地切掉大块区域。7.2 日志、输出一致性与失败重试批量跑的时候稳定比速度重要。打开日志记录每张图片的输入路径、开始时间、结束时间、是否成功。尤其要把失败图片单独写到日志里方便统一复查。输出一致性也要注意。多测试几轮之后如果发现同一张图每次输出的检测结果数量不同大多是随机增强或推理时没有固定随机种子。训练时保证数据增强可复现推理时不加载训练增强输出就会稳定很多。失败重试要设置上限。不要遇到一张坏图就无限重试。比如最多重试三次三次都不行就跳过并且写入日志最后统一生成失败清单。7.3 排查链路输入、环境、参数、数据很多问题看起来像模型能力不足实际是前置条件没做好。我给自己的排查顺序一般是先看输入图片是否完整、格式是否支持、路径是否正确。再看环境依赖比如 CUDA、PyTorch、ONNX Runtime 的版本兼容性。接着看参数比如 conf、iou、batch size、图片尺寸。最后才怀疑数据和模型本身。这个顺序能避免很多浪费时间的事。比如图片路径里带了中文Windows 下很容易读取失败比如某个依赖版本不匹配导致 GPU 推理报错你以为自己模型写错了折腾半天才发现是环境问题。把排查顺序固定下来你就不会在第一次遇到报错时手忙脚乱。结语这个项目真正做完以后你收获的绝不仅仅是一张能自动上色的古籍图。你会在整个过程里把检测、分割、数据标注、训练、验证、导出、C 部署、批量处理、问题排查全部走一遍。这套流程放到任何其他 CV 场景里都是通用的骨架。如果你只跑官方 demo永远只能看到那几行优美的输出只有自己把脏活累活干一遍才知道深度学习项目里真正决定成败的往往不是模型结构而是数据、路径、日志和参数边界。我个人更建议先把单张流程跑稳再谈批量先把小模型跑通再换大模型先把检测主线做好再优化上色效果。这样一步步推进比一开始就要“完美方案”要靠谱得多。