从零开始构建仓储视觉识别系统：从图像标注到模型部署(修订)

从零开始构建仓储视觉识别系统：从图像标注到模型部署

从零开始构建仓储视觉识别系统：从图像标注到模型部署

📚 系列文章导航

本系列围绕企业知识助手、售后智能体和仓储视觉识别，介绍从数据准备、模型开发到部署评测的实践流程，并提供配套排障指南。有修订版的文章，建议优先阅读修订版。

一、企业知识助手

从业务资料整理开始，逐步完成问答数据构建、模型微调、权重合并、量化与本地部署。

👉 从零开始构建企业知识助手：业务资料整理、模型微调与本地部署（修订版）

二、售后智能体

围绕售后业务，学习工具注册、智能体构建以及上线评测。

👉 从零开始构建售后智能体：从工具注册到上线评测

三、仓储视觉识别

从图像标注开始，逐步完成视觉模型训练、导出与部署。

👉 从零开始构建仓储视觉识别系统：从图像标注到模型部署（修订版）

四、模型开发排障

遇到环境、依赖、训练、推理、量化或部署问题时，可以按故障所在环节查阅。

👉 模型开发实用排障指南：从 Python（编程语言）环境到训练、推理与部署（修订版）

历史版本

仓库希望从现场照片中找出纸箱、周转箱和托盘的位置，供工作人员核对。我们将围绕这个业务，完成图片整理、人工标注、训练、评估、模型压缩和运行端迁移。这是一份可以边做边查的学习记录，不要求先会编程；示例场景不附带真实业务数据，也不预设任何识别成绩。

这里做的是Object Detection（目标检测）：既判断物体是什么，也给出它在图里的位置。人先用矩形写出参考答案，再让模型从这些图片学习；学习后用另一批图片检查效果，最后把模型交给独立程序处理新图片。

文章先给出一条完整实践主线，再集中解释参数与可选做法，最后按现象排查问题。主线统一使用三类目标、640像素输入、一次离线增强、固定版本训练框架、处理器上的独立推理。示例数字只是让各段能衔接，不是普遍最优配置。

Python（编程语言）代码写进文件，终端命令在命令窗口执行，两者不要混贴。代码框上方会标明新建或追加的文件；同名文件按出现顺序拼接，保留缩进，不复制代码框边界。术语在文字中解释，代码标识符和文件名保持程序要求的原样。文中图片为教学示意，不是实际软件截图。

第一部分：按顺序完成实践

1. 建立本地和服务器环境

目标：准备能标注、能运行脚本的工作位置。

操作位置：本地Windows（桌面系统）使用PowerShell 7（命令终端）；训练端使用Ubuntu（服务器系统）的Bash（命令解释器）。

先修改：连接地址、端口、账号及可写目录必须换成自己的；主线本地目录为D:\warehouse_vision，服务器目录为/home/user/projects/warehouse_vision。

参数与原理见对应参考。下面按顺序操作。

先认识三个类别：0 → carton（纸箱）、1 → tote（周转箱）、2 → pallet（托盘）。后续标注、数据配置、评估和推理必须使用同一顺序。改变业务类别时先看类别与坐标约定，不能只改界面上的名称。

在本地建立标注环境

以下命令假设已安装Conda（环境管理工具）。找不到命令时先按环境准备与替代方案完成安装或初始化，再回来继续；已有可用环境应先核对版本，不在原环境盲目升级。

conda create -n warehouse_label python=3.10 -y
conda activate warehouse_label
python -m pip install "numpy==1.26.4" "labelme==5.6.1" "opencv-python==4.10.0.84" "pandas==2.2.3"
python -m pip check
New-Item -ItemType Directory -Force D:\warehouse_vision\raw,D:\warehouse_vision\curated,D:\warehouse_vision\review,D:\warehouse_vision\reports | Out-Null
Set-Location D:\warehouse_vision
python -c "import sys; print(sys.executable)"

raw（原件目录）存照片；curated（整理目录）存待标注图片；review（复查目录）存暂不采用的图片；reports（记录目录）存检查记录。这几个目录首次使用应为空。

连接服务器并准备训练环境

另开一个本地终端，输入连接命令。密码输入通常不显示字符，按提示完成登录，不把密码写入代码。

ssh -p 实际端口 实际账号@实际服务器地址

hostname
pwd
nvidia-smi
free -h
df -h
conda env list
mkdir -p /home/user/projects/warehouse_vision/curated /home/user/projects/warehouse_vision/models /home/user/projects/warehouse_vision/reports /home/user/projects/warehouse_vision/exports /home/user/projects/warehouse_vision/deployment
cd /home/user/projects/warehouse_vision
conda create -n warehouse_train python=3.10 -y
conda activate warehouse_train

主线假设服务器有可供PyTorch（训练框架）使用的NVIDIA（显卡厂商）显卡，并且驱动兼容CUDA（显卡计算平台）12.1构建。先让环境提供者确认这一条件；不同硬件请使用对应安装分支，不要直接套用下面的构建。确认兼容后执行：

