数集仓 · 入门教学案例 · V1.0.2

给果干照片画上检测框，
完成你的第一个视觉项目

这份教程解决一个具体问题：怎样把“有图片、有标注”变成“能运行、能展示、能解释”的课程项目。你将先使用随包模型得到预测结果，再亲手准备数据、训练模型和整理实验。

1. 解压到一个固定文件夹

本教程面向 Windows、Python 3.12、CPU。无需独立显卡。安装环境需要联网和数 GB 空间；完成安装后，演示使用包内模型和图片，不需要再次下载模型。

1. 右键项目 ZIP，选择“全部解压”。不要在 ZIP 预览窗口中直接双击程序。
2. 建议解压到 D:\citrus_project。没有 D 盘可用 C:\citrus_project。
3. 进入能看到 INSTALL.cmd 的文件夹。若里面还套一层项目文件夹，请继续进入。
4. 在文件夹空白处右键，选择“在终端中打开”。以下以 PowerShell 为例。

Set-Location 'D:\citrus_project'
Get-ChildItem

如果目录不同，只修改第一行的目录。复制代码框中的命令，逐行执行，不要复制代码框外的说明文字。

citrus_project/
├── 开始学习.html          ← 本教程，双击浏览
├── INSTALL.cmd           ← 安装独立环境
├── START_DEMO.cmd        ← 启动本机演示
├── install_env.py / check_environment.py
├── demo.py / demo.html / project_runtime.py
├── prepare_dataset.py / run_yolo.py
├── requirements.txt / package-manifest.json
├── data/dried-citrus-fruits-dataset.zip
├── models/citrus-best.pt  ← 30 轮实验模型
├── models/yolo26n.pt      ← 从头开展教学训练的预训练权重
├── samples/              ← 两张演示原图
├── examples/             ← 真实实验记录及成功、失败图片
├── reference/            ← 固定划分与原始参数记录
└── licenses/             ← 开源许可与数据来源

2. 第一次安装：每种结果分别怎么处理

2.0 先运行 INSTALL.cmd，识别当前状态

1. 在解压后的项目文件夹里找到 INSTALL.cmd，双击。
2. 出现黑色窗口是正常的，这就是显示安装过程的终端。先读最后几行，不要看到“按任意键”就认为装好了。
3. 新版会检查项目环境、Python Launcher、常见安装位置和已有应用的可用 Python，要求 3.12 且为 64 位；不会改动其他软件的 Python。

2.1 没有找到 Python，具体怎样安装？

如果已经显示“已找到”，跳到 2.2。只有出现“未开始安装”才需要这一步。不要为了这个案例卸载 ArcGIS、其他项目或其他版本的 Python。

1. 用浏览器打开 Python 官方 3.12.10 下载页。这是可提供传统 Windows 安装器的 3.12 版本；页面会列出后续安全版本，有可用的更新版 3.12 环境也可以由安装入口检查识别。包内原实验使用 3.12.14，版本与结果需如实记录。
2. 向下找到 Files 区域，选择 Windows installer (64-bit)。普通 Intel / AMD Windows 电脑使用这一项；不要选 source、embeddable、32-bit 或 ARM64。本案例未验证 ARM 电脑。
3. 下载后打开安装程序。确认标题是 Python 3.12，勾选 Add python.exe to PATH，保留默认的 Launcher 选项，再点 Install Now。使用默认的个人安装目录即可。
4. 等待出现 Setup was successful，点 Close。如果显示安装错误，不要继续本教程，先记录该错误。
5. 回到项目文件夹，重新双击 INSTALL.cmd。新版会检查默认安装位置，不要求你先手工修改系统环境变量。

$env:PYTHON312_EXE = 'C:\你的实际安装目录\python.exe'
.\INSTALL.cmd

2.2 项目依赖正在安装：哪些需要等，哪些不用等？

安装器创建当前目录下的 .venv，按 5 个阶段显示中文状态：创建环境 → 安装 CPU 模型依赖 → 安装其他依赖 → 检查依赖冲突 → 校验文件并实际预测一张图。首次需要联网和数 GB 空间，不是免安装便携版；不同网络和电脑耗时不同。

• 看见 Downloading、Installing collected packages 或阶段变化：继续等，不要关闭窗口。
• 每隔一段时间出现“仍在运行”：子进程还没有结束，但不保证下载字节正在增长。若约 10 分钟没有任何新下载或安装信息，可先检查网络和 outputs/install.log 的最后几行；这不是自动判失败的时限。
• 确实需要中断时在终端按 Ctrl+C；恢复网络后重新双击 INSTALL.cmd，安装器会检查复用已完成的依赖。不要删除数据或模型来修复网络错误。
• 出现“安装失败”：已经停止，继续等待无效；按第 8 节处理。

完整依赖安装日志在 outputs/install.log。如果连 Python 都未找到，Python 安装器尚未启动，因此没有这份日志也是正常的。只有明确安装成功后，按任意键关闭安装窗口，再进入第 3 步。

3. 快速体验：先用模型得到一张预测图

1. 确认上一节安装成功后，双击 START_DEMO.cmd。首次误点启动文件时，新版会自动进入安装；如果安装失败，仍需先按提示修复。熟悉终端的用户也可用下面的命令。
2. 等待终端显示 Ready，浏览器将打开本机页面。
3. 点击“试试样例 1：单个目标”，再点击“开始检测”。
4. 右侧出现真实预测框，下方列出编号、置信度和框坐标。
5. 点击“保存带框图片”和“保存结果 JSON”，保存你的这次输出。
6. 换成“样例 2：观察误检”，重复检测，对照下方说明。

.\.venv\Scripts\python.exe -B demo.py

