メインコンテンツまでスキップ

Docker バックエンド

このガイドでは、NVIDIA GPU 付きの Linux ホストで splat-transform をコンテナ化されたバックエンドサービスとして実行する方法を説明します。

このガイドが必要な場合​

splat-transform は Node.js CLI で、公開された npm パッケージは Node 22+ が動作するところであればどこでも動作します — Docker は厳密には必要ありません。

いくつかの機能は GPU 専用で、WebGPU なしでは動作しません：--filter-cluster、--filter-floaters、.voxel.json 出力と --collision-mesh（コリジョンメッシュガイドを参照）、そして .webp 画像出力（画像のレンダリングを参照）です。デシメーションと SOG 出力はデフォルトで GPU を使用しますが、CPU でも動作します。ただし球面調和を含む SOG 出力は、CPU ではおおよそ 5-10 倍遅くなります。詳しい内訳は GPU が必要な機能を参照してください。

すべての GPU パスは WebGPU を経由し、Linux 上では Vulkan で実装されています。これが下記のホストおよびコンテナの要件を定めています。

GPU 専用機能を必要とせず、SH 圧縮の CPU コストを許容できる（または入力に SH がない）場合は、CPU 専用バリアント にスキップしてください。

ホストの前提条件（Docker の外側）​

これらはホストマシン上で構成する必要があります — コンテナ内からはインストールできません。コンテナはホストの NVIDIA ドライバと Vulkan ICD を再利用するためです。

  1. Vulkan ICD を公開するドライバを持つ NVIDIA GPU（ほとんどのコンシューマドライバは公開していますが、一部のヘッドレスクラウドドライバはデフォルトで公開していません）。
  2. NVIDIA Container Toolkit がインストールおよび構成された Docker Engine。これが --gpus all を機能させ、ランタイムにホストの NVIDIA ドライバライブラリ（Vulkan ICD JSON を含む）をコンテナに投影します。
  3. （オプション）ホスト上の vulkan-tools — Docker の外側からドライバをサニティチェックするのに便利です（例：コンテナを起動する前にホストで vulkaninfo --summary）。コンテナは下記の Dockerfile でインストールされる vulkan-tools apt パッケージを介して独自の Vulkan ローダーを持ってきます。

AWS GPU インスタンス​

g4dn、g5、g6 などの AWS GPU インスタンスでは、互換性のある NVIDIA ドライバで Vulkan バックエンドを実行できます。Vulkan を使用するためだけに GRID ドライバを導入する必要はありません。AWS は Tesla、GRID、ゲーミングドライバがサポートする API に Vulkan を挙げています。インストール手順は使用する AMI によって異なります。

EKS 向けの Amazon Linux 2023 NVIDIA 高速化 AMI（AL2023_x86_64_NVIDIA）には、NVIDIA ドライバと NVIDIA Container Toolkit が含まれています。PlayCanvas では、NVIDIA A10G GPU を搭載した g5.4xlarge および g5.8xlarge インスタンスでこの AMI を使用しており、GRID ドライバを別途インストールしていません。NVIDIA Kubernetes デバイスプラグインをインストールし、各 GPU ワーカー Pod に nvidia.com/gpu: 1 を要求してください。

スタンドアロンの Docker やその他の AMI では、上記のホストの前提条件と、インスタンスおよび OS に対応する AWS のドライバインストール方法に従ってください。EKS は必須ではありません。ドライバを置き換える前に、既存のドライバと Vulkan の動作を確認してください。以下の診断コマンドが利用できない場合は、vulkan-tools をインストールしてください。

ホストからドライバと Vulkan ICD を検証：

nvidia-smi             # ドライババージョン、GPU モデル
vulkaninfo --summary   # 物理デバイスを持つ NVIDIA Vulkan ICD

NVIDIA ドライバとコンテナランタイムの連携はホスト上で設定する必要があります。以下の Dockerfile はコンテナ側の Vulkan ローダーとライブラリをインストールします。コンテナ内でも GPU アクセスを確認してください。

最小限の Dockerfile​

Ubuntu 22.04 に公開された CLI と Vulkan の依存パッケージをインストールする、最小限のマルチステージ Dockerfile です。splat-transform は CUDA ツールキットを使用しないため、CUDA ベースイメージは不要です：