python -m pip install "torch==2.5.1" "torchvision==0.20.1" --index-url https://download.pytorch.org/whl/cu121
python -m pip install "numpy==1.26.4" "opencv-python==4.10.0.84" "ultralytics==8.3.40" "pandas==2.2.3" "matplotlib==3.9.2" "scikit-learn==1.5.2" "onnx==1.17.0" "onnxruntime==1.20.1" "pillow==11.0.0" "pyyaml==6.0.2"
python -m pip check
python -c "import torch, ultralytics; print(torch.__version__, torch.cuda.is_available(), ultralytics.__version__)"
python -m pip freeze > reports/environment.txt

版本组合用于明确教学接口，不代表已在你的机器上安装成功。后续训练使用显卡编号0；独立推理使用CPU（中央处理器），不能把这两个阶段的速度直接比较。

学会保存和运行代码

本地用文本编辑器打开项目文件夹，新建指定的.py文件，按UTF-8（统一字符编码）保存。不要保存成.py.txt。服务器可用nano 文件名.py（打开文本编辑器）；粘贴代码后按Ctrl+O（保存）、回车，再按Ctrl+X（退出）。初次不熟悉编辑器时，先看编辑器具体操作。

保存只会写文件。运行必须回到对应终端，在项目根目录执行python 文件名.py。每次重新连接服务器，都先激活环境并进入项目根目录。

完成检查：本地解释器路径属于标注环境，服务器版本符合所选组合；显卡主线的可用性检查返回True（是），目录可写。安装失败先排错，不带着依赖错误开始训练。

将实际资料接入统一的类别和来源配置

在本地项目根目录建立 classes.json（类别名称文件），保存下面的示例。标注、构建数据、预览和评估均读取这一份文件；列表位置就是类别编号。

["carton", "tote", "pallet"]

拿到其他业务类别时，先逐项确认“编号0是什么、编号1是什么”，再修改这个文件。已有标注采用的编号必须与之相同；不能只按字母重新排序。训练后导出的运行配置从模型读取类别，打包前还会与评估记录核对。

随后把图片复制进 raw（原始资料的工作副本）。无需强制改成某种带分隔符的文件名。新建 source_groups.json（采集来源清单），键为包含扩展名的真实文件名，值为同一次连拍、同一视频片段或已确认独立采集组，例如：

{
  "image001.jpg": "session01",
  "image002.jpg": "session01",
  "image003.jpg": "session04",
  "image004.jpg": "session08"
}

文件多时，把下面的独立小例子保存为 make_source_list.py（来源清单草稿），在本地项目目录运行一次；已有清单不会被覆盖。它只列文件名，不自动猜来源。

import json
from pathlib import Path

root = Path(__file__).resolve().parent
files = sorted(p for p in (root / "raw").iterdir() if p.is_file() and p.suffix.lower() in {".jpg", ".jpeg", ".png", ".bmp"})
draft = {p.name: "" for p in files}
with (root / "source_groups.json").open("x", encoding="utf-8") as file:
    json.dump(draft, file, ensure_ascii=False, indent=2)
print("请按真实来源填写每个空字符串；不要一张图随意编一个组")

python make_source_list.py

有人工清单时不要再运行草稿程序。若确实不知道采集来源，应先向数据提供者核对，结合近似画面保守分组并记录依据；不能仅凭不同文件名就断言彼此独立。图片目录含子目录时，先在工作副本整理并解决重名，再同步来源；后面的主线只扫描第一层。

已有标注时，保留原始坐标再导入

没有标注：按第2步整理图片，再到第3步画框。已经有有效标注：使用本节导入分支，随后跳到第4步构建数据。不要对已有标注的图片单独旋转、翻转或裁剪。

此分支支持两角点矩形的 Labelme（图形标注工具）文件和 YOLO（目标检测模型系列）的五列文本标签。其他格式先用对应工具转换，并抽样画回检查。不要把未知格式仅改扩展名。

把图片及同名标注放入 raw，新建 import_labeled_images.py（已有标注导入脚本），先保存第一段。FORMAT（格式）按资料选择；目标 curated（整理目录）必须为空。

from pathlib import Path
from PIL import Image
import json
import shutil

ROOT = Path(__file__).resolve().parent
FORMAT = "yolo"  # yolo为五列文本；labelme为矩形结构化文件
if FORMAT not in {"yolo", "labelme"}:
    raise ValueError("请先转换为已确认的检测标注格式")
source = ROOT / "raw"
output = ROOT / "curated"
output.mkdir(exist_ok=True)
if any(output.iterdir()):
    raise ValueError("请使用新的空整理目录，避免混入不同方向或标注版本")
groups = json.loads((ROOT / "source_groups.json").read_text(encoding="utf-8"))
files = sorted(p for p in source.iterdir() if p.is_file() and p.suffix.lower() in {".jpg", ".jpeg", ".png", ".bmp"})
mapping, stems = {}, set()

在同一个文件末尾追加第二段。这里不应用 EXIF（图片元信息）自动旋转；沿用原始像素坐标，之后必须画框确认。若已有标注依据的是旋转后的显示方向，应先在专用副本中同步变换图片与坐标，不能继续套用此导入例子。

