gpu-hot：用 NVML 輪詢與 hub 聚合看住你的 NVIDIA 卡
🔥 Real-time NVIDIA GPU dashboard
秒懂
- 它是什麼？
- gpu-hot 是一個以 FastAPI 加 Socket.IO 推送即時指標的自架儀表板，單機與多節點用同一個映像檔。它的價值在輪詢頻率與部署成本，風險則在 hub 模式的網路暴露面與前端渲染負擔。
- 適合誰用？
- 如果你手上有幾台裝了 NVIDIA 卡的機器，想要一個不依賴雲端、能同時看單機與跨節點指標的介面，gpu-hot 的部署成本很低：一個 docker run 就能跑起來，多節點再加一個 hub 容器。如果你的環境需要長期保存歷史指標、跨重啟查詢趨勢、或需要對外網開放監控端點，這個專案不適合，因為 README 描述的歷史圖表是前端行為，持久化儲存並未出現在專案結構中，而 hub 節點是明文 HTTP。
- 可以商用嗎？
- 可以。MIT 是寬鬆授權：你可以使用、修改並販售以它為基礎的軟體，只需保留著作權與授權聲明。
- 還在維護嗎？
- 有在維護。儲存庫最近一次提交在 22 天前。
- 用什麼語言寫的？
- 主要是 JavaScript（依據 GitHub 的語言統計）。
以上回答依據專案的 GitHub 資料（最近同步於 2026年9月15日）與我們的分析，不構成法律意見。
開源專案深度解析
它解決的是「現在這張卡在幹嘛」這個問題
nvidia-smi 本身能回答這個問題，但它是快照，你得反覆手動執行，而且一次只能看一台機器。gpu-hot 把這件事變成一個常駐的網頁：後端持續輪詢 GPU，前端用 WebSocket 接收推送並畫成卡片與折線圖。README 列出的指標涵蓋利用率、溫度、記憶體、功耗、風扇轉速、時脈、PCIe 資訊、P-State、節流狀態，以及編解碼器工作階段。這份清單比多數人日常會看的欄位更長，P-State 與節流狀態對排查降頻問題特別有用。
目標讀者很明確：自己管機器的人。跑本地 LLM 推論、跑訓練、跑算圖農場，手上有一到數十張卡，不想為此接一套 Prometheus 加 Grafana 的堆疊。README 說它可以從 1 張卡擴到 100 張以上，但這個數字來自文件陳述，不是實測結果。真正決定它好不好用的是輪詢間隔與節點數量這兩個變數。
資料流：NVML 輪詢、Socket.IO 推送、前端批次渲染
後端是 FastAPI，入口在 app.py，路由與 WebSocket 處理分別放在 core/handlers.py 與 core/hub_handlers.py。真正的取樣邏輯在 core/monitor.py，走 NVML；core/metrics/collector.py 負責收集，core/metrics/utils.py 處理數值。如果 NVML 在新卡上正常但舊卡取不到值，core/nvidia_smi_fallback.py 提供另一條路徑，改用 nvidia-smi 的輸出解析。這是兩套不同的取樣機制，間隔也分開設定。
前端不是被動接收。static/js/socket-handlers.js 做的是批次渲染，也就是把短時間內到達的多筆更新合併後再更新 DOM，避免每個推送都觸發一次重繪。static/js/chart-manager.js 管圖表的資料與生命週期，chart-config.js 放 Chart.js 的設定，chart-drawer.js 是關聯性抽屜。這個分工說明作者清楚高頻更新下前端的成本在哪。
有一個設計值得指出：README 明確寫著，沒有客戶端連線時輪詢會自動暫停，閒置時 CPU 使用率接近零。這對長時間掛著的監控服務是合理的取捨，代價是斷線期間的資料不會被補回來，歷史圖表因此存在斷點。
啟動方式與關鍵環境變數
單機最短路徑是一行：docker run -d --gpus all -p 1312:1312 ghcr.io/psalias2006/gpu-hot:latest，然後開 http://localhost:1312。前置條件是 Docker 加上 NVIDIA Container Toolkit，兩者缺一不可。
多節點分成兩側。每台 GPU 伺服器跑同樣的映像檔，加上 -e NODE_NAME=$(hostname) 讓節點有可辨識的名稱；hub 機器不需要 GPU，用 -e GPU_HOT_MODE=hub 搭配 -e NODE_URLS=http://server1:1312,http://server2:1312,http://server3:1312，以逗號分隔。NODE_URLS 在 hub 模式下是必填。
其餘可調的鍵：NVIDIA_VISIBLE_DEVICES=0,1 限制只看特定卡，預設全部；NVIDIA_SMI=true 強制走 nvidia-smi 模式，README 建議在舊卡上指標出不來時加；UPDATE_INTERVAL 是 NVML 輪詢間隔，預設 0.5 秒；NVIDIA_SMI_INTERVAL 是 fallback 的間隔，預設 2.0 秒。埠號 1312 寫在 core/config.py 的 PORT，不是環境變數，要改得動程式碼。
想看行程名稱的話，README 給的作法是加上 --init --pid=host，並附帶一句提醒：這會讓容器存取主機的行程資訊。這是一個實質的權限擴張，不是裝飾性的旗標。從原始碼啟動則是 git clone 之後 docker-compose up --build。
hub 模式的代價：明文 HTTP 與單點依賴
hub 模式的實作在 core/hub.py。它的工作是輪流去打各節點的 /api/gpu-data 或對應的 WebSocket，再把結果彙整成一份給前端。這裡有兩個具體限制。
第一，NODE_URLS 用的是 http:// 前綴，README 全文沒有提到 TLS、認證或權杖。這代表任何能連到節點 1312 埠的人都能讀到完整的 GPU 指標與行程資訊，而行程資訊可能包含模型名稱、資料集路徑這類不該外流的字串。文件在疑難排解段落裡給的建議是 sudo ufw allow 1312/tcp，那是開通而非收斂。要安全就得自己在外層加反向代理與網路隔離，這部分專案沒有提供。
第二，hub 是聚合點。節點離線時，README 給的排查方式是 curl http://node-ip:1312/api/gpu-data 確認連通性，這說明 hub 對節點的偵測就是靠請求失敗。節點數量增加時，hub 要維護的連線數也跟著增加，而 hub 機器本身不需要 GPU，意味著它的規格取決於節點數而非算力。文件沒有描述 hub 在高節點數下的行為上限。
它不保存歷史，這件事比看起來重要
README 的 Features 裡寫著 Historical charts，涵蓋利用率、溫度、功耗與時脈。但把專案結構看一遍：core/ 底下是 config、monitor、handlers、hub、hub_handlers、nvidia_smi_fallback 與 metrics 兩個檔案，沒有資料庫層，沒有時序資料庫客戶端，requirements.txt 的內容未在材料中列出但專案結構裡找不到對應模組。合理的推論是這些圖表的資料只存在瀏覽器端記憶體裡。
這個推論如果成立，後果很具體：重新整理頁面，圖表從零開始；換一台電腦開儀表板，看不到剛才那段時間的曲線；要回答「昨天下午三點那張卡為什麼掉到 30%」這種問題，gpu-hot 幫不上忙。它是一扇窗，不是一台錄影機。
如果你的需求是事後追查，Prometheus 加 dcgm-exporter 是更合適的組合。dcgm-exporter 由 NVIDIA 維護，把 GPU 指標暴露成 Prometheus 格式，由 Prometheus 負責長期儲存與查詢，Grafana 負責視覺化。差別在架構取向：gpu-hot 把取樣、傳輸、呈現壓在一個容器裡，換來五分鐘上線；dcgm-exporter 那條路把三者拆開，換來可查詢的歷史與既有的告警生態，代價是要維護三個元件與它們的設定檔。
輪詢間隔是唯一真正有效的效能旋鈕
README 在疑難排解裡對效能問題只給了一個建議：把 UPDATE_INTERVAL 調大，例如 -e UPDATE_INTERVAL=2.0。這等於承認取樣頻率是主要成本來源。預設 0.5 秒代表每秒兩次 NVML 查詢，乘上 GPU 數量與指標欄位數，再加上序列化與 WebSocket 推送。
這裡有個不明確的地方：UPDATE_INTERVAL 只控制 NVML 路徑，走 nvidia-smi fallback 時由 NVIDIA_SMI_INTERVAL 控制，預設 2.0 秒。兩條路徑的間隔是獨立的，README 沒有說明同時生效時的行為。舊卡使用者如果只調了 UPDATE_INTERVAL 卻發現沒變化，原因可能就在這裡。
另一個未在文件中交代的點是 hub 模式下 UPDATE_INTERVAL 的歸屬。它是設在節點端還是 hub 端，還是兩者都要設，材料沒有說明。實務上應該設在節點端，因為取樣發生在那裡，但這是推論，不是文件保證。
前端方面，socket-handlers.js 的批次渲染是為了吸收高頻推送。如果節點數多、每節點又多卡，前端要處理的資料量會線性成長，而 README 對這條路徑的極限沒有任何描述。文件提到可以擴到 100 張卡以上，但沒有說明那是在什麼間隔、什麼節點數、什麼瀏覽器條件下。
API 表面很小，這是優點也是限制
HTTP 端只有三個端點：GET / 給儀表板，GET /api/gpu-data 給 JSON 快照，GET /api/version 給版本與更新資訊。WebSocket 走 /socket.io/，訊息裡有三個頂層欄位：data.gpus 是每張卡的指標，data.processes 是作用中的 GPU 行程，data.system 是主機的 CPU、RAM、swap、磁碟與網路。
小的 API 表面意味著好接。要把 GPU 利用率丟進既有的告警腳本，打 /api/gpu-data 解析 JSON 就行，不需要學新的查詢語言。要自己寫一個更精簡的看板，接 /socket.io/ 拿同樣的資料也可以。
限制也在這裡。沒有查詢參數可以只取特定 GPU 或特定欄位，沒有分頁，沒有歷史區間查詢，沒有指標名稱的穩定性承諾。README 沒有把 API 標為穩定介面，而 v1.9.0 到 v1.9.2 之間隔了兩個月就有三個版本，欄位結構是否會在次版本間變動，得自己看 release notes 判斷。把它當成內部工具用沒問題，當成對外承諾的介面就要多一層轉接。
誰該用、誰不該用，以及導入前先驗什麼
適合的場景：單台或少量 GPU 機器，需要一個隨手可開的即時視窗；實驗室或小型團隊想同時看幾台機器的狀態，又不打算維運 Prometheus 堆疊；已經有 Docker 與 NVIDIA Container Toolkit，只想再加一個容器。這種情況下 gpu-hot 的啟動成本幾乎是零，MIT 授權也讓內部改動沒有額外顧慮。
不適合的場景：需要事後追查與長期趨勢；需要對外網或跨部門開放監控端點；需要以 API 形式對外提供穩定的指標介面；節點數量多到 hub 的聚合負擔成為瓶頸。這幾種情況該往 dcgm-exporter 加 Prometheus 的方向走。
導入前先驗三件事。一，在目標機器上跑 docker run --rm --gpus all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi，這是 README 給的容器 GPU 存取測試，過了才代表 --gpus all 真的有效。二，開起來後確認指標有沒有出現，舊卡要加 -e NVIDIA_SMI=true。三，如果要開行程監控，先想清楚 --pid=host 讓容器看見主機行程這件事能不能接受，不能就別加這個旗標。
授權是 MIT，條款允許修改與再散布，需保留著作權與授權聲明。這不是法律意見，商用前請自行確認你對映像檔來源與相依套件的合規要求。維護成本方面，材料顯示專案在 2026 年 5 月到 7 月之間出了三個版本，最近一次推送是 2026 年 8 月，屬於仍在活動的專案，但沒有任何關於支援週期或破壞性變更政策的說明。升級前建議先讀 release notes，並在非生產節點上先跑一次。
編輯結論
如果你手上有幾台裝了 NVIDIA 卡的機器，想要一個不依賴雲端、能同時看單機與跨節點指標的介面，gpu-hot 的部署成本很低：一個 docker run 就能跑起來，多節點再加一個 hub 容器。如果你的環境需要長期保存歷史指標、跨重啟查詢趨勢、或需要對外網開放監控端點，這個專案不適合，因為 README 描述的歷史圖表是前端行為，持久化儲存並未出現在專案結構中，而 hub 節點是明文 HTTP。導入前先確認三件事：容器內 nvidia-smi 是否正常、NVIDIA_SMI 是否需要設為 true、以及 hub 與節點之間的 1312 埠是否只在內網可達。
社群筆記