基于 YOLO11n 的马铃薯外观品质缺陷检测系统

基于 YOLO11n 的马铃薯外观品质缺陷检测系统

本文介绍一个面向农产品加工、分选线与入库质检场景的目标检测应用。项目以 YOLO11n 为检测模型、Streamlit 为交互界面，支持单张图片、批量图片与视频输入，可识别瘀伤薯、裂纹薯、正常马铃薯和发芽薯四类目标，输出边界框、类别与置信度。

一、项目背景：为什么要做马铃薯外观品质检测

马铃薯是重要的薯类作物，收获、储运和加工环节中的外观变化直接影响商品等级与售价。瘀伤、开裂、发芽等问题在人工分选线上虽然可以被有经验的工人识别，但实际生产中存在一些长期难题：

1. 人眼分级标准不完全一致：不同工人对"轻微裂纹"和"明显裂纹"的边界理解不同，容易导致同批次商品分级结果波动。
2. 连续作业导致疲劳：分选线通常需要长时间盯看，工人注意力下降后漏检率上升，尤其在薯块滚动速度较快时。
3. 缺陷样本难以回溯：人工记录多为抽检摘要，一旦出现客诉，很难快速定位问题批次的具体图像证据。
4. 发芽判断有滞后性：轻度发芽在薯块堆叠时容易被遮挡，等到肉眼明显可见时往往已经扩散。

本项目将上述流程封装成一个可直接运行的 Web 应用。用户不需要编写推理脚本，也不必逐张调用命令行程序；打开浏览器即可上传图像，查看原图与检测图，并在需要时批量处理图片或分析视频。

视频演示与源码下载

https://www.bilibili.com/video/BV1RgnG62Ehp/

包含： 📦完整项目源码 📦 预训练 模型权重

🗂️数据集

项目运行效果

• *Web 界面总览

  

  
  

• *单张图片识别效果

  

  
  

• *批量图片合规检查

  

  
  

二、项目功能与检测类别

系统使用 YOLO11n 权重执行目标检测，数据集配置为四个类别：

应用提供以下主要能力：

1. 单张图片检测：上传 JPG、PNG 等常见格式，输出带边界框的检测图与逐目标明细。
2. 批量图片检测：一次提交多张图片，也支持 ZIP 图片包；应用逐张推理并汇总结果，便于快速筛查一批来料。
3. 视频检测：上传视频后按帧执行检测，输出带标注的结果视频与分析信息。
4. 摄像头输入：通过应用界面调用可用摄像头进行实时检测。浏览器权限、运行环境和摄像头接入方式会影响此功能可用性。
5. 阈值调节：侧栏提供置信度阈值滑块。阈值调低通常保留更多候选框，可能增加误检；调高则过滤弱候选，可能漏掉较小或模糊目标。
6. 结果查看与导出：除标注图外，还可查看类别、置信度、边界框坐标等表格信息，方便复核、导出和整理。

需要说明：检测结果是图像层面的模型判断，不等同于对整批马铃薯商业等级的自动结论。模型输出应与人工抽检、感官评价标准及加工要求结合使用。

三、系统整体架构

系统采用清晰的分层结构：浏览器负责上传与展示，Streamlit 负责交互与流程控制，Ultralytics YOLO 执行模型推理，OpenCV、Pandas 等组件承担图像处理与结果整理。

用户 / 浏览器
    │ 上传图片、图片压缩包或视频，调整置信度阈值
    ▼
Streamlit 应用（app/streamlit_app.py）
    │ 输入校验、模式分发、进度提示、结果展示与下载
    ▼
YOLO11n 推理模型（model/best.pt）
    │ 预处理 → 前向推理 → 置信度筛选 → NMS
    ▼
结果后处理
    │ 类别名称、置信度、xyxy 坐标、标注图与汇总数据
    ▼
浏览器展示 / 下载结果

项目界面配置集中在 configs/project.yaml，包括应用标题、简介、主题色、默认推理阈值、批量上限等。将展示信息与推理代码分离后，修改标题或颜色通常不需要改动核心逻辑。

四、YOLO 推理流程简述

YOLO 属于单阶段目标检测方法：模型在一次前向过程中同时预测目标位置与类别，不需要像两阶段检测那样先生成候选区域再逐个分类，适合构建交互式检测应用。

