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。
• 在重装系统或更新基础镜像后恢复可用环境，需要从头重新验证。

上述每种情况都接受同一个通用解决方案：让容器/wheel 组合匹配 CUDA 13 和 SM121， 不要与 ABI 对抗。

容器优先原则

在下方细节之前，先做一个快速判断：

• 标准训练/推理工作 → NGC PyTorch 容器。
• 以 Unsloth 为中心的微调 → Unsloth 容器（它已内置为该路径验证过的 固定 Triton/xformers/transformers 组合）。
• 两者都不适用（自定义系统包、本地 IDE 解释器） → 裸 pip，严格按后面的确切顺序执行。

默认使用容器。以 nvcr.io/nvidia/pytorch:25.09-py3 作为通用工作的基础 —— 这是在此硬件上确认可用的最新 tag；如果本地已有更新的受支持 tag 就拉取它， 而不是死守 25.11-py3。NGC 的 tag 带日期，因此直接运行即可：

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

相比之下，unsloth/unsloth:dgxspark-latest 是一个移动 tag —— 在用于任何可复现的工作之前，先解析并固定其 digest；裸 tag 只是探索步骤， 不是默认调用方式。完整的拉取-检查-固定流程，以及 finetuning/ 运行目录的 flag 理由/卷挂载：references/container-workflow.md。把裸 pip 视为例外。

容器优先的立场出于固定版本，而非便利性。Triton、xformers 和 transformers 版本 与 GB10 的 SM121 目标和 CUDA 13 的交互非常紧密；容器将它们全部锁定在一个 已在此硬件上验证过的组合中。裸 pip 则把这种解析留给你，一次一个导入错误。

当裸 pip 确有必要时，严格按顺序照搬 NVIDIA playbook 的安装序列：

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"

第二条命令的 --no-deps flag 不是可选项 —— 让 pip 在 aarch64 上重新解析 Unsloth 的依赖树，是引入不兼容 torch 或 triton 构建的常见方式。 第三行也不是可选项：NGC 基础镜像自带的 torchao 对当前 peft 的 LoRA-attach 路径来说太旧（ImportError: ... torchao ... only versions above 0.16.0 are supported）—— 这是硬性阻断，不是警告。上面每个 == 固定版本都是关键， 取自 references/stack-matrix.md 中带日期的已知良好版本矩阵（其 Last verified 日期 决定是否过时）—— 未固定版本的安装会解析出当前 PyPI 版本，远超此 Unsloth 版本所支持的范围。

当新的受支持版本发布时，拉取新的 tag。 仅当项目需要额外叠加系统包时，才从两个基础镜像之一在本地重建 —— 不要为了“升级”镜像已固定的组件而重建。两条路径的详情： references/container-workflow.md。

还有一项预检：官方 DGX Spark playbook 曾经发布过有问题的版本。在长期运行前， 先查看 github.com/NVIDIA/dgx-spark-playbooks（以及 references/stack-matrix.md 中的其他资源）上的近期 issue，再逐字信任某个配方。

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，仅这一点并不构成故障。

典型症状：

• ImportError: undefined symbol，引用了某个 CUDA 运行时函数。
• 第一次调用 .cuda() 时发生段错误，没有有用的回溯信息。
• 一个 wheel 能干净地安装，然后在导入时报错——pip 的解析器不检查 CUDA ABI，只检查版本约束。
• 两个“完全相同”的环境表现不同——通常一个装有 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)

此调用返回两个值；确切的输出格式为一行，<bool> <cuda-version>：

True 13.0

如果它打印 False，不要直接跳到重装 wheel——ABI 不匹配只是若干原因之一：

假设	快速检查
运行时/标志	nvidia-smi 在容器内也失败
设备可见性	echo $CUDA_VISIBLE_DEVICES
权限	ls -l /dev/nvidia*
CUDA 初始化状态	进程卡死；重试新的 shell/容器
ABI 不匹配（常见元凶）	torch.version.cuda 不是 13.x

先检查 nvidia-smi——如果它不显示 GPU，那就是前三种情况之一，而不是 ABI。只有在确认 ABI 后才重装 wheel。每种假设的详情：references/stack-matrix.md。在容器启动后立即运行，在安装项目特定包之前。

再检查一项：如果训练开始后 Triton 内核编译失败，设置 TRITON_PTXAS_PATH=/usr/local/cuda/bin/ptxas 并重试——完整变通方法列表见 references/stack-matrix.md。

下一步

经过验证的环境只是起点。另见：spark-training-gotchas，用于训练运行前的故障预检；以及 spark-memory-thermal-ops，用于长时间训练期间的统一内存 OOM 和热节流。