计算机视觉 / 系统课时

建立工程交付规范

建立工程交付规范

一个能在开发机运行的 OpenCV 项目还不等于可交付。交付规范要把依赖、配置、日志、测试、启动方式和验收条件全部固定下来,使另一位开发者拿到仓库后可以按文档复现环境、运行程序并判断结果是否合格。

学习目标

  • 建立最小但完整的项目交付清单,明确每类文件承担的职责。
  • 固定依赖、配置和日志格式,让环境差异能被快速定位。
  • 用自动化测试与量化验收条件判断交付是否通过,而不是只看“能启动”。

固定最小交付内容

一个中小型 OpenCV Python 项目至少应交付以下内容:src/ 放业务代码,tests/ 放自动化测试,models/ 放允许随项目分发的模型或下载说明,config.yaml 放运行参数,requirements.txt 固定依赖,README.md 写启动与验收步骤,logs/ 和 outputs/ 由程序运行时创建。

不要把摄像头索引、模型绝对路径、阈值和输出目录散落在代码里。交付前检查仓库中是否出现开发机专属路径,例如 /Users/name/... 或 C:\Users\name\...;这类路径必须改为相对项目根目录的路径或配置项。

依赖文件应锁定已经验证过的版本,而不是只写包名。下面版本仅作为一组可复现示例,适用于 Python 3.11;实际项目应锁定你在目标机器上完成验收的版本组合。

text
opencv-python==4.10.0.84
numpy==2.1.3
PyYAML==6.0.2
pytest==8.3.3

验证方法是在全新虚拟环境中安装该文件,并记录 python --version 与 python -m pip freeze。如果项目需要 CUDA、OpenVINO、GStreamer 或系统级编解码器,还要在 README 中单独列出系统依赖,因为它们不会被 requirements.txt 自动安装。

把运行参数放进配置并在启动时校验

配置文件只放会随设备、模型或环境变化的参数。下面示例把摄像头、模型路径、检测阈值和日志级别集中到一个文件,避免为了换设备或模型重新修改 Python 源码。

yaml
camera_index: 0
frame_width: 1280
frame_height: 720
requested_fps: 30
model_path: models/detector.onnx
confidence_threshold: 0.50
nms_threshold: 0.45
log_level: INFO
output_dir: outputs

程序启动时至少校验三类边界:model_path 必须存在,confidence_threshold 和 nms_threshold 必须在 0~1 之间,frame_width 与 frame_height 必须为正整数。配置写错时应直接退出并说明字段名,不要等到推理阶段才出现含糊的 OpenCV 异常。

让日志回答环境、输入和结果

日志至少要覆盖启动环境、输入源状态和处理结果三类信息。启动时记录 Python/OpenCV 版本、配置文件路径和模型路径;打开摄像头后记录后端、实际分辨率和 FPS;运行阶段记录帧号、耗时、检测数量,并把异常写成 ERROR 级别。

推荐格式至少包含时间、级别、模块和消息,例如 <TIME> INFO capture camera=0 backend=<BACKEND> size=1280x720 fps=30.00。不要只写“camera ok”或“inference failed”,因为这种日志无法比较设备差异,也不能还原故障发生时的输入条件。

敏感信息不要写入日志:访问令牌、数据库密码、含个人信息的原始帧路径都应省略或脱敏。日志文件建议按日期或大小轮转,例如单文件 10 MB、保留 5 个备份,避免长时间运行把磁盘写满。

把启动和测试命令写成可复制步骤

README 中的命令应从“一个空的终端”开始就能执行,不依赖开发者记忆。下面以 Linux/macOS 和 Python 3.11 为例,先创建虚拟环境、安装依赖,再运行测试;Windows 可使用对应的 .venv\Scripts\python.exe 路径执行同样的 -m pip 与 -m pytest 命令。

bash
python3.11 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python -m pytest -q

预期输出

text
<N> passed in <TIME>s

如果测试需要摄像头或模型文件,应把这类用例标成集成测试,并在 README 明确前置条件。普通单元测试不应因为开发机没有摄像头而全部失败;例如配置解析、坐标转换、NMS 前后的数据处理都可以在无硬件环境下测试。

用量化标准验收交付

“程序能跑”不能作为验收标准。至少定义功能、稳定性、性能和可复现性四类指标,并给出测试条件。下面是一套可直接用于 720p 单摄像头检测项目的示例标准,性能数字必须绑定具体硬件,不能脱离机器型号单独比较。

验收项 示例标准 验证方法
环境复现 全新 Python 3.11 虚拟环境安装成功 重新执行依赖安装,退出码为 0
摄像头稳定性 连续读取 3000 帧,成功率至少 99.9% 统计 read() 成功帧数
输入契约 实际帧尺寸为 1280×720,3 通道 BGR 启动日志记录 frame.shape
模型可用性 模型加载成功并完成 100 次推理,无异常 集成测试循环 forward()
性能 指定目标机上 P95 单帧处理耗时不高于 80 ms 记录 1000 帧耗时并计算分位数
日志 无未处理异常,关键启动参数完整 检查日志中 ERROR 和启动字段
输出 输出文件可打开,检测框坐标不越界 自动检查文件存在与坐标范围

若项目换了模型、输入分辨率、OpenCV 版本或硬件,必须重新跑这张验收表。交付记录应同时保存测试日期、Git 提交 ID、Python/OpenCV 版本和目标机信息;这样后续出现性能退化或输出变化时,才能判断是代码、模型还是环境发生了变化。

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

目录与阅读设置

阅读设置

17

记录一个想法

建立工程交付规范

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

登录哪都通