简介基于Python与Shell的低慢小无人机识别预警系统可见光设计源码定位为低空安防与计算机视觉方向的工程参考面向无人机监管研发人员、算法工程师及有一定基础的视觉学习者解决低慢小无人机监测与及时预警问题并覆盖可见光图像采集、分析与识别等关键环节。包体共140个文件以55个Python脚本为核心配合41个YAML与11个YML配置文件、5个Shell部署脚本、多个Dockerfile以及说明文档、许可证、贡献指南等构成一套完整且可扩展的工程框架压缩包仅4.25MB便于下载与版本管理。目前已有328人学习浏览适合作为理解可见光识别系统架构、借鉴预警流程设计的参考。内容涵盖图像处理、参数灵活配置、容器化部署、Git协作规范等使用者可基于源码快速搭建实验环境并根据实际场景调整识别策略进行二次开发与算法验证也可用于教学演示和课程设计。1. 可见光方案在低慢小无人机识别里的定位反直觉的地方在于低慢小无人机这么难抓主流方案却都在跟雷达较劲而这个项目干脆把雷达扔了。原因不复杂——这类目标飞行高度通常在500米以下、速度慢、RCS反射面积小雷达回波微弱到和目标周围的鸟群难以区分误报率高到值班人员被迫屏蔽报警。可见光识别则走另一条路传感器分辨率高无人机轮廓纹理在光学成像里是明确信息几公里范围内只要目标进入视场识别精度和稳定性都要比雷达高一个量级误报率也低得多。这个源码包就是一套完整的可见光识别预警框架Python承担图像采集、模型推理、状态判断的完整链路Shell脚本负责部署、更新和运维52个YAML/YML配置把算法参数和业务规则完全解耦138个文件的体量说明它不是教学demo而是一套能直接落到园区周界、机场净空区、活动现场这类真实场景的工程骨架。2. 源码结构拆解与Python识别链路实现一个138个文件的源码包第一眼会劝退不少人。但按文件类型拆开看结构其实非常清晰51个Python脚本是业务主体负责从图像采集到预警输出的完整链路41个YAML和11个YML配置文件控制所有可变参数把算法逻辑和运行参数彻底解耦5个Shell脚本承担部署、备份、状态检查等运维操作剩下的Markdown、文本、JPEG和配置杂项补齐了文档、测试样本和版本管理。这种组织方式有一个实际好处算法工程师改Python不动配置运维工程师调参数不碰代码两拨人可以并行工作。2.1 图像采集层的实现细节识别链路的第一步是拿到连续的视频帧。项目里Python脚本的处理方式是标准的OpenCV VideoCapture流程但针对低慢小无人机的场景做了两个特殊处理。一是把输入源抽象成两层支持直接读摄像头设备号也支持读局域网内的RTSP视频流二是对每帧图像做定尺缩放统一送到检测网络之前先resize到固定分辨率避免不同摄像头源带来的分辨率抖动影响识别稳定性。import cv2 import numpy as np class FrameSource: 视频源抽象摄像头/视频文件/RTSP流统一走这个接口 def __init__(self, source, frame_width1280, frame_height720): self.cap cv2.VideoCapture(source) self.frame_width frame_width self.frame_height frame_height self.cap.set(cv2.CAP_PROP_BUFFERSIZE, 2) # 降低帧缓存延迟 def read(self): ret, frame self.cap.read() if not ret: return None # 统一缩放过大的原图直接降采样减少推理耗时 if frame.shape[1] ! self.frame_width: frame cv2.resize(frame, (self.frame_width, self.frame_height)) return frameCAP_PROP_BUFFERSIZE设置成2是为了避免OpenCV默认的帧缓存积压导致画面延迟过大如果开4路以上摄像头建议同时开两个线程去读帧否则Python的GIL会让单线程读取成为瓶颈。rtsp流的地址需要带超时参数cv2.VideoCapture(rtsp://user:passip:554/stream1)在断流时会阻塞通常用cv2.setTimeout配合心跳检测做断线重连。2.2 检测推理模块的模型组织检测部分是系统的核心。比较常规的做法是采用YOLO系列的轻量模型在低空场景下目标尺寸小输入分辨率不能压得太低项目里倾向把网络输入保持在640×640以上。推理代码里做了个关键设计模型加载只执行一次所有视频帧都复用同一个Session而不是每帧重新加载模型这样处理速度才能稳定在实时水平。import cv2 import numpy as np class DroneDetector: 无人机目标检测器基于YOLO的ONNX推理 def __init__(self, model_path, conf_thres0.35, iou_thres0.45): self.net cv2.dnn.readNetFromONNX(model_path) self.net.setPreferableBackend(cv2.dnn.DNN_BACKEND_OPENCV) self.conf_thres conf_thres # 置信度阈值低于该值直接丢弃 self.iou_thres iou_thres # NMS去重的IoU阈值 def detect(self, frame): blob cv2.dnn.blobFromImage( frame, 1/255.0, (640, 640), swapRBTrue, cropFalse ) self.net.setInput(blob) outputs self.net.forward() # 输出格式为 [batch, num_anchors, 5 num_classes] boxes, scores [], [] for out in outputs[0]: score np.max(out[4:]) if score self.conf_thres: continue # ... 坐标还原和NMS处理 return boxes, scores置信度阈值0.35是相对保守的数值实测在能见度好的白天无人机目标置信度通常能到0.6以上0.35的阈值主要是照顾黄昏和逆光场景。误报主要来自飞鸟单纯调阈值抑制不了鸟的误检需要在后处理里加运动特征判别这个后面章节展开。2.3 预警输出的状态机设计预警不能做成检测到目标就报警那样飞鸟会让你一夜报警几百次。项目的做法是引入状态机单帧检测到目标进入关注态连续N帧都检测到才进入预警态预警态每M帧确认一次目标还在不在目标丢失超过K帧就回到正常态。这样把单帧误检过滤掉同时避免目标短暂遮挡造成的报警抖动。class AlertStateMachine: 三级预警状态机NORMAL - ATTENTION - ALERT def __init__(self, enter_frames5, hold_frames3, exit_frames10): self.enter_frames enter_frames # 连续多少帧确认目标进入预警 self.hold_frames hold_frames # 预警后每隔多少帧复核一次 self.exit_frames exit_frames # 目标消失多少帧后退出预警 self.state NORMAL self.counter 0 def update(self, num_targets): if num_targets 0: self.counter 1 else: self.counter 0 if self.state NORMAL and self.counter self.enter_frames: self.state ATTENTION elif self.state ATTENTION and self.counter self.hold_frames: self.state ALERT return self.stateenter_frames和exit_frames的取值需要根据视频帧率推算。25fps的摄像头5帧大约等于0.2秒也就是说目标在画面里稳定出现0.2秒才进入关注态这个时间足够过滤掉鸟类快速飞过造成的偶发检测。注意状态机的代码只返回状态具体报警动作由Shell脚本或外部消息模块负责项目里的Python代码保持了这种单一职责的划分。3. Shell脚本与部署运维自动化Python做业务逻辑没问题但真要部署到现场设备上还得靠Shell把环境、依赖、模型文件、启动参数串起来。项目的5个Shell脚本覆盖了从安装到日常维护的完整运维场景环境初始化、服务启停、模型热更新、日志清理、数据备份。用Shell而不是Ansible这类配置管理工具主要是考虑到目标设备可能只有很小的系统资源Shell脚本零依赖、可手工执行、排错直观在嵌入式Linux设备上更实用。3.1 环境初始化与依赖安装脚本一个典型的init脚本要处理的事情比想象中多检查Python版本、创建虚拟环境、安装Python依赖、确认模型文件完整性。常见做法是分步执行并返回明确的退出码这样哪一步失败一眼就能看到。#!/bin/bash # init_env.sh - 部署环境初始化 set -e PYTHON_BIN$(command -v python3) VENV_DIR./venv MODEL_DIR./models echo [1/4] 检查Python版本 $PYTHON_BIN --version || { echo Python3未安装; exit 1; } echo [2/4] 创建虚拟环境 if [ ! -d $VENV_DIR ]; then $PYTHON_BIN -m venv $VENV_DIR fi source $VENV_DIR/bin/activate echo [3/4] 安装依赖 pip install --upgrade pip pip install -r requirements.txt echo [4/4] 校验模型文件 if [ ! -f $MODEL_DIR/drone_detector.onnx ]; then echo 模型文件缺失请检查models目录 exit 2 fi echo 环境初始化完成注意set -e的作用任何一条命令返回非零退出码时脚本立即终止避免在依赖残缺的环境里继续往下执行制造半成品状态。虚拟环境固定到./venv而不是系统全局是因为项目里的YAML配置和Dockerfile都按相对路径引用Python解释器统一放项目目录里迁移时不会漏东西。模型文件校验单独退出码2跟环境错误区分开排错时能直接判断是依赖问题还是模型文件问题。3.2 模型热更新与日志滚动无人机识别模型不是一成不变的现场收集到新的负样本后要定期更新模型。Shell脚本实现模型热更新核心逻辑是把新模型下载到临时路径校验MD5后原子替换正式模型文件再触发Python进程重载推理模块。#!/bin/bash # update_model.sh - 模型热更新 MODEL_DIR./models TMP_FILE${MODEL_DIR}/.drone_model.tmp TARGET_FILE${MODEL_DIR}/drone_detector.onnx MD5_EXPECTED$1 curl -fsSL http://oss.internal/models/drone_v2.onnx -o $TMP_FILE || exit 1 # 校验文件完整性防止下载中断导致模型损坏 ACTUAL_MD5$(md5sum $TMP_FILE | awk {print $1}) if [ $ACTUAL_MD5 ! $MD5_EXPECTED ]; then echo MD5校验失败终止更新 rm -f $TMP_FILE exit 2 fi mv $TMP_FILE $TARGET_FILE echo 模型更新完成触发检测服务重载 # 通过信号通知Python进程重新加载模型 pkill -HUP -f drone_detector.py 2/dev/null || truemv在同一文件系统内是原子操作不会出现更新到一半文件损坏的情况。pkill发送的SIGHUP信号告诉Python进程捕获信号后重新加载模型具体实现是Python代码里用signal模块挂接了SIGHUP的处理函数。这种热更新方式能实现在不中断视频流的情况下完成模型升级适合现场不便重启的服务。3.3 Docker镜像CPU版和ARM版为什么分开项目里同时提供了Dockerfile和Dockerfile-cpu、Dockerfile-arm64两个变体这个设计很务实。CPU版面向x86服务器ARM版面向飞腾、瑞芯微这类嵌入式设备两者底层依赖完全不同ARM版需要安装交叉编译好的OpenCV和针对ARM平台优化的推理库CPU版则要避免装到GPU版驱动导致启动失败。# Dockerfile-cpu - x86 CPU部署镜像 FROM python:3.9-slim WORKDIR /app COPY requirements.txt . RUN pip install -r requirements.txt --no-cache-dir COPY . . # 时区设置为本地时间保证预警日志时间可读 ENV TZAsia/Shanghai CMD [bash, start.sh]搭建镜像时的关键点是基础镜像选slim版本而不是完整版省出来的体积对现场设备很有意义ARM版构建则需要用buildx指定platform参数在x86构建机上交叉编译ARM镜像。如果设备上要跑GPU推理Dockerfile还需要挂载CUDA基础镜像并额外处理驱动映射官方镜像仓库里的nvidia/cuda就是现成的基础标签但低慢小识别场景大多数是纯CPU部署单路视频流每帧推理耗时控制在50毫秒内就可以接受。4. YAML配置体系与识别阈值调优源码包里YAML和YML文件加起来52个占了快四成文件数可见配置在系统设计里的分量。为什么用两种后缀这是因为解析库的兼容性问题YAML标准后缀是.yaml但PyYAML和部分OpenCV工具对.yml的兼容性更好。项目里两类文件的分工是.yaml存业务配置如识别参数、报警规则、数据源地址.yml存OpenCV相关配置如模型参数文件、相机标定数据。4.1 识别参数配置的层级设计低慢小无人机识别不能只靠一个检测模型打天下不同场景下的最优参数差异很大塔吊比对的工地场景需要更高的置信度要求但机场跑道场景需要更低的迟滞时间。项目的配置文件没有把所有参数都堆在一个文件里而是拆成几个细粒度模块主配置文件通过include机制引用子配置这样现场调参时只需要改对应场景的片段不会被无关参数干扰。# config/detector.yaml - 检测器业务配置 detector: model_path: models/drone_detector.onnx input_size: [640, 640] conf_threshold: 0.35 nms_threshold: 0.45 device: cpu frame_source: type: rtsp url: rtsp://admin:password192.168.1.64:554/stream1 reconnect_interval: 5 alert: state_machine: enter_frames: 5 hold_frames: 3 exit_frames: 10 notification: webhook_url: http://alert-center.internal/api/pushconf_threshold从0.35提高到0.5会明显减少误报但也会把一部分低置信度的真实小目标过滤掉这个数值的调整最好配合当天能见度条件晴天用0.5雾天降到0.3。reconnect_interval控制RTSP断线重连的间隔设置为5秒是平衡识别实时性和网络压力的结果太短会频繁重连把设备搞崩太长会漏掉断线期间的无人机活动。4.2 多级预警规则的场景化配置预警规则不能只有一个阈值要支持多级告警。常见设计是把预警分为黄色预警和红色预警两级黄色预警是检测到疑似目标红色预警是目标持续存在且轨迹可疑。轨迹可疑的判断可以基于目标在画面中心区域停留的时长或目标朝向敏感区域移动的趋势这些规则全部在配置文件里声明Python代码只负责读取规则并执行。alert_rules: yellow: min_duration_sec: 3 min_confidence: 0.35 target_size_pixels: 40 red: min_duration_sec: 10 min_confidence: 0.6 target_size_pixels: 80 near_restricted_zone: true restricted_zones: - name: runway_area polygon: [[100, 200], [500, 200], [500, 600], [100, 600]]restricted_zones里的polygon定义的是画面坐标系里的禁飞区多边形目标框中心点落入多边形内才触发红色预警。target_size_pixels的单位是像素40像素以下的目标通常是远处的小鸟或噪声直接过滤既不损失真实目标又能砍掉大量干扰。配置文件不用改代码的优势在这里体现现场工程师看到误报直接改YAML里对应规则保存后系统自动热加载不用等开发人员改代码发版本。4.3 数据目录data1到data4的组织逻辑项目里出现的data1、data2、data3、data4四个数据目录从文件类型和业务逻辑推断分别对应四个不同的数据流data1是模型训练用的标注图像集data2是系统运行时的实时截图缓存data3是预警事件的历史记录data4是负样本库专门收集飞鸟、气球、风筝等容易误检的干扰目标。这种按用途切分而不是按时间切分的方式在模型迭代时非常高效训练新版本模型时只需要把data1和data4按比例合并不会因为混着运行时截图导致训练集脏数据。5. 端到端验证与高频排错实战源码能跑通和能稳定运行是两码事这个系统的验证链路分三层环境层、模型层、业务层。环境层先验证摄像头和RTSP流能正常读取模型层验证推理输出能正确框出目标业务层再验证整条预警链路包括通知发送。任何一层失败都能通过日志快速定位。我在部署这类系统时会先跑一个单帧测试脚本输入一张JPEG图片输出检测结果的标注图确认模型权重文件本身没问题再接入实时视频流这样能把变量拆开。5.1 从源码启动的完整命令序列拿到源码包后按顺序执行先跑init_env.sh装环境再改detector.yaml里的视频源地址最后用start.sh启动。启动后别急着看画面先看一眼日志里的推理耗时和检测数量推理耗时超过100毫秒说明设备算力不够或者输入分辨率设置过高检测数量一直为0则大概率是模型路径配错了或者RTSP流用户名密码不对。# 初始化Python环境 ./scripts/init_env.sh # 启动识别预警服务 ./scripts/start.sh # 查看实时运行日志 tail -f logs/drone_detector.log # 手动执行一次测试推理验证模型完整性 python scripts/test_inference.py --image samples/test_input.jpgtest_inference.py跑完会输出检测到的目标数量和坐标信息如果输出为空先用python手动加载模型看看能不能成功读入ONNX文件很多情况下是onnxruntime和opencv-python的版本冲突导致模型加载直接抛异常。5.2 高频故障与其排查方向实际部署里最常遇到的问题基本集中在这几类排查顺序也是从下往上先看环境再谈业务。如果是Docker部署还要额外检查容器内的时区和内存限制是否合适。故障现象大概率原因排查命令或操作启动报缺少Python模块requirements.txt未安装完整pip list | grep 模块名画面黑屏无帧输出RTSP地址错误或摄像头编码格式不支持ffprobe rtsp_url 确认流信息检测框一直在但报警不触发enter_frames数值过大或状态机未进入ALERT态查看日志中state字段的变化日志报CUDA错误环境是CPU设备但配置里device写了cuda检查detector.yaml中device: cpu模型加载异常ONNX版本与opencv-dnn不兼容python -c import cv2; cv2.dnn.readNetFromONNX(xxx)表格里的前两行覆盖了最常见的两类问题。RTSP流无法读取时用ffprobe确认地址可用只是第一层验证很多海康大华的摄像头新固件默认开了H.265编码OpenCV对H.265的支持不完整需要到摄像头后台切换成H.264编码再试。模型加载报错则几乎都是版本兼容问题OpenCV的dnn模块对不同版本ONNX算子支持度有差异建议固定使用requirements.txt里锁定的版本不要轻易升级。5.3 SIGHUP热加载与报警通知联调技巧最后分享一个我在实际项目里总结的联调技巧报警通知先接到本地HTTP服务调试用nc命令模拟告警中心接收请求确认Python代码确实把预警信息推送出去了再接真实消息平台。命令很简单在后台监听端口然后触发一次预警看终端是否打印出POST请求。# 监听本地9000端口模拟告警中心接收推送 nc -l 9000 # 手动触发一次测试预警 python scripts/test_alert.py --level red # 观察推送内容检查时间戳和坐标字段是否完整 tail -f logs/alert_push.logtest_alert.py会往配置的webhook_url发送一条真实格式的JSON消息如果nc窗口里能看到完整请求体说明Python和Shell这条预警链路已经全部打通。之后再把webhook_url改成真实平台地址替换配置文件后进程会自动加载不需要重启服务这就是热加载配置带来的调试效率。整个系统的故障处理核心就是拆变量模型、视频源、配置、Shell脚本四个层分开验证哪一层的问题都不会蔓延到其他层这是源码里分层设计的最大收益。本文还有配套的精品资源点击获取