NVIDIA DGX Spark 环境搭建实战指南基于 GB10/aarch64/CUDA 13 的容器优先策略与 ABI 匹配【免费下载链接】agentsMulti-harness agentic plugin marketplace for Claude Code, Codex, Cursor, OpenCode, GitHub Copilot, and Google Antigravity项目地址: https://gitcode.com/GitHub_Trending/agents24/agents本指南以plugins/dgx-spark-ops/skills/spark-environment-setup技能文档为主体系统讲解在 NVIDIA DGX SparkGB10 Grace Blackwell、aarch64、CUDA 13上搭建 PyTorch / Unsloth / TRL / vLLM 等训练与推理环境的完整方法论容器优先的决策规则、严格版本钉死的 bare-pip 安装序列、CUDA 12/13 的 ABI 匹配原理以及环境验证与故障排查清单。读完你将能够独立完成一台 Spark 机器的环境初始化、诊断最常见的 libcudart / wheel-ABI 报错并在训练前可靠地确认 GPU 可见性与软件栈正确性。平台背景一个比标准 x86 CUDA 12 更“窄”的平台DGX Spark 搭载的是 GB10 Grace Blackwell 芯片其环境特征决定了安装方式不能照搬普通 GPU 服务器CPU 架构aarch64ARM64GPU 计算能力SM121torch.cuda.get_device_capability()返回(12, 1)内存128GB 统一内存UMACPU 与 GPU 共享同一个内存池CUDA 版本CUDA 13。相比一台标准的 x86 CUDA 12 机器这是一个更年轻、生态更窄的平台aarch64 CUDA 13 的 wheel 生态仍在逐步补齐中。因此包的选择与 ABI 匹配比平时重要得多——很多 wheel 装上了、pip 也不报错但到import或第一次 kernel 启动时才失败。这正是本技能存在的意义让容器/wheel 组合与 CUDA 13 和 SM121 匹配而不是与 ABI 对抗。何时使用本技能根据 SKILL.md 的说明以下场景应启用本技能在一台全新的 Spark 机器上为训练或推理搭建环境遇到 import 错误报错中出现libcudart、缺失符号missing symbol或“装好了但加载不了”的 wheelPyTorch、Unsloth、TRL、vLLM、xformers 等框架安装失败、卡死或静默回退到 CPU需要在 NGC 容器与 bare pip 之间做取舍系统重装或基础镜像更新后需要从零恢复一套可用环境。这些场景的通用解法是一致的让容器/wheel 组合匹配 CUDA 13 与 SM121不要与 ABI 对抗。容器优先规则Container-First Rule决策先行。在深入细节之前先做三个快速判断场景选择标准训练/推理工作NGC PyTorch 容器Unsloth 为核心的微调Unsloth 容器已内置经过验证的 Triton/xformers/transformers 组合两者都不合适需要自定义系统包、本地 IDE 解释器bare pip严格按下方精确序列执行默认使用容器。选择容器并非出于便利而是为了“钉死版本”pinningTriton、xformers、transformers 的版本与 GB10 的 SM121 目标及 CUDA 13 之间存在很窄的交互面容器把这些版本一次性锁死在一块已经在这台硬件上验证过的组合上而 bare pip 把版本解析的责任留给了你一次一个坏 import 地慢慢排查。NGC PyTorch 容器通用基础以nvcr.io/nvidia/pytorch:25.09-py3作为通用工作基础——这是本技能确认可在此硬件上工作的较新标签。直接运行即可docker run --runtimenvidia --gpus all -it --rm \ nvcr.io/nvidia/pytorch:25.09-py3完整的推荐调用方式含共享内存与数据卷挂载见 container-workflow.mddocker run --runtimenvidia --gpus all -it --rm \ --ipchost --ulimit memlock-1 --ulimit stack67108864 \ -v $(pwd)/finetuning:/workspace/finetuning \ nvcr.io/nvidia/pytorch:25.09-py3各 flag 的作用--runtimenvidia --gpus all把 GB10 GPU 暴露给容器。缺少它时容器内 PyTorch 会报告无 CUDA 设备即便宿主机上nvidia-smi一切正常--ipchost与--ulimit memlock-1 --ulimit stack67108864避免 PyTorch DataLoader 工作进程因共享内存不足而饿死-v $(pwd)/finetuning:/workspace/finetuning把仓库的finetuning/运行目录挂载到宿主机使 checkpoint 与日志落在宿主机文件系统而非容器临时层——注意--rm会在退出时删除容器任何未挂载出来的数据都会丢失。关于标签版本SKILL.md提到的“较新的 blessed 标签”是指导性建议而非硬性要求——如果本地没有缓存该标签且拉取不现实回退到本地可用的最新25.x标签即可并在运行的记录中注明这一差异而不是被版本号卡住。Unsloth 容器移动标签必须先解析并钉死 digest与 NGC 镜像的日期标签25.09-py3不同unsloth/unsloth:dgxspark-latest是一个移动标签moving tag。它只适合作为“发现步骤”不应直接作为正式运行的调用方式。任何需要可复现的场合尤其 CI都必须先解析并钉死其 digest# 1. 发现步骤拉取移动标签并确认它能启动 docker pull unsloth/unsloth:dgxspark-latest # 2. 把标签解析为当前 digest docker inspect --format{{index .RepoDigests 0}} unsloth/unsloth:dgxspark-latest # - unsloth/unslothsha256:resolved digest # 3. 按 digest 运行——这才是可复现的调用方式 docker run --runtimenvidia --gpus all -it --rm \ --ipchost --ulimit memlock-1 --ulimit stack67108864 \ -v $(pwd)/finetuning:/workspace/finetuning \ unsloth/unslothsha256:resolved digest如果一条运行记录只写了dgxspark-latest标签而标签后来移动了这条记录就无法复现。每次采用新的 blessed 版本时都要重新解析、重新钉死 digest。Unsloth 镜像的优势在于它自带经过该硬件验证的 Triton/xformers/transformers 组合优先于从 NGC 基础镜像自建 Unsloth 镜像。拉新标签 vs 本地重建拉取新标签当官方宣布新的 blessed 版本、或你正在追一个新标签 changelog 声称已修复的 bug 时本地重建仅当某个项目需要额外叠加一个系统包或 Python 依赖且该依赖与镜像已钉死的训练栈不冲突时才以两个镜像之一为FROM基础做本地重建。不要为了“升级”镜像里已经钉死的组件而重建镜像——那会重新引入版本矩阵问题而容器存在的意义正是避免它。两个路径的完整细节见 container-workflow.md。bare pip 例外必须逐字执行的精确序列当 bare pip 确实有必要时需要严格按 NVIDIA 官方 playbook 的安装序列逐字、按顺序执行pip install transformers5.13.1 peft0.19.1 hf_transfer0.1.9 datasets4.3.0 trl1.8.0 pip install --no-deps unsloth2026.7.2 unsloth_zoo2026.7.2 bitsandbytes0.49.2 pip install -U torchao0.17.0这两条约束不是可选项第二条的--no-deps必不可少。让 pip 在 aarch64 上重新解析 Unsloth 的依赖树是拉入不兼容 torch 或 triton 构建的常见途径第三条同样必不可少。NGC 基础镜像自带的torchao对当前peft的 LoRA-attach 路径来说太旧了会直接报ImportError: ... torchao ... only versions above 0.16.0 are supported——这是硬性阻塞hard blocker不是警告。序列中每一个钉死都是有意义的全部取自 stack-matrix.md 中带日期的 known-good 版本矩阵其Last verified日期决定了时效性。不钉死的安装会解析到当前 PyPI 版本而它们往往远超这个 Unsloth 版本所支持的范围。bare-pip 逃生通道用 uv 隔离如果容器确实不合适详见 SKILL.md 的 Container-First Rule在 container-workflow.md 中还有一个明确建议用uv隔离环境而不是系统 Python并在其中执行上述 NVIDIA playbook 序列。需要特别留意的坑如果uv坚持采用某个与 playbook 钉死版本冲突的依赖版本在 aarch64/CUDA 13 生态还很年轻的背景下很常见要用uv pip install --override强制穿透钉死版本而不是让解析器静默替换成不兼容的构建。搭建完成后务必先用下文“验证命令”一节确认环境可信再投入使用。一个额外的前置检查官方 DGX Spark playbook 曾出现过发布即损坏的情况。在把某个 recipe 用于长时间运行之前先检查github.com/NVIDIA/dgx-spark-playbooks的近期 issues以及 stack-matrix.md 列出的其他资源再决定是否逐字信任。ABI 规则Spark 上最常见的失败根源Spark 上最最常见的失败是CUDA 12/13 ABI 不匹配一个针对libcudart.so.12构建的 wheel被加载到只有libcudart.so.13的系统上。安装通常能成功失败要到很晚才暴露——以缺失符号missing-symbol错误或一个看起来与 CUDA 无关的段错误segfault出现。修复方式只有两条从download.pytorch.org/whl/cu130cu130 标签的 aarch64 构建拉取 wheel或直接使用上面已经携带匹配构建的容器。在追查任何提到 CUDA 符号的堆栈之前先检查已装 wheel 是对哪个 CUDA 标签构建的python3 -c import torch; print(torch.version.cuda)如果输出不是以13开头ABI 不匹配就是首先要修的问题。有一个需要澄清的例外NGC 容器构建如nvcr.io/nvidia/pytorch:25.09-py3是内部针对 CUDA 13 构建的 torch没有cu130wheel 标签——所以pip show torch不会显示cu130。这种“缺少 cu130 标签”本身并不是失败别误判。典型症状清单ImportError: undefined symbol报错指向某个 CUDA runtime 函数第一次调用.cuda()时段错误且没有有用的回溯wheel 安装干净利落但 import 时失败——pip 的解析器只检查版本约束从不检查 CUDA ABI两个“完全相同”的环境行为不一致——通常一个装的是 cu130 wheel另一个残留着 cu121/cu124。无论症状是哪种修复方式都一样让 wheel 的 CUDA 标签与系统匹配或使用已经匹配的容器。ABI 排查的底层命令gotcha-checks.md对应spark-training-gotchas技能的 G1给出了可运行的底层检查python3 -c import torch; print(torch.version.cuda) python -c import ctypes; ctypes.CDLL(libcudart.so.13) ldconfig -p | grep libcudarttorch.version.cuda是权威信号应当报告13.xctypes加载确认libcudart.so.13确实存在于系统中——如果抛OSError问题是驱动/runtime 安装而不是 wheelldconfig -p列出当前注册的所有 CUDA runtime 版本——如果libcudart.so.12与libcudart.so.13并存那通常是更早安装留下的残留也是 ABI 不匹配的常见来源。组件快速对照表下表是各组件在 Spark 上最可能被问及的状态速览完整表格含 wheel URL、构建参数、sm_121 与 sm_121a 的区别、带日期的 known-good 版本矩阵见 stack-matrix.md组件状态PyTorch✅ 官方提供 cu130 aarch64 wheelbitsandbytes✅ 开箱即用0.48Triton✅ 需要设置TRITON_PTXAS_PATH环境变量flash-attn❌ 跳过 pip 构建NGC 容器内置可用版本见spark-training-gotchas的 G2xformers仅源码构建需设置TORCH_CUDA_ARCH_LIST12.1vLLM仅 nightly wheelwheels.vllm.ai/nightly/cu130SM121 修复约 2026-06 才进入 nightly 通道TransformerEngine / NVFP4 训练仅限容器其余组件——Unsloth、Axolotl、TRL、PEFT——通过上面的容器优先路径都能干净安装。LLaMA-Factory 和 NeMo 在 Spark 上比较脆弱先查上游 issues 再决定是否依赖。几个值得注意的细节来自 stack-matrix.mdflash-attn没有 sm_121 kernel 可发运也暂时构建不出来。而 PyTorch 的 SDPA 后端在这块硬件上反而更快不必花时间追 flash-attn 构建。NGC 容器里预装的 flash-attn 2.7.4.post1 在 GB10capability(12,1)上可正常执行xformers没有预编译的 aarch64/SM121 wheel必须用TORCH_CUDA_ARCH_LIST12.1从源码构建否则构建会指向错误的架构要么失败要么静默产出不可用的 kernelTransformerEngine / NVFP4裸 pip 不现实请用 NGC PyTorch 容器。NVFP4BlockScaling面向 SM100 设计SM121 上的支持应视为“有保留的”而非保证。带日期的 known-good 版本矩阵stack-matrix.md 明确解释了为什么 SKILL.md 的 bare-pip 序列要显式钉死datasets/trl不钉死的pip install transformers peft hf_transfer datasets trl accelerate会解析到当前 PyPI 上远超该 Unsloth 版本支持范围的版本——pip 照样安装只是事后才警告。截至Last verified: 2026-07-14在nvcr.io/nvidia/pytorch:25.09-py3上端到端验证bf16 LoRA 加载 attach 完整 SFT 运行的组合为包验证可用版本transformers5.13.1trl1.8.0peft0.19.1datasets4.3.0按组合原样钉死未单独复验unsloth/unsloth_zoo2026.7.2torchao0.17.0纯 Python wheelNGC 基础镜像自带 0.13.0git太旧需在 Unsloth 之后pip install -U torchaobitsandbytes0.49.2hf_transfer0.1.9见下方弃用说明这是带日期的快照需要复核不是永久钉死。若 bare-pip 最终落在与表格不同的组合pip 解析器漂移是常态先重跑 SKILL.md“验证命令”一节的 loadLoRA-attach 冒烟测试再检查gh issue list --repo NVIDIA/dgx-spark-playbooks是否有匹配的版本偏差报告。一个易被忽略的弃用hf_transferHF_HUB_ENABLE_HF_TRANSFER在huggingface_hub1.23 已被弃用。现在设置它只会产生FutureWarning下载实际走 Xet 通道而非 hf_transfer——影响是表面性的下载依然成功且快。旧 recipe 里提到hf_transfer的环境设置应理解为意图“让下载变快”而非字面的当前 API 要求在huggingface_hub1.23 上应设置HF_XET_HIGH_PERFORMANCE1。sm_121 与 sm_121aNVFP4 性能差异的根源GB10 的 GPU 标识为sm_121。部分更新的 kernel 特性——特别是 NVFP4 的原生cvt.e2m1x2转换指令——需要按sm_121a超集目标编译的代码而非普通sm_121。如果 NVFP4 推理在这块硬件上比 FP8 慢约 32%原因就在于此kernel 很可能没有用a变体编译。在断定硬件本身是瓶颈之前先检查所用 wheel/容器的构建参数。环境验证命令跑任何昂贵任务之前先确认 GPU 可见在运行任何昂贵任务之前先确认环境确实能看到 GPUimport torch print(torch.cuda.is_available(), torch.version.cuda)这个调用返回两个值输出格式为一行bool cuda-versionTrue 13.0如果打印出的是False不要直接跳到重装 wheel——ABI 不匹配只是多种可能原因之一。按假设逐一排查假设快速检查Runtime/启动参数容器内nvidia-smi也失败设备可见性echo $CUDA_VISIBLE_DEVICES权限ls -l /dev/nvidia*CUDA 初始化状态进程卡死换新 shell/新容器重试ABI 不匹配常见元凶torch.version.cuda不是13.x先查nvidia-smi——如果它不显示 GPU问题属于前三类而不是 ABI。只有在确认 ABI 之后才重装 wheel。逐假设排查的完整顺序stack-matrix.md 给出了五类假设的完整判别顺序Runtime/flags如果docker run缺少--runtimenvidia --gpus all容器内nvidia-smi会失败或显示无设备而宿主机正常。修复带两个 flag 重跑设备可见性echo $CUDA_VISIBLE_DEVICES——被显式设置为空字符串而非未设置会隐藏所有设备过期的索引如单 GPU 机器上的1会隐藏唯一设备。修复unset CUDA_VISIBLE_DEVICES或设为0权限ls -l /dev/nvidia*——条目缺失或读时Permission denied说明容器/用户无法打开设备节点rootless 或严格的 seccomp/AppArmor 配置下常见。修复匹配宿主机的 device-cgroup 规则或 GPU 负载不要用 rootlessCUDA 初始化状态之前中途崩溃的进程可能把 CUDA context 卡死在该进程树上。在新 shell或新起的容器而不是同 shell 里新起的 Python 进程里重试成本最低ABI 不匹配最后一个要查的假设。torch.version.cuda不以13开头即确认——这是五种里唯一真正需要重装 wheel 才能解决的。在排除 1–4 之前重装是浪费循环真实原因是 flag、环境变量或权限时结果不会改变。一个与 torchcodec/驱动交互相关的 ABI 案例是这块硬件上报告最多的 (5) 类实例可用gh issue list --repo NVIDIA/dgx-spark-playbooks查当前报告。Triton kernel 编译失败若训练开始后 Triton kernel 编译失败设置以下环境变量并重试export TRITON_PTXAS_PATH/usr/local/cuda/bin/ptxas不设置的话kernel 编译会找不到ptxas。完整 workaround 列表见 stack-matrix.md。从环境到训练与同仓库其他技能/工具衔接一个验证通过的环境只是起点。本技能在plugins/dgx-spark-ops插件内与以下模块协同工作spark-training-gotchas训练前的失败预检。它把 GB10 上反复出现的十类故障命名为 G1–G10编号对运行检查的工具是“承重”的。其中 G1CUDA 12/13 ABI、G2flash-attn、G8官方 playbook 损坏、G9容器优先 vs bare pip与本技能直接相关spark-memory-thermal-ops统一内存 OOM 与长时间运行的散热节流处理——它假设任务能启动处理的是运行中的问题dgx-spark-ops-engineer环境医生 agent按顺序执行硬件身份确认 → G1–G10 检查 → 内存余量计算 → 输出env-report.json的预检流程结论以ready/ready-with-warnings/blocked三种裁决呈现spark-preflight命令入口把调用者描述的计划负载转给上述 agent执行完整预检并写env-report.json。快速三连检Fast Triagespark-training-gotchas 给出了三个最便宜的预检命令python3 -c import torch; print(torch.version.cuda) # 期望 13.xG1NGC 构建没有 cu130 标签——那不是失败import torch; print(torch.cuda.get_device_capability()) # 期望 (12, 1)G7{ [ -f /.dockerenv -o -f /run/.containerenv ] || grep -qE docker|containerd /proc/1/cgroup; } 2/dev/null echo container || echo unknown # G9其中 G9 的容器检测在 gotcha-checks.md 中有更严谨的版本仅靠一次grep docker /proc/1/cgroup并不可靠因为 cgroup v2 布局和部分 runtime/namespace 会隐藏 runtime 名称——匹配失败只能说明“unknown”不能证明是裸机。自动化的 preflight.shspark-training-gotchas的 assets/preflight.sh 覆盖 G1、G3、G4、G7、G9输出契约固定每行结果以 G 编号开头可自动化的给出 PASS/FAIL/WARN无法自动化的给 SKIP原始读数G3、G4给INFO:前缀。G2flash-attn 存在性与 Unsloth 覆盖、G6进程普查、G8上游 issue 查询、G10配置审查不可自动化需按 gotcha-checks.md 手动执行。例如预检输出会是这样的形态 G1: CUDA 12/13 ABI G1 PASS: torch built against CUDA 13.0 G3: UMA headroom (raw reading) G3 INFO: free/used (GB): 61 62 G4: thermal snapshot (raw reading) G4 INFO: 42 C, 85 W G7: SM121 capability (kernel target arch NOT checked here) G7 PASS: SM121 hardware capability confirmed (partial — verify the kernel target arch (sm_121a) manually, see gotcha-checks.md G7) G9: container vs bare pip G9 PASS: running inside a container (Docker/Podman marker file present)从环境到运行的完整路径小结决策默认 NGC PyTorch 容器nvcr.io/nvidia/pytorch:25.09-py3Unsloth 微调用 Unsloth 容器先解析并钉死 digest两者都不合适才走 bare pip匹配 ABI确认torch.version.cuda以13开头否则从download.pytorch.org/whl/cu130重装或用容器验证 GPU 可见性torch.cuda.is_available()为True为False时按 假设排查表runtime → 环境变量 → 权限 → CUDA 状态 → ABI顺序处理预检故障模式跑 preflight.sh 覆盖自动化的 G1/G3/G4/G7/G9其余按 G 编号手动核验启动长任务前查github.com/NVIDIA/dgx-spark-playbooks近期 issues核对 stack-matrix.md 的Last verified日期确认版本矩阵未过期。需要强调的是本仓库是可读的所有技能文档、参考矩阵、检查脚本与 agent 指令均可在 plugins/dgx-spark-ops 目录下直接查阅其中 SKILL.md 是本指南的主体依据container-workflow.md 与 stack-matrix.md 分别提供了容器调用细节与版本矩阵的完整证据。【免费下载链接】agentsMulti-harness agentic plugin marketplace for Claude Code, Codex, Cursor, OpenCode, GitHub Copilot, and Google Antigravity项目地址: https://gitcode.com/GitHub_Trending/agents24/agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 NVIDIA DGX Spark 环境搭建实战指南：基于 GB10/aarch64/CUDA 13 的容器优先策略与 ABI 匹配
NVIDIA DGX Spark 环境搭建实战指南基于 GB10/aarch64/CUDA 13 的容器优先策略与 ABI 匹配【免费下载链接】agentsMulti-harness agentic plugin marketplace for Claude Code, Codex, Cursor, OpenCode, GitHub Copilot, and Google Antigravity项目地址: https://gitcode.com/GitHub_Trending/agents24/agents本指南以plugins/dgx-spark-ops/skills/spark-environment-setup技能文档为主体系统讲解在 NVIDIA DGX SparkGB10 Grace Blackwell、aarch64、CUDA 13上搭建 PyTorch / Unsloth / TRL / vLLM 等训练与推理环境的完整方法论容器优先的决策规则、严格版本钉死的 bare-pip 安装序列、CUDA 12/13 的 ABI 匹配原理以及环境验证与故障排查清单。读完你将能够独立完成一台 Spark 机器的环境初始化、诊断最常见的 libcudart / wheel-ABI 报错并在训练前可靠地确认 GPU 可见性与软件栈正确性。平台背景一个比标准 x86 CUDA 12 更“窄”的平台DGX Spark 搭载的是 GB10 Grace Blackwell 芯片其环境特征决定了安装方式不能照搬普通 GPU 服务器CPU 架构aarch64ARM64GPU 计算能力SM121torch.cuda.get_device_capability()返回(12, 1)内存128GB 统一内存UMACPU 与 GPU 共享同一个内存池CUDA 版本CUDA 13。相比一台标准的 x86 CUDA 12 机器这是一个更年轻、生态更窄的平台aarch64 CUDA 13 的 wheel 生态仍在逐步补齐中。因此包的选择与 ABI 匹配比平时重要得多——很多 wheel 装上了、pip 也不报错但到import或第一次 kernel 启动时才失败。这正是本技能存在的意义让容器/wheel 组合与 CUDA 13 和 SM121 匹配而不是与 ABI 对抗。何时使用本技能根据 SKILL.md 的说明以下场景应启用本技能在一台全新的 Spark 机器上为训练或推理搭建环境遇到 import 错误报错中出现libcudart、缺失符号missing symbol或“装好了但加载不了”的 wheelPyTorch、Unsloth、TRL、vLLM、xformers 等框架安装失败、卡死或静默回退到 CPU需要在 NGC 容器与 bare pip 之间做取舍系统重装或基础镜像更新后需要从零恢复一套可用环境。这些场景的通用解法是一致的让容器/wheel 组合匹配 CUDA 13 与 SM121不要与 ABI 对抗。容器优先规则Container-First Rule决策先行。在深入细节之前先做三个快速判断场景选择标准训练/推理工作NGC PyTorch 容器Unsloth 为核心的微调Unsloth 容器已内置经过验证的 Triton/xformers/transformers 组合两者都不合适需要自定义系统包、本地 IDE 解释器bare pip严格按下方精确序列执行默认使用容器。选择容器并非出于便利而是为了“钉死版本”pinningTriton、xformers、transformers 的版本与 GB10 的 SM121 目标及 CUDA 13 之间存在很窄的交互面容器把这些版本一次性锁死在一块已经在这台硬件上验证过的组合上而 bare pip 把版本解析的责任留给了你一次一个坏 import 地慢慢排查。NGC PyTorch 容器通用基础以nvcr.io/nvidia/pytorch:25.09-py3作为通用工作基础——这是本技能确认可在此硬件上工作的较新标签。直接运行即可docker run --runtimenvidia --gpus all -it --rm \ nvcr.io/nvidia/pytorch:25.09-py3完整的推荐调用方式含共享内存与数据卷挂载见 container-workflow.mddocker run --runtimenvidia --gpus all -it --rm \ --ipchost --ulimit memlock-1 --ulimit stack67108864 \ -v $(pwd)/finetuning:/workspace/finetuning \ nvcr.io/nvidia/pytorch:25.09-py3各 flag 的作用--runtimenvidia --gpus all把 GB10 GPU 暴露给容器。缺少它时容器内 PyTorch 会报告无 CUDA 设备即便宿主机上nvidia-smi一切正常--ipchost与--ulimit memlock-1 --ulimit stack67108864避免 PyTorch DataLoader 工作进程因共享内存不足而饿死-v $(pwd)/finetuning:/workspace/finetuning把仓库的finetuning/运行目录挂载到宿主机使 checkpoint 与日志落在宿主机文件系统而非容器临时层——注意--rm会在退出时删除容器任何未挂载出来的数据都会丢失。关于标签版本SKILL.md提到的“较新的 blessed 标签”是指导性建议而非硬性要求——如果本地没有缓存该标签且拉取不现实回退到本地可用的最新25.x标签即可并在运行的记录中注明这一差异而不是被版本号卡住。Unsloth 容器移动标签必须先解析并钉死 digest与 NGC 镜像的日期标签25.09-py3不同unsloth/unsloth:dgxspark-latest是一个移动标签moving tag。它只适合作为“发现步骤”不应直接作为正式运行的调用方式。任何需要可复现的场合尤其 CI都必须先解析并钉死其 digest# 1. 发现步骤拉取移动标签并确认它能启动 docker pull unsloth/unsloth:dgxspark-latest # 2. 把标签解析为当前 digest docker inspect --format{{index .RepoDigests 0}} unsloth/unsloth:dgxspark-latest # - unsloth/unslothsha256:resolved digest # 3. 按 digest 运行——这才是可复现的调用方式 docker run --runtimenvidia --gpus all -it --rm \ --ipchost --ulimit memlock-1 --ulimit stack67108864 \ -v $(pwd)/finetuning:/workspace/finetuning \ unsloth/unslothsha256:resolved digest如果一条运行记录只写了dgxspark-latest标签而标签后来移动了这条记录就无法复现。每次采用新的 blessed 版本时都要重新解析、重新钉死 digest。Unsloth 镜像的优势在于它自带经过该硬件验证的 Triton/xformers/transformers 组合优先于从 NGC 基础镜像自建 Unsloth 镜像。拉新标签 vs 本地重建拉取新标签当官方宣布新的 blessed 版本、或你正在追一个新标签 changelog 声称已修复的 bug 时本地重建仅当某个项目需要额外叠加一个系统包或 Python 依赖且该依赖与镜像已钉死的训练栈不冲突时才以两个镜像之一为FROM基础做本地重建。不要为了“升级”镜像里已经钉死的组件而重建镜像——那会重新引入版本矩阵问题而容器存在的意义正是避免它。两个路径的完整细节见 container-workflow.md。bare pip 例外必须逐字执行的精确序列当 bare pip 确实有必要时需要严格按 NVIDIA 官方 playbook 的安装序列逐字、按顺序执行pip install transformers5.13.1 peft0.19.1 hf_transfer0.1.9 datasets4.3.0 trl1.8.0 pip install --no-deps unsloth2026.7.2 unsloth_zoo2026.7.2 bitsandbytes0.49.2 pip install -U torchao0.17.0这两条约束不是可选项第二条的--no-deps必不可少。让 pip 在 aarch64 上重新解析 Unsloth 的依赖树是拉入不兼容 torch 或 triton 构建的常见途径第三条同样必不可少。NGC 基础镜像自带的torchao对当前peft的 LoRA-attach 路径来说太旧了会直接报ImportError: ... torchao ... only versions above 0.16.0 are supported——这是硬性阻塞hard blocker不是警告。序列中每一个钉死都是有意义的全部取自 stack-matrix.md 中带日期的 known-good 版本矩阵其Last verified日期决定了时效性。不钉死的安装会解析到当前 PyPI 版本而它们往往远超这个 Unsloth 版本所支持的范围。bare-pip 逃生通道用 uv 隔离如果容器确实不合适详见 SKILL.md 的 Container-First Rule在 container-workflow.md 中还有一个明确建议用uv隔离环境而不是系统 Python并在其中执行上述 NVIDIA playbook 序列。需要特别留意的坑如果uv坚持采用某个与 playbook 钉死版本冲突的依赖版本在 aarch64/CUDA 13 生态还很年轻的背景下很常见要用uv pip install --override强制穿透钉死版本而不是让解析器静默替换成不兼容的构建。搭建完成后务必先用下文“验证命令”一节确认环境可信再投入使用。一个额外的前置检查官方 DGX Spark playbook 曾出现过发布即损坏的情况。在把某个 recipe 用于长时间运行之前先检查github.com/NVIDIA/dgx-spark-playbooks的近期 issues以及 stack-matrix.md 列出的其他资源再决定是否逐字信任。ABI 规则Spark 上最常见的失败根源Spark 上最最常见的失败是CUDA 12/13 ABI 不匹配一个针对libcudart.so.12构建的 wheel被加载到只有libcudart.so.13的系统上。安装通常能成功失败要到很晚才暴露——以缺失符号missing-symbol错误或一个看起来与 CUDA 无关的段错误segfault出现。修复方式只有两条从download.pytorch.org/whl/cu130cu130 标签的 aarch64 构建拉取 wheel或直接使用上面已经携带匹配构建的容器。在追查任何提到 CUDA 符号的堆栈之前先检查已装 wheel 是对哪个 CUDA 标签构建的python3 -c import torch; print(torch.version.cuda)如果输出不是以13开头ABI 不匹配就是首先要修的问题。有一个需要澄清的例外NGC 容器构建如nvcr.io/nvidia/pytorch:25.09-py3是内部针对 CUDA 13 构建的 torch没有cu130wheel 标签——所以pip show torch不会显示cu130。这种“缺少 cu130 标签”本身并不是失败别误判。典型症状清单ImportError: undefined symbol报错指向某个 CUDA runtime 函数第一次调用.cuda()时段错误且没有有用的回溯wheel 安装干净利落但 import 时失败——pip 的解析器只检查版本约束从不检查 CUDA ABI两个“完全相同”的环境行为不一致——通常一个装的是 cu130 wheel另一个残留着 cu121/cu124。无论症状是哪种修复方式都一样让 wheel 的 CUDA 标签与系统匹配或使用已经匹配的容器。ABI 排查的底层命令gotcha-checks.md对应spark-training-gotchas技能的 G1给出了可运行的底层检查python3 -c import torch; print(torch.version.cuda) python -c import ctypes; ctypes.CDLL(libcudart.so.13) ldconfig -p | grep libcudarttorch.version.cuda是权威信号应当报告13.xctypes加载确认libcudart.so.13确实存在于系统中——如果抛OSError问题是驱动/runtime 安装而不是 wheelldconfig -p列出当前注册的所有 CUDA runtime 版本——如果libcudart.so.12与libcudart.so.13并存那通常是更早安装留下的残留也是 ABI 不匹配的常见来源。组件快速对照表下表是各组件在 Spark 上最可能被问及的状态速览完整表格含 wheel URL、构建参数、sm_121 与 sm_121a 的区别、带日期的 known-good 版本矩阵见 stack-matrix.md组件状态PyTorch✅ 官方提供 cu130 aarch64 wheelbitsandbytes✅ 开箱即用0.48Triton✅ 需要设置TRITON_PTXAS_PATH环境变量flash-attn❌ 跳过 pip 构建NGC 容器内置可用版本见spark-training-gotchas的 G2xformers仅源码构建需设置TORCH_CUDA_ARCH_LIST12.1vLLM仅 nightly wheelwheels.vllm.ai/nightly/cu130SM121 修复约 2026-06 才进入 nightly 通道TransformerEngine / NVFP4 训练仅限容器其余组件——Unsloth、Axolotl、TRL、PEFT——通过上面的容器优先路径都能干净安装。LLaMA-Factory 和 NeMo 在 Spark 上比较脆弱先查上游 issues 再决定是否依赖。几个值得注意的细节来自 stack-matrix.mdflash-attn没有 sm_121 kernel 可发运也暂时构建不出来。而 PyTorch 的 SDPA 后端在这块硬件上反而更快不必花时间追 flash-attn 构建。NGC 容器里预装的 flash-attn 2.7.4.post1 在 GB10capability(12,1)上可正常执行xformers没有预编译的 aarch64/SM121 wheel必须用TORCH_CUDA_ARCH_LIST12.1从源码构建否则构建会指向错误的架构要么失败要么静默产出不可用的 kernelTransformerEngine / NVFP4裸 pip 不现实请用 NGC PyTorch 容器。NVFP4BlockScaling面向 SM100 设计SM121 上的支持应视为“有保留的”而非保证。带日期的 known-good 版本矩阵stack-matrix.md 明确解释了为什么 SKILL.md 的 bare-pip 序列要显式钉死datasets/trl不钉死的pip install transformers peft hf_transfer datasets trl accelerate会解析到当前 PyPI 上远超该 Unsloth 版本支持范围的版本——pip 照样安装只是事后才警告。截至Last verified: 2026-07-14在nvcr.io/nvidia/pytorch:25.09-py3上端到端验证bf16 LoRA 加载 attach 完整 SFT 运行的组合为包验证可用版本transformers5.13.1trl1.8.0peft0.19.1datasets4.3.0按组合原样钉死未单独复验unsloth/unsloth_zoo2026.7.2torchao0.17.0纯 Python wheelNGC 基础镜像自带 0.13.0git太旧需在 Unsloth 之后pip install -U torchaobitsandbytes0.49.2hf_transfer0.1.9见下方弃用说明这是带日期的快照需要复核不是永久钉死。若 bare-pip 最终落在与表格不同的组合pip 解析器漂移是常态先重跑 SKILL.md“验证命令”一节的 loadLoRA-attach 冒烟测试再检查gh issue list --repo NVIDIA/dgx-spark-playbooks是否有匹配的版本偏差报告。一个易被忽略的弃用hf_transferHF_HUB_ENABLE_HF_TRANSFER在huggingface_hub1.23 已被弃用。现在设置它只会产生FutureWarning下载实际走 Xet 通道而非 hf_transfer——影响是表面性的下载依然成功且快。旧 recipe 里提到hf_transfer的环境设置应理解为意图“让下载变快”而非字面的当前 API 要求在huggingface_hub1.23 上应设置HF_XET_HIGH_PERFORMANCE1。sm_121 与 sm_121aNVFP4 性能差异的根源GB10 的 GPU 标识为sm_121。部分更新的 kernel 特性——特别是 NVFP4 的原生cvt.e2m1x2转换指令——需要按sm_121a超集目标编译的代码而非普通sm_121。如果 NVFP4 推理在这块硬件上比 FP8 慢约 32%原因就在于此kernel 很可能没有用a变体编译。在断定硬件本身是瓶颈之前先检查所用 wheel/容器的构建参数。环境验证命令跑任何昂贵任务之前先确认 GPU 可见在运行任何昂贵任务之前先确认环境确实能看到 GPUimport torch print(torch.cuda.is_available(), torch.version.cuda)这个调用返回两个值输出格式为一行bool cuda-versionTrue 13.0如果打印出的是False不要直接跳到重装 wheel——ABI 不匹配只是多种可能原因之一。按假设逐一排查假设快速检查Runtime/启动参数容器内nvidia-smi也失败设备可见性echo $CUDA_VISIBLE_DEVICES权限ls -l /dev/nvidia*CUDA 初始化状态进程卡死换新 shell/新容器重试ABI 不匹配常见元凶torch.version.cuda不是13.x先查nvidia-smi——如果它不显示 GPU问题属于前三类而不是 ABI。只有在确认 ABI 之后才重装 wheel。逐假设排查的完整顺序stack-matrix.md 给出了五类假设的完整判别顺序Runtime/flags如果docker run缺少--runtimenvidia --gpus all容器内nvidia-smi会失败或显示无设备而宿主机正常。修复带两个 flag 重跑设备可见性echo $CUDA_VISIBLE_DEVICES——被显式设置为空字符串而非未设置会隐藏所有设备过期的索引如单 GPU 机器上的1会隐藏唯一设备。修复unset CUDA_VISIBLE_DEVICES或设为0权限ls -l /dev/nvidia*——条目缺失或读时Permission denied说明容器/用户无法打开设备节点rootless 或严格的 seccomp/AppArmor 配置下常见。修复匹配宿主机的 device-cgroup 规则或 GPU 负载不要用 rootlessCUDA 初始化状态之前中途崩溃的进程可能把 CUDA context 卡死在该进程树上。在新 shell或新起的容器而不是同 shell 里新起的 Python 进程里重试成本最低ABI 不匹配最后一个要查的假设。torch.version.cuda不以13开头即确认——这是五种里唯一真正需要重装 wheel 才能解决的。在排除 1–4 之前重装是浪费循环真实原因是 flag、环境变量或权限时结果不会改变。一个与 torchcodec/驱动交互相关的 ABI 案例是这块硬件上报告最多的 (5) 类实例可用gh issue list --repo NVIDIA/dgx-spark-playbooks查当前报告。Triton kernel 编译失败若训练开始后 Triton kernel 编译失败设置以下环境变量并重试export TRITON_PTXAS_PATH/usr/local/cuda/bin/ptxas不设置的话kernel 编译会找不到ptxas。完整 workaround 列表见 stack-matrix.md。从环境到训练与同仓库其他技能/工具衔接一个验证通过的环境只是起点。本技能在plugins/dgx-spark-ops插件内与以下模块协同工作spark-training-gotchas训练前的失败预检。它把 GB10 上反复出现的十类故障命名为 G1–G10编号对运行检查的工具是“承重”的。其中 G1CUDA 12/13 ABI、G2flash-attn、G8官方 playbook 损坏、G9容器优先 vs bare pip与本技能直接相关spark-memory-thermal-ops统一内存 OOM 与长时间运行的散热节流处理——它假设任务能启动处理的是运行中的问题dgx-spark-ops-engineer环境医生 agent按顺序执行硬件身份确认 → G1–G10 检查 → 内存余量计算 → 输出env-report.json的预检流程结论以ready/ready-with-warnings/blocked三种裁决呈现spark-preflight命令入口把调用者描述的计划负载转给上述 agent执行完整预检并写env-report.json。快速三连检Fast Triagespark-training-gotchas 给出了三个最便宜的预检命令python3 -c import torch; print(torch.version.cuda) # 期望 13.xG1NGC 构建没有 cu130 标签——那不是失败import torch; print(torch.cuda.get_device_capability()) # 期望 (12, 1)G7{ [ -f /.dockerenv -o -f /run/.containerenv ] || grep -qE docker|containerd /proc/1/cgroup; } 2/dev/null echo container || echo unknown # G9其中 G9 的容器检测在 gotcha-checks.md 中有更严谨的版本仅靠一次grep docker /proc/1/cgroup并不可靠因为 cgroup v2 布局和部分 runtime/namespace 会隐藏 runtime 名称——匹配失败只能说明“unknown”不能证明是裸机。自动化的 preflight.shspark-training-gotchas的 assets/preflight.sh 覆盖 G1、G3、G4、G7、G9输出契约固定每行结果以 G 编号开头可自动化的给出 PASS/FAIL/WARN无法自动化的给 SKIP原始读数G3、G4给INFO:前缀。G2flash-attn 存在性与 Unsloth 覆盖、G6进程普查、G8上游 issue 查询、G10配置审查不可自动化需按 gotcha-checks.md 手动执行。例如预检输出会是这样的形态 G1: CUDA 12/13 ABI G1 PASS: torch built against CUDA 13.0 G3: UMA headroom (raw reading) G3 INFO: free/used (GB): 61 62 G4: thermal snapshot (raw reading) G4 INFO: 42 C, 85 W G7: SM121 capability (kernel target arch NOT checked here) G7 PASS: SM121 hardware capability confirmed (partial — verify the kernel target arch (sm_121a) manually, see gotcha-checks.md G7) G9: container vs bare pip G9 PASS: running inside a container (Docker/Podman marker file present)从环境到运行的完整路径小结决策默认 NGC PyTorch 容器nvcr.io/nvidia/pytorch:25.09-py3Unsloth 微调用 Unsloth 容器先解析并钉死 digest两者都不合适才走 bare pip匹配 ABI确认torch.version.cuda以13开头否则从download.pytorch.org/whl/cu130重装或用容器验证 GPU 可见性torch.cuda.is_available()为True为False时按 假设排查表runtime → 环境变量 → 权限 → CUDA 状态 → ABI顺序处理预检故障模式跑 preflight.sh 覆盖自动化的 G1/G3/G4/G7/G9其余按 G 编号手动核验启动长任务前查github.com/NVIDIA/dgx-spark-playbooks近期 issues核对 stack-matrix.md 的Last verified日期确认版本矩阵未过期。需要强调的是本仓库是可读的所有技能文档、参考矩阵、检查脚本与 agent 指令均可在 plugins/dgx-spark-ops 目录下直接查阅其中 SKILL.md 是本指南的主体依据container-workflow.md 与 stack-matrix.md 分别提供了容器调用细节与版本矩阵的完整证据。【免费下载链接】agentsMulti-harness agentic plugin marketplace for Claude Code, Codex, Cursor, OpenCode, GitHub Copilot, and Google Antigravity项目地址: https://gitcode.com/GitHub_Trending/agents24/agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考