1. 适用范围本教程只针对deploy/目录也就是项目的最终部署成果。其目标是在 Orange Pi AI Pro 开发板上完成以下事项安装依赖与准备运行环境。配置 ONNX Runtime、视频源与模型路径。构建并运行 C 推理程序。启动 Web 仪表盘进行可视化展示。在需要时切换到CANN EP使用 NPU。2. 部署交付物说明deploy/目录中的关键内容如下路径作用deploy/models/version3.onnx板端分类模型deploy/yolo11n-pose.onnx板端姿态模型deploy/cpp_demo/板端 C 推理引擎deploy/install_deps_orangepi.sh一键安装构建依赖与 ONNX Runtimedeploy/dashboard.pyFlask Web 仪表盘deploy/stream_video.py可选视频流模拟器deploy/artifacts/板端运行摘要与事件记录3. 部署架构4. 前置条件4.1 硬件Orange Pi AI Pro 开发板。稳定电源。可用网络连接。显示器、键盘、鼠标或可用 SSH 登录方式。4.2 软件Ubuntu 22.04 LTS aarch64。build-essential、cmake、pkg-config、libopencv-dev。ONNX Runtime aarch64 版本。若使用 Web 面板需安装python3-flask。若使用stream_video.py建议安装python3-opencv。5. 上传部署目录推荐把deploy/整个目录拷贝到开发板例如scp-rdeploy orangepiboard-ip:~/Desktop/上传完成后的推荐目录~/Desktop/deploy/6. 安装依赖进入部署目录后执行cd~/Desktop/deploychmodx install_deps_orangepi.sh ./install_deps_orangepi.sh该脚本会自动执行apt-get update安装build-essential、cmake、pkg-config、libopencv-dev、wget、tar下载并解压onnxruntime-linux-aarch64-1.24.3如果你计划使用面板或视频流模拟器建议额外安装sudoapt-getinstall-ypython3-flask python3-opencv7. 配置环境文件7.1 复制模板cd~/Desktop/deploy/cpp_demo/scriptscporangepi_aipro.env.example orangepi_aipro.env7.2 修改关键变量重点检查以下变量变量说明建议ONNXRUNTIME_ROOTONNX Runtime 根目录指向实际解压路径ONNXRUNTIME_INCLUDE_DIRONNX Runtime 头文件目录通常用默认拼接即可ONNXRUNTIME_LIBRARYlibonnxruntime.so路径必须存在VIDEO_PATH本地视频路径适用于文件模式SOURCE_TYPEvideo或camera根据输入源选择CAMERA_INDEX摄像头索引或流地址支持整数和 HTTP / RTSP 地址FEATURE_SOURCE特征来源推荐yolo-onnxPOSE_MODEL_PATH姿态模型路径指向../yolo11n-pose.onnxMODEL_PATH分类模型路径指向../models/version3.onnxONNX_EP执行提供器建议先cpu后cannSUMMARY_JSON摘要输出路径建议保留7.3 重要注意事项模板文件默认写的是onnxruntime-linux-aarch64-1.23.2。安装脚本默认下载的是onnxruntime-linux-aarch64-1.24.3。因此你必须按实际解压目录修改ONNXRUNTIME_ROOT不能直接照抄模板默认值。一个更符合当前安装脚本结果的示例配置如下ONNXRUNTIME_ROOT../../third_party/onnxruntime-linux-aarch64-1.24.3ONNXRUNTIME_INCLUDE_DIR${ONNXRUNTIME_ROOT}/includeONNXRUNTIME_LIBRARY${ONNXRUNTIME_ROOT}/lib/libonnxruntime.soBUILD_DIRbuild-orangepi-onnxENABLE_ONNXONENABLE_MINDSPOREOFFVIDEO_PATH../fn.mp4MODEL_PATH../models/version3.onnxPOSE_MODEL_PATH../yolo11n-pose.onnxFEATURE_SOURCEyolo-onnxONNX_EPcpuONNX_DEVICE_ID0SUMMARY_JSON../artifacts/cpp_demo_onnx_orangepi_summary.jsonMAX_FRAMES20LOG_EVERY108. 先做环境自检在正式运行前建议先执行cd~/Desktop/deploy/cpp_demobashscripts/check_cann_env.sh scripts/orangepi_aipro.env该脚本会检查libonnxruntime.so是否存在。npu-smi是否可用。Ascend / CANN 相关环境变量。当前 ONNX Runtime 是否真的导出CANN EP所需符号。如果脚本提示当前库没有CANN EP符号则必须先更换为带 CANN 执行提供器的 ONNX Runtime再把ONNX_EP切到cann。9. 推荐运行顺序9.1 阶段一CPU 冒烟测试先验证“工程能编译、模型能加载、参数能跑通”cd~/Desktop/deploy/cpp_demoONNX_EPcpuFEATURE_SOURCEsyntheticMAX_FRAMES20bashscripts/orangepi_build_and_run.sh--envscripts/orangepi_aipro.env该模式不依赖真实姿态提取适合快速排除编译和运行时错误。9.2 阶段二完整 ONNX 链路测试切回真实姿态模型与分类模型cd~/Desktop/deploy/cpp_demoONNX_EPcpuFEATURE_SOURCEyolo-onnxMAX_FRAMES0OUTPUT_VIDEO../artifacts/result.mp4EVENT_LOG../artifacts/incidents.jsonbashscripts/orangepi_build_and_run.sh--envscripts/orangepi_aipro.env该模式会编译fight_detection_demo加载姿态 ONNX 与分类 ONNX处理输入视频或视频流生成事件日志与摘要文件9.3 阶段三切换到 CANN EP / NPU只有在你已经确认当前 ONNX Runtime 带有CANN EP时才建议执行cd~/Desktop/deploy/cpp_demoONNX_EPcannONNX_DEVICE_ID0MAX_FRAMES0bashscripts/orangepi_build_and_run.sh--envscripts/orangepi_aipro.env若运行时报错提示SessionOptionsAppendExecutionProvider_CANN相关问题说明当前 ONNX Runtime 仍不是 CANN 版本。10. 输入源配置方式10.1 本地视频文件SOURCE_TYPEvideoVIDEO_PATH../fn.mp410.2 USB 摄像头SOURCE_TYPEcameraCAMERA_INDEX010.3 HTTP / RTSP 视频流该工程支持把CAMERA_INDEX当作流地址使用例如SOURCE_TYPEcameraCAMERA_INDEXhttp://board-ip:5555/video_feed这是因为当前openCapture逻辑会优先判断CAMERA_INDEX是否为纯数字若不是纯数字则按网络流地址处理。11. 启动 Web 仪表盘在新的终端中执行cd~/Desktop/deploy python3 dashboard.py浏览器访问http://board-ip:5000仪表盘读取的关键文件为/dev/shm/preview.jpg/dev/shm/status.json因此只有在 C 推理引擎运行后仪表盘才会展示实时结果。11.1 让仪表盘显示事件视频列表dashboard.py默认从~/Desktop/deploy/cpp_demo/artifacts枚举event_*.mp4。如果你希望列表正常显示推荐把事件日志路径显式设置到该目录例如cd~/Desktop/deploy/cpp_demoONNX_EPcpuFEATURE_SOURCEyolo-onnxEVENT_LOG../cpp_demo/artifacts/incidents.jsonbashscripts/orangepi_build_and_run.sh--envscripts/orangepi_aipro.env这样生成的event_*.mp4会与仪表盘扫描目录保持一致。12. 可选启动视频流模拟器如果你没有外部摄像头但想模拟一个 HTTP 视频流可执行cd~/Desktop/deploy python3 stream_video.py默认服务地址http://board-ip:5555/video_feed随后把环境文件中的输入源改为SOURCE_TYPEcameraCAMERA_INDEXhttp://board-ip:5555/video_feed13. 运行结果与验收方式13.1 重点产物文件说明deploy/artifacts/cpp_demo_onnx_orangepi_summary.json板端 ONNX 路线摘要deploy/artifacts/cpp_demo_npu_summary.json板端 NPU 演示摘要deploy/artifacts/incidents.json事件日志deploy/artifacts/incidents_npu.jsonNPU 演示事件日志deploy/artifacts/result.mp4输出视频deploy/cpp_demo/artifacts/event_*.mp4事件片段视频13.2 仓库内现有样例结果场景产物文件结果开发板视频文件模式deploy/artifacts/cpp_demo_onnx_orangepi_summary.json1221 帧60 次事件约 1.39 FPS开发板 NPU 流模式deploy/artifacts/cpp_demo_npu_summary.json3235 帧9 次事件约 11.38 FPS这些结果主要用于说明工程链路已经打通。实际部署阈值、误报率与输入源质量仍需结合现场环境做进一步标定。14. 常见问题14.1 找不到 ONNX Runtime 头文件或动态库请优先检查ONNXRUNTIME_ROOT是否写对。ONNXRUNTIME_INCLUDE_DIR与ONNXRUNTIME_LIBRARY是否和实际解压目录匹配。模板中的版本号是否已经根据安装结果改成1.24.3或你的实际版本。14.2onnx-epcann启动失败最常见原因是当前 ONNX Runtime 是 CPU 版。先执行check_cann_env.sh确认是否真的存在CANN EP导出符号。14.3 仪表盘打开但没有图像请检查C 推理程序是否正在运行。/dev/shm/preview.jpg与/dev/shm/status.json是否被持续更新。浏览器访问的是否是开发板实际 IP。14.4 视频流无法连接若使用http://、rtsp://或rtmp://地址请优先在板端通过其他工具验证该流确实可访问再检查CAMERA_INDEX配置。14.5 输出视频编码失败如果输出视频时报 GStreamer 或编码错误请检查输出文件扩展名是否正确必要时安装常见编解码插件。14.6 检测结果误报较多优先从以下参数入手THRESHOLDSMOOTH_K输入视频质量与拍摄视角