lupine

环境要求

• GPU 机器：已安装 NVIDIA 驱动，并支持 docker run --gpus all（需 nvidia-container-toolkit）
• CPU-only 客户端机器：只需安装 Docker，无需本地 GPU
• 服务端与客户端镜像标签需保持一致，格式为 cuda-<cuda-version>-ubuntu<ubuntu-version>，示例固定为 cuda-13.3.
• 两条机器之间网络可达，且服务端 14833 端口可被客户端访问
• 如需在客户端跑 PyTorch，还需准备 Dockerfile.pytorch-lupine 并从源码构建镜像

安装与启动步骤

1. 1GPU 机器启动服务端

   在带 GPU 的机器上运行服务端镜像，--gpus all 暴露全部 GPU，并把容器 14833 端口映射到宿主机。

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

   复制

2. 2客户端连接验证

   在仅 CPU 的机器上运行客户端镜像，用 -e LUPINE_SERVER 指向服务端地址，执行 nvidia-smi 查看远程 GPU。

   docker run --rm -it \
     -e LUPINE_SERVER=192.168.1.10:14833 \
     ghcr.io/lupinemachines/lupine-client:cuda-13.3.1-ubuntu24.04 \
     nvidia-smi

   复制

3. 3构建 PyTorch 镜像

   用仓库自带的 Dockerfile.pytorch-lupine 在客户端镜像基础上装 python3、pip 和 CUDA 13.2 版 torch。

   docker build -f Dockerfile.pytorch-lupine -t lupine-pytorch:cuda-13.3 .

   复制

4. 4运行 PyTorch 测试

   在 CPU-only 机器上运行刚构建的镜像，脚本会执行 microgpt_train，成功时打印 PASS。

   docker run --rm \
     -e LUPINE_SERVER=192.168.1.10:14833 \
     lupine-pytorch:cuda-13.3

   复制

5. 5运行代码生成

   源码构建前先执行 codegen 脚本，确认输出中没有任何报错。

   ./codegen/run.sh

   复制

6. 6CMake 编译源码

   编译出 libcuda.so.1、libcudart、libnvidia-ml.so.1、libamdhip64.so.1 等 shim 以及服务端可执行文件。

   cmake -S . -B build
   cmake --build build

   复制

7. 7本地启动服务端

   本地开发时先启动自编译的服务端，成功后会打印监听 14833 端口，再发起客户端命令。

   ./local.sh server

   复制

8. 8本地预加载运行客户端

   本地开发不走镜像时，需要在执行 CUDA 命令前预加载编译出的 libcuda.so.1 作为 shim。

关键配置

如何确认成功

服务端成功时会打印 Server listening on port 14833...；客户端执行 nvidia-smi 能看到远程 GPU 型号；PyTorch 测试输出 microgpt_train: PASS。

常见问题

注意事项

• 服务端镜像必须用 --gpus all 启动，普通容器无法访问 GPU。
• CUDA 运行时 shim 会把 cuda* 调用转发到驱动 shim 的连接上，因此两者必须来自同一次构建。
• Docker 的 server 目标依赖生成的平台路由注册表，缺少客户端产物时无法构建服务端镜像。
• 构建可再分发服务端时需通过 LUPINE_CLIENT_BUNDLE_INPUT 传入暂存的原生客户端目录。