alebal123bal/khadas_yolov8n_multithread

# khadas_yolov8n_multithread - 在 RK3588S NPU 上进行实时无人机检测

**在传感器 46 FPS 的极限下实现实时 YOLOv8n 无人机检测，仅需约 140 MB 的内存。** 这是一个为 **Rockchip RK3588S** SoC 设计的高吞吐量、低占用计算机视觉 pipeline：它捕获实时 1080p MIPI 帧，在所有 **3 个 NPU 核心**上并行运行 YOLOv8n（将吞吐量从约 31 FPS 提升到 **46 FPS** —— 现在的瓶颈是摄像头，而不是 pipeline），并将带有注释的结果流式传输到 HDMI 或 RTSP。捕获、色彩转换/缩放和推理完全在固定功能的硅片（ISP、RGA、NPU）上运行，因此 CPU 保持空闲，内存也**稳定在每路流约 140 MB** —— 足够小，甚至可以在最便宜的 2 GB RK3588S 开发板上运行，而不仅仅是高端开发套件。适用于任何 RK3588S 开发板；在 **Khadas Edge2** 上构建并测试。 然后它更进一步：当被追踪的无人机离开场景时，设备端的 LLM（Qwen2.5-0.5B，运行在*同一个* NPU 上）会生成一段关于刚刚发生事件的自然语言评估。整个系统由一系列通过 Unix-domain socket 连接的、小型且独立的进程组成 —— 检测结果向下游流入多目标追踪、时间特征提取、存在状态 FSM 以及按需生成的 LLM 摘要。 **核心亮点** - **榨干传感器性能：** 3 线程 NPU 推理将吞吐量从约 31 FPS 提升到 46 FPS 的摄像头极限 —— pipeline 不再是瓶颈。 - **完全硬件加速：** 捕获 (ISP)、色彩转换/缩放 (RGA) 和推理 (NPU) 完全不经过 CPU，使得每路流的内存占用 (RSS) 稳定在约 140 MB。 - **可在任何 RK3588S 开发板上运行：** 由于占用极小（单流约 140 MB，双流约 290 MB），它可以轻松适配市场上最便宜的 RK3588S 开发板 —— 甚至是那些**低至约 90 欧元**的 2 GB 型号 —— 而不仅仅是高端开发套件。 - **支持双摄像头：** 独立的每设备 socket 允许两路流同时运行并进行并行控制。 - **可组合的 pipeline：** 检测 → ByteTrack → 时间特征 → 存在状态 FSM → 按需 LLM 摘要，每一步都是独立的进程。 - **为 LLM 移交 NPU：** `blackout`/`resume` 控制平面会释放整个 NPU，以便 LLM 能全速运行，完成后再将其交还给摄像头。 **目标硬件：** 任何基于 RK3588S 的开发板、aarch64 Linux，并配备 OS08A10 MIPI 摄像头。在 **Khadas Edge2** 上开发并测试。支持从 x86-64/WSL 交叉编译，或在开发板上原生编译。 有关完整的软件架构（内部 pipeline 和多进程拓扑的 Mermaid 图表），请参见 [docs/architecture.md](docs/architecture.md)； 有关启动命令，请参见 [docs/usage.md](docs/usage.md)。 **相关仓库** - **[RKNN_TRAIN_YOLO](https://github.com/alebal123bal/RKNN_TRAIN_YOLO)** —— 用于训练、转换和导出此处使用的 Rockchip NPU `.rknn` 格式 YOLO 模型的完整 pipeline。 - **[RKLLM_LLAMA_QWEN](https://github.com/alebal123bal/RKLLM_LLAMA_QWEN)** —— 在 RK3588S 上运行优化后 LLM 模型的完整 pipeline，支持在 NPU (RKLLM) 或 CPU (llama) 上运行。 ## 性能表现 3 线程推理池为每个 NPU 核心运行一个 RKNN context（`rknn_dup_context` + `rknn_set_core_mask`），在所有三个核心上实现了捕获、推理和显示的流水线化。在 1080p 分辨率和 YOLOv8n 640×640 的条件下，这将吞吐量从 **约 31.2 FPS**（简单的单线程循环）提升到了 **46 FPS** 的 OS08A10 摄像头极限 —— pipeline 不再是瓶颈，传感器才是。每个模型完整的 FPS、延迟和 CPU/NPU/RAM 数据详见 [docs/benchmarks.md](docs/benchmarks.md)。 ## 完全硬件加速 → 极小的内存占用 每一项繁重的逐帧操作都在 RK3588S 专用的固定功能模块（摄像头 ISP、RGA、NPU）上运行，从不经过 CPU —— 因此在 CPU 端没有大型中间帧缓冲区或临时张量。系统会循环使用预分配的固定缓冲池（`N_BUF`，参见 [`src/main.cc`](yolov8n_cap_multithread/src/main.cc) 中的 `BufPool`），而不是逐帧分配，从而保持内存**稳定且受限**：**单路 1080p 流约为 137–152 MB RSS**，**双路流约为 276–304 MB**（并且这还重复计算了共享的 `librknnrt.so` / `librga.so` 内存页）。 由于 NPU、ISP 和 RGA 在整个 RK3588S 系列中完全相同，同一个二进制文件可以在最便宜的 2 GB 开发板（**约 90 欧元**）上全速运行 —— 无需 8/16 GB 的开发套件。逐帧的卸载分配表和 pipeline 图表请参见 [docs/architecture.md](docs/architecture.md)。 ## 构建与部署 **原生编译（在开发板上）：** ``` cd yolov8n_cap_multithread bash build.sh ``` **交叉编译（WSL / x86-64 Linux）：** ``` # 一次性 setup sudo apt-get install gcc-aarch64-linux-gnu g++-aarch64-linux-gnu bash setup_sdk.sh # fetches librga v1.10.5_[8] + librknnrt v2.3.2 cd yolov8n_cap_multithread bash build.sh # uses toolchain-aarch64.cmake (aarch64-linux-gnu-g++) scp -r install/yolov8n_cap_multithread/ khadas@:~/programs/ ``` 运行：`./yolov8n_cap_multithread ` 启动命令请参见 [docs/usage.md](docs/usage.md)，关于 IPC 控制/数据平面、下游的追踪/时间特征/LLM 阶段以及 RTSP 流媒体设置，请参见 [docs/usage_advanced.md](docs/usage_advanced.md)。 ## 仓库结构 ``` yolov8n_cap_multithread/ ├── CMakeLists.txt # builds main pipeline + all auxiliary processes ├── build.sh # convenience wrapper around CMake ├── toolchain-aarch64.cmake # cross-compile toolchain (WSL / x86 → aarch64) ├── data/ │ ├── coco_1_labels_list.txt │ └── model/ # .rknn model files │ ├── include/ # YOLO pipeline headers │ ├── camera_util.h │ ├── drm_func.h │ ├── local_display.h # HDMI output via DRM / Wayland │ ├── model_utils.h │ ├── postprocess.h # YOLOv8 decode + NMS │ ├── rga_func.h # Rockchip RGA color-space conversion / resize │ ├── rtsp_stream.h # GStreamer RTSP publisher │ └── ipc/ # shared IPC layer (control + data planes) │ ├── bounded_queue.h # drop-oldest queue used by all publishers │ ├── i_control_server.h │ ├── i_data_publisher.h │ ├── messages.h # in-process DetectionMessage type │ ├── unix_control_server.h │ ├── unix_data_publisher.h │ ├── wire_protocol.h # ALL on-the-wire structs + socket paths │ └── yolo_control_state.h │ ├── src/ # YOLO pipeline implementation │ ├── main.cc # multi-threaded RKNN pipeline (3 NPU cores) │ ├── camera_util.cc │ ├── local_display.cc │ ├── model_utils.cc │ ├── postprocess.cc │ ├── rga_func.cc │ ├── rtsp_stream.cc │ └── ipc/ │ ├── unix_control_server.cc # JSON control plane over AF_UNIX │ └── unix_data_publisher.cc # binary detection stream over AF_UNIX │ ├── tracker/ # ByteTrack stage (separate process) │ ├── include/ │ │ └── bytetrack_adapter.h # IByteTracker interface │ └── src/ │ ├── bytetrack_service.cc # main() — reads data, writes tracks │ └── iou_tracker.cc # default IOU-greedy implementation │ ├── temporal/ # Temporal-features stage (separate process) │ ├── include/ │ │ ├── track_state.h # per-track history + feature math │ │ └── track_manager.h # lifecycle + per-frame orchestration │ └── src/ │ ├── temporal_service.cc # main() — reads tracks, writes events │ ├── track_state.cc │ └── track_manager.cc │ ├── tools/ # Standalone client / debug binaries │ ├── control_client.cc # send pause/resume/blackout/status commands │ ├── data_receiver.cc # consume raw detections (yolo_data socket) │ ├── tracks_receiver.cc # consume tracked dets (yolo_tracks socket) │ ├── events_receiver.cc # consume temporal events (yolo_events socket) │ └── event_summarizer.cc # presence FSM + on-demand LLM (production sink) │ ├── utility_board_scripts/ # board-side helpers (deployed to install tree) │ └── run_qwen.sh # feeds a snapshot to Qwen2.5-0.5B via llm_demo │ ├── build/ # CMake out-of-source build tree └── install/ # `make install` deploy tree (scp this to board) └── yolov8n_cap_multithread/ ├── yolov8n_cap_multithread ├── bytetrack_service ├── temporal_service ├── control_client ├── data_receiver ├── tracks_receiver ├── events_receiver ├── event_summarizer ├── data/ # models + labels ├── utility_board_scripts/ # run_qwen.sh └── lib/ # librknnrt.so, librga.so ``` ### 进程拓扑 每个阶段都是一个独立的操作系统进程；它们通过按设备划分的 Unix-domain socket（`` = V4L2 设备号，例如 `33`）进行通信。完整的软件架构 —— 包括内部的 `main.cc` pipeline 和多进程拓扑（均以 Mermaid 图表形式展示）—— 记录在 [docs/architecture.md](docs/architecture.md) 中。 ## 许可证与免责声明 基于 **Apache License 2.0** 授权 —— 请参见 [LICENSE](LICENSE)。 这是一个**独立的个人项目**，仅供**教育与学术研究目的**使用。它**不隶属于作者的所有雇主或客户，也未获得其认可**，也**不适用于生产环境、关键业务、安全关键、监控或国防用途**。“UAV”（无人机）类别仅用于基准测试推理 pipeline 的示例检测目标。本软件**“按原样”提供，不提供任何形式的保证**，并且**您须自行负责**遵守所有适用的出口管制及其他相关法律法规。完整文本请参见 [DISCLAIMER.md](DISCLAIMER.md)。

标签：Bash脚本, RK3588S, YOLOv8, 嵌入式AI, 无人机检测, 目标检测, 计算机视觉, 边缘计算