for path in files:
    if path.stem in stems or not isinstance(groups.get(path.name), str) or not groups[path.name].strip():
        raise ValueError("图片主干重名或来源组未填写")
    annotation = path.with_suffix(".txt" if FORMAT == "yolo" else ".json")
    if not annotation.is_file():
        raise ValueError(f"缺少标注：{annotation.name}；空标签也须人工确认")
    target = output / (path.stem + ".png")
    with Image.open(path) as image:
        image.convert("RGB").save(target)
    if FORMAT == "yolo":
        shutil.copy2(annotation, target.with_suffix(".txt"))
    else:
        record = json.loads(annotation.read_text(encoding="utf-8"))
        record["imagePath"], record["imageData"] = target.name, None
        target.with_suffix(".json").write_text(json.dumps(record, ensure_ascii=False, indent=2), encoding="utf-8")
    stems.add(path.stem)
    mapping[target.name] = groups[path.name]
if not mapping:
    raise ValueError("没有导入任何图片，请检查目录层级和扩展名")
(ROOT / "curated_groups.json").write_text(json.dumps(mapping, ensure_ascii=False, indent=2), encoding="utf-8")
print("导入数量：", len(mapping), "；继续构建和画回检查")

python import_labeled_images.py

若导入中断，先读明确报出的文件，再在新的空工作副本重跑，避免把残留目录当作完整结果。后面 build_dataset.py（数据构建脚本）的 ANNOTATION_FORMAT（标注格式）也要改为同样的格式。

传到训练端时一起复制：curated（图片与标注）、curated_groups.json（整理后来源清单）、classes.json（类别顺序）。标注仍在本地而图片去了服务器，会导致后续构建失败。

2. 收集图片并保留清理记录

目标：形成可解码、命名一致、经过人工复核的图片集合。

操作位置：本地标注环境，工作目录D:\warehouse_vision。

先修改：把原始图片放进raw，按前节填写source_groups.json（来源清单）。文件可以保留原名；同一次采集的近似画面使用同一个来源组。

参数与原理见对应参考。下面按顺序操作。

收集不同光照、距离、遮挡和背景的场景；准备各类别的正例，也保留人工确认没有目标的负例。相邻帧不能当作独立场景。主线从现成照片开始；只有视频时先执行可选抽帧，再回到这里。

定位原始图片和输出目录

新建项目根目录的prepare_images.py。

Path（路径对象）帮助程序找到文件；ROOT（项目根目录变量）始终跟随脚本位置。此脚本只处理原始目录第一层。

from pathlib import Path
from PIL import Image, ImageOps
import hashlib
import json
import numpy as np
import cv2
import pandas as pd

ROOT = Path(__file__).resolve().parent
output = ROOT / "curated"
output.mkdir(exist_ok=True)
if any(output.iterdir()):
    raise ValueError("整理目录已有文件，请使用新的实验目录，避免覆盖已有标注")
files = sorted(p for p in (ROOT / "raw").iterdir()
               if p.suffix.lower() in {".jpg", ".jpeg", ".png", ".bmp"})
if not files:
    raise ValueError("原始图片目录为空")
seen, names, records = {}, set(), []
source_groups = json.loads((ROOT / "source_groups.json").read_text(encoding="utf-8"))
if any(p.is_dir() for p in (ROOT / "raw").iterdir()):
    raise ValueError("原始目录含子目录；请先在副本中整理第一层文件与来源清单")

读取图片、修正方向并检查重复

在prepare_images.py文件末尾追加，紧接该文件上一个示例。

读取失败记为待复查；像素完全相同记为重复。清晰度数值只用于人工排序，不设置自动删图阈值。

for path in files:
    try:
        with Image.open(path) as im:
            im = ImageOps.exif_transpose(im).convert("RGB")
            array = np.array(im)
        digest = hashlib.sha256(str(array.shape).encode() + array.tobytes()).hexdigest()
        if digest in seen:
            records.append({"source": path.name, "status": "duplicate", "detail": seen[digest]})
            continue
        group = source_groups.get(path.name)
        if not isinstance(group, str) or not group.strip():
            raise ValueError("来源清单缺少此图片的采集组")
        if path.stem in names:
            raise ValueError("转换后文件主干重名，请在工作副本中解决并同步清单")
        gray = cv2.cvtColor(array, cv2.COLOR_RGB2GRAY)
        sharpness = float(cv2.Laplacian(gray, cv2.CV_64F).var())
        im.save(output / (path.stem + ".png"))
        names.add(path.stem)
        seen[digest] = path.name
        records.append({"source": path.name, "status": "candidate", "detail": sharpness})
    except Exception as error:
        records.append({"source": path.name, "status": "review", "detail": str(error)})

保存清理清单

在prepare_images.py文件末尾追加，紧接该文件上一个示例。

