在 NVIDIA DGX…

当在 DGX Spark 上安装 ML 框架遇到 libcudart 缺失符号、wheel ABI 不匹配或想决定用 NGC 容器还是裸 pip 时，按此流程搭建并验证环境。

适用场景

解决思路

1. 优先使用容器而非裸 pip：通用训练/推理用 NGC PyTorch 容器，Unsloth 微调用 Unsloth 容器，两者都不适用（需要自定义系统包或本地 IDE 解释器）才走裸 pip。
2. 通用工作以 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。
3. unsloth/unsloth:dgxspark-latest 是移动 tag，用于可复现任务前必须先解析并固定其 digest；裸 tag 只用于探索，不能作为默认调用方式。
4. 裸 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"。
5. 第二条命令的 --no-deps 不可省略：让 pip 在 aarch64 上重新解析 Unsloth 依赖树，常会拉入不兼容的 torch 或 triton 构建。
6. 第三条 torchao 升级也不可省略：NGC 基镜像自带的 torchao 对当前 peft 的 LoRA-attach 路径太旧，会报 ImportError: ... torchao ... only versions above 0.16.0 are supported，这是硬阻塞而非警告。
7. 所有 == 版本钉死都不可省略，它们来自 references/stack-matrix.md 中带日期的已知可用版本矩阵（以其中的 Last verified 日期判断是否过时）；不钉版本会解析到当前 PyPI 上远超该 Unsloth 版本支持范围的版本。
8. 只有项目需要额外系统包时才从两个基镜像之一本地重建，不要为了“升级”镜像已钉死的组件而重建。
9. 长时间运行前先检查 github.com/NVIDIA/dgx-spark-playbooks 的近期 issue（以及 references/stack-matrix.md 中的其他资源），因为官方 playbook 曾发布过有问题的版本。
10. 遇到 CUDA 12/13 ABI 不匹配（wheel 针对 libcudart.so.12 构建却加载在只有 libcudart.so.13 的系统上）时，从 download.pytorch.org/whl/cu130 拉取 cu130 标签的 aarch64 wheel，或改用已带匹配构建的容器。
11. 追查涉及 CUDA 符号的堆栈前，先用 python3 -c "import torch; print(torch.version.cuda)" 检查已安装 wheel 是针对哪个 CUDA tag 构建的；若输出不以 13 开头，先修 ABI 不匹配。
12. 注意 NGC 容器内 torch 是针对 CUDA 13 内部构建的，没有 +cu130 wheel tag，pip show torch 不会显示 cu130，这种缺失本身不算失败。
13. 识别 ABI 不匹配的典型症状：ImportError: undefined symbol 指向 CUDA runtime 函数；首次 .cuda() 调用段错误且无有用 traceback；wheel 安装干净但 import 时失败（pip 解析器只查版本约束不查 CUDA ABI）；两个“相同”环境行为不同（通常一个用 cu130 wheel，另一个残留 cu121/cu124）。
14. 组件状态速查：PyTorch 用官方 cu130 aarch64 wheel；bitsandbytes 开箱即用；Triton 需设置 TRITON_PTXAS_PATH 参数；flash-attn 跳过 pip 构建，NGC 已捆绑可用版本；xformers 只能源码构建（TORCH_CUDA_ARCH_LIST=12.1）；vLLM 仅 nightly wheel；TransformerEngine/NVFP4 训练仅限容器。
15. Unsloth、Axolotl、TRL、PEFT 走上述容器优先路径可干净安装；LLaMA-Factory 和 NeMo 在 Spark 上很脆弱，先查上游 issue。
16. 跑昂贵任务前先验证环境能看到 GPU：import torch; print(torch.cuda.is_available(), torch.version.cuda)，输出应为一行 <bool> <cuda-version>，例如 True 13.0。
17. 若输出 False，不要直接重装 wheel，按假设逐一排查：nvidia-smi 在容器内也失败→运行时/参数问题；echo $CUDA_VISIBLE_DEVICES→设备可见性；ls -l /dev/nvidia*→权限；进程卡死→重开 shell/容器；torch.version.cuda 不是 13.x→ABI 不匹配（最常见）。先查 nvidia-smi，若它看不到 GPU 就是前三类问题而非 ABI，确认 ABI 后才重装 wheel。
18. 在容器启动后、安装项目特定包之前立即运行上述验证。
19. 若训练开始后 Triton kernel 编译失败，设置 TRITON_PTXAS_PATH=/usr/local/cuda/bin/ptxas 后重试。
20. 环境验证通过只是起点：训练前查 spark-training-gotchas 做失败预检，长时间训练的统一内存 OOM 和热降频查 spark-memory-thermal-ops。

适用边界 · 注意事项

• 不是 DGX Spark（GB10/aarch64/CUDA 13）平台时，本经验的容器 tag、wheel 源和版本矩阵不适用。
• 需要自定义系统包或使用本地 IDE 解释器时，容器优先路径不适用，应走裸 pip 流程。
• 项目需要额外系统包时不要为“升级”镜像已钉死的组件而重建镜像，只在确有额外系统包需求时才本地重建。