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 Runtime |
deploy/dashboard.py | Flask 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 orangepi@<board-ip>:~/Desktop/上传完成后的推荐目录：
~/Desktop/deploy/6. 安装依赖
进入部署目录后执行：
cd~/Desktop/deploychmod+x 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_ROOT | ONNX Runtime 根目录 | 指向实际解压路径 |
ONNXRUNTIME_INCLUDE_DIR | ONNX Runtime 头文件目录 | 通常用默认拼接即可 |
ONNXRUNTIME_LIBRARY | libonnxruntime.so路径 | 必须存在 |
VIDEO_PATH | 本地视频路径 | 适用于文件模式 |
SOURCE_TYPE | video或camera | 根据输入源选择 |
CAMERA_INDEX | 摄像头索引或流地址 | 支持整数和 HTTP / RTSP 地址 |
FEATURE_SOURCE | 特征来源 | 推荐yolo-onnx |
POSE_MODEL_PATH | 姿态模型路径 | 指向../yolo11n-pose.onnx |
MODEL_PATH | 分类模型路径 | 指向../models/version3.onnx |
ONNX_EP | 执行提供器 | 建议先cpu，后cann |
SUMMARY_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_DIR=build-orangepi-onnxENABLE_ONNX=ONENABLE_MINDSPORE=OFFVIDEO_PATH=../fn.mp4MODEL_PATH=../models/version3.onnxPOSE_MODEL_PATH=../yolo11n-pose.onnxFEATURE_SOURCE=yolo-onnxONNX_EP=cpuONNX_DEVICE_ID=0SUMMARY_JSON=../artifacts/cpp_demo_onnx_orangepi_summary.jsonMAX_FRAMES=20LOG_EVERY=108. 先做环境自检
在正式运行前，建议先执行：
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_EP=cpuFEATURE_SOURCE=syntheticMAX_FRAMES=20bashscripts/orangepi_build_and_run.sh--envscripts/orangepi_aipro.env该模式不依赖真实姿态提取，适合快速排除编译和运行时错误。
9.2 阶段二：完整 ONNX 链路测试
切回真实姿态模型与分类模型：
cd~/Desktop/deploy/cpp_demoONNX_EP=cpuFEATURE_SOURCE=yolo-onnxMAX_FRAMES=0OUTPUT_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_EP=cannONNX_DEVICE_ID=0MAX_FRAMES=0bashscripts/orangepi_build_and_run.sh--envscripts/orangepi_aipro.env若运行时报错提示SessionOptionsAppendExecutionProvider_CANN相关问题，说明当前 ONNX Runtime 仍不是 CANN 版本。
10. 输入源配置方式
10.1 本地视频文件
SOURCE_TYPE=videoVIDEO_PATH=../fn.mp410.2 USB 摄像头
SOURCE_TYPE=cameraCAMERA_INDEX=010.3 HTTP / RTSP 视频流
该工程支持把CAMERA_INDEX当作流地址使用，例如：
SOURCE_TYPE=cameraCAMERA_INDEX=http://<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_EP=cpuFEATURE_SOURCE=yolo-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_TYPE=cameraCAMERA_INDEX=http://<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.json | NPU 演示事件日志 |
deploy/artifacts/result.mp4 | 输出视频 |
deploy/cpp_demo/artifacts/event_*.mp4 | 事件片段视频 |
13.2 仓库内现有样例结果
| 场景 | 产物文件 | 结果 |
|---|---|---|
| 开发板视频文件模式 | deploy/artifacts/cpp_demo_onnx_orangepi_summary.json | 1221 帧，60 次事件，约 1.39 FPS |
| 开发板 NPU 流模式 | deploy/artifacts/cpp_demo_npu_summary.json | 3235 帧，9 次事件，约 11.38 FPS |
这些结果主要用于说明工程链路已经打通。实际部署阈值、误报率与输入源质量仍需结合现场环境做进一步标定。
14. 常见问题
14.1 找不到 ONNX Runtime 头文件或动态库
请优先检查：
ONNXRUNTIME_ROOT是否写对。ONNXRUNTIME_INCLUDE_DIR与ONNXRUNTIME_LIBRARY是否和实际解压目录匹配。- 模板中的版本号是否已经根据安装结果改成
1.24.3或你的实际版本。
14.2onnx-ep=cann启动失败
最常见原因是当前 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- 输入视频质量与拍摄视角
