yolov5-inferrence/docs/上传链路修复与项目结构说明.md

上传链路修复与项目结构说明

本次修改

本次修改目标是让推理程序只负责当前帧识别结果上报，不在推理侧处理抖动、持续时间或漏报补偿。

• 只有 prop >= conf_threshold 且目标在 workspace 内，才进入 upload 候选。
• 0.30 <= prop < conf_threshold 只记录为 weak_present，不上传。
• prop < 0.30 只记录为 filtered_low_conf，不上传。
• 低置信截图功能已停用：maybe_trigger_low_conf_snapshot 仍保留在代码中，但当前没有调用点。
• 取消推理侧三帧稳定门槛，抖动和持续时间判断交给管理程序。
• 取消 500ms upload 节流逻辑，当前帧满足上传条件就尝试上报；如果已有上传线程正在运行，则记录 upload_skip_busy。
• 保留同一 class_idx 的多 label 合并上传逻辑。
• upload 日志保留复查字段：label、number、prop、box、edge_touch、left_edge、boxes、rga。
• upload busy 状态改为创建线程前预约、线程结束后释放，避免连续帧在上传线程尚未置位前重复创建多个上传线程。

命令行与日志

命令行输出恢复为主分支风格，不再受日志采样影响：

• 低于阈值：skip prop = ... for class ...
• workspace 内且超过阈值：in result ...
• workspace 外：not in result ...

日志系统与命令行输出分离：

• .log 里的详细检测事件如 frame_seen、strong_present、weak_present、filtered_workspace、filtered_low_conf 仍按采样策略记录。
• upload_positive 和 upload_positive_payload 每次真实上传都会记录。
• edge_touch=1 表示目标框贴到 640x640 模型输入边界，left_edge=1 表示贴左边界；这两个字段只用于复查，不影响上传判断。
• rga= 记录最近一次 RGA 输入输出信息，如源宽高、stride、640x640 目标区域和上下填充位置，便于对照 RTSP 现场流和回放视频。
• frame= 是推理回调序号，不等同于主循环中的 handling [N]th frame。

心跳包

管理程序源码已拉到本地 rk1808-tool/ 用于对照。

当前管理程序的 /video/post 入口在 rk1808-tool/controllers/report.go，接收 JSON 结构为：

serial
at
type
params[].name
params[].class_idx
params[].number

推理程序保留 60 秒本地心跳日志，但不再通过 /video/post 上传心跳：

• HEARTBEAT_SECS = 60
• 如果 60 秒内没有正例 upload，只记录 heartbeat_log_only ... upload=0。
• 心跳不会生成 heartbeat_payload，也不会进入 /video/post。
• 推理程序禁止主动上传 number=0；upload_info 也会防御性跳过 total_number <= 0。
• 原因：当前 rk1808-tool 的 InsertEvent 用 class_idx 作为全局缓存 key，不区分摄像头；任意摄像头的 number=0 都可能取消同一 class_idx 的真实事件。

当前这份 rk1808-tool 代码里，重启推理程序主要依赖子进程退出后的 RunAsDaemon finalizer 触发 CheckNeedRestart；未看到独立的“收不到心跳就重启”逻辑。

当前项目结构

主要源码：

• main.cpp：参数解析、RTSP 读取、视频分段保存、解码主循环。
• rknn.cpp / rknn.h：推理回调、检测结果过滤、日志、upload 和心跳逻辑。
• yolov5.cc / yolov5.h：RKNN 模型初始化与推理调用。
• postprocess.cc / postprocess.h：后处理、label/code 加载。
• vertix.cpp / vertix.h：workspace 多边形过滤。
• utils.cpp / utils.h：HTTP JSON 上传、时间工具等。

依赖目录：

• rknn/：RKNN 头文件和库。
• mpp/：Rockchip MPP 头文件和库。
• rga/：RGA 头文件和库。
• ffmpeg/：FFmpeg 头文件和库。
• cjson/：JSON 处理库。

文档与辅助：

• docs/cross_compile_wsl_linaro.md：WSL + Linaro 交叉编译说明。
• docs/debounce_positive_upload_plan.md：早期去抖和日志方案记录，仅作历史参考。
• rk1808-tool/：本地拉取的管理程序源码，用于对照 /video/post 和重启逻辑。

构建产物

按 Linaro 路线构建：

wsl -d Ubuntu bash -lc "mkdir -p /home/smos/yolov5-linaro-build && cd /home/smos/yolov5-linaro-build && cmake /mnt/c/Users/Smos.DESKTOP-6MT98U8/Desktop/yolov5-inference && make -j16 && file yolov5"

当前产物位置：

/home/smos/yolov5-linaro-build/yolov5

验证要点：

• 产物是 ARM aarch64 ELF。
• 链接 librknn_api.so。
• 不应出现 GLIBC_2.33、GLIBC_2.34、GLIBCXX_3.4.29 依赖。