ML 採用手冊
此技能提供一套適應性強的方法論，用於將機器學習模型導入現有的軟體工程專案中。它透過結構化 ML 的研究、解耦、訓練與整合方式，縮小了傳統軟體工程（SWE）與 MLOps 之間的鴻溝。
啟用時機
- 使用者要求在其現有程式碼庫中「新增 ML」或「新增演算法」。
- 正在規劃將新模型（例如推薦、分類、預測）整合到非 ML 應用程式中。
- 為代理建構一個工作流程，以自適應地建立、訓練並部署 ML 元件。
階段 1：問題框架與可行性
在編寫模型程式碼之前，先確立「為什麼」與「怎麼做」。
- 啟發式檢查： 詢問使用者是否可以使用簡單的啟發式方法（例如正規表示式、基於規則的排序）更快解決問題。如果可以，從那裡開始。
- 指標定義： 定義 ML 模型試圖改善的業務指標（例如點擊率、降低延遲）。
- 錯誤預算： 定義「不良」預測的樣貌，以及系統應如何處理它。
階段 2：資料就緒性
沒有乾淨、可存取的資料，ML 就毫無用處。
- 審查資料來源： 識別訓練資料的存放位置。是即時資料庫、靜態 CSV 還是 API？
- 資料合約： 為輸入資料建立一個架構（schema）。需要哪些特徵？如果某個特徵遺失該怎麼辦？
- 防止資料洩漏： 確保使用者提出的資料分割不會意外地將未來資訊洩漏到訓練集中（例如，對時間序列資料進行時間順序分割）。
階段 3：架構整合與解耦
不要將模型推理與核心業務邏輯緊密耦合。
- API 邊界： 建議將模型放在 API 端點後面（例如使用
fastapi-patterns或django-patterns），或放在一個專用的服務類別中。 - 備用機制： 設計一個預設狀態。如果模型回應時間過長或拋出錯誤，系統必須優雅地回退到硬編碼規則。
- 功能標誌： 將新的 ML 推理呼叫包裝在功能標誌（feature flag）中，以便可以安全地逐步推出（或回滾）。
階段 4：模型實作與訓練
為程式碼建立可重現且可迭代的結構。
- 從簡單開始： 先建立一個基線模型（例如一個簡單的 scikit-learn Logistic Regression 或一個最基本的 PyTorch 線性層）。
- 可重現性： 應用
pytorch-patterns或類似的最佳實踐：設定隨機種子、使程式碼無關裝置、並明確記錄張量/陣列形狀。 - 自動化驗證： 要求對資料轉換和推理架構進行測試。不接受沒有評估腳本（能與基線進行比較）的模型。
階段 5：移交至 MLOps
一旦基線模型整合完成，將焦點轉移到持續營運。
- 參考
mle-workflow： 引導使用者設定實驗追蹤、模型註冊表和漂移偵測。 - CI/CD： 將模型評估步驟添加到現有的 CI 管道中，以確保未來的提交不會降低模型效能。
代理疊代工作流程
透過此手冊協助使用者時，代理應：
- 提出釐清問題 以在提出架構之前完成階段 1。
- 草擬資料合約（階段 2）供使用者核准。
- 在編寫訓練迴圈 之前，於階段 3 先撰寫解耦介面（API/服務）。
- 在階段 4 提供一個可重現的腳本，用於訓練模型並儲存產出物。