lupinemachines/lupine

LUPINE is a GPU over IP bridge allowing GPUs on remote machines to be attached to CPU-only machines.

LUPINE – GPU-over-IP 橋接器

是什麼 – LUPINE 讓沒有 GPU（或僅有 CPU）的機器能透過網路使用另一台主機上的 GPU。它透過提供一個輕量級的 CUDA 驅動程式模擬層（libcuda.so.1 與 libnvidia-ml.so.1）來實現，該模擬層會透過持久的 TCP 連接，將所有 CUDA API 呼叫轉發至遠端伺服器程序。

對 AI/ML 為何重要 – 使用現代深度學習框架（PyTorch、TensorFlow 等）進行訓練與推論需要支援 CUDA 的 GPU。LUPINE 讓這些 GPU 在本地看起來可用，因此現有程式碼無需修改，即可在廉價的 CPU 專用工作站、CI 執行器，甚至 Mac 上執行，而繁重的運算仍保留在遠端伺服器上。

核心元件

元件	功能
lupine-server (Docker 影像)	在擁有一个或多個 GPU 的機器上執行。接收來自客戶端的 RPC，執行真實的 CUDA 呼叫並回傳結果。
lupine-client (Docker 影像)	CUDA 驅動程式庫的即插即用替代品。當 CUDA 程式啟動時，客戶端的 `libcuda.so.1` 會攔截呼叫並轉送至伺服器。
模擬層 (`libcuda.so.1`, `libnvidia-ml.so.1`)	放置於客戶端的 `LD_LIBRARY_PATH` 上，使 `nvidia-smi` 及任何 CUDA 執行時庫等工具能自動使用 LUPINE，無需程式碼變更。
檢查點提供者（可選）	由使用者提供的程式庫，可在伺服器正常關閉後持久化連線識別碼並還原狀態。

主要功能（如 README 所述）

Docker 優先分發 – 伺服器與客戶端以即用型容器形式發布，支援任意 CUDA 版本（例如 cuda-13.1.0-ubuntu24.04）。
託管示範 – 提供一個公開的示範伺服器，配備 Tesla T4；您只需一條 docker run 命令即可嘗試。
跨平台 – 支援從 Linux、macOS（透過 Docker）以及任何可執行客戶端容器的平台使用。
多 GPU、多伺服器 – 您可列出多個 LUPINE_SERVER 端點；GPU 會作為單一序號清單暴露，跨主機的 cuMemcpyDtoD/cuMemcpyPeer 由客戶端進行中繼處理。
連線穩定性 – TCP keep-alive（60 秒空閒，15 秒探測，3 次重試）與指數退避連線重試機制可防止長時間執行的訓練工作在空閒時掛起。
追蹤日誌 – 設定 LUPINE_TRACE 為 0/1/2 或檔案路徑，可取得詳細的客戶端/伺服器 RPC 追蹤。
設備 printf 轉送 – 當內核使用 printf 時，LUPINE 會擷取設備緩衝區並轉送至客戶端的 stdout。
透過代理支援 TLS – 伺服器使用明文 HTTP/2；您可將其置於任何 TLS 終止反向代理（接受 HTTPS URL）之前。
優雅關閉檢查點 – 收到 SIGTERM 時，伺服器停止接受新連線，讓進行中的 CUDA 呼叫完成，並可選擇性呼叫使用者提供的檢查點程式庫。

典型工作流程

在 GPU 設備主機上啟動伺服器：

docker run --rm --gpus all -p 14833:14833 \
  ghcr.io/lupinemachines/lupine-server:cuda-13.1.0-ubuntu24.04

在 CPU 專用主機上執行客戶端，指向伺服器：

docker run --rm -it -e LUPINE_SERVER=<server_ip>:14833 \
  ghcr.io/lupinemachines/lupine-client:cuda-13.1.0-ubuntu24.04 nvidia-smi

輸出將顯示遠端 GPU，如同本地 GPU 一般。

在客戶端容器內執行任何 CUDA 程式（PyTorch、TensorFlow、自訂 CUDA 程式碼）。程式會看到名為 lupine:0（或 lupine:1，…）的設備，並可正常使用。
可選：多 GPU – 在 LUPINE_SERVER 中提供以逗號分隔的伺服器清單，以聚合多台機器的 GPU。
可選：檢查點提供者 – 若需在伺服器重啟後保留連線，請設定 LUPINE_CHECKPOINT_LIBRARY 與 LUPINE_SESSION。

範例用例 – PyTorch 訓練

倉儲附帶一個小型 Dockerfile，用於建構支援 PyTorch 的客戶端影像。建構完成後，您可執行訓練腳本（microgpt_train）連接到遠端 RTX 4090，並觀察損失下降，證明整個訓練迴圈可透過網路正常運作。

限制與注意事項（來自 README）

延遲 – 網路取代了 PCIe 連結，因此大規模資料傳輸（如影片編碼、巨大的主機到設備複製）可能成為瓶頸。模型訓練通常只移動一次模型，之後主要在設備端進行，因此影響較小。
無直接伺服器間對等存取 – 跨主機 cuMemcpyPeer 透過客戶端中繼處理；真正的零複製對等存取尚未支援。
認證/TLS – LUPINE 本身不實作認證；您必須將其置於 TLS 終止代理後，或添加自己的前端以實現加密或憑證檢查。
需匹配的 CUDA 版本 – 客戶端與伺服器影像必須使用相同的 CUDA 主/次版本建構；否則模擬層將不相容。
檢查點提供者為可選 – 若不提供，優雅關閉仍可運作，但狀態不會持久化。

快速入門

# 1. 嘗試公開示範（無需設定）
docker run --rm -e LUPINE_SERVER=demo.lupinemachines.com:14833 \
  ghcr.io/lupinemachines/lupine-client:cuda-13.1.0-ubuntu24.04 nvidia-smi -L

# 2. 在 GPU 機器上執行自己的伺服器
docker run --rm --gpus all -p 14833:14833 \
  ghcr.io/lupinemachines/lupine-server:cuda-13.1.0-ubuntu24.04

# 3. 從 CPU 專用機器執行 CUDA 程式（例如 PyTorch）
export LUPINE_SERVER=$(hostname -I | awk '{print $1}'):14833
docker run --rm -e LUPINE_SERVER=$LUPINE_SERVER \
  ghcr.io/lupinemachines/lupine-client:cuda-13.1.0-ubuntu24.04 python3 -c "import torch; print(torch.cuda.is_available())"

若最後一行命令輸出 True，表示 LUPINE 正確轉發了 CUDA 呼叫。

接下來可查看的內容

原始碼 – codegen/ 包含從 CUDA 標頭檔生成 RPC 存根的產生器；checkpoint_provider.h 定義了可選的檢查點 ABI。
文件 – README 覆蓋了大多數操作選項；如需深度整合（如自訂檢查點程式庫），請閱讀倉儲中的標頭檔。
社群 – GitHub 倉儲的 Issues 與 Pull Requests 討論了新增 TLS 前端、多主機對等存取等改進。

總結 – LUPINE 是一種實用、開源的方式，可將任何網路可存取的 GPU 轉換為 AI 訓練與推論的即插即用 CUDA 裝置，其 Docker 影像使部署變得簡單。