DGX Spark 训练避坑指南G1–G10 十类已知故障的预检与诊断实战基于 spark-training-gotchas 技能【免费下载链接】agentsMulti-harness agentic plugin marketplace for Claude Code, Codex, Cursor, OpenCode, GitHub Copilot, and Google Antigravity项目地址: https://gitcode.com/GitHub_Trending/agents24/agentsDGX Spark 搭载 GB10 芯片Grace BlackwellSM121 架构128GB 统一内存aarch64在启动、内存、散热、带宽和精度五个维度上存在十类反复出现的故障模式。本指南以当前仓库中plugins/dgx-spark-ops/skills/spark-training-gotchas/SKILL.md为骨架逐条讲解这十个编号故障G1–G10的症状、根因、可运行的检查命令与修复手段并结合 gotcha-checks.md 与 preflight.sh 给出自动化预检方案。读完你将掌握在任何多小时的 GB10 训练任务开始前如何用几分钟定位 CUDA ABI 不匹配、UMA 假 OOM、热节流、带宽上限等隐患而不是在跑到第六小时时才回头排查。关键原则G1–G10 的编号是承重的——仓库内用于跑这些检查的工具都按编号引用它们诊断结论也应始终以 G 编号为准dgx-spark-ops-engineer 智能体 明确要求每个诊断必须标注 G 编号缺少 G 编号的 Spark 故障视为未完成诊断。请在长任务开始前阅读本文而不是在第六小时之后。何时使用本技能spark-training-gotchas面向以下典型场景凡命中其一都应先跑一遍 G1–G10 检查再动手训练任务无法启动抛出与真实原因无关的 import 错误或段错误segfault任务 OOM而nvidia-smi仍显示内存有富余任务正常启动后运行中途吞吐量明显下降任何多小时或多 epoch 的 GB10 任务启动之前计划把两台 Spark 互联dual-Spark之前需要先决定并行策略需要在 FP8 与 NVFP4 之间为 Spark 上的推理/训练选型。常见问题速查表#症状修复G1undefined symbol / 段错误改用 cu130 wheel 或匹配的容器G2flash-attn 使用了错误的 backend跳过 pip 构建在 NGC 容器上用 monkeypatch 覆盖G3明明有富余内存却 OOM清空 page cacheG4吞吐量下降 / 重启预期约 100W 的持续功耗上限G5内存密集型 step 变慢按 180–192 GB/s 做预算G6缓存中途被逐出同一时间只跑一个重型任务G7NVFP4 比 FP8 更慢除非编译目标为sm_121a否则继续用 FP8G8官方 playbook 直接失败先查上游 issueG9安装后环境被破坏使用容器G10双 Spark TP 挂起只用 DDP/FSDP绝不用 TPG1CUDA 12/13 ABI 不匹配症状ImportError: undefined symbol并指向某个 CUDA 函数或第一次调用.cuda()时直接段错误。根因绝大多数 PyPI wheel 链接的是libcudart.so.12而 Spark 自带 CUDA 13。pip 的依赖解析器从不检查 CUDA ABI因此问题只会在 import 或首次 kernel 启动时暴露——典型的安装成功、加载失败。检查torch.version.cuda是权威信号应返回13.xpython3 -c import torch; print(torch.version.cuda) python -c import ctypes; ctypes.CDLL(libcudart.so.13) ldconfig -p | grep libcudart按 gotcha-checks.md G1 的说明不要依赖pip show torch | grep cu130NGC 容器如nvcr.io/nvidia/pytorch:25.11-py3内部自行用 CUDA 13 构建 torch没有cu130wheel tag所以pip show里查不到cu130并不等于失败ctypes加载libcudart.so.13若抛出OSError说明是驱动/运行时安装问题而不是 wheel 问题ldconfig -p中同时出现libcudart.so.12和libcudart.so.13是早期安装的常见残留也是 ABI 不匹配的常见来源。修复从download.pytorch.org/whl/cu130重装cu130 标记的 aarch64 构建或使用已内置匹配构建的 NGC/Unsloth 容器。这也是 spark-environment-setup 中ABI Rule的核心结论无论症状如何修复方式都是让 wheel 的 CUDA tag 与系统匹配。G2flash-attn——跳过 pip 构建留意 Unsloth 的自动探测症状pip install flash-attn依然失败或卡住Unsloth 还可能在你显式指定 SDPA 的情况下静默训练 flash-attn。根因裸 pip 环境下没有 aarch64/sm_121 的 flash-attn wheel但 NGC 容器自带可用的 SM121 flash-attn而 Unsloth 会自动优先使用它从而丢弃attn_implementationsdpa参数。检查python -c import flash_attn; print(flash_attn.__version__) 21 | tail -5 python -c import torch; print(torch.backends.cuda.flash_sdp_enabled())按 gotcha-checks.md G2 的记录裸 pipimport 失败是预期行为没有 aarch64/sm_121 wheel反而可以确认没有训练代码路径隐式依赖 flash-attnNGC PyTorch 容器已在nvcr.io/nvidia/pytorch:25.09-py3上验证flash-attn 2.7.4.post1 预装在 GB10capability(12, 1)上调用flash_attn_func能成功执行且输出形状正确——没有 sm_121 kernel的论断只针对自己从源码构建不适用于容器内已携带的版本真正的陷阱Unsloth 的 import 时 patch banner 报告FA2 True并自动优先 flash-attn——即使调用方显式传了attn_implementationsdpa。Unsloth 的 loaderunsloth/models/llama.py2026.7.2调用内部resolve_attention_implementation(...)时不转发调用方的requested_attn_implementation参数并直接 pop 掉该 kwarg源码里注释# No need since we auto call it。实测显式传attn_implementationsdpa后model.config._attn_implementation仍为flash_attention_2。修复裸 pip跳过 flash-attn直接使用 SDPA不用改任何代码NGC 容器唯一可靠的覆盖方式是 monkeypatch在调用from_pretrained之前执行import unsloth.models._utils as _unsloth_utils _unsloth_utils.HAS_FLASH_ATTENTION False这会迫使resolve_attention_implementation走elif supports_sdpa:分支而不是 flash-attn 分支实测 monkeypatch 后config._attn_implementation sdpa。注意绕开 Unsloth、直接用 TRL/PEFT 时传给AutoModelForCausalLM.from_pretrained的attn_implementationsdpa是会被正常尊重的——这个缺陷是 Unsloth 特有的不是 TRL/transformers 的通用问题。G3128GB 上限之下的 UMA OOM症状模型加载/训练时 OOM但nvidia-smi仍报告 128GB 上限之下有富余内存某些驱动/环境组合下甚至直接返回[N/A]而不是数字。根因safetensors 加载时 mmap 与 CUDA 分配器会对页面双重计数QLoRA 可能比 bf16更早OOM因为反量化会引入瞬时分配。检查看真实内存压力要用free -g和/proc/meminfo而不是nvidia-smifree -g cat /proc/meminfo | grep -i hugeUMA 意味着 CUDA 分配与主机 RAM 共享同一个 128GB 池而nvidia-smi只报告 CUDA 一侧。在部分驱动/环境组合下nvidia-smi --query-gpumemory.used,memory.total不是少报而是直接返回[N/A], [N/A]——据此写 headroom 检查脚本会什么都 grep 不到。这也是 spark-memory-thermal-ops 中 UMA 内存模型的核心加载模型是瞬时峰值而非稳态mmap 页与 CUDA 拷贝在同一窗口内同时占池。修复清空 page cache需要 root属于两次运行之间的重置操作绝不是训练中途的常规步骤sync echo 3 /proc/sys/vm/drop_caches注意这会在系统范围内刷新 page cache盒子上所有进程的缓存文件读取都会受影响。G4热节流症状多小时的运行中途吞吐量骤降或盒子在持续负载下自发重启。根因持续功耗上限约 100W远低于标称的 240W长任务推入这个天花板后就会降频有时直接重启。检查采样温度与功耗用-l 5每 5 秒一次至少对一个有代表性的负载观察 10–15 分钟再下结论nvidia-smi --query-gputemperature.gpu,power.draw --formatcsv -l 5按 gotcha-checks.md G4标称功耗 240W如果功耗稳定在 100W 附近而温度持续攀升或已在高位平台期盒子就是在节流。温度上升但功耗仍接近峰值还不是节流事件——继续观察。该命令不需要 rootCtrl-C 结束。修复如果功耗在 240W 之下平台化而温度持续爬升就把节流当作原因改善散热或缩短单次运行时长。不要反过来调 batch size / 精度去修复一个本就是平台正常表现的功耗平台——这一点在 spark-memory-thermal-ops 的 Thermal Monitoring 一节被反复强调持续约 100W 是平台功耗上限不是配置 bug。G5带宽天花板症状内存密集型负载——尤其是 decode-heavy 的 RL 循环——远低于预期吞吐量就进入平台期。根因273 GB/s 是规格峰值而非持续值实测带宽在 180–192 GB/s 区间。检查实测 step 时间与测量区间对比而不是与规格值对比。注意 G5 检查是侵入式的是这份检查文件里唯一不能对活跃负载运行的一项它会在 UMA 系统上分配约 4GB 并反复 clone 该 tensor在 128GB 已被其他任务占用大部分余量的盒子上可能 OOM 掉那个任务只在空闲主机上运行。python -c import torch, time x torch.randn(1_000_000_000, devicecuda, dtypetorch.float32) torch.cuda.synchronize() t0 time.time() for _ in range(20): y x.clone() torch.cuda.synchronize() dt time.time() - t0 gbps (x.numel() * 4 * 2 * 20) / dt / 1e9 print(f{gbps:.1f} GB/s) del x, y torch.cuda.empty_cache() 修复按 180–192 GB/s 做吞吐量预算如果原计划建立在 273 GB/s 的规格数字上投入排期之前务必修正。G6全局 UMA 资源争用症状进程的 KV cache/权重在运行中途被静默逐出而它自己的日志里没有任何 OOM 记录。根因统一内存是一个全局池一个未设上限或接近容量的进程会与任何其他进程竞争并可能逐出对方。小型、有界的工作负载不会——例如 4GB 的 LoRA 与gpu-memory-utilization0.5上限的 vLLM 可以共存。检查列出所有驻留 GPU 的进程nvidia-smi ps aux | grep -E vllm|ollama|python.*train | grep -v grepnvidia-smi显示每进程内存ps过滤能抓到在统一内存下可能不清晰出现在nvidia-smi输出中的推理服务vLLM、Ollama。修复single-heavy-job 规则只适用于未设上限或接近容量的工作负载——先停止或限制无关服务。实测4GB 的 LoRA 微调与--gpu-memory-utilization 0.5或更低启动的 vLLM 在同一台机器上能干净共存。判断是否要停掉另一个进程要看它的内存上限而不是只看它是否存在。G7SM121 上 NVFP4 比 FP8 更慢症状把 Spark 上的推理负载从 FP8 切到 NVFP4 反而变慢。根因除非 kernel 以sm_121a为目标编译SM121 缺少cvt.e2m1x2指令没有它 NVFP4 大约慢 32%。检查python -c import torch; print(torch.cuda.get_device_capability())GB10 上应返回(12, 1)——这确认了 SM121。SM121 没有原生的cvt.e2m1x2转换路径未针对sm_121a目标编译的 NVFP4 kernel 会回退到慢路径大约落后 FP8 32%。检查 kernel 构建的目标架构通常是TORCH_CUDA_ARCH_LIST或类似构建标志再假设 NVFP4 在这块硬件上是更快的选择。sm_121与sm_121a的差异在 stack-matrix.md 中有专门一节sm_121a是超集目标NVFP4 的原生转换指令需要它。修复除非构建目标为sm_121a否则继续用 FP8。G8官方 playbook 过时症状严格照搬官方 DGX Spark playbook 仍然失败本地配置找不到任何解释。根因官方 playbook 曾不止一次发布即损坏技术栈演进速度快于文档。检查gh issue list --repo NVIDIA/dgx-spark-playbooks --state open --limit 20需要已认证的ghCLI或用浏览器访问同 URL 替代。在按字面信任某个 recipe 跑长任务或昂贵任务之前先扫一遍 open issue 中与你遵循的 playbook 和命令相关的条目。修复信任某条 recipe 用于昂贵运行之前先查NVIDIA/dgx-spark-playbooks仓库的近期 issue。这条纪律同样写在 spark-environment-setup 与 stack-matrix.md 中——后者明确列出github.com/NVIDIA/dgx-spark-playbooks等权威资源并给出同样的告诫官方 playbook 发布过损坏版本。开始长任务之前先检查各仓库的近期 issue而不是等它失败之后。G9容器优先而非裸 pip症状昨天还好用的裸 pip 环境在一次无关的pip install之后坏掉或两个一模一样的环境行为不同。根因裸 pip 让 Triton、xformers、transformers 各自漂移没有任何机制把它们钉在 GB10 的 SM121 目标上。检查if [ -f /.dockerenv ] || [ -f /run/.containerenv ]; then echo in container (marker file) elif grep -qE (docker|containerd|kubepods) /proc/1/cgroup 2/dev/null; then echo in container (cgroup marker) else echo unknown — no container marker matched, this does not prove a bare host fi pip list 2/dev/null | grep -E ^(torch|triton|xformers|transformers) 第一段检查 Docker 的/.dockerenv与 Podman 的/run/.containerenv标记文件然后回退到 cgroup 字符串检查——单独grep docker /proc/1/cgroup并不可靠cgroup v2 布局和部分运行时/命名空间会隐藏运行时名称所以匹配失败只能算unknown永远不能证明是裸主机。第二段列出实际安装版本——裸 pip 时与 NGC 或 Unsloth 镜像中的锁定集对比尽早发现漂移而不是等到 import 时报错。修复优先使用 NGC 容器tag 选择见 spark-environment-setup 或 container-workflow.md或 Unsloth 的容器。如果确实无法避免裸 pip严格按 NVIDIA 的安装顺序执行包括对 Unsloth 使用--no-depspip 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 构建的常见路径第三行的torchao0.17.0也非可选——NGC 基础镜像自带的 torchao 对当前 peft 的 LoRA-attach 路径太老ImportError: ... torchao ... only versions above 0.16.0 are supported这是硬阻断而非警告。每个pin 都是承重的来自 stack-matrix.md 中带日期的 known-good 版本矩阵。G10双 Spark 只支持 DDP/FSDP症状跨两台 Spark 的 tensor-parallel 启动挂起、比单 Spark 慢得多、或直接报错。根因ConnectX-7 对梯度/参数同步DDP、FSDP足够快但对 TP 的细粒度流量太薄。检查确认配置的并行策略python -c import os print(WORLD_SIZE:, os.environ.get(WORLD_SIZE)) print(parallelism strategy check: confirm config uses DDP or FSDP, not TP/tensor_parallel) rg -l --iglob *.yaml --iglob *.yml -e tensor_parallel|tp_size|tensor-parallel . \ || grep -rlE tensor_parallel|tp_size|tensor-parallel --include*.yaml --include*.yml .要递归搜索而非只搜当前目录——非递归的*.yaml *.ymlglob 会漏掉嵌套配置而且被重定向/抑制的错误会读成没有 TP 配置其实可能只是目录不对。如果工作负载的配置路径已知直接显式传路径搜索即可。任何在双 Spark 任务上的匹配都是配置错误。修复双 Spark 场景选择 DDP 或 FSDP绝不用tensor parallelism——TP 在这块硬件上仅限单节点。快速分流Fast Triage跑任何其他检查之前先执行这三条最廉价的检查python3 -c import torch; print(torch.version.cuda) # 期望 13.x (G1)NGC 构建没有 cu130 tag——那不是失败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自动化预检preflight.sh[assets/preflight.sh](https://link.gitcode.com/i/710955871c13078c99bb96759828cb5f)对 G1–G10 中可自动化的子集做快速检查覆盖G1、G3、G4、G7、G9其余G2 的 flash-attn/Unsloth 覆盖检查、G6 进程普查、G8 上游 issue 查询、G10 配置审查因需要人工判断不在此脚本覆盖范围需回到 gotcha-checks.md 手动执行。用法bash preflight.sh输出契约从源码头注释可见preflight.sh L1-L13非常明确这也是下游工具能解析它的基础每一行结果都以 G 编号开头G1/G9 输出 PASS/FAIL/WARN 判定G3/G4 输出INFO:原始读数需要结合 SKILL.md 的人工判断G7 只对硬件 capability 输出 PASS/WARN——它不验证 kernel 目标架构sm_121a那一步仍需手动见 gotcha-checks.md G7无法执行时输出SKIP:如 torch 不可导入、nvidia-smi不可用、/proc/1/cgroup不可读。脚本具体行为preflight.sh L16-L49G1读取torch.version.cuda为空输出G1 SKIP: torch not importable以13开头输出G1 PASS否则G1 FAIL并提示需要 13.xG3free -g取第二行输出G3 INFO: free/used (GB): free usedG4nvidia-smi --query-gputemperature.gpu,power.draw单次快照输出G4 INFO: ...不可用时G4 SKIP: nvidia-smi not availableG7capability 等于(12, 1)输出G7 PASS附带需手动验证 sm_121a的说明否则G7 WARN: unexpected capability ...G9Docker/Podman 标记文件命中输出G9 PASS: ... marker file presentcgroup 命中输出G9 PASS: ... cgroup marker present/proc/1/cgroup可读但无匹配输出G9 UNKNOWN并明确这不证明是裸主机不可读输出G9 SKIP。在插件体系中的位置该技能不是孤立的spark-training-gotchas是dgx-spark-ops插件dgx-spark-ops-engineer 智能体 spark-preflight 命令的核心执行部分。完整预检工作流是按 spark-environment-setup 确认硬件身份GB10/aarch64/CUDA 13capability(12, 1)与栈状态运行本技能的preflight.sh自动覆盖 G1/G3/G4/G7/G9并用 gotcha-checks.md 评估其余 G2/G5/G6/G8/G10每个结论必须标注 G 编号用 spark-memory-thermal-ops 的 UMA 核算表计算负载内存余量写出env-report.jsonverdict 为ready/ready-with-warnings/blockedblocked 时先给出对应 gotcha 的 FIX 再谈其他。技能间的分工是spark-training-gotchas负责启动前的失败模式预检spark-memory-thermal-ops负责运行中的 UMA OOM 与热节流处置spark-environment-setup提供两者依赖的已被验证可工作的环境前提。三者的版本矩阵、容器 tag 与检查命令都以带日期的 known-good 快照为准——gotcha-checks.md 顶部注明Last verified: 2026-07-14CUDA、PyTorch 或 DGX Spark 栈发布新主版本时应刷新使用前请留意该日期是否已过时。【免费下载链接】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），仅供参考