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）に対応した、即時実行可能なコンテナとして公開されています。
ホストされたデモ – Tesla T4を搭載した公開デモサーバーが利用可能。1つの 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のリモートGPUに対して実行し、損失が減少することを確認できます。これにより、ネットワーク越しに完全な学習ループが動作することを証明しています。

制限事項と注意点（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は、Dockerイメージを用いて展開が簡単な、実用的でオープンソースな方法で、ネットワークにアクセス可能な任意のGPUをAI学習や推論用の即時置き換えCUDAデバイスに変換します。