spark-environment-setup

Spark 環境のセットアップ

DGX Spark には GB10 Grace Blackwell チップが搭載されています。aarch64 CPU、SM121 GPU、128GB 統合メモリ、CUDA 13 です。これは標準的な x86 CUDA 12 マシンよりも狭く若いプラットフォームであるため、パッケージの選択と ABI の整合が通常以上に重要になります。aarch64 + CUDA 13 向けの wheel エコシステムはまだ整備途上です。

このスキルを使う場面

• 新品の Spark マシンをトレーニングまたは推論用にセットアップするとき。
• libcudart に言及するインポートエラー、シンボルが見つからないエラー、または「インストールは成功したが読み込めない」wheel に遭遇したとき。
• フレームワークのインストール (PyTorch、Unsloth、TRL、vLLM、xformers) が失敗する、ハングする、または黙って CPU にフォールバックするとき。
• NGC コンテナを使うか、素の pip を使うかを判断するとき。
• OS の再インストールやベースイメージの更新後に、動作するセットアップを復元し、ゼロから再検証する必要があるとき。

これらはいずれも同じ一般的な対処法を受け入れます。コンテナ/wheel の組み合わせを CUDA 13 と SM121 に合わせ、ABI と戦わないことです。

コンテナファーストのルール

以下の詳細の前に、簡単な判断です。

• 標準的なトレーニング/推論作業 → NGC PyTorch コンテナ。
• Unsloth 中心のファインチューニング → Unsloth コンテナ (そのパス向けにすでに検証済みの、固定された Triton/xformers/transformers の組み合わせが同梱されています)。
• どちらも合わない (カスタムのシステムパッケージ、ローカル IDE のインタープリタ) → 後述の正確な手順に従って素の pip。

デフォルトはコンテナです。一般的な作業のベースには nvcr.io/nvidia/pytorch:25.09-py3 を使用してください。このハードウェアで動作確認済みの最新タグです。25.11-py3 に固執してブロックするのではなく、ローカルで利用可能であれば、より新しい認定タグを pull してください。NGC のタグは日付入りなので、そのまま実行しても問題ありません。

docker run --runtime=nvidia --gpus all -it --rm \
  nvcr.io/nvidia/pytorch:25.09-py3

対照的に unsloth/unsloth:dgxspark-latest は動くタグです。再現性が必要な用途で実行する前に、そのダイジェストを解決して固定してください。素のタグはあくまで発見のための手順であり、デフォルトの起動方法ではありません。完全な pull-inspect-pin の手順と、finetuning/ の run ディレクトリ向けのフラグの根拠/ボリュームマウントについては、references/container-workflow.md を参照してください。素の pip は例外として扱ってください。

コンテナファーストの姿勢の理由は、利便性ではなく固定 (ピン留め) です。Triton、xformers、transformers のバージョンは、GB10 の SM121 ターゲットと CUDA 13 に対して狭く相互作用します。コンテナはそれらすべてを、このハードウェアですでに検証済みの組み合わせに対してまとめて固定します。素の pip は、その解決をあなたに委ね、壊れたインポートを1つずつ経験させることになります。

素の pip が正当化される場合は、NVIDIA プレイブックのインストール手順にそのまま、順番どおりに従ってください。

pip install "transformers==5.13.1" "peft==0.19.1" "hf_transfer==0.1.9" "datasets==4.3.0" "trl==1.8.0"
pip install --no-deps "unsloth==2026.7.2" "unsloth_zoo==2026.7.2" "bitsandbytes==0.49.2"
pip install -U "torchao==0.17.0"

2番目のコマンドの --no-deps フラグは任意ではありません。aarch64 で pip に Unsloth の依存ツリーを再解決させるのは、互換性のない torch や triton ビルドを引き込む一般的な原因です。3行目も任意ではありません。NGC ベースイメージに同梱の torchao は、現在の peft の LoRA アタッチ経路には古すぎます (ImportError: ... torchao ... only versions above 0.16.0 are supported)。これは警告ではなく、ハードなブロッカーです。上記のすべての == による固定は重要です。references/stack-matrix.md にある日付入りの検証済みバージョンマトリクスから取得したものです (その Last verified の日付が古さを左右します)。固定しないインストールは、この Unsloth リリースがサポートする範囲を大きく超える現在の PyPI バージョンを解決してしまいます。

新しい認定リリースがアナウンスされたら、新しいタグを pull してください。プロジェクトが追加のシステムパッケージを重ねる必要がある場合にのみ、2つのベースのいずれかからローカルでリビルドしてください。イメージがすでに固定しているコンポーネントを「アップグレード」するためではありません。両方のパスの詳細は references/container-workflow.md を参照してください。

もう1つの事前確認: 公式の DGX Spark プレイブックは以前、壊れた状態で出荷されたことがあります。長時間の実行でレシピをそのまま信用する前に、github.com/NVIDIA/dgx-spark-playbooks の最近の issue (および references/stack-matrix.md にある他のリソース) を確認してください。

