PositiveLoss/acoustic-uav-detector

来源: https://github.com/PositiveLoss/acoustic-uav-detector

战场环境中的声学无人机检测——复现

一篇开放复现论文：

《Acoustic UAV Detection in Battlefield Scenarios: Handling Noise, Domain Shift, and Weak Labels》
作者：Vadym Vilhurin, Volodymyr Sydorskyi, Andrii Shevtsov — ICMCIS 2026 · arXiv:2608.14287v1 (https://arxiv.org/abs/2608.14287)

该论文在同时存在三个难题的情况下，仅通过声音检测小型无人机：战场噪声、两种差异极大的麦克风间的传感器域偏移，以及弱且极度不平衡的标签（目标类别在训练数据中占比<1%）。
其解决方案包括：PCEN前端处理、将ConvNeXt-Tiny音频事件检测模型中的频率池化替换为可学习投影器，以及一套基于辅助类别、噪声注入混合与课程RMS掩膜的域感知训练策略。

本仓库完整实现了上述端到端方案，同时复现了论文的评估协议（表III–V、检测距离研究及图3–8）。

首先坦诚说明

论文数据非公开。
数据集包含由Zvook（https://zvook.tech）从前线与活跃防空传感器收集的30万+条录音。
缺乏该数据，无人能复现论文的具体数字。
但可复现的是方法和协议，这正是本仓库的核心：
忠实实现全部方法，并额外生成了一个结构复现论文数据的双域合成语料库——
Mic-1作为大型辅助域，Mic-2作为小型目标域，两者间存在传感器差异，训练→验证→测试集呈现从清洁到实战的场景迁移，且目标类别在训练数据中占比不足1%。
此处生成的数字基于合成音频，仅用于验证消融实验阶梯是否如论文所述般有效，而非声称复现论文结果。
若将清单指向真实录音，同一代码无需修改即可直接训练。

快速开始

uv sync  

在合成语料库上运行完整的表V消融实验阶梯（M1笔记本约需100分钟）：

uv run uav-detector ablation --preset demo --out-dir runs/demo --manifest data/manifest_demo.csv  

或快速检查流程（10个阶段，每阶段2个epoch，约10分钟）：

uv run uav-detector ablation --preset smoke --out-dir runs/smoke --manifest data/manifest_smoke.csv  

随后进行分析与绘图：

uv run uav-detector analysis --out-dir runs/demo --manifest data/manifest_demo.csv  
uv run uav-detector figures --out-dir runs/demo --manifest data/manifest_demo.csv  
uv run uav-detector report --out-dir runs/demo --manifest data/manifest_demo.csv  

预设配置：

注：paper预设若未指定清单，将动态生成约35万合成片段——这并非设计初衷，其本意应指向真实音频（参见在真实录音上训练）。

方法与代码对应关系

参数量符合论文预期：
使用GeM池化时为28.42M（论文：28.22M），
使用频率投影器时为31.08M（论文：30.97M），
即投影器增加2.66M参数（论文增加2.75M）。

双域语料库

synth.py 基于随机种子程序化生成每个片段——9秒@32kHz，无需下载，无磁盘占用，比特级可复现。
corpus.py 按表I和表II中每设备每类别的精确计数布局片段，可通过--scale缩放，保留使任务具有挑战性的比例关系。

三个刻意设计的选择体现了论文的难度：

• 类无人机混淆声源：发电机、摩托、风扇产生的谐波簇与四旋翼机同处60–260Hz频段，且具有强幅度调制。
  它们在清洁的现场测试训练集中几乎缺失（p=0.06），但在战区验证/测试集中常见（p=0.34/0.42）。
  这是验证集→测试集性能差距的主要原因，复现了论文自身的现象。
• 真正的弱标签：声源仅在片段部分时段可听（飞越包络可能降至近零），因此正样本片段中负帧占多数——这正是注意力池化与RMS掩膜存在的场景。
• 非线性传感器差异：Mic-2应用带软削波的电平相关AGC。线性频率响应会被逐样本标准化消除，而AGC的非线性特性使得域偏移持续存在于嵌入空间，表III–IV测量的是真实差异。

信噪比（SNR）故意设低：近距0–8dB，中距-8–1dB，远距-17–-6dB，现场/冬季/春季数据集分别偏移+3/0/-3dB。
试听语料库：

uv run uav-detector synth --scale 0.01 --materialise data/examples --limit 2  

图示

Log-Mel与PCEN对比（单条合成无人机片段）
论文图3的合成Mic-2小型无人机片段复现：
Log-Mel图被平稳噪声底主导，而PCEN抑制噪声底并暴露旋翼的调制谐波簇与飞越包络。

语料库各类别分面图
uav-detector figures会在/figures/生成：

• fig3_mel_vs_pcen.png与corpus_overview.png——即上述两图。
• tsne_.png——图4–7的四分面图：
  按类别/麦克风与季节划分的嵌入空间、仅目标类别的季节分布、按麦克风划分的噪声类别（此图中Mic-2簇明显分离）。
• fig8_range_roc.png——图8：近/中距与远距飞越的ROC曲线。

结果

完整表格见RESULTS.md，由uav-detector report重新生成。
demo阶梯在M1笔记本上约需100分钟。

小型无人机类别的测试集F1与论文报告值对比：

可复现部分：论文核心结论得到强有力复现。
仅在目标域训练导致崩溃（测试F1 22.3，精确度12.6%——模型对所有片段均触发），添加Mic-1辅助域及其四类飞行器后F1提升+50。
这对应论文贡献4：来自不同域的辅助无人机类别能提升目标域泛化能力。

SWA略微提升（+1.0），噪声注入混合提升更多（+1.3，且此步骤首次提升精确度：58.6%→65.0%），RMS掩膜无变化——
阶梯形状与论文一致（论文中这些步骤分别+9.9、+15.9、-0.4）。

PCEN是本实验中最大的单项增益（测试F1 +8.4），且几乎弥合了验证集-测试集差距：
所有Log-Mel阶段约90验证/72测试，而PCEN达到85/83。
这比论文报道的效果更强（论文中PCEN以少量测试F1换取鲁棒性），原因易解释：合成Mic-2链路末端是带软削波的电平相关AGC，自适应增益控制恰好能对此进行反向补偿。
真实硬件差异更复杂。

不可复现部分：两点，均具启示性：

• 频率投影器反而有害（Log-Mel分支-3.4 F1，PCEN分支-1.1），而论文中其提升+2.6。
  论文中其设计目的是在低频噪声掩盖基频时恢复谐波比。本语料库中基频通常完整，故额外容量无用武之地，且小数据集上20 epoch足以过拟合。
  这是合成数据的特性，并非反对论文设计的证据。
• 对抗验证未下降（表IV：论文从97.1%降至69.1%测试ROC AUC；此处所有配置均保持~97%）。
  合成传感器差异是确定性滤波器加固定AGC（应用于每个Mic-2片段），因此嵌入空间上的线性探测器总能完美恢复差异，无视任何增强。
  真实麦克风存在单元间与会话间差异，这正是噪声注入混合可模糊的对象。为模拟器添加逐录音硬件差异应是首要改进。

表III结果居中：全局传感器偏移的方向与排序可复现（增强模型比基线更能区分麦克风，PCEN比增强Log-Mel区分度更低——轮廓系数0.79 vs 0.73，论文0.208 vs 0.170），且PCEN给出最低的Mic-2噪声季节轮廓系数（0.100 vs 基线0.147），匹配论文的0.259 vs 0.385。绝对值远高于论文，因合成域可清晰分离。

检测距离研究在demo规模下运行但无意义：仅6个远距测试片段在3%子采样后保留，论文为241个。

PCEN模型嵌入空间t-SNE

嵌入空间定性复现了论文图4–7：
类别形成独立簇，Mic-2环境噪声形成独立且远离Mic-1噪声的簇（论文描述的域偏移），小型无人机簇紧邻其旁——误报正源于此——
且小型无人机验证集与测试集片段重叠，匹配论文发现：信号类别的季节偏移很小。

在真实录音上训练

docs/DATASETS.md 调研了可替代论文语料库的公共数据集、适配Mic-1与Mic-2角色的数据集，以及四个陷阱（采样率、片段长度、会话泄漏、语料库来源泄漏），否则生成的数字将无意义。

所有流程由清单CSV驱动：

uid,path,device,label,split,season,distance,seed  
rec-0001,/data/mic2/2026-03-01T09-12-33.wav,mic2,small_drone,train_small,spring,medium,0  

• path：真实音频文件（任何soundfile可读格式；重采样至32kHz并裁剪/填充至9秒），或synth://进行程序化渲染。
• device：mic1或mic2。
• label：small_drone、drone、jet_aircraft、helicopter、propeller_aircraft、noise。
• split：train_small、train_full、val、test。
  遵循论文做法：从连续流切割的片段应保持在同一分集中，否则评估会泄漏。
• season、distance：仅合成器与距离研究使用；distance若有可标注为人类可理解的“近/中/远”。

随后：

uv run uav-detector train --config configs/pcen_full.yaml --preset paper --manifest /data/manifest.csv  

追踪与恢复

训练每epoch后写入last.pt——包含模型、优化器、epoch、历史、top-k记录与RNG状态——中断运行可从此处继续：

uv run uav-detector ablation --preset demo --resume  

恢复以epoch为粒度：加权采样器无法epoch中回滚，中断的epoch会重做而非继续。
last.pt原子写入，崩溃时不会损坏；--force会删除它，因重训练≠恢复。
checkpoint_every平衡写入成本与中断可能丢失的工作量。

指标可发送至trackio（https://huggingface.co/docs/trackio），一个本地优先的追踪器：

uv sync --extra track  
uv run uav-detector ablation --preset demo --track --project uav-detector  
just dashboard  

每epoch记录损失、准确率、学习率、验证集宏F1/二分类F1及各类别F1；最终记录测试指标、参数量与运行时间。
阶梯的每个阶段在单一项目下按输出目录分组，使表V的十次运行在单一仪表盘中对齐。
无--track时追踪器为空操作对象，故trackio永不成为硬依赖。

导出至ONNX

uv sync --extra onnx  
uv run uav-detector export --run runs/demo/pcen_projector --input waveform  

两种输入契约，均输出含动态批次维度的probs、logits与embedding：

每次导出均与eager PyTorch在未追踪的批次大小上验证，若输出差异超过float32噪声（通常~5e-06）或形状漂移，运行会失败并明确报错。
音频契约——采样率、片段长度、步长、Mel数、前端、类别顺序——写入模型的metadata_props，使用者仅需文件：

import onnx, onnxruntime as ort, numpy as np  
meta = {p.key: p.value for p in onnx.load("model.onnx").metadata_props}  
classes = meta["classes"].split(",")  # small_drone索引为0  
session = ort.InferenceSession("model.onnx")  
probs = session.run(None, {"waveform": audio_batch})[0]  # (batch, 6), float32  

在M1 CPU上，PCEN波形图处理9秒片段仅需…