06 · ML 工具鏈與實驗管理
來源:本機技能沉澱(無單一原始文件;以官方文件與實務經驗綜合) 網路充實:2026-11-12(查證 vLLM v0.32 / SGLang v0.5.23 現行版本、TGI 維護狀態、TRL 1.9 與實驗追蹤工具現況)
一、環境管理:uv 為預設,conda 只補非 Python 依賴
| 工具 | 定位 | 何時用 |
|---|---|---|
| uv | Rust 寫的解析器 + venv + lockfile | 預設首選,uv sync 秒級 |
| conda / mamba | 管 CUDA toolkit、cuDNN、編譯器 | 需要釘系統級 CUDA 時 |
| pip-tools | requirements.in → requirements.txt |
舊專案、要可審核的純 pip 流程 |
實務建議:uv 管 Python 套件、Docker image 釘 CUDA,兩者分責,勿在同一專案用 conda 與 uv 裝同一個 torch。
CUDA 與 PyTorch 的坑(最常炸的地方):
| 現象 | 原因 | 解法 |
|---|---|---|
driver version is insufficient |
驅動低於 wheel 的 CUDA runtime | 升級驅動或改裝較低 cuXXX wheel |
undefined symbol |
torch 與 vLLM / flash-attn 編譯期 CUDA 不一致 | 三者對齊同一 CUDA 版本 |
| 同一 image 本機可跑、叢集不行 | 驅動只在 host | 用 nvidia-container-toolkit,勿在 image 裝驅動 |
原則:PyTorch wheel 自帶 CUDA runtime,只需 host 驅動夠新(同 major 內有 minor 相容)。
二、實驗追蹤:先看你要不要自架
| 工具 | 型態 | 優勢 | 弱點 |
|---|---|---|---|
| W&B | SaaS 為主 | 曲線、sweep、報告最順 | 費用隨人數長、資料出企業 |
| MLflow | 可自架 OSS | 追蹤 + registry + serving 一體 | UI 較舊、大規模要養後端 |
| TensorBoard | 本地 / 免費 | 零成本、PyTorch 原生 | 無協作、無 hyperparam 比較 |
決策:個人/小團隊先用 TensorBoard 或 MLflow 本機;要多人比較與 sweep 再上 W&B;資料不能出境的用 MLflow 自架。 別為 3 個實驗架 SaaS。
最低要求(無論用哪個):每次 run 記下 git commit、資料集雜湊、完整 config、硬體、seed。少這五樣,實驗就不可重現。
三、資料版本控制
| 方案 | 適用規模 | 說明 |
|---|---|---|
| git + 雜湊檔 | < 100MB | 檔案放物件儲存,git 只存 sha256 + 路徑 manifest |
| DVC | 中大型 | dvc.yaml 定義 pipeline,資料存 S3/GCS,git 存指標 |
| HF Datasets | 公開/半公開 | 自帶版本、串流、push_to_hub |
最小方案:manifest.json 記路徑+sha256,就夠回答「用哪版資料訓的」。
四、模型與權重管理
- 權重一律不進 git;用 HF Hub 私有 repo 或 S3 + 版本前綴。
- Git LFS 只加速 clone,不省儲存費,部分 CI 也不支援。
- Model registry 至少要有:模型 id、base model、訓練 config、eval 分數、推出日期、資料集雜湊。
- 8B bf16 約 16GB、4-bit 約 5GB;70B bf16 約 140GB,傳輸成本要算進部署時間。
實務上「資料夾 + JSON metadata + 物件儲存」已夠 90% 團隊;registry 的價值是上線審批紀錄,不是儲存本身。
五、服務框架:何時用哪個
| 框架 | 適用 | 不適用 |
|---|---|---|
| FastAPI + vLLM | 自架 LLM 推論的預設答案 | 需要複雜多模型 DAG 時 |
| SGLang | 大量共用前綴(agent、多輪、固定 RAG 模板) | 需要最廣模型覆蓋時 |
| Triton Inference Server | 多框架、多模型、企業級排程 | 小團隊,維運成本過高 |
| BentoML | 要打包成可移植 artifact、快速出 API | 極致吞吐調優 |
| Ray Serve | 多模型組合、需要弹性擴展的複合 pipeline | 單一模型單純服務 |
2026 現況:vLLM 與 SGLang 開箱效能接近,選型看「哪個先支援你的模型」與「流量是否共用前綴」,別看廠商貼的倍數。TGI 已由維護者建議遷移,新專案不要起。TensorRT-LLM 最快但學習曲線陡、僅 NVIDIA。
六、容器與部署:image 大小是維運成本
| 基底 | 大小(約) | 建議 |
|---|---|---|
nvidia/cuda:12.x-devel |
8–12GB | 只在編譯 stage 用 |
nvidia/cuda:12.x-runtime |
3–5GB | 推論 image 的合理起點 |
python:3.12-slim |
150MB | 純應用層(打 API、不碰 GPU) |
做法:multi-stage — builder 用 devel 裝 uv 與編譯依賴,runtime 只複製 venv 與程式。GPU 推論常見結果 6–8GB;權重用掛載卷或 init container 下載,不要烘進 image。
七、CI/CD for ML
| 階段 | 檢查 |
|---|---|
| lint / type | ruff + mypy,30 秒內結束 |
| 單元測試 | pytest,資料用 10 筆假資料 |
| smoke test | 真的載入小模型跑 1 次 forward,抓 CUDA/依賴錯 |
| eval gate | golden set 分數低於基線就 fail |
| 產出 | model card 與 artifact |
CI 不要跑完整訓練。CI 證明「能跑」,不證明「效果好」;效果驗證放在獨立 eval pipeline。
八、專案結構建議
repo/
pyproject.toml # uv 管理
src/pkg/{data,train,eval,serve}/
configs/ # 每個實驗一份 yaml
tests/
data/manifest.json
config 管理:實驗參數用 Hydra(可組合、可覆寫),服務設定用 pydantic-settings(吃環境變數、有型別驗證)。Hydra 給訓練,pydantic 給 runtime,別互換。
實務檢查清單
- [ ]
uv.lock與 Dockerfile 已提交,新人 10 分鐘可跑起 - [ ] CUDA / torch / vLLM 版本對齊並寫進 README
- [ ] 每次 run 記錄 commit、資料雜湊、config、seed
- [ ] 權重不進 git,有 registry 或 manifest
- [ ] CI 有 smoke test,能抓「載不進模型」這類錯
- [ ] image < 10GB,權重外掛,有 model card 與 eval gate
常見誤解
| 誤解 | 事實 |
|---|---|
| 「DVC 是資料版控的必要條件」 | 雜湊 manifest 已能回答 90% 的問題 |
| 「Triton 一定比 vLLM 快」 | 單一 LLM 場景 vLLM 通常夠用且好維運 |
| 「CI 跑完整訓練才叫 ML CI」 | CI 只驗證可執行性,效果驗證是另一條 pipeline |