(ROOT / "reports").mkdir(exist_ok=True)
pd.DataFrame(records).to_csv(ROOT / "reports/image_inventory.csv", index=False, encoding="utf-8-sig")
counts = pd.Series([r["status"] for r in records]).value_counts().to_dict()
print("处理数量：", counts, flush=True)
if counts.get("candidate", 0) == 0:
    raise ValueError("零张可用候选，请查看图片清单并修复路径、来源或图片内容")
curated_groups = {Path(r["source"]).stem + ".png": source_groups[r["source"]] for r in records if r["status"] == "candidate"}
(ROOT / "curated_groups.json").write_text(json.dumps(curated_groups, ensure_ascii=False, indent=2), encoding="utf-8")
print("记录已保存，请人工复查候选图片与失败项。")

Set-Location D:\warehouse_vision
python prepare_images.py

打开reports/image_inventory.csv（图片清单），查看candidate（候选）、duplicate（重复）和review（待复查）。再用图片查看器逐张检查整理目录，把不采用的图片移到复查目录；来源清单可保留这些历史记录，划分只读取当前整理目录里的图片。重复图和坏图的原件仍在原件目录。修正方向以后再画框。

完成检查：清理记录与候选图片相符，严重坏图已移出，困难但可辨认的样本没有被一概排除；每张候选图仍能从curated_groups.json（整理后来源清单）追溯；零候选必须停止修复。

3. 使用标注工具画框、修正并保存

目标：给每个目标建立正确的矩形和类别答案。

操作位置：本地Labelme（图像标注工具）5.6.1窗口。

先修改：输入和输出目录均为D:\warehouse_vision\curated；使用矩形、手动保存、不嵌入图片、不保留上一张标注。

参数与原理见对应参考。下面按顺序操作。

约定画框规则并打开目录

一个独立目标画一个框。两个纸箱分开画，纸箱和托盘可分别画框且允许重叠。本例统一框住可辨认目标的可见外接范围，不猜测遮挡后的完整轮廓。边缘目标框到图片边界；无法确认类别的图片先移入复查集合。

02_边界框质量示意

conda activate warehouse_label
labelme

01_标注界面导览

点击File（文件）→ Open Dir（打开目录），选择整理目录，在File List（文件列表）中单击图片。
点击File（文件）→ Change Output Dir（更改输出目录），选择同一个整理目录。
取消Save With Image Data（保存时嵌入图片数据）；关闭自动保存，先练习手动保存。
确认Keep Previous Annotation（保留上一张标注）未启用。Label List（类别列表）是类别名称，Polygon Labels（图形标注列表）才是当前图中已标的对象，不要混淆。

给一个物体画矩形

点击Edit（编辑）→ Create Rectangle（创建矩形）。
在可见外轮廓左上角单击，再移动到右下角单击，完成两个角点。
标签窗口中输入carton（纸箱），点击OK（确定）。其他类别分别填写tote（周转箱）、pallet（托盘）。若工具直接复用了已选类别，立即检查结果。
查看画布及图形标注列表。目标应完整，额外背景尽量少。再次选择创建矩形，为下一个对象画框。

调整大小、位置和类别

先点击Edit（编辑）→ Edit Polygons（编辑图形）。选中框后拖动角点改大小，拖动框内部改位置；双击右侧对应标注条目，或选中后用Edit Label（编辑标签）改类别。选中多余的框，使用Delete Polygons（删除图形）删除。

未完成的形状用Esc（取消）退出。Delete File（删除文件）针对整份标注文件，不能用来代替删除单个框。放大检查边缘，完成后用Fit Window（适应窗口）恢复整图，从左到右再检查漏标。更多快捷键及撤销条件见标注工具参考。

保存后重新打开验证

点击Save（保存），确认文件名与图片同名，仅扩展名变为.json。在系统文件管理器中确认图片和标注都在整理目录。点击Next Image（下一张）后再返回，最后关闭工具并重新打开一张已标图片，核对框能恢复。

没有目标的图片也要人工确认并保存空标注。普通保存不可用时尝试Save As（另存为）；打开文件确认shapes（图形列表）为[]（空列表）。没有标注文件表示尚未确认，不自动当成负样本。

完成检查：每张采用的图片都有同名标注，重新打开可显示；多个对象分别有框，类别拼写一致，空标注确实对应无目标图片。

4. 传输标注并构建训练、验证数据

目标：把矩形答案转换成模型可读标签，按采集组划分并画回图片复核。

操作位置：先在本地文件传输客户端上传；后面的代码在训练服务器项目根目录编写并运行。

先修改：项目中的classes.json（类别顺序）与真实标注一致；VAL_GROUPS（验证采集组）换成真实存在、覆盖全部类别的一部分采集组，必须留出训练组。

参数与原理见对应参考。下面按顺序操作。

上传图片及同名标注

在文件传输客户端新建连接，选择服务实际支持的SFTP（安全文件传输协议）或FTP（文件传输协议），填写真实地址、端口和账号。进入远端项目根目录，把本地整个整理目录及classes.json、curated_groups.json两个配置文件一起上传。等待队列结束，检查失败项和远端文件数量，防止形成两层同名目录。客户端下载界面和复核动作见文件传输参考。