对一张输入图像，典型推理过程包括：

1. 图像预处理：读取文件并转换为模型可接收的张量，按输入尺寸进行缩放与填充。
2. 模型前向计算：YOLO11n 提取特征并生成类别分数与边界框候选。
3. 置信度过滤：按当前阈值剔除低分候选框。界面默认值来自项目配置，可通过侧栏调整。
4. 非极大值抑制（NMS）：对高度重叠的候选框去重，减少同一薯块被重复框出的情况。
5. 结果绘制与结构化：将类别、置信度和坐标整理为表格，同时生成叠加检测框的图像。

薯块检测与常规大型物体检测存在差异。真实场景中，多颗马铃薯可能相互堆叠遮挡；表皮反 光 会让薯块与背景亮度接近；瘀伤和裂纹往往只体现在局部纹理变化，对相机分辨率与光照均匀性要求较高。因此拍摄方式、背景颜色、光源方向与目标尺度都会影响模型输出。部署时应先用实际相机和目标环境验证，不宜仅凭少量示例判断效果。

五、核心推理代码解读

下面摘取项目图像推理函数的主要逻辑。它调用 Ultralytics 的 model.predict，再把结果转换为标注图和 Pandas 表格：

def infer_image_path(model: YOLO, image_path: Path, conf: float) -> tuple:
    result = model.predict(str(image_path), conf=conf, verbose=False)[0]
    annotated = result.plot()
    rows = []
    if result.boxes is not None:
        for box in result.boxes:
            cls_id = int(box.cls.item())
            confidence = float(box.conf.item())
            x1, y1, x2, y2 = [float(v) for v in box.xyxy[0].tolist()]
            rows.append({
                "class_id": cls_id,
                "class_name": result.names[cls_id],
                "confidence": round(confidence, 4),
                "x1": round(x1, 1), "y1": round(y1, 1),
                "x2": round(x2, 1), "y2": round(y2, 1),
            })
    return annotated[:, :, ::-1], pd.DataFrame(rows)

关键点如下：

• model.predict(..., conf=conf) 将用户设置的阈值传入推理接口，控制候选框保留范围。
• result.plot() 绘制类别标签与边界框，避免另行编写绘图逻辑。
• result.boxes 包含类别索引、置信度与坐标；坐标采用 xyxy 表示，即左上角与右下角位置。
• result.names[cls_id] 将类别索引转为模型类别名。类别名称与顺序必须与权重训练时保持一致，否则会出现"框对类错"。
• Ultralytics 绘图结果通常为 BGR 通道顺序，返回前用 [:, :, ::-1] 转为 RGB，以适配 Streamlit 图像展示。
• 每个检测框整理为字典，最终形成 DataFrame，便于前端展示，也可扩展为 CSV 导出或入库统计。

模型对象通过 Streamlit 的资源缓存机制加载，避免每次交互重复初始化；批量图片与视频流程复用同一实例，并通过临时目录管理上传文件，减少逻辑分散。

六、Streamlit 页面与配置组织

项目页面主要分为三部分：

• 页面顶部：项目名称、马铃薯外观品质检测用途简介与场景标签。
• 侧栏：置信度阈值控制与场景信息。
• 主区域：通过输入类型选择器切换检测流程，显示原图、检测图、分析表格与下载按钮。

推理阈值和界面文案由配置文件读取：inference.conf 为默认置信度，inference.iou 控制重叠框筛选参数，inference.max_batch_images 限制单次批量数量。建议调整参数时一次只改变一个变量，并保留一组代表性图像做对比，避免仅凭单张图片下结论。

当前 UI 不展示整体检测率等模型评测指标卡，重点是实际输入图像后的检测结果、类别与置信度。置信度只反映单个候选框的分数，不能等同于整体准确率；某个框置信度较高，不代表模型在所有光照、角度与背景条件下都有同等表现。

七、快速部署

7.1 环境准备

依赖清单位于 requirements.txt。建议在项目目录创建独立虚拟环境，降低与其他 Python 项目冲突：

python -m venv .venv

Windows PowerShell 激活：

.\.venv\Scripts\Activate.ps1

安装依赖：

pip install -r requirements.txt

