deploy: ORT/TensorRT backends (strongly typed), staged pipeline, cross-backend verification

[vividf]

Stacked PR 5/15 — ⬅ #14 | #16 ➡

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

三 backend 執行層 + 跨 backend 驗證 + deploy config schema。這幾個模組同 PR 是依賴閉環:verifier → pipeline → backends;config schema → verifier scenario 型別;models/base.py → utils/deploy(legacy 型別)→ backends。

設計決策

1. TensorRT 一律 strongly typed(tensorrt_builder.py):engine 精度由 ONNX 圖的型別決定,不由 builder flag 猜。weak-typed + FP16 flag 讓 TRT kernel 自選精度——在量化模型上實測翻車過;strongly typed 把精度變成圖上可審查的事實,與 deploy: ONNX toolchain — export, precision pass (fp16 sea / fp32 Q/DQ islands), graph modify #14 的 precision pass 構成閉環(圖怎麼寫、engine 就怎麼跑)。
2. plugin 載入時序:load_tensorrt_plugin_libraries 在 registry init 前載 .so;缺檔 FileNotFoundError;parse 失敗疑似 plugin 時錯誤訊息附 deploy.tensorrt.plugin_libraries 提示。
3. verification 哲學:量化/FP16 stage 的 raw-logit 跨 backend 差是預期行為(fake-quant vs 真 int8 kernel 捨入路徑不同),metric 相等才是真 gate。預設 tolerance 故意嚴,逼每個新模型做一次有意識的校準;fail 訊息給建議 gate(observed × SUGGESTED_GATE_HEADROOM=1.25,常數含出處註解)並要求把 observed 記進 config 註解。
4. StagedPipeline:三 backend 用同一套 stage 序列,差別只在 GraphStage 執行體(torch module / ORT session / TRT engine);PipelineCache 一 run 一 cache、無 invalidation(docstring 載明契約)。

逐檔導覽

• backends/tensorrt_builder.py:strongly-typed build、optimization profile、plugin 載入、workspace。
• backends/tensorrt_runner.py / onnx_runner.py:engine / ORT session 執行體。
• deployment/pipeline.py:StagedPipeline、PipelineCache、cuda-synced 計時。
• verification/backend_verifier.py:scenario 執行(config 宣告 pytorch(cuda) vs tensorrt(cuda) 等)。
• verification/output_comparator.py:遞迴逐 tensor 比 max_diff、建議 gate、caveat 機制(模型可宣告某輸出跨 backend 不可比的理由,gate 大聲跳過而不是配一個沒人能辯護的 tolerance)。
• deployment/config.py:deploy schema(unknown-key 驗證走 deploy: stage-graph foundation (GraphStage/TorchStage) + shared runtime utils #13 的共用 helper)。
• models/base.py:框架 hook + legacy export 契約(TODO 標記,過渡期)。
• utils/deploy.py:整檔 legacy(TODO 待刪),新路徑僅 models/base.py 的過渡型別 import。

檔案清單(點開)

autoware_ml/deployment/backends/__init__.py 20 +
autoware_ml/deployment/backends/onnx_runner.py 118 ++++++
.../deployment/backends/tensorrt_builder.py 158 ++++++++
autoware_ml/deployment/backends/tensorrt_runner.py 205 ++++++++++
autoware_ml/deployment/config.py 372 ++++++++++++++++++
autoware_ml/deployment/pipeline.py 278 +++++++++++++
autoware_ml/deployment/verification/__init__.py 33 ++
.../deployment/verification/backend_verifier.py 197 ++++++++++
.../deployment/verification/output_comparator.py 271 +++++++++++++
autoware_ml/models/base.py 1 +
.../deployment/test_backend_verifier_scenarios.py 95 +++++
autoware_ml/tests/deployment/test_deploy_config.py 162 ++++++++
.../tests/deployment/test_output_comparator.py 75 ++++
.../tests/deployment/test_pipeline_result.py 71 ++++
autoware_ml/utils/deploy.py 428 ++++-----------------

Review checklist

• strongly-typed 決策的註解是否足以說服未來想加 FP16 flag 的人。
• comparator 的遞迴結構比對(list/tuple/tensor;dict 明確不支援)邊界。
• utils/deploy.py 新路徑零依賴確認。

🤖 Generated with Claude Code