[犀牛鸟-A2]：加入可配置的小目标候选区域感知 STAL 分配器

[onion-hong]

问题

VisDrone 的密集小目标在数据增强和 resize 后可能缺少足够的候选网格。仓库原有 fixed-stride STAL 行为也无法直接作为纯 TAL 对照，因此本 PR 将候选策略显式拆为 pure、fixed 和 adaptive，并补齐机制诊断、配置校验和统一评测工具。

实现

• 增加 stal_candidate_mode={pure,fixed,adaptive}。默认仍为 fixed，保持当前仓库行为；旧的 stal_enabled=True 兼容入口选择 adaptive。
• adaptive 模式按增强后目标相对面积扩展候选区域，并支持面积自适应 top-k、最小候选保障、冲突感知放宽、候选质量/监督权重约束和零正样本救援。所有新增策略默认关闭或设置为行为中性值。
• STAL 数值参数进入统一配置契约，拒绝 bool 冒充数值、NaN/Inf、非法范围和互相抵消的参数组合。
• 面积乘积显式使用 FP32，避免 800×800 场景下 FP16 溢出导致小目标门控或候选容量误判。
• 训练 telemetry 分开记录增强后 STAL 相对面积组、COCO-style <32² 组和全体目标，并覆盖候选、alignment、top-k、冲突、救援及 target score。
• 增加项目 COCO-style 分档评测和 VisDrone 八字段 TXT 导出工具。评测使用原始验证图像 GT 面积与 maxDets=500，并明确这些面积档不是 VisDrone 官方分档。

与现有 A2 PR 的关系

当前 #274、#280 和 #293 也提交了 A2 方案。#274 强调候选扩展、分档 top-k、最小正样本路径和证据边界；#280 给出紧凑的三组结果与正样本覆盖表；#293 保留 A16 最小候选方案并报告其单 seed 最佳尝试。它们的训练配方、基线、分配规则和评测处理不同，APs 不能直接并表。

本 PR 的独立范围是：按训练画布相对面积连续插值 top-k、候选容量/质量/监督权重与 rescue 的正交开关、分配阶段及 target-score telemetry、FP16 面积乘积保护，以及带输入完整性检查的 COCO-style 分档评测和官方 TXT 导出；实验上提供同配方 FP32 pure/fixed/adaptive 三 seed 对照及成体系的参数/失败分析。#253 已合入的候选冲突修复是本工作的上游依赖，不作为本 PR 的新增贡献。各份实现不应机械合并；review 时可按配置 API、默认兼容性、测试与诊断需求选择保留范围。

额外上游贡献

在推进 A2、复核训练与评测可信度的过程中，我还定位并提交了多项独立的上游缺陷修复。截至本 PR 提交时，以下 8 项均已合入 Tencent/YOLO-Master:main：

• #263 fix(train): reset accumulation after epoch recovery：恢复并重跑 epoch 前重置梯度累积游标并清理残留梯度。
• #267 fix(mixture): count routed auxiliary loss once for vector task losses：避免向量任务损失重复计入路由辅助损失。
• #268 fix(agent): supervise jobs and query process state safely：修复 Agent 任务监督及进程状态查询的可靠性问题。
• #269 fix(data): restore GC state and preserve archive inputs：恢复数据流程修改的 GC 状态，并避免破坏归档输入。
• #270 fix(model-zoo): validate each redirect before following：逐跳校验模型下载重定向，避免绕过目标校验。
• #271 fix(ui): render OBB and classification result tables：修复 OBB 与分类结果表的 UI 渲染。
• #272 docs(export): fix runnable Exporter examples：修正文档中无法直接运行的 Exporter 示例。
• #273 fix(train): replay epochs after prevalidation rollback：验证前回滚成功后重跑作废 epoch，避免将未保留的更新计入训练进度。

此外，较早提交的 #211 已修复 PEFT LoRA 在线模型与 EMA 的 scaling 状态不同步问题并合入主分支。以上修复不计入 A2 的算法创新或 APs 提升证据，单独列出供 review 核验。

实验协议与结果

正式对照使用完整 VisDrone train/val（6471/548）、YOLO-Master v0.1-N、imgsz=800、120 epoch、patience=0、batch 6、FP32、MuSGD、optimizer warmup 3、Mosaic 1/close_mosaic 10，选择每组 best.pt。主指标是原图 GT <32²、IoU .50:.05:.95、maxDets=500 的项目 COCO-style APs。

最终 adaptive-w0 配置为 stal_candidate_mode=adaptive、stal_area_threshold=0.0016、stal_relaxation=8、stal_warmup_epochs=0、stal_small_topk=10、stal_small_topk_min=10；候选质量门、最小候选保障、rescue、NWD 和 SimD 均关闭，aux_gain=1、mixture_aux_budget=3。

