deploy: stage-graph foundation (GraphStage/TorchStage) + shared runtime utils

[vividf]

Stacked PR 3/15 — ⬅ #12 | #14 ➡

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

Deployment 框架的地基:stage graph + 全 stack 共用的輕量 utils。從這個 PR 起每一層都值得細 review。

核心設計:模型自述怎麼拆

一個模型的 deploy 面 = 一個 build_stages(),回傳 stage 序列,只有兩種 stage:

• GraphStage:一張可匯出子圖 = 一份 ONNX = 一顆 engine。宣告 name/module/inputs/outputs;inputs/outputs 名就是 ONNX IO 名,值經 StageContext(跨 stage 的 name→tensor 字典)取放。進階欄位各有明確語意:torch_fallback_backends(某 backend 跑不了這張圖時退回 torch,如 spconv 圖之於 ORT)、onnx_dynamic_axes(宣告即動態的維度,如點數)、onnx_transforms(這張圖固有的匯出後重寫,如 bias+activation 摺進 plugin 節點)、output_fields(最終 stage 輸出 → assemble_predictions 的鍵名映射)。
• TorchStage:不可匯出的膠水(voxelize/scatter/索引計算),永遠跑 PyTorch,簽名 fn(context) -> {name: value}。

為什麼這樣設計:真實模型不是一張圖(sparse conv 要 plugin、動態索引、不該進圖的前處理)。stage graph 把「哪裡可以是圖、哪裡必須是 torch」變成模型的宣告,pipeline 照宣告執行——新模型不改框架,框架不認識任何模型。

逐檔導覽

• deployment/stages.py:兩個 stage dataclass、StageContext、validate_stages(名字唯一、宣告完整、output_fields ⊆ outputs)、artifact_path 命名規則。
• types/backend.py:Backend 型別(pytorch/onnx/tensorrt)。
• utils/config_parsing.py:reject_unknown_keys——deploy 與 quantization 的 config schema 共用同一個 unknown-key 驗證(打錯字的 option 立即爆,不會靜默落到預設值)。
• utils/runtime.py、builders/mlflow_builder.py(run-status context manager)+ 測試:pr7(quantize script)與 pr8(deploy script)都依賴,故下沉到地基層。
• autoware_ml/__init__.py(license header)、.gitignore(+work_dirs)。

檔案清單(點開)

.gitignore 2 +
autoware_ml/__init__.py 22 +++
autoware_ml/builders/mlflow_builder.py 26 +++-
autoware_ml/deployment/__init__.py 27 ++++
autoware_ml/deployment/stages.py 193 +++++++++++++++++++++++++++
autoware_ml/tests/deployment/__init__.py 0 
autoware_ml/tests/utils/test_mlflow_utils.py 6 +-
autoware_ml/types/backend.py 48 +++++++
autoware_ml/utils/config_parsing.py 44 ++++++
autoware_ml/utils/runtime.py 15 +++

Review checklist

• validate_stages 的錯誤訊息品質(新模型作者宣告錯誤時的第一接觸面)。
• GraphStage.__post_init__ 的 output_fields 檢查是否涵蓋常見宣告錯。
• 共用 utils 放地基層的取捨(替代:各層自帶 → 重複)。

🤖 Generated with Claude Code