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를 사용할 수 있게 해주는 도구입니다. 이는 지속적인 TCP 연결을 통해 원격 서버 프로세스로 모든 CUDA API 호출을 전달하는 가벼운 CUDA 드라이버 쉴(libcuda.so.1 및 libnvidia-ml.so.1)을 제공함으로써 작동합니다.

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)에 대해 즉시 실행 가능한 컨테이너로 배포됩니다.
호스팅된 데모 – 공개 데모 서버(테슬라 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 학습

리포지토리는 PyTorch 지원 클라이언트 이미지를 빌드하는 작은 Dockerfile을 제공합니다. 빌드 후, microgpt_train 스크립트를 원격 RTX 4090에 대해 실행하면 손실이 감소하는 것을 확인할 수 있으며, 이는 네트워크를 통해 전체 학습 루프가 작동함을 입증합니다.

제한 사항 및 주의사항 (README에서)

지연 시간 – 네트워크가 PCIe 링크를 대체하므로, 대규모 데이터 전송(예: 동영상 인코딩, 거대한 호스트-디바이스 복사)은 버퍼링이 될 수 있습니다. 모델 학습은 모델을 한 번만 이동하고 대부분의 작업을 디바이스 측에서 수행하므로 영향은 제한적입니다.
서버 간 직접 피어 액세스 없음 – 호스트 간 cuMemcpyPeer는 클라이언트를 통해 스테이징 처리됩니다. 진정한 제로-코피 피어 액세스는 아직 지원되지 않습니다.
인증/TLS – LUPINE 자체는 인증을 구현하지 않습니다. 암호화나 자격 증명 검사가 필요하면 프록시 뒤에 배치하거나 자체 프론트엔드를 추가해야 합니다.
일치하는 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 리포지토리의 이슈와 풀 리퀘스트는 TLS 프론트엔드 추가, 멀티호스트 피어 액세스, 기타 개선 사항에 대해 논의하고 있습니다.

결론 – LUPINE은 Docker 이미지를 통해 배포가 간편한 실용적이고 오픈소스적인 방법으로, 네트워크로 접근 가능한 모든 GPU를 AI 학습 및 추론용 즉시 대체 CUDA 장치로 변환합니다.