5.4 KiB
5.4 KiB
技术栈
本文是唯一的选型与命令速查表；模块职责见 04-architecture.md。
V1：Python 验证版
| 维度 | 选型 | 状态 | 理由 |
|---|---|---|---|
| 运行时 | CPython 3.8.10 | 已验证 | 当前环境可导入现有依赖；升级 Python 需单独任务验证。 |
| 桌面 UI | PyQt5 | 已验证 | 现有 GUI 已使用，适合实时画面、弹窗和信号线程。 |
| 视频与图像 | OpenCV（含 FFmpeg） | 已验证 | 读取 RTSP、绘制叠加层和保存截图。 |
| Pose 推理 | Ultralytics 8.3.205 + YOLOv8 Pose | 已验证 | 当前 best.pt 能加载为 17 点 person Pose 模型。 |
| 跟踪 | 轻量归一化框中心最近邻 | 已实现基线 | 为时序事件提供人员 ID；固定机位、稀疏人员适用；多人交叉可能换 ID，待有回归素材后再评估 ByteTrack 或全局匹配。 |
| 事件逻辑 | 纯 Python 模块 + pytest | 已定 | 与 GUI 解耦，便于正反例录像回归。 |
| 本地配置 | JSON 示例文件 + 未跟踪的 config.local.json |
已定 | 不把 RTSP 凭证提交仓库。 |
| 日志与截图 | JSONL + PNG/JPG 文件 | 已定 | 无数据库的可审计演示证据。 |
| 声音 | Windows winsound |
已定 | 不增加额外音频依赖。 |
| 测试 | pytest、compileall、录像回放 smoke | 已定 | 覆盖纯逻辑与可观察演示行为。 |
V2：Go 部署版
| 维度 | 选型 | 状态 | 理由 |
|---|---|---|---|
| 语言 | Go | 已定 | 面向长时间 RTSP 运行、并发控制和单一交付物。 |
| 模型工件 | 固定输入尺寸的 ONNX Pose 模型 | 已定 | Go 不直接加载 .pt；模型由已验收 V1 权重导出并记录哈希。 |
| 推理运行时 | github.com/yalue/onnxruntime_go v1.31.0 + ONNX Runtime CPU DLL |
Spike 已验证 | Windows 上以显式 DLL 路径加载锁定的 1×3×640×640 Pose ONNX，已完成一次真实录像首帧推理；该包装器的 C API 为 26，V2 构建必须启用 CGO/MinGW，并在发布包锁定匹配 DLL 的来源与 SHA-256。 |
| 视频输入 | 受控的 ffmpeg.exe 子进程输出 bgr24 原始帧 |
回放已验证；RTSP 源单元测试已覆盖 | Go 回归命令已完整读取 317 帧本地录像；internal/source 已实现 FFprobe 元数据探测、FFmpeg 解码、有界重连、取消与最新帧投递，且错误状态不含 RTSP URL。避免未配置的 GoCV/OpenCV 开发绑定。T-304 仍须随应用锁定 FFmpeg/FFprobe 的版本、哈希，并在现场验证真实流重连。 |
| 图像预处理与 Pose 解析 | Go 实现的 BGR→RGB、CHW、640 letterbox、NMS、17 点及坐标还原 | 合成契约与本机漏检回放已验证 | 采用 Ultralytics 的 114 补边、双线性缩放后转 uint8 的语义；Go 首帧输出两个人，与 V1 对应结果的 box 坐标差在已记录的 6 像素容差内。demo/1.mp4 是真实摔倒但在现有 V1 配置下漏检，不能称为“无报警反例”；仍需经同意、符合固定俯视大厅/走廊边界的正例录像完成事件级确认。 |
| 演示 UI | github.com/lxn/walk（Windows 原生控件） |
Spike 已验证 | 双 Tab 骨架可在 CGO_ENABLED=0 编译，避免 Fyne/OpenGL 首次编译的高复杂度；正式版仍须实现浅灰蓝底、白色卡片，红色仅表示确认摔倒。 |
| 测试 | go test ./... + V1 回归录像 |
已定 | V2 行为必须与 V1 基线对照。 |
关键选型纪律
- V1 不引入新模型、数据库、云服务或重量级告警依赖。
- RTSP 凭证仅来自环境变量或未跟踪本地文件；示例配置只含变量名。
- V2 的 ONNX 预处理、NMS、关键点解析、坐标还原和阈值必须与 V1 录像基线一致。
onnxruntime.dll、ffmpeg.exe与ffprobe.exe是 V2 发布依赖，必须以明确版本、来源和 SHA-256 随发布清单锁定；不得把开发机 Python 包、Go 模块缓存或系统 PATH 当成交付依赖。- V2 的 ONNX Runtime 包装器依赖 CGO；构建机必须固定 Go、MinGW 和 CGO 环境，运行端只加载已锁定的 DLL。CPU 是当前唯一已验证执行路径。
- 如果 V2 需要 GPU 专用引擎，必须记录显卡、驱动、运行时版本和回退 CPU 路径；不能将硬件绑定伪装成通用稳定性。
当前可运行命令
| 用途 | 命令 |
|---|---|
| 基线检查 | ./init.ps1 |
| 旧代码编译检查 | python -m compileall -q demo |
| 旧 GUI 启动 | Set-Location demo; python main.py |
| V1 依赖安装 | python -m pip install -r v1/requirements.txt（显式执行；init.ps1 不自动安装） |
| V1 单元测试 | python -m pytest v1/tests -v |
| V2 单元测试 | Set-Location v2; $env:CGO_ENABLED='1'; go test ./... |
| V2 ONNX/视频 Spike | Set-Location v2; $env:CGO_ENABLED='1'; go run ./cmd/spike --ffmpeg <ffmpeg.exe> --video <local-video> --width <w> --height <h> --onnx assets\best.onnx --ort-dll <onnxruntime.dll> |
| V2 录像事件回归 | Set-Location v2; $env:CGO_ENABLED='1'; go run ./cmd/regression --ffmpeg <ffmpeg.exe> --video <local-video> --width <w> --height <h> --fps <fps> --onnx assets\best.onnx --ort-dll <onnxruntime.dll> |
| V2 Walk UI 编译 Spike | Set-Location v2; $env:CGO_ENABLED='0'; go build ./cmd/ui-spike |
演进决策
- 先保持 Python 3.8.10 与现有依赖，避免为了升级环境打断演示基线；V1 验收后再评估支持期限与升级。
best.pt是 Pose 基线，不是默认永久模型；只有同一现场录像的量化比较能决定是否改用官方权重、提高输入尺寸或做数据适配。