计算机视觉 / 系统课时
交付模型与项目文档
交付模型与项目文档
本课把训练成果整理为可验证、可部署、可回滚的正式交付包。你将统一权重、配置、推理代码、数据说明、指标报告和部署文档,并生成版本清单、压缩包与哈希校验文件。
学习目标
- 设计完整且职责清晰的模型交付目录
- 为权重、数据、指标和部署步骤补齐必要文档
- 使用脚本生成带版本号和校验信息的发布包
规划交付清单
交付对象不只是 best.pt。开发人员需要推理入口和配置,运维人员需要环境与部署步骤,业务验收人员需要类别定义、指标和已知限制。将这些内容放入同一版本目录,才能避免文件来源不一致。

推荐的最小目录如下,目录名应包含业务名称和版本号,避免不同批次文件互相覆盖。
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
└── SHA256SUMSrelease.yaml 记录版本、入口、权重和兼容环境;SHA256SUMS 用于确认文件在传输后没有损坏或被替换。原始训练数据若因体积、许可或隐私不能交付,也必须在数据说明中写清来源、类别、划分方式和限制。
固化文档内容
model-card.md 应说明模型用途、禁止用途、类别列表、输入尺寸、阈值和已知误差;metrics.md 应保留测试集版本、Precision、Recall、mAP 和关键类别表现。只写一个总 mAP,无法解释模型在哪些场景容易失败。
deployment.md 至少包含运行环境、依赖安装、启动命令、输入输出路径、GPU 与 CPU 差异、日志位置和回滚方法。所有命令都应从干净环境重新执行一次,确认文档不是依赖作者本机状态才能成功。
数据说明要明确训练集、验证集和测试集的数量及划分原则,并记录重复样本、模糊标注、隐私脱敏和版权许可处理。指标报告中的数据版本必须与交付权重对应,不能把旧测试结果附在新权重上。
自动打包与校验
下面的 Linux 脚本会检查必要文件、复制到版本目录、生成发布清单和 SHA-256 校验文件,最后创建压缩包。运行前应确保列出的源文件均已准备完成。
#!/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):
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。随后按部署文档创建新环境,使用约定样本完成一次推理,并比对类别、阈值、输出路径和业务告警结果。
发布记录应保存版本号、权重哈希、交付日期、负责人和验收结论。回滚时不覆盖当前目录,而是重新部署上一稳定版本,并保留故障版本的日志和输入样本,便于后续复现问题。
正式验收至少覆盖完整性、可运行性、指标一致性和文档可读性。压缩包能解压不等于交付成功;只有接收方在独立环境中完成推理和结果核对,才算真正可用。
本课总结
- 正式交付应同时包含权重、配置、代码、文档、依赖和校验信息
- 数据版本、指标报告与权重必须一一对应
- 版本目录、哈希校验和回滚记录共同保证交付可追踪
下一课预告
本章内容至此完成,后续可基于同一交付规范继续扩展服务化部署、性能压测和生产监控。