机器学习与深度学习 / 系统课时

建立工程交付规范

建立工程交付规范

一个能训练成功的 PyTorch 项目还不等于可交付项目。交付时要让另一台机器能够回答六个问题:装什么依赖、用什么配置、加载哪个模型、怎样运行、怎样判断成功、出错去哪里查。下面给出一套最小但完整的交付清单和验收方法。

学习目标

  • 把依赖、配置、日志、模型版本、测试和运行文档整理成可核对的交付物。
  • 为模型文件建立可追溯的版本清单与哈希校验。
  • 用自动化测试和一次冷启动验收确认交付包可复现。

固定七类交付物

建议每次发布都包含七类内容:依赖锁定文件、运行配置、模型权重、发布清单、测试、运行手册和日志目录。不要只交一个 .pt 文件,否则接手者无法判断模型需要什么代码、输入协议或类别映射。

PyTorch 工程交付物与运行验收关系

项目根目录不需要复杂,但名称要稳定。至少约定 requirements.lock、config.yaml、model.pt、manifest.json、tests/、RUNBOOK.md 和 logs/。训练临时文件、缓存和大批中间 checkpoint 不应混入正式发布包。

锁定依赖和运行配置

在已验证通过的虚拟环境中导出精确版本,交付时优先从锁定文件安装,而不是让接手者自行猜测兼容版本。

bash
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__)"

预期输出:

text
torch_import_ok
torch_version=<PYTORCH_VERSION>

<PYTORCH_VERSION> 是锁定环境中的实际版本,交付清单必须记录同一个值。配置文件则只放可变参数,例如设备、batch size、输入尺寸、类别映射路径和日志级别;密钥、访问令牌不要写进仓库或发布包。

给模型建立发布清单

模型文件必须和它的上下文绑定。manifest.json 至少记录发布版本、模型文件名、文件哈希、代码提交、PyTorch 版本、输入形状和类别顺序。SHA-256 能快速发现模型被替换、截断或传输损坏。

下面的脚本会计算 model.pt 的哈希,并生成合法 JSON 清单;把示例中的提交号和版本替换成实际值。

python
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))

预期输出:

text
manifest: True
sha256_length: 64

release、git_commit 和 torch_version 必须来自本次真实发布;不要把示例值直接带进生产。重新复制模型后再次计算哈希,只要与清单不同,就停止部署并重新取得原始制品。

让日志和测试回答“是否正常”

训练日志至少包含时间、阶段、epoch、step、loss、主要指标和异常堆栈;推理服务至少记录模型版本、请求 ID、耗时和错误类型。不要默认记录原始图片、完整文本或用户敏感字段。

自动化测试要覆盖三个最低门槛:模型能加载、输入输出形状符合契约、一个固定黄金样本得到预期类别。测试失败时发布流程直接终止,而不是“先上线再观察”。

运行测试时使用统一入口:

bash
python -m pytest -q

预期结果示例:

text
3 passed in <TIME>

<TIME> 会随机器不同而变化;关键是退出码为 0 且三个验收测试全部通过。若项目还包含 ONNX 或推理服务,应把对应的加载和接口烟雾测试加入同一套验收。

RUNBOOK 写到别人能独立启动

RUNBOOK.md 不需要写成长文,但必须给出环境前提、安装命令、配置位置、启动命令、健康检查、模型回滚和日志位置。一个可执行的启动段落至少说明 Python 版本、工作目录和入口文件。

最终验收要在“干净环境”完成一次:新建虚拟环境,按 requirements.lock 安装,放入交付的 config.yaml 与 model.pt,核对 manifest.json 哈希,运行测试,再执行正式入口。只有这条冷启动链路完整通过,交付包才具备可复现性;原开发机上能跑不能替代这一步。

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

目录与阅读设置

阅读设置

17

记录一个想法

建立工程交付规范

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

登录哪都通