若需要浏览器直接播放结果视频，可安装 FFmpeg 并确认命令行可用；图片检测不依赖该组件。

7.2 启动应用

在项目根目录执行：

streamlit run app/streamlit_app.py

浏览器访问：

http://localhost:8501

7.3 局域网访问

如需同一局域网内其他设备访问，可将监听地址设为 0.0.0.0：

streamlit run app/streamlit_app.py --server.address 0.0.0.0 --server.port 8501

其他设备使用运行主机的局域网 IP 与端口访问，例如 http://192.168.x.x:8501。实际 IP 以主机网络配置为准；连接失败时检查设备是否同网段、防火墙是否放行 TCP 端口、路由器是否启用客户端隔离。不要在没有访问控制的情况下将开发用服务直接暴露到公网。

八、使用步骤

1. 启动应用并打开浏览器页面。
2. 在侧栏设置置信度阈值；首次体验可沿用默认值，再根据误检、漏检情况调整。
3. 选择输入方式：单张图片、批量图片、视频或可用摄像头。
4. 上传清晰、目标完整的图像；批量模式可一次选择多个文件或提交 ZIP。
5. 查看标注结果与检测明细。无检测框可能意味着图中无可识别目标，也可能是目标过小、被遮挡或阈值较高。
6. 人工复核后下载需要留存的标注图或结果文件。

九、效果评估与使用边界

训练记录中包含 mAP、Precision、Recall 等评测指标，但 UI 按需求不显示整体检测率。不同指标关注点不同：Precision 看检出目标中正确的比例，Recall 看实际目标中被找到的比例，mAP 综合不同置信度与定位标准下的检测质量。这些指标来自特定数据划分，不能直接等同生产现场表现。

马铃薯检测的域差异比较明显：品种颜色、薯块大小、表皮湿润程度、背景材质、光源色温和相机角度都会改变图像分布。部署前建议准备覆盖不同品种、尺寸、光照、遮挡和背景的现场图像，逐类人工核验模型表现。误检较多时可适当提高阈值，或检查背景是否与样本差异过大；漏检较多时可尝试降低阈值、改善拍摄清晰度与目标尺寸，并持续记录难例供后续评估。

以下情况尤其需要谨慎：

• 薯块只占少量像素、图像压缩严重或主体失焦；
• 多薯堆叠造成相互遮挡；
• 表皮强反光或环境光过暗；
• 裂纹、瘀伤等细微特征在单张图中纹理不足；
• 现场图像与训练样本分布差异明显。

因此，本项目适合作为外观初筛、巡检辅助与原型验证工具；涉及商品分级定价、农药或防腐处理及生产决策时，应由专业人员结合标准与现场情况确认。

十、项目结构与扩展方向

马铃薯外观品质缺陷检测数据集_yolo11n/
├── app/
│   └── streamlit_app.py       # Web 应用与推理交互
├── configs/
│   └── project.yaml           # 页面、主题与推理配置
├── model/
│   └── best.pt                # YOLO11n 检测权重
├── dataset/                   # 数据集图像与标注
├── outputs/                   # 运行时结果目录
├── train/                     # 已有评估与运行产物
├── requirements.txt           # Python 依赖清单
└── README.md                  # 项目使用说明

后续可以从几个方向迭代：第一，接入产线相机或分级设备图像流，减少手工上传；第二，增加按批次、时间段和类别汇总的统计视图，辅助分析缺陷发生规律；第三，为结果加入人工复核状态，区分模型初筛与确认记录；第四，在充分验证性能与隐私要求后，将 推理部署 到边缘设备以降低延迟；第五，建立困难样本回流机制，定期评估模型在不同品种、季节与设备上的泛化表现。

十一、总结

这个项目把 YOLO11n 的薯块外观检测能力封装成一个易部署、可交互的 Streamlit 应用，覆盖单图、批量图片和视频等常用入口，并提供置信度调节、结果可视化与结构化明细。它展示了从权重加载、单图推理、结果转换到 Web 交互的完整工程链路。

对初学者，这个项目适合学习目标检测模型如何接入实际应用：模型只负责产生预测，完整产品还需要处理上传、绘制、表格整理、配置管理与部署访问。对农产品加工与品控使用者，系统可作为外观初筛辅助工具，但最终分级判断仍应结合人工抽检与商品标准执行。