【NVIDIA Cosmos実践入門】第1回：環境構築編 — DGX SparkでのCosmosインストール完全ガイド（Cosmos 2.5 & Cosmos 3）

はじめに

こんにちは。SCSKの濱田です。
本連載では、私が社内で行ったNVIDIAのフィジカルAI向けモデル群「NVIDIA CosmosTM」の検証について、全4回（仮）にわたって紹介していきます。

NVIDIA Cosmosは、フィジカルAI向けの世界基盤モデル（World Foundation Model：WFM）として注目を集めています。しかし、実際にどのような環境で動かし、何ができるのかについては日本語の情報がまだ多くありません。
そこで本連載では、SCSKが実際にCosmosを導入・検証しながら、

  • Cosmos環境の構築方法
  • Predict / Transfer / Reasonの使い方
  • Cosmos 2.5とCosmos 3の違い
  • フィジカルAI開発における活用可能性

を実際の検証結果と共にご紹介します。

まずはNVIDIA Cosmosの概要を知りたい方へ
NVIDIA Cosmosの基本機能や世界基盤モデル（WFM）の仕組み、Predict・Transfer・Reasonの違いについては、NVIDIA Cosmos製品ページで詳しく解説しています。

ちなみに今回の検証では、NVIDIA DGX SparkTMを利用しました。DGX Sparkはデスクトップ型のコンパクトなAIサーバーで個人や少人数のチームでも利用しやすく、CosmosのようなGPUリソースが求められる検証にもぴったりです。

今回の環境では、CosmosをDGX SparkのホストOSへ直接インストールするのではなく、モデルごとにDockerイメージとDockerコンテナを分ける構成を採用しました。Transfer 2.5、Predict 2.5、Reason 2、Cosmos 3などをそれぞれ独立した環境として管理し、各コンテナの中でJupyterLabも起動します。

今回のゴール
DGX Spark上でDockerとNVIDIA Container Toolkitを確認し、Cosmosのリポジトリ取得、DGX Spark向けDockerfileの調整、Dockerイメージのビルド、JupyterLabを含むコンテナ起動までを行います。最終的には、社内LAN上のWindows PCからWebブラウザで各Cosmos環境へアクセスできる状態にします。

今回採用した環境構成

今回の検証では、DGX SparkをCosmosの共通実行基盤として使用します。ただし、Predict、Transfer、Reason、Cosmos 3を一つのPython環境へ詰め込むのではなく、モデルごとにDockerイメージを作成します。

Cosmosの環境構成

この構成にすると、あるモデルで依存パッケージを変更しても、別のモデルの環境へ影響しません。また、JupyterLabを各コンテナの内部で起動するため、Notebookが使用するPythonとCosmos本体が使用するPythonを同じ環境にそろえやすくなります。ちなみに、今回のDGX Spark単体ではあまり関係ありませんが、複数GPU環境ではアプリケーション側でGPUを選択する方法に加えてコンテナ単位で利用可能なGPUを分離できます。そのため、複数のモデルや利用環境を並行して管理する場合にも、コンテナ化は資源管理を分かりやすくする利点があります。

DockerとNVIDIA Container Toolkitを確認する

DGX SparkにはDockerとNVIDIA Container Toolkitが通常導入されています。最初に、両方のコマンドが利用できることを確認します。

docker --version
nvidia-ctk --version
dockerのバージョン

ここで両方のバージョン情報が表示されれば、以降のDockerベースの構築へ進めます。

社内ネットワーク環境で必要な設定をする

社内ネットワークからGitHub、Hugging Face、Docker Hubなどへアクセスする環境では、社内プロキシや証明書の設定が必要になる場合があります。セキュリティ上の観点から詳細は伏せますが、DGX Spark本体に加えてコンテナ内部でも通信が可能な様に設定が必要になります。

Git LFSを導入してCosmosリポジトリを取得する

CosmosのリポジトリではGit LFSを使用するため、最初にGit LFSを導入します。

sudo apt install git-lfs
git lfs install

続いて、利用するCosmosモデルのリポジトリを取得します。

git clone git@github.com:nvidia-cosmos/<repository_name>.git
cd <repository_name>
git lfs pull

<repository_name>には、Transfer 2.5、Predict 2.5、Reason 2、Cosmos 3（cosmos-framework）など、対象となるリポジトリ名を指定します。Cosmos 2.x系とCosmos 3では使用するリポジトリが異なるため、対象モデルの公式リポジトリを確認して取得します。

Cosmosリポジトリのgit cloneおよびgit lfs pull完了後のディレクトリ

Pythonバージョンを調整する

今回の検証では、依存ライブラリとの組み合わせを確認する過程でPythonバージョンを変更して試行しました。Cosmosは更新が速く、必要なPythonやライブラリのバージョンも変更されるため、構築時点の公式リポジトリの指定を確認することが重要です。

DockerfileをDGX Spark向けに変更する

次に、リポジトリ付属のDockerfileをDGX Spark向けに調整します。Transfer 2.5で実際に使用したDockerfileでは、主に次の変更を入れています。

変更項目今回の設定目的
ベースイメージnvidia/cuda:13.0.0-cudnn-devel-ubuntu24.04DGX Spark側のCUDA環境に合わせる
追加パッケージgit-lfs、libx11-devなどモデル実行と依存ライブラリへ対応する
CUDA用extraCUDA_NAME=cu130uvの依存解決をCUDA 13系へ合わせる
JupyterLabuv pip install jupyterlab同じコンテナからNotebookを利用する
公開ポートEXPOSE 8888JupyterLabの待受ポートを明示する

Transfer 2.5用Dockerfileの主要変更部分は、概念的には次のようになります。

