计算机视觉 / 系统课时

交付模型与项目文档

交付模型与项目文档

本课把训练成果整理为可验证、可部署、可回滚的正式交付包。你将统一权重、配置、推理代码、数据说明、指标报告和部署文档,并生成版本清单、压缩包与哈希校验文件。

学习目标

  • 设计完整且职责清晰的模型交付目录
  • 为权重、数据、指标和部署步骤补齐必要文档
  • 使用脚本生成带版本号和校验信息的发布包

规划交付清单

交付对象不只是 best.pt。开发人员需要推理入口和配置,运维人员需要环境与部署步骤,业务验收人员需要类别定义、指标和已知限制。将这些内容放入同一版本目录,才能避免文件来源不一致。

YOLOv5 项目交付包与使用角色关系图

推荐的最小目录如下,目录名应包含业务名称和版本号,避免不同批次文件互相覆盖。

text
yolov5-safety-v1.0.0/
├── weights/
│   └── best.pt
├── configs/
│   ├── data.yaml
│   └── infer.yaml
├── src/
│   └── infer_project.py
├── docs/
│   ├── model-card.md
│   ├── data-description.md
│   ├── metrics.md
│   └── deployment.md
├── requirements.txt
├── release.yaml
└── SHA256SUMS

release.yaml 记录版本、入口、权重和兼容环境;SHA256SUMS 用于确认文件在传输后没有损坏或被替换。原始训练数据若因体积、许可或隐私不能交付,也必须在数据说明中写清来源、类别、划分方式和限制。

固化文档内容

model-card.md 应说明模型用途、禁止用途、类别列表、输入尺寸、阈值和已知误差;metrics.md 应保留测试集版本、Precision、Recall、mAP 和关键类别表现。只写一个总 mAP,无法解释模型在哪些场景容易失败。

deployment.md 至少包含运行环境、依赖安装、启动命令、输入输出路径、GPU 与 CPU 差异、日志位置和回滚方法。所有命令都应从干净环境重新执行一次,确认文档不是依赖作者本机状态才能成功。

数据说明要明确训练集、验证集和测试集的数量及划分原则,并记录重复样本、模糊标注、隐私脱敏和版权许可处理。指标报告中的数据版本必须与交付权重对应,不能把旧测试结果附在新权重上。

自动打包与校验

下面的 Linux 脚本会检查必要文件、复制到版本目录、生成发布清单和 SHA-256 校验文件,最后创建压缩包。运行前应确保列出的源文件均已准备完成。

bash
#!/usr/bin/env bash
set -euo pipefail

VERSION="${1:-v1.0.0}"
PROJECT="yolov5-safety"
TARGET="dist/${PROJECT}-${VERSION}"
ARCHIVE="${TARGET}.tar.gz"

REQUIRED_FILES=(
  "weights/best.pt"
  "configs/data.yaml"
  "configs/infer.yaml"
  "src/infer_project.py"
  "docs/model-card.md"
  "docs/data-description.md"
  "docs/metrics.md"
  "docs/deployment.md"
  "requirements.txt"
)

# 在复制前阻止不完整交付
for file in "${REQUIRED_FILES[@]}"; do
  if [[ ! -f "$file" ]]; then
    echo "missing=$file" >&2
    exit 1
  fi
done

# 重建版本目录,避免旧文件混入本次发布
rm -rf "$TARGET"
mkdir -p "$TARGET"/{weights,configs,src,docs}

cp weights/best.pt "$TARGET/weights/"
cp configs/data.yaml configs/infer.yaml "$TARGET/configs/"
cp src/infer_project.py "$TARGET/src/"
cp docs/*.md "$TARGET/docs/"
cp requirements.txt "$TARGET/"

# 发布清单和哈希均由脚本生成,减少手工修改错误
cat > "$TARGET/release.yaml" <<EOF
project: ${PROJECT}
version: ${VERSION}
framework: yolov5
weights: weights/best.pt
entrypoint: src/infer_project.py
EOF

(
  cd "$TARGET"
  find . -type f ! -name "SHA256SUMS" -print0     | sort -z     | xargs -0 sha256sum > SHA256SUMS
)

# 压缩包保留版本目录作为顶层,便于多版本并存
tar -czf "$ARCHIVE" -C dist "$(basename "$TARGET")"

echo "release_dir=$TARGET"
echo "archive=$ARCHIVE"
echo "checksum_file=$TARGET/SHA256SUMS"

预期输出(保存为 package_release.sh,执行 bash package_release.sh v1.0.0):

text
release_dir=dist/yolov5-safety-v1.0.0
archive=dist/yolov5-safety-v1.0.0.tar.gz
checksum_file=dist/yolov5-safety-v1.0.0/SHA256SUMS

若任何必要文件缺失,脚本会输出 missing=<PATH> 并停止,不会生成不完整发布包。哈希值由文件内容决定,每次更换权重、代码或文档后都必须重新打包。

执行验收与回滚

接收方应先解压发布包并执行 sha256sum -c SHA256SUMS,确认所有文件均显示 OK。随后按部署文档创建新环境,使用约定样本完成一次推理,并比对类别、阈值、输出路径和业务告警结果。

发布记录应保存版本号、权重哈希、交付日期、负责人和验收结论。回滚时不覆盖当前目录,而是重新部署上一稳定版本,并保留故障版本的日志和输入样本,便于后续复现问题。

正式验收至少覆盖完整性、可运行性、指标一致性和文档可读性。压缩包能解压不等于交付成功;只有接收方在独立环境中完成推理和结果核对,才算真正可用。

本课总结

  • 正式交付应同时包含权重、配置、代码、文档、依赖和校验信息
  • 数据版本、指标报告与权重必须一一对应
  • 版本目录、哈希校验和回滚记录共同保证交付可追踪

下一课预告

本章内容至此完成,后续可基于同一交付规范继续扩展服务化部署、性能压测和生产监控。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

交付模型与项目文档

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通