服务器目标路径例如curated/image001.png和同名标注文件，名称以真实文件为准。下载回一对图片与标注重开检查，确认传输可用后继续。

填写类别和验证采集组

新建项目根目录的build_dataset.py。

示例使用session04与session08，只是命名示范。原始数据不同就修改这两个值；不要为了凑名字把同一视频拆成两个组。

import json
import shutil
from pathlib import Path
from collections import Counter
from PIL import Image
import yaml

ROOT = Path(__file__).resolve().parent
NAMES = json.loads((ROOT / "classes.json").read_text(encoding="utf-8"))
VAL_GROUPS = {"session04", "session08"}  # 改成你实际留作验证的采集组
group_map = json.loads((ROOT / "curated_groups.json").read_text(encoding="utf-8"))
if not NAMES or len(NAMES) != len(set(NAMES)) or not all(isinstance(n, str) and n.strip() for n in NAMES):
    raise ValueError("类别名必须是非空且不重复的字符串")
ANNOTATION_FORMAT = "labelme"  # 已有YOLO文本时改为 yolo
output = ROOT / "dataset"
if output.exists():
    raise ValueError("数据集目录已存在，请使用新目录构建，避免混入旧划分")
images = sorted((ROOT / "curated").glob("*.png"))
if not images:
    raise ValueError("没有整理后的PNG图片")

核对标注并计算中心坐标

在build_dataset.py文件末尾追加，紧接该文件上一个示例。

输入是像素角点，输出是相对图片大小的中心和宽高。不认识的类别、非矩形、越界框或缺失标注会报错。计算过程见坐标示例。


def read_yolo_labels(path):
    if not path.is_file():
        raise ValueError(f"缺少标签：{path.name}；确认无目标后才能建立空标签")
    result = []
    for line in path.read_text(encoding="utf-8").splitlines():
        values = list(map(float, line.split()))
        if len(values) != 5:
            raise ValueError("检测标签每行必须有五个数")
        category, x, y, w, h = values
        if not category.is_integer() or not 0 <= category < len(NAMES):
            raise ValueError("类别编号不是有效整数")
        if not (0 < w <= 1 and 0 < h <= 1 and 0 <= x-w/2 <= x+w/2 <= 1 and 0 <= y-h/2 <= y+h/2 <= 1):
            raise ValueError("坐标越界、非有限值或框面积为零")
        result.append((int(category), x, y, w, h))
    return result

def read_boxes(image_path):
    if ANNOTATION_FORMAT == "yolo":
        return read_yolo_labels(image_path.with_suffix(".txt"))
    if ANNOTATION_FORMAT != "labelme":
        raise ValueError("请先将标注转换为本流程支持的格式")
    annotation = image_path.with_suffix(".json")
    if not annotation.is_file():
        raise ValueError(f"缺少已确认的标注：{image_path.name}")
    data = json.loads(annotation.read_text(encoding="utf-8"))
    with Image.open(image_path) as image:
        width, height = image.size
    if (data["imageWidth"], data["imageHeight"]) != (width, height):
        raise ValueError("图片尺寸与标注记录不同")
    if (annotation.parent / data["imagePath"]).resolve() != image_path.resolve():
        raise ValueError("标注指向另一张图片，请先修正图片路径")
    result = []
    for shape in data["shapes"]:
        if shape["shape_type"] != "rectangle" or len(shape["points"]) != 2:
            raise ValueError("此转换示例只接受两角点矩形，请先统一标注")
        category = NAMES.index(shape["label"])
        (ax, ay), (bx, by) = shape["points"]
        x1, x2 = sorted([float(ax), float(bx)])
        y1, y2 = sorted([float(ay), float(by)])
        if not (0 <= x1 < x2 <= width and 0 <= y1 < y2 <= height):
            raise ValueError("发现越界或面积为零的框")
        result.append((category, (x1+x2)/2/width, (y1+y2)/2/height,
                       (x2-x1)/width, (y2-y1)/height))
    return result

检查训练和验证是否覆盖所有类别

在build_dataset.py文件末尾追加，紧接该文件上一个示例。

items, counts, totals = [], {"train": Counter(), "val": Counter()}, Counter()
if any(p.name not in group_map for p in images):
    raise ValueError("来源清单缺少整理后的图片")
groups = {group_map[p.name] for p in images}
if not VAL_GROUPS or not VAL_GROUPS <= groups or groups <= VAL_GROUPS:
    raise ValueError("请选择实际存在的部分采集组作为验证集，并保留训练组")
for path in images:
    split = "val" if group_map[path.name] in VAL_GROUPS else "train"
    boxes = read_boxes(path)
    counts[split].update(box[0] for box in boxes)
    totals[split] += 1
    items.append((path, split, boxes))
for split in ("train", "val"):
    if set(counts[split]) != set(range(len(NAMES))):
        raise ValueError(f"{split}中有类别没有标注实例，请调整真实数据覆盖")
