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 镜像使部署变得简单。