ABI ルール

Spark で最もよくある失敗は、CUDA 12/13 の ABI ミスマッチです。libcudart.so.12 に対してビルドされた wheel を、libcudart.so.13 しか存在しないシステムで 読み込んだ場合に発生します。インストール自体は通常 成功し、失敗は後になってシンボル未定義エラーや、 明らかに CUDA を指しているわけではないセグメンテーション フォルトとして表面化します。

修正方法: download.pytorch.org/whl/cu130 から wheel を 取得する（cu130 タグ付きの aarch64 ビルド）、または 上記のコンテナのいずれかを使用します。これらの コンテナには、すでに一致したビルドが含まれています。 CUDA シンボルに言及したスタックトレースを追う前に、 インストールされた wheel がどの CUDA タグに対して ビルドされたかを確認してください:

python3 -c "import torch; print(torch.version.cuda)"

この出力が 13 で始まらない場合、ABI ミスマッチが 最初に修正すべき問題です。NGC コンテナビルド（例: nvcr.io/nvidia/pytorch:25.09-py3）は、内部的に CUDA 13 に対して torch をビルドしており、+cu130 wheel タグは付きません — そこでは pip show torch は cu130 と表示されず、その不在自体は失敗では ありません。

典型的な症状:

• CUDA ランタイム関数を参照する ImportError: undefined symbol。
• 最初の .cuda() 呼び出しでのセグメンテーションフォルト、 有用なトレースバックなし。
• クリーンにインストールされた後にインポート時に失敗する wheel — pip のリゾルバは CUDA ABI をチェックせず、 バージョン制約のみをチェックします。
• 「同一」の 2 つの環境が異なる挙動を示す — 通常、 一方には cu130 wheel があり、もう一方には cu121/cu124 の残骸があります。

修正方法は症状にかかわらず同じです: wheel の CUDA タグを システムに一致させるか、すでに一致しているコンテナを 使用してください。

コンポーネント早見表

登場する可能性が高いコンポーネントの簡易ステータスです。 wheel の URL、ビルドフラグ、sm_121 と sm_121a の 区別、日付付きの動作確認済みバージョンマトリックスを 含む完全な表: references/stack-matrix.md。

コンポーネント	ステータス
PyTorch	✅ 公式 cu130 aarch64 wheel
bitsandbytes	✅ すぐに動作します
Triton	✅ TRITON_PTXAS_PATH パラメータの設定が必要です
flash-attn	❌ pip ビルドはスキップしてください。NGC に動作するものが同梱されています — spark-training-gotchas G2 を参照
xformers	ソースビルドのみ（TORCH_CUDA_ARCH_LIST=12.1）
vLLM	nightly wheel のみ
TransformerEngine / NVFP4 train	コンテナ専用

その他すべて — Unsloth、Axolotl、TRL、PEFT — は、 上記のコンテナファーストの手順でクリーンに インストールできます。LLaMA-Factory と NeMo は Spark では不安定です。まず上流の issue を 確認してください。

検証コマンド

高コストな処理を実行する前に、環境が実際に GPU を 認識できることを確認してください:

import torch
print(torch.cuda.is_available(), torch.version.cuda)

この呼び出しは 2 つの値を返します。正確な出力形式は 1 行で、<bool> <cuda-version> です:

True 13.0

代わりに False と表示される場合、すぐに wheel の 再インストールに飛びつかないでください — ABI ミスマッチは 複数ある原因の 1 つです:

仮説	簡単な確認
ランタイム/フラグ	nvidia-smi がコンテナ内でも失敗する
デバイスの可視性	echo $CUDA_VISIBLE_DEVICES
権限	ls -l /dev/nvidia*
CUDA 初期化状態	プロセスがスタックしている。新しいシェル/コンテナで再試行
ABI ミスマッチ（通常の原因）	torch.version.cuda が 13.x でない

まず nvidia-smi を確認してください — GPU が表示されない 場合、最初の 3 つのいずれかであり、ABI ではありません。 wheel の再インストールは ABI が確認されてからに してください。仮説ごとの詳細: references/stack-matrix.md。 コンテナ起動直後、プロジェクト固有のパッケージを インストールする前に実行してください。

もう 1 つの確認: トレーニング開始後に Triton カーネルの コンパイルが失敗する場合、 TRITON_PTXAS_PATH=/usr/local/cuda/bin/ptxas を設定して 再試行してください — 完全なワークアラウンド一覧は references/stack-matrix.md を参照してください。

次のステップ

検証済みの環境は、あくまで出発点にすぎません。あわせて 参照してください: トレーニング実行前の障害プリフライトに ついては spark-training-gotchas、長時間実行中の ユニファイドメモリ OOM とサーマルスロットリングに ついては spark-memory-thermal-ops を参照してください。