# syntax=docker/dockerfile:1.4

# リモートインストールスクリプトを bash にパイプするのではなく
# 公式イメージから Node.js を取得します。
FROM node:22-slim AS node

FROM ubuntu:22.04

# NVIDIA Container Toolkit がランタイムにホストの NVIDIA ドライバ
# ライブラリと Vulkan ICD をコンテナに投影できるように、
# compute + graphics + utility capabilities を公開します。
ENV NVIDIA_VISIBLE_DEVICES=all
ENV NVIDIA_DRIVER_CAPABILITIES=compute,graphics,utility

RUN apt-get update \
    && apt-get install -y --no-install-recommends \
        ca-certificates \
        vulkan-tools \
        libgl1 libglvnd0 libglx0 libegl1 libxext6 \
    && rm -rf /var/lib/apt/lists/*

# 公式イメージから Node.js と npm を持ってきます。
COPY --from=node /usr/local/bin/ /usr/local/bin/
COPY --from=node /usr/local/lib/node_modules/ /usr/local/lib/node_modules/

RUN npm install -g @playcanvas/splat-transform

RUN useradd --create-home --uid 2000 splat
USER splat
WORKDIR /work

ENTRYPOINT ["splat-transform"]

各部分が何をしているかについてのいくつかのメモ：

  • ubuntu:22.04 — ベースとなる OS を提供します。NVIDIA Container Toolkit が実行時にホストのドライバライブラリを提供します。
  • NVIDIA_VISIBLE_DEVICES=all — Docker または Kubernetes がコンテナに割り当てた GPU を公開します。
  • NVIDIA_DRIVER_CAPABILITIES=compute,graphics,utility — graphics が重要です；これなしではツールキットは Vulkan ICD をマウントしません。
  • vulkan-tools — vulkaninfo（デバッグに役立つ）を提供し、コンテナが必要とする Vulkan ローダーをプルインします。
  • libgl1、libglvnd0、libglx0、libegl1、libxext6 — Vulkan/EGL ドライバが依存するランタイムライブラリ。
  • node:22-slim ステージ + COPY --from=node — サードパーティのインストールスクリプトを bash にパイプすることなく Node.js と npm を提供します。
  • npm install -g @playcanvas/splat-transform — 公開された CLI を PATH にインストールします。
  • 非 root の splat ユーザーはバッチワーカーには良いデフォルトで、ホストにマウントされたディレクトリに書き込まれるファイルが root に所有されないようにします。

ビルドと実行​

イメージをビルド：

docker build -t splat-transform .

現在のディレクトリを /work としてマウントして変換を実行：

docker run --rm --gpus all -v "$PWD":/work splat-transform \
    input.ply output.sog

イメージは非 root ユーザー（UID 2000）として実行されるため、ホストにマウントされたディレクトリに書き込まれるファイルはホストユーザーではなく UID 2000 に所有され、ホストディレクトリが UID 2000 によって書き込み可能でない場合、コンテナはまったく書き込みに失敗します。ポータブルな修正は --user "$(id -u):$(id -g)" を渡すことです：

docker run --rm --gpus all --user "$(id -u):$(id -g)" \
    -v "$PWD":/work splat-transform input.ply output.sog

残りの例は簡潔さのために --user を省略しています — ホストディレクトリをマウントする呼び出しには追加してください。

通常の splat-transform 呼び出しはすべて機能します — 完全な CLI サーフェスについては CLIリファレンス を参照してください。例えば：

# GPU SOG 圧縮
docker run --rm --gpus all -v "$PWD":/work splat-transform \
    -i 20 input.ply output.sog

# ボクセル + コリジョンメッシュ
docker run --rm --gpus all -v "$PWD":/work splat-transform \
    room.ply --filter-cluster --seed-pos 0,1,0 \
    --voxel-external-fill --voxel-carve \
    --collision-mesh room.voxel.json

GPU アクセスの検証​

2つの簡単なチェックで GPU が見えていることを確認できます。

CLI 経由で GPU アダプタを一覧表示：

docker run --rm --gpus all splat-transform --list-gpus

GPU の名前を持つ少なくとも1つの Vulkan アダプタが表示されるはずです（例：NVIDIA L4、Tesla T4）。

Vulkan を直接サニティチェック：

docker run --rm --gpus all --entrypoint vulkaninfo splat-transform --summary

vulkaninfo は NVIDIA の driverID を持つ GPU0 セクションを出力するはずです。失敗した場合は、まずホスト上の Vulkan を確認し、次に NVIDIA Container Toolkit の設定、GPU の割り当て、コンテナのライブラリを確認してください。

CPU 専用バリアント​

GPU 専用機能（--filter-cluster、--filter-floaters、.voxel.json、--collision-mesh、.webp）が必要なければ、GPU のセットアップを完全にスキップして、はるかに小さいベースイメージを使用できます。SOG / meta.json / lod-meta.json / .html 出力もこのイメージで動作します — SH 圧縮ステップは CPU にフォールバックします：

FROM node:22-slim
RUN npm install -g @playcanvas/splat-transform
WORKDIR /work
ENTRYPOINT ["splat-transform"]

--gpus なしで実行：

docker run --rm -v "$PWD":/work splat-transform input.ply output.ply

GPU イメージとは異なり、node:22-slim はデフォルトで root として実行されるため、--user なしではバインドマウントされたホストディレクトリに書き込まれるファイルはホストで root に所有されます。--user "$(id -u):$(id -g)" を渡す（ビルドと実行 で説明されているとおり）か、このイメージが共有用途であれば Dockerfile に非 root の USER 行を追加してください。

GPU イメージを維持しつつ、単一の実行で CPU モードを強制したい場合は、-g cpu を渡します：

docker run --rm -v "$PWD":/work splat-transform -g cpu input.ply output.sog

-g cpu は GPU 専用機能（--filter-cluster、--filter-floaters、.voxel.json、--collision-mesh、.webp）と互換性がないことに注意してください。CPU 側の SH 圧縮も GPU よりおおよそ 5-10 倍遅くなります。

トラブルシューティング​

  • --list-gpus がアダプタを報告しない。 Vulkan ICD がコンテナに届いていません。--gpus all で実行したこと、NVIDIA_DRIVER_CAPABILITIES に graphics が含まれていること、NVIDIA Container Toolkit がホストにインストールおよび構成されていることを確認してください。
  • vulkaninfo が Could not find a Vulkan ICD を報告する。 ホスト上で NVIDIA の Vulkan ドライバが動作することを確認してください。ホスト上で Vulkan が動作する場合は、コンテナが GPU にアクセスできることと、NVIDIA_DRIVER_CAPABILITIES に graphics が含まれていることを確認してください。AWS では上記のとおり適切なドライバまたは高速化 AMI を使用してください。GRID ドライバが必須とは限りません。
  • vulkaninfo がセグフォルトするか libXext.so.6 のロードに失敗する。 libxext6 がイメージから欠落しています — Dockerfile の apt-get install 行に含まれていること（および AWS では libXext がホストにもインストールされていること）を確認してください。
  • docker: Error response from daemon: could not select device driver "" with capabilities: [[gpu]]。 NVIDIA Container Toolkit がインストールされていないか、Docker デーモンが構成を取得していません。ツールキットを再インストールし、Docker を再起動してください。
  • バインドマウントされたディレクトリ内の出力がホストユーザーに所有されていない。 コンテナのデフォルトユーザー（GPU イメージでは UID 2000、slim イメージでは root）がホストの UID と一致しません。--user "$(id -u):$(id -g)" を docker run に渡してそれらを揃えるか、マウントする前にコンテナの UID に出力ディレクトリを chown してください。
  • バインドマウントされたディレクトリへの書き込みで Permission denied。 コンテナのデフォルトユーザーがホストディレクトリへの書き込みアクセス権を持ちません。--user "$(id -u):$(id -g)" を使用するか、コンテナユーザーが書き込めるようにホストディレクトリを chown してください。
  • コンテナ内で splat-transform: command not found。 ビルド中に npm install -g @playcanvas/splat-transform が正常に実行されたことを確認してください。デフォルトのエントリポイントはすでにバイナリを呼び出しているため、splat-transform を指定しなくても docker run <image> --help が動作するはずです。