ARG BASE_IMAGE=nvidia/cuda:13.0.0-cudnn-devel-ubuntu24.04
FROM ${BASE_IMAGE}

ARG CUDA_NAME=cu130
ENV CUDA_NAME=${CUDA_NAME}

# 依存関係をuvで構築
# uv sync --locked --no-install-project --extra=${CUDA_NAME}

# JupyterLabを同じ環境へ追加
RUN uv pip install jupyterlab
EXPOSE 8888

Dockerイメージをビルドする

Dockerfileの調整が終わったら、モデルごとにDockerイメージをビルドします。イメージ名は、後でdocker runに指定する名前と一致させます。

Transfer 2.5の例

sudo docker build -t cosmos-transfer2.5 \
  --build-arg STANDALONE=true \
  -f Dockerfile .

Predict 2.5の例

sudo docker build -t cosmos-predict2.5 \
  --build-arg STANDALONE=true \
  -f Dockerfile .

Reason 2の例

sudo docker build -t cosmos-reason2 -f Dockerfile .

ビルド後は、作成されたイメージを確認します。

sudo docker images
ビルド結果

JupyterLabを起動するCosmosコンテナを作る

今回の運用では、Cosmosをコマンドライン専用コンテナとして起動するのではなく、コンテナ起動と同時にJupyterLabを立ち上げます。Transfer 2.5では、次のような構成で起動しています。

docker run --gpus all -itd \
  --entrypoint python \
  --restart=unless-stopped \
  --ipc=host \
  -p 8802:8888 \
  --ulimit memlock=-1 \
  -e HF_TOKEN="<Hugging Faceトークン>" \
  -e NVIDIA_DRIVER_CAPABILITIES=all \
  --name cosmos-transfer-2.5 \
  cosmos-transfer2.5 \
  -m jupyter lab --ip=0.0.0.0 --port=8888 --no-browser --allow-root --NotebookApp.token=''

--entrypoint pythonを指定しているため、コンテナ起動時にはPythonから-m jupyter labを実行します。--restart=unless-stoppedも付けているため、DGX SparkやDockerデーモンの再起動後も、明示的に停止していなければコンテナが再起動する構成です。

複数モデルをポートで分けて公開する

JupyterLabはコンテナ内部ではいずれも8888番ポートで待ち受けます。DGX Sparkのホスト側では、モデルごとに異なるポートへ割り当てます。今回のCosmos 2.5系では、次のように分けています。

モデルホスト側ポートコンテナ側
Cosmos Transfer 2.588028888
Cosmos Predict 2.588038888
Cosmos Reason 288048888
Cosmos 3系88058888

Cosmos 3でも基本的な考え方は同じです。Dockerイメージを用意し、そのイメージの依存関係に合わせてDockerfileを調整し、JupyterLabを別のホスト側ポートへ割り当てます。

起動状態を確認する

docker ps
dockerの実行結果

たとえばTransfer 2.5であれば、社内LAN上のWindows PCから次のURL形式でアクセスできます。

http://<DGX SparkのIPアドレス>:8802
JupyterLabを認証なしで社内LANへ公開する構成について
今回の検証環境では、社内の利用者がブラウザから利用できるように--NotebookApp.token=''でJupyterLabのトークン認証を無効化しています。この設定では、ネットワーク的に到達できる利用者がNotebook上でコードを実行できます。そのため、インターネットへ公開する構成には使用せず、社内ネットワーク側の到達範囲、ファイアウォール、利用者範囲を明確にした検証環境として扱います。

環境構築時に注意したポイント

ホスト側とコンテナ側のネットワークは別に考える

ホストOSでGitHubやHugging Faceへ接続できても、Dockerビルド中やコンテナ内では同じプロキシ設定が自動的に使われるとは限りません。一般利用者はあまり意識することはありませんが、制限された環境だと思わぬ申請や確認が必要になることがあります。

DGX Sparkに合わせてCUDAは13系に統一する

Cosmosの各リポジトリでは、対象GPUや実行環境に応じて複数のCUDA構成が用意されています。特にDGX SparkではCUDA 13系を前提とする構成が指定されているため、使用するモデルの公式ドキュメントとDGX Spark側の環境を確認して構築しました。

別のマシンからイメージを持ってこない

今まで使っていたイメージやコンテナがある場合、それを持ってくることも考えられます。しかし、DGX SparkのCPUはArm系アーキテクチャを使用しているので、大体の場合は再ビルドが必要です。

おわりに

今回は、DGX Spark上でCosmosを実際に利用するために採用したDockerベースの環境構築を紹介しました。ポイントは、CosmosをホストOSへ直接入れるのではなく、モデルごとにコンテナ化し、JupyterLabまでそのコンテナに含めることです。

この構成にすると、Windows PC側にはCUDA、Python、Cosmosを導入する必要がありません。DGX Sparkへ計算環境を集約し、社内LANからWebブラウザでアクセスすることで、複数の利用者が同じ検証基盤を使用できます。

参考情報

  1. NVIDIA DGX Spark Documentation
    https://docs.nvidia.com/dgx/dgx-spark/
  2. NVIDIA Cosmos Documentation
    https://docs.nvidia.com/cosmos/
  3. NVIDIA Cosmos GitHub Organization
    https://github.com/nvidia-cosmos

著者プロフィール

著者プロフィール画像

濱田　悠（はまだ　ゆう）
SCSK株式会社　アプリケーションエンジニア
NVIDIA GPU、Omniverse / Isaac Sim、Physical AI、生成AI基盤などの技術検証・提案に従事。

お問い合わせ・資料DL

NVIDIAソリューションに関するご相談や、各種資料ダウンロードはこちらから