浏览器没有自动打开时，手动访问 http://127.0.0.1:8771/。运行期间不要关闭终端；完成后回到终端按 Ctrl+C。界面仅绑定本机，不对局域网或公网提供服务。

样例 1 · 计数一致

标签为 class_5 一个，示例模型也预测一个。计数相同仍不能单独证明框位置正确。

样例 2 · 有额外预测

标签为 class_5 一个，但在 0.25 阈值下还预测了 class_0 和 class_2。框重叠时要结合 JSON 检查。

3.1 换自己的图片

点击“本机图片”，选择 JPG 或 PNG，再点击“开始检测”。限制为 10 MB、2000 万像素。图片在本机内存中处理，程序不上传云端，也不自动保存你选择的原图。数据分布不同的照片可能效果很差，这正是需要记录的实验结果。

3.2 理解阈值与置信度

框旁边的 0.99 是单个预测的置信度，不是模型准确率。把阈值从 0.25 调到 0.50，再点击检测，观察哪些框消失。提高阈值可能减少误检，也可能漏掉目标；降低阈值不等于模型更好。换图或改变阈值后，旧结果会清空，避免错配。

4. 检查数据并理解标注

.\.venv\Scripts\python.exe -B prepare_dataset.py --zip data/dried-citrus-fruits-dataset.zip

脚本读取包内原始 ZIP，不修改它。检查图片解码、图片标签配对、标签数值和六个类别编号，并用固定种子划分数据。

生成 prepared/check_report.json、split_manifest.json、data.yaml 和图像标签目录。完全相同像素的图片保持在同一集合；近似重复和同一采集场景尚未人工复查，因此这套划分用于入门教学。

Start-Process '.\prepared\annotations.html'

预览中的红框来自原始标签，不是模型输出。YOLO 标签每行有五个字段：

类别编号  中心x  中心y  宽度  高度
5         0.50   0.50   0.60  0.70

上面只是格式示意，坐标按图像宽高归一化。一个标签文件的每一行表示一个目标。打开 prepared/labels/train 下的 TXT，与同名图片对照。

5. 自己训练：先一轮，再完整实验

5.1 一轮试跑

.\.venv\Scripts\python.exe -B run_yolo.py train --model models/yolo26n.pt --epochs 1 --imgsz 320 --batch 4 --device cpu --name smoke

该命令使用包内预训练权重，不把已训练好的 citrus-best.pt 误当成新实验起点。epochs 是轮数，imgsz 是模型输入尺寸，batch 是每批图片数。Windows 数据读取进程数设为 0。

5.2 完整入门训练

.\.venv\Scripts\python.exe -B run_yolo.py train --model models/yolo26n.pt --epochs 30 --imgsz 320 --batch 4 --device cpu --name baseline

训练完成后查看 runs/baseline/results.csv 和图表。best.pt 按验证集表现选出，last.pt 是最后一轮。示例实验在 i9-14900HX CPU 上训练约 10.2 分钟；普通电脑可能更久，不能把这个时长作为保证。

第二次实验改名为 baseline_v2，不要覆盖第一次结果。模型效果有限也可以形成教学案例：记录真实结果，说明可能原因，再比较改进方案。

6. 在测试集评估，并预测图片

没有时间训练时，可先用随包模型跑通评估：

.\.venv\Scripts\python.exe -B run_yolo.py test --model models/citrus-best.pt --imgsz 320 --name test_example
.\.venv\Scripts\python.exe -B run_yolo.py predict --model models/citrus-best.pt --source prepared/images/test --imgsz 320 --name predict_example

自己的 30 轮训练完成后，把 --model 改为 runs/baseline/weights/best.pt，实验名分别改为 test_mine 和 predict_mine。

mAP 是检测指标，不要写成“分类准确率 95.65%”。测试集较小，相似图片可能影响结果。你的环境和训练结果可能不同；请填写自己的输出。不要反复根据测试成绩调参，调参主要依据验证集。

6.1 文件夹移动后怎么办

本包训练脚本会按 data.yaml 所在目录重新定位默认的 prepared 数据，不依赖作者电脑的绝对路径。若你自行改了配置结构，请同步调整 path、train、val、test。已安装的 .venv 通常不能直接搬家；在新目录重新运行 INSTALL.cmd。

7. 把实验整理成你自己的课程报告

打开 实验记录模板.html，按章节填写自己的参数、指标和截图。它是提纲，不是可直接冒充个人实验的现成报告。

1. 问题：输入一张果干照片，输出框、类别编号和数量。
2. 数据：记录数量、类别编号、许可和数据划分限制。
3. 环境：从 environment-check.json 和安装日志提取实际版本。
4. 训练：记录轮数、输入尺寸、批大小、设备和实验名。
5. 结果：粘贴自己生成的 metrics.json 数字和预测图。
6. 错误：至少保留一个误检或漏检，说明它为什么不符合标签。
7. 改进：提出复查类别名称、按采集场景划分、补充真实场景图片等具体方向。

演示时按“问题 → 原图与标签 → 运行预测 → 解释失败 → 改进方向”顺序讲。不要宣称模型已达到生产效果，也不以模型分数代替自己的分析。

8. 常见错误：先看现象，再做最小修复

需要反馈问题时，提供：执行的命令、终端最后约 20 行、环境检查结果和操作到哪一步。不要发送账号口令、网盘提取码或整台电脑的信息。

使用与许可

项目软件与随包 YOLO 模型按 AGPL-3.0 开源方案提供，许可和完整项目源文件随包保留；数据依据原始声明另行标明 Apache 2.0。请阅读 licenses/使用说明.txt 与原始来源记录。教程整理和配套服务与开源代码的使用权区分，不把开源模型包装成独家闭源授权。