print("图片数量：", dict(totals), "目标数量：", counts)
for c, name in enumerate(NAMES):
    positive = sum(s == "val" and any(box[0] == c for box in boxes) for _, s, boxes in items)
    print(name, "验证正图片：", positive, "负图片：", totals["val"]-positive)
    if positive == totals["val"]:
        print("此类没有负图片，图像级AUC将标记为未定义；如需有效AUC，请补充真实背景覆盖")

在build_dataset.py文件末尾追加，紧接该文件上一个示例。

for split in ("train", "val"):
    (output / "images" / split).mkdir(parents=True)
    (output / "labels" / split).mkdir(parents=True)
for path, split, boxes in items:
    shutil.copy2(path, output / "images" / split / path.name)
    lines = [str(b[0]) + " " + " ".join(f"{v:.6f}" for v in b[1:]) for b in boxes]
    (output / "labels" / split / (path.stem + ".txt")).write_text(
        "\n".join(lines) + ("\n" if lines else ""), encoding="utf-8")
config = {"path": str(output.resolve()), "train": "images/train", "val": "images/val",
          "names": dict(enumerate(NAMES))}
(ROOT / "warehouse.yaml").write_text(yaml.safe_dump(config, allow_unicode=True), encoding="utf-8")
(ROOT / "reports/split_manifest.json").write_text(
    json.dumps({p.name: s for p, s, _ in items}, ensure_ascii=False, indent=2), encoding="utf-8")

cd /home/user/projects/warehouse_vision
python build_dataset.py
cat warehouse.yaml

应得到dataset/images/train（训练图片）、dataset/images/val（验证图片）及对应的dataset/labels（标签目录），以及warehouse.yaml（数据配置）。配置的绝对路径要指向服务器实际数据位置。

准备标签重绘目录

新建项目根目录的preview_labels.py。

from pathlib import Path
from PIL import Image, ImageDraw
import json

ROOT = Path(__file__).resolve().parent
names = json.loads((ROOT / "classes.json").read_text(encoding="utf-8"))
output = ROOT / "reports/label_previews"
output.mkdir(exist_ok=True)

把转换标签画回原图

在preview_labels.py文件末尾追加，紧接该文件上一个示例。

for split in ("train", "val"):
    for path in sorted((ROOT / "dataset/images" / split).glob("*.png")):
        image = Image.open(path).convert("RGB")
        draw = ImageDraw.Draw(image)
        width, height = image.size
        label = ROOT / "dataset/labels" / split / (path.stem + ".txt")
        for line in label.read_text(encoding="utf-8").splitlines():
            category, x, y, w, h = map(float, line.split())
            box = ((x-w/2)*width, (y-h/2)*height, (x+w/2)*width, (y+h/2)*height)
            draw.rectangle(box, outline="lime", width=3)
            draw.text((box[0], max(0, box[1]-14)), names[int(category)], fill="red")
        image.save(output / (split + "__" + path.name))

python preview_labels.py

完成检查：下载并查看reports/label_previews（标签预览），框的位置和类别与标注一致；reports/split_manifest.json（划分记录）中同一采集组没有跨训练、验证。修正时改原始标注，在新的输出目录重新构建，不改预览图冒充标签修正。

5. 保存训练集增强副本

目标：用一次可追溯的亮度变化与水平翻转扩充训练图片，保持验证集不动。

操作位置：训练服务器项目根目录。

先修改：主线使用固定随机种子42、默认关闭翻转、亮度范围0.85—1.15；只处理训练图片。

参数与原理见对应参考。下面按顺序操作。

准备增强输入和固定随机过程

新建项目根目录的augment_training.py。

from pathlib import Path
from PIL import Image, ImageEnhance, ImageOps
import random
import pandas as pd

ROOT = Path(__file__).resolve().parent
images = ROOT / "dataset/images/train"
labels = ROOT / "dataset/labels/train"
if list(images.glob("*__aug.png")):
    raise ValueError("已经有增强副本，请不要重复增强这些副本")
paths = sorted(images.glob("*.png"))
rng = random.Random(42)
records = []
FLIP_PROBABILITY = 0.0  # 方向、文字敏感内容保持0；确认镜像不改变类别含义时才设0.5

同步变换图片和边界框

在augment_training.py文件末尾追加，紧接该文件上一个示例。

for path in paths:
    flip = rng.random() < FLIP_PROBABILITY
    brightness = rng.uniform(0.85, 1.15)
    image = Image.open(path).convert("RGB")
    if flip:
        image = ImageOps.mirror(image)
    image = ImageEnhance.Brightness(image).enhance(brightness)
    lines = []
    for line in (labels / (path.stem+".txt")).read_text(encoding="utf-8").splitlines():
        category, x, y, w, h = map(float, line.split())
        x = 1-x if flip else x
        lines.append(f"{int(category)} {x:.6f} {y:.6f} {w:.6f} {h:.6f}")
    name = path.stem + "__aug"
    image.save(images / (name+".png"))
    (labels / (name+".txt")).write_text("\n".join(lines)+("\n" if lines else ""), encoding="utf-8")
    records.append({"source": path.name, "augmented": name+".png", "flip": flip, "brightness": brightness})
pd.DataFrame(records).to_csv(ROOT / "reports/augmentation_manifest.csv", index=False, encoding="utf-8-sig")

