deploy: ONNX toolchain — export, precision pass (fp16 sea / fp32 Q/DQ islands), graph modify

[vividf]

Stacked PR 4/15 — ⬅ #13 | #15 ➡

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 是什麼

ONNX 工具鏈,本 stack 最需要細看的一層:export 包裝、兩條 precision pass、config 驅動的圖手術。

Precision pass:自動路由(模型端零 precision 代碼)

圖的事實	走哪條	原因
有 plugin domain(autoware::)	自家 island cast,整圖無島	AutoCast 用 TRT parser 推型別,不認未註冊 plugin op
有 Q/DQ(INT8/FP8)	自家 island cast:fp32 島 + fp16 海	AutoCast 拒收 Q/DQ 模型;island 是正確性地基(見下)
純圖	ModelOpt AutoCast(autocast.py)	有逐節點數值守門

Island 規則手冊(全部是量出來的)

誰進島(_quantized_island_names,4 條依序):① 所有 Q/DQ 節點;② scale/zero-point 的 producer(fp32 scale 位元組級保留——scale 就是量化本身);③ 每個 DQ 輸出的消費者(量化 Conv/Gemm 本體);④ 反向生長:從每個 Q 的 data 輸入只沿 float data slot 往回穿過 commuting whitelist,讓「量化 op → pointwise → 下一個 Q」整段零 cast。

cast 放哪:只在島↔海與圖 IO 邊界,每條跨界 float 邊恰好一顆;整數邊(zero-point/shape/indices)永不 cast——_ISLAND_FLOAT_INPUT_SLOTS 逐 op 顯式表 + import 時 assert 與 whitelist 鎖死(擴 whitelist 忘了 slot 行 → import 直接爆)。圖 IO 保 fp32(runtime ABI)。

違反的實測代價:

規則	代價
scale 保 fp32	fp16-typed Q/DQ 踩 TRT 10.8/10.16 缺陷:fp16 合併 scale subnormal → 融合 kernel 產 NaN、build 零警告(PTv3 mIoU 0.73→0.075;自包含 20-node repro:work_dirs/fp8_probe/nvidia_minimal_repro.py,ORT 同圖算得對,四實作對一)
DQ→消費者直連	TRT INT8 融合 pattern 對不上,build assert("1 scale factor element")
鏈到下一個 Q 零 cast	Q-propagation 被 Cast 擋 → 量化 conv 具現化 fp32:同 backbone 4.76 vs 3.87 ms
海全 fp16	未量化區跑 fp32:CenterPoint 6.75 vs 4.44 ms

心智模型:島的 fp32 是「記號」不是執行精度——TRT 把島內 DQ→Conv→Relu→Q 融成 int8 進出 kernel;實際執行 = 海 fp16、島 int8、邊界 cast 實測共 0.118 ms。

維護契約與防呆

• whitelist 是 per-TRT-version 契約;斷鏈分級警告:真缺口 WARNING(附兩條出路)、已知非交換 op(LayerNorm/Gelu…)DEBUG——量化不可交換的 op 留在 fp16 海、之後 requantize 是設計而非缺口(islanding 它們只會逼 fp32 執行)。
• 反向生長「只沿 float slot」是 battery 抓過的真 bug 修正:Gather 入 whitelist 後 int64 索引鏈被拖進島 → 邊界 cast 污染 int 邊 → parse 爆。
• 控制流子圖(If/Loop/Scan)明確 raise,不靜默轉出混型圖。
• in-house 而非 onnxconverter-common 的理由:該庫在島內插 round-trip cast、留過期 value_info、島清單被重算——三層補丁;自家 pass 從構造上只在真邊界造 cast,補丁不需存在。

逐檔導覽

• onnx/precision.py:island pass 全部(路由事實函式、whitelist、slot 表、成員資格、cast pass、斷鏈警告)。
• onnx/autocast.py:ModelOpt AutoCast 包裝 + keep_topk_in_fp16(TopK 的 fp16 保持器)。
• onnx/export.py:torch.onnx.export 包裝(dynamic axes/shapes、外部資料合併)。
• onnx/modify.py:deploy.onnx.modify_graph 的圖手術執行器。
• 測試:test_onnx_export.py(19 個:island 位元組級精確、castless 鏈、shape-op 生長不碰 int 邊、控制流 raise、boundary rewire、FP8 拼法…)。

檔案清單(點開)

autoware_ml/deployment/onnx/__init__.py 47 ++
autoware_ml/deployment/onnx/autocast.py 134 ++++++
autoware_ml/deployment/onnx/export.py 253 ++++++++++
autoware_ml/deployment/onnx/modify.py 69 +++
autoware_ml/deployment/onnx/precision.py 481 +++++++++++++++++++
autoware_ml/tests/deployment/test_onnx_export.py 573 +++++++++++++++++++++++

Review checklist

• 4 條成員資格規則逐條對 docstring 的實測理由。
• slot 表逐 op 檢查(哪個輸入是 int)。
• _warn_broken_quantized_chains 的一跳偵測邏輯(為什麼只查一跳)。
• 驗證:189 單測 + 三模型六臂 battery 全基準(CenterPoint INT8 4.43ms/0.4538/gates PASS;BEVFusion INT8 5.44/0.4223、FP8 0.4515;PTv3 QAT 0.7339/7.02)。

🤖 Generated with Claude Code