61 lines
6.0 KiB
Markdown
61 lines
6.0 KiB
Markdown
# 技术栈
|
||
|
||
> 本文是唯一的选型与命令速查表；模块职责见 [04-architecture.md](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 | 本机发布目录已验证 | Windows 上以显式 DLL 路径加载锁定的 1×3×640×640 Pose ONNX，已完成一次真实录像首帧推理；该包装器的 C API 为 26，V2 构建必须启用 CGO/MinGW。`build-v2-release.ps1` 已从显式本机 DLL 生成 SHA-256 清单；现场 RTSP 推理仍待验收。 |
|
||
| 视频输入 | 受控的 `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 原生控件） | 操作窗口已编译 | 浅灰蓝双 Tab、最新帧、来源/事件状态、脱敏设置、开始/停止、确认声音与弹窗入口已实现；避免 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` |
|
||
| V2 正式应用 | `Set-Location v2; $env:CGO_ENABLED='1'; go run ./cmd/silver-pose --config <local-config.json>` |
|
||
| V2 发布目录 | PowerShell：`Set-Location v2; ./scripts/build-v2-release.ps1 -OnnxPath <locked-onnx> -OrtDllPath <release-dll> -FfmpegPath <ffmpeg.exe> -FfprobePath <ffprobe.exe> -OutputDirectory <empty-folder>`；CMD 便捷入口：`scripts\build-v2-release.bat`，参数完全相同且退出码透传。 |
|
||
|
||
## 演进决策
|
||
|
||
- 先保持 Python 3.8.10 与现有依赖，避免为了升级环境打断演示基线；V1 验收后再评估支持期限与升级。
|
||
- `best.pt` 是 Pose 基线，不是默认永久模型；只有同一现场录像的量化比较能决定是否改用官方权重、提高输入尺寸或做数据适配。
|