机器学习与深度学习 / 系统课时
建立工程交付规范
建立工程交付规范
一个能训练成功的 PyTorch 项目还不等于可交付项目。交付时要让另一台机器能够回答六个问题:装什么依赖、用什么配置、加载哪个模型、怎样运行、怎样判断成功、出错去哪里查。下面给出一套最小但完整的交付清单和验收方法。
学习目标
- 把依赖、配置、日志、模型版本、测试和运行文档整理成可核对的交付物。
- 为模型文件建立可追溯的版本清单与哈希校验。
- 用自动化测试和一次冷启动验收确认交付包可复现。
固定七类交付物
建议每次发布都包含七类内容:依赖锁定文件、运行配置、模型权重、发布清单、测试、运行手册和日志目录。不要只交一个 .pt 文件,否则接手者无法判断模型需要什么代码、输入协议或类别映射。

项目根目录不需要复杂,但名称要稳定。至少约定 requirements.lock、config.yaml、model.pt、manifest.json、tests/、RUNBOOK.md 和 logs/。训练临时文件、缓存和大批中间 checkpoint 不应混入正式发布包。
锁定依赖和运行配置
在已验证通过的虚拟环境中导出精确版本,交付时优先从锁定文件安装,而不是让接手者自行猜测兼容版本。
python -m pip freeze > requirements.lock
python -m pip install -q -r requirements.lock
python -c "import torch; print('torch_import_ok'); print('torch_version=' + torch.__version__)"预期输出:
torch_import_ok
torch_version=<PYTORCH_VERSION><PYTORCH_VERSION> 是锁定环境中的实际版本,交付清单必须记录同一个值。配置文件则只放可变参数,例如设备、batch size、输入尺寸、类别映射路径和日志级别;密钥、访问令牌不要写进仓库或发布包。
给模型建立发布清单
模型文件必须和它的上下文绑定。manifest.json 至少记录发布版本、模型文件名、文件哈希、代码提交、PyTorch 版本、输入形状和类别顺序。SHA-256 能快速发现模型被替换、截断或传输损坏。
下面的脚本会计算 model.pt 的哈希,并生成合法 JSON 清单;把示例中的提交号和版本替换成实际值。
import hashlib
import json
from pathlib import Path
import torch
model_path = Path("model.pt")
sha256 = hashlib.sha256(model_path.read_bytes()).hexdigest()
manifest = {
"release": "2026.10.04",
"model_file": model_path.name,
"sha256": sha256,
"git_commit": "abc1234",
"torch_version": torch.__version__,
"input_shape": [1, 3, 224, 224],
"classes": ["class-a", "class-b", "class-c", "class-d", "class-e"],
}
Path("manifest.json").write_text(
json.dumps(manifest, ensure_ascii=False, indent=2),
encoding="utf-8",
)
print("manifest:", Path("manifest.json").exists())
print("sha256_length:", len(sha256))预期输出:
manifest: True
sha256_length: 64release、git_commit 和 torch_version 必须来自本次真实发布;不要把示例值直接带进生产。重新复制模型后再次计算哈希,只要与清单不同,就停止部署并重新取得原始制品。
让日志和测试回答“是否正常”
训练日志至少包含时间、阶段、epoch、step、loss、主要指标和异常堆栈;推理服务至少记录模型版本、请求 ID、耗时和错误类型。不要默认记录原始图片、完整文本或用户敏感字段。
自动化测试要覆盖三个最低门槛:模型能加载、输入输出形状符合契约、一个固定黄金样本得到预期类别。测试失败时发布流程直接终止,而不是“先上线再观察”。
运行测试时使用统一入口:
python -m pytest -q预期结果示例:
3 passed in <TIME><TIME> 会随机器不同而变化;关键是退出码为 0 且三个验收测试全部通过。若项目还包含 ONNX 或推理服务,应把对应的加载和接口烟雾测试加入同一套验收。
RUNBOOK 写到别人能独立启动
RUNBOOK.md 不需要写成长文,但必须给出环境前提、安装命令、配置位置、启动命令、健康检查、模型回滚和日志位置。一个可执行的启动段落至少说明 Python 版本、工作目录和入口文件。
最终验收要在“干净环境”完成一次:新建虚拟环境,按 requirements.lock 安装,放入交付的 config.yaml 与 model.pt,核对 manifest.json 哈希,运行测试,再执行正式入口。只有这条冷启动链路完整通过,交付包才具备可复现性;原开发机上能跑不能替代这一步。