models: BEVFusion export fusion + head correctness (permanent work, not parking)

[vividf]

Stacked PR 12/15 — ⬅ #21 | #22 ➡

Stack(base pr-stack-base = 7e35d97):#11 → #12 → #13 → #14 → #15 → #16 → #17 → #18 → #19 → #20(CenterPoint 全功能點)→ #21 → #25 → #22 → #23 → #24(= 開發 branch HEAD,逐位元一致)。合併由下而上,每合一層把下一層 base retarget。

這個 PR 是什麼(以及為什麼從 parking 拆出來)

BEVFusion 的 export fusion 與 head 正確性工作——永久資產。原本混在 #11(parking),review 時抓出:這些工作不會隨模型本體被替換——換了別人的 multitask 之後,BN fold、fused-MHA export、velocity-loss 修正照樣要在,埋在會被整塊丟掉的 parking 裡等於預約遺失。因此獨立成 PR。

逐檔導覽

• models/detection3d/encoders/sparse.py(+66):
  • _fuse_sparse_convolution_bn:在 export 副本上把每對相鄰(sparse conv, BatchNorm1d)fold 掉(用 spconv 的 fuse_spconv_bn_eval)——fold 必須發生在 export wrapper 建構之前,wrapper 才會帶著 fold 產生的 bias。部署圖無 BN、訓練 encoder 保留 BN。
  • _convert_sparse_convolution(do_sort):export 轉換帶 serialization order 參數。
• models/detection3d/heads/transfusion.py(+158):
  • fuse_export_attention:export 產出 fusion-ready 的 attention 形式——不擋 TensorRT Myelin 的 MHA 融合(實測 fused 0.25 ms vs unfused 0.68 ms @ j6gen2 dense 圖)。
  • shared_conv_norm_act:shared conv 的 conv(no bias)+BN+ReLU 形式(否則 BN+ReLU 會 clip 掉約一半 shared-feature 能量——註解載明)。
  • AWML 參考 ckpt 的暫時分支(TODO 標記待刪)。
  • velocity-loss masking:untracked 物件的 GT velocity 是 non-finite,必須離開 loss——masking 不夠因為 nan*0 還是 nan,target 也要歸零(與 CenterHead.loss 同慣例)。
• tests/models/test_bevfusion_sparse.py:BN fold 數值斷言(fold_scale 沿 dim0、expected_weight 逐元素)。
• tests/models/test_transfusion.py(+98):velocity masking 測試。

檔案清單(點開)

autoware_ml/models/detection3d/encoders/sparse.py 66 +++++++--
.../models/detection3d/heads/transfusion.py 158 +++++++++++++++++----
autoware_ml/tests/models/test_bevfusion_sparse.py 13 +-
autoware_ml/tests/models/test_transfusion.py 98 +++++++++++++

Review checklist

• fold 的「export 副本」語意:訓練模型絕不被 in-place 改動。
• fused-MHA export 形式與 models: PTv3 onboarding (stage graph, seg3d export, INT8 QAT/FP8) #23 PTv3 export_modules 的關係(同一哲學:export 態重寫、訓練態不動)。
• velocity masking 的 nan*0 陷阱處理與 CenterHead 慣例一致。

🤖 Generated with Claude Code