方案	seed 0	seed 1	seed 2	三 seed APs 均值 ± SD
pure TAL	12.947795	13.262371	12.880747	13.030304 ± 0.203752
fixed-stride STAL	13.064431	12.961409	13.156323	13.060721 ± 0.097510
adaptive-w0	13.414071	13.319065	13.135239	13.289458 ± 0.141754

adaptive-w0 相对 pure 的三 seed 配对均值为 +0.259154 个绝对百分点，95% Student-t CI 为 [-0.249674, +0.767982]；相对 fixed 为 +0.228738 点，95% CI 为 [-0.308802, +0.766278]。seed0 的 Mosaic-off 对照为 pure 11.692718%、adaptive-w0 12.001212%，差 +0.308493 点。

配对统计使用评测器未舍入的原始数值；表中各 seed 仅显示到小数点后六位。

P2 参数敏感性与失败分析

P2 采用参数敏感性路线，已覆盖面积门限、放宽幅度、warmup、面积自适应 top-k、候选质量/冲突处理和辅助损失交互；没有宣称第二数据集或 seg/pose 泛化。完整表格、协议边界和失败分析见 scripts/stal/EXPERIMENTS.md。

• 面积门限从原始 1% 收窄到 0.5%/0.3%/0.16%，最终 0.16% 进入完整训练；seed0 APs 从原 adaptive 的 13.167447% 提高到 13.337117%，再加入 8→10 面积 top-k 仅到 13.364341%。
• 放宽幅度 r4/r6/r8 的短筛没有单调关系。真实批次中 r0→r8 使冲突损失占已覆盖 GT 的比例从 10.49% 升到 12.31%，而高于 epsilon 的 alignment 比例都约为 7.64%。
• 完整数据 24 轮固定节点中，warmup 0/5/10 的 APs 分别为 9.207494%、8.964761%、8.626137%，因此选择 warmup0；这些只是筛选证据。历史四组中 epoch10/20/40 总体 mAP 排名与最终 APs 排名的 Spearman 相关分别为 -0.8/0.0/0.8，不能拿早期排名冒充 120 轮结论。
• 质量感知覆盖在 1618 图、24 轮中把训练 small 零正样本率从 10.2975% 降到 8.9193%、ARs500 提高 0.2018 点，但 APs 从 4.127463% 降到 4.108997%。这直接说明“覆盖改善”不是“有效监督改善”。
• fixed→原 adaptive 的预测诊断显示 AP50s +0.3761 点，但 AP75s -0.0489 点、ARs500 -0.0153 点；conf=0.1 的几何诊断中重复/竞争框和定位/混合错误分别增加 1356 和 1108。类别上 car 改善，而 people、van、truck 退步。上述是定位线索，不是可加和的 AP 因果分解。

现有证据支持的失败解释是：adaptive 确实扩大了候选覆盖，但新增候选中包含弱 alignment 和竞争监督，粗 IoU 检出改善没有稳定转化为严格 IoU 下的定位与排序收益；同时训练门控按增强后相对面积触发，而 APs 按原图面积分档，二者不是同一目标集合。保存预测已经经过 conf=0.001 和每图 500 框截断，因此仍不能把剩余差距精确分摊给原始检测头、NMS、分类或定位。

官方 VisDrone2018-DET-toolkit（commit 005445782213e20cb91bc50a597db3dd949e749a）也已用于原始 548 张 val annotation。pure 三 seed 的 AP/AP50/AP75/AR500 均值为 22.485790/40.305926/21.527257/39.055283%，fixed 为 22.766510/41.167061/21.611777/39.221645%；adaptive-w0 seed0 为 22.743838/41.140512/21.415664/39.090666%。当前留存的官方评测包不含 adaptive-w0 seed1/2 TXT，故不声称其官方三 seed 均值。官方指标不提供 small/medium/large 分档，不能替代上述 P1 APs；APm、APl、ARs500 和每档正样本统计列在实验文档中。

验证

• 361 passed, 1 skipped：全部 13 个 test_stal_*.py、test_tal_mps_regression.py 和 test_default_config_integrity.py
• 新增 scripts/stal/** 与 tests/test_stal_*.py 通过 Ruff check
• PR 内 23 个 Python 文件通过 ruff format --check
• git diff --check 通过

测试覆盖 pure 关闭等价、fixed 默认兼容、adaptive 激活、面积阈值边界、空 GT、极小框、重叠 GT、冲突、候选保障、配置非法值、FP32/BF16/FP16/AMP 有限值、E2E telemetry、分档评测和 VisDrone 导出合法性。提交前复核还增加了直接构造 assigner 时的布尔/数值边界，以及预测置信度 [0,1] 范围检查。

结论与限制

三 seed 平均 APs 为正向变化，但配对置信区间跨 0，且提升没有达到 P1 要求的 +1.0 个绝对百分点。因此本 PR 只提交可配置机制、可复核诊断、评测工具和当前实验事实，不宣称 P1 已完成。仓库既有 core lint 问题仍会使对整个修改核心文件执行 unrestricted Ruff check 报错；本 PR 新增的 STAL 脚本和测试本身已通过 lint。