python augment_training.py
python preview_labels.py

打开增强记录，查看新生成的__aug.png（增强副本）和同名标签。翻转必须同步改变框的横坐标；亮度变化不改框。后面的训练示例已经关闭同类在线增强，不需要再手动协调两套设置。方向有业务含义时先把翻转关闭，再重新构建本轮数据。

完成检查：新增副本仅在训练集，重绘后框仍贴合；再次运行会被阻止，防止副本继续叠加。此时可按归档方法备份图片、原始标注、数据配置、划分及增强记录。

6. 加载预训练模型并训练

先确认提供的权重能走这条路线

本文后面的独立解码器只适用于已确认的YOLOv8检测输出，不是所有检测模型的通用接口。资源给出其他模型时，先检查其框架、版本、任务类型与加载说明；不要只把文件重命名成 yolov8n.pt（示例权重）来尝试。

在训练端新建临时检查脚本，把 weight（权重位置）改为真实路径；以下为独立检查，不会训练：

from pathlib import Path
from ultralytics import YOLO

weight = Path("models/yolov8n.pt")
if not weight.is_file():
    raise FileNotFoundError(weight)
model = YOLO(str(weight))
print("任务：", model.task)
print("原类别：", model.names)
model.info()
if model.task != "detect":
    raise ValueError("当前不是检测权重，请选择对应任务流程")

预训练模型原类别与当前业务不同，可以在检测训练中按新的数据配置调整输出层；这与把分类、分割权重当检测权重是两回事。先把真实路径写进训练脚本的 weight，训练成功后后面的导出使用本次产生的 best.pt（最佳权重），不再使用预训练文件。

若只需调整可训练特征层，先打印 model.model.model（网络层序列），再按检查到的层编号设置 freeze（冻结层）。例如 freeze=2 表示冻结该实现最前面的两层，不等于冻结两个任意命名模块；比较可训练参数与短训练结果后再决定。

若业务确实要求修改网络宽度或深度，可在确认兼容的YOLOv8结构上使用下面的替换示例，替换训练脚本中的 model = YOLO(str(weight)) 这一句，其后的训练调用继续保留。该句位于 main（主函数）内部，粘贴时把下面整段统一缩进四个空格；不要追加到文件末尾：

import copy
import yaml

base = YOLO(str(weight))
architecture = copy.deepcopy(base.model.yaml)
architecture.pop("yaml_file", None)
architecture.pop("scale", None)
architecture.pop("scales", None)
architecture["depth_multiple"] = 0.33
architecture["width_multiple"] = 0.25
config_path = ROOT / "custom_detector.yaml"
config_path.write_text(yaml.safe_dump(architecture, sort_keys=False), encoding="utf-8")
model = YOLO(str(config_path), task="detect").load(str(weight))
model.info()

这两个数是小网络的演示倍率，不是更优的保证。结构改变可能导致部分预训练权重无法匹配，必须阅读加载的匹配数量，先完成一次前向和短训练。只要求常规微调时，不必执行结构替换。导出后若输出含独立目标分数、多个输出、动态维度或已嵌入去重，应使用该结构明确支持的导出和推理分支；不能继续套本文原始候选解码器。

Windows本地训练时，使用该电脑上的实际项目路径；没有可用显卡只能选择 device="cpu"（处理器），并接受训练可能明显变慢。先设 workers=0（不启用加载子进程）定位问题，保留 if __name__ == "__main__"（脚本入口保护），再按资源增加工作进程。

目标：从已有权重学习仓储三类目标，保留日志、参数和模型文件。

操作位置：训练服务器项目根目录，已激活训练环境。

先修改：准备与Ultralytics（检测框架）8.3.40兼容的YOLOv8n（轻量检测模型）权重，保存为models/yolov8n.pt；核对数据配置与显卡编号0。

参数与原理见对应参考。下面按顺序操作。

预训练权重是已有学习结果，不是标注答案。从可信模型发布方获取兼容文件并保留来源；重命名其他模型不等于转换成兼容结构。主线参数固定为40轮、批量8、输入640、不冻结、不开混合精度，并明确关闭重复在线增强。

导入训练框架并定位项目

新建项目根目录的train_detector.py。

from pathlib import Path
from ultralytics import YOLO

ROOT = Path(__file__).resolve().parent

配置训练并设置运行入口

在train_detector.py文件末尾追加，紧接该文件上一个示例。

main（主函数）把训练步骤放在一起；最下面的入口判断让直接运行脚本时才启动，避免多进程重复执行。

def main():
    weight = ROOT / "models/yolov8n.pt"
    if not weight.is_file():
        raise FileNotFoundError("请先准备与框架匹配的预训练权重")
    if (ROOT / "runs/warehouse_v1").exists():
        raise ValueError("实验目录已存在，请归档旧实验并同步后续路径后再运行")
    model = YOLO(str(weight))
    model.info()
    model.train(
        data=str(ROOT / "warehouse.yaml"), imgsz=640,
        epochs=40, batch=8, device=0, workers=2,
        optimizer="SGD", lr0=0.005, momentum=0.9, weight_decay=0.0005,
        patience=10, seed=42, amp=False, freeze=None,
        hsv_h=0.0, hsv_s=0.0, hsv_v=0.0,
        degrees=0.0, translate=0.0, scale=0.0,
        fliplr=0.0, flipud=0.0, mosaic=0.0, mixup=0.0,
        project=str(ROOT / "runs"), name="warehouse_v1", exist_ok=False,
        plots=True, save=True,
    )

if __name__ == "__main__":
    main()

python -m py_compile train_detector.py
python -u train_detector.py

语法检查通过后，训练终端应显示数据扫描、每轮损失和验证记录。损失用于观察学习过程，验证指标用于判断泛化；不能只看训练损失。目录已存在时先保留旧实验，再按重训与恢复处理，不覆盖旧结果。

完成检查：检查runs/warehouse_v1/results.csv（逐轮日志）、args.yaml（实际参数）、weights/best.pt（框架按验证准则选出的权重）和last.pt（最后检查点）。没有这些实际文件就先排查训练，不继续导出。

7. 在验证集生成指标、矩阵和曲线

先分清框架验证与最终运行函数验证

本节第一次运行时不加额外开关，检查训练框架指标；第9、10步导出后增加 --runtime（使用部署运行函数评估），对验证集逐图运行第8步的预处理、推理、类别选择、去重和坐标还原，再生成指标。两条路线在报告中分开标明，不把框架指标冒充最终入口指标。

固定版本8.3.40的预测分支不能只依靠 rect=False（关闭矩形填充）保证方形输入，因此下面显式定义方形填充预测器。检测平均精度使用匹配器和插值精度包络；ROC（受试者工作特征曲线）仍明确为图像级类别存在性。见对应版本预测实现及指标实现。

独立运行函数日常置信度阈值为0.25，计算平均精度时显式降至0.001以保留排序候选；预处理与后处理算法不变。固定阈值F1继续用0.25。若接口要求固定阈值下的性能，应另外保留该阈值的完整验证结果，不能混淆两种定义。

目标：从当前模型的真实预测生成评估文件，并记录统计定义。

操作位置：训练服务器项目根目录。

先修改：默认模型为runs/warehouse_v1/weights/best.pt；报告名为baseline（基准），类别顺序保持一致。

参数与原理见对应参考。下面按顺序操作。

本例同时记录mAP（平均精度均值）、固定阈值F1（精确率与召回率的调和平均）、混淆矩阵和PR（精确率—召回率曲线）。ROC（受试者工作特征曲线）与AUC（曲线下面积）另按‘每张图是否出现某类’计算；它不衡量定位精度，不能与检测mAP混为一谈。详细公式和阈值见指标参考。

计算真实框和预测框的重叠比例

新建项目根目录的evaluation_helpers.py。

import numpy as np

def pairwise_iou(a, b):
    a = np.asarray(a, dtype=float).reshape(-1, 4)
    b = np.asarray(b, dtype=float).reshape(-1, 4)
    left_top = np.maximum(a[:, None, :2], b[None, :, :2])
    right_bottom = np.minimum(a[:, None, 2:], b[None, :, 2:])
    intersection = np.maximum(right_bottom-left_top, 0).prod(axis=2)
    area_a = np.maximum(a[:, 2:]-a[:, :2], 0).prod(axis=1)
    area_b = np.maximum(b[:, 2:]-b[:, :2], 0).prod(axis=1)
    return intersection / np.maximum(area_a[:, None]+area_b[None, :]-intersection, 1e-12)

读取验证图片的真实标签

在evaluation_helpers.py文件末尾追加，紧接该文件上一个示例。

def read_truth(label_path, width, height):
    classes, boxes = [], []
    for line in label_path.read_text(encoding="utf-8").splitlines():
        category, x, y, w, h = map(float, line.split())
        classes.append(int(category))
        boxes.append([(x-w/2)*width, (y-h/2)*height,
                      (x+w/2)*width, (y+h/2)*height])
    return np.array(classes, dtype=int), np.array(boxes, dtype=float).reshape(-1, 4)

记录命中、错类、漏检和误检

在evaluation_helpers.py文件末尾追加，紧接该文件上一个示例。

def add_confusion(matrix, gt_classes, gt_boxes, pred_classes, pred_boxes, threshold=0.5):
    overlaps = pairwise_iou(gt_boxes, pred_boxes)
    candidates = np.argwhere(overlaps >= threshold)
    candidates = sorted(candidates, key=lambda p: overlaps[p[0], p[1]], reverse=True)
    used_gt, used_pred = set(), set()
    for g, p in candidates:
        if g in used_gt or p in used_pred:
            continue
        matrix[gt_classes[g], pred_classes[p]] += 1
        used_gt.add(g)
        used_pred.add(p)
    background = len(matrix)-1
    for g, category in enumerate(gt_classes):
        if g not in used_gt:
            matrix[category, background] += 1
    for p, category in enumerate(pred_classes):
        if p not in used_pred:
            matrix[background, category] += 1