DGX Spark 训练故障排障手册G1–G10 可运行检查命令与修复指南【免费下载链接】agentsMulti-harness agentic plugin marketplace for Claude Code, Codex, Cursor, OpenCode, GitHub Copilot, and Google Antigravity项目地址: https://gitcode.com/GitHub_Trending/agents24/agentsNVIDIA DGX Spark 搭载 GB10Grace BlackwellSM121aarch64 架构128GB 统一内存CUDA 13围绕启动、内存、散热、带宽与精度存在十个反复出现的故障模式。本指南以plugins/dgx-spark-ops插件的spark-training-gotchas技能中编号 G1–G10 的检查命令references/gotcha-checks.md为核心逐一给出每个故障的可运行检测命令、判定标准与修复手段并交叉印证preflight.sh自动化脚本、环境搭建与 UMA 内存/散热技能中的底层依据。读完你可以在长训练任务启动前、或运行失败时按编号快速定位根因避免第 6 小时才发现问题。背景GB10 硬件特性决定故障模式DGX Spark 的 GB10 芯片有四个打破常规硬件假设的特征十个 gotcha 全部由此派生128GB 统一内存UMAGPU 与 CPU 共享同一个内存池nvidia-smi只报告 CUDA 侧视图无法反映真实内存压力G3、G6CUDA 13 与 aarch64 生态较新PyPI 上大量 wheel 仍链接libcudart.so.12与系统 ABI 不匹配且 aarch64 CUDA 13 的 wheel 生态仍在补齐中G1、G2、G9持续功耗上限远低于额定值额定 240W持续负载下实际被压到约 100W长时间运行会触发降频甚至重启G4内存带宽为实测上限而非规格值273 GB/s 是规格天花板实测稳定在 180–192 GB/sG5。编号 G1–G10 是承重约定技能面向的工具如 preflight.sh 与 dgx-spark-ops-engineer agent按编号输出与消费检查结果任何 DGX Spark 专项诊断都必须引用其 G 编号。症状速查表#症状修复方向G1undefined symbol / 段错误使用 cu130 wheel 或匹配的容器G2flash-attn 后端被错误选用裸 pip 跳过构建NGC 容器上使用 monkeypatchG3有剩余内存仍 OOM释放 page cacheG4吞吐下降 / 重启预期持续功耗约 100W 上限G5内存受限步骤变慢按 180–192 GB/s 预算G6运行中途缓存被驱逐同一时刻只跑一个重型 GPU 任务G7NVFP4 比 FP8 更慢除非sm_121a否则保持 FP8G8playbook 直接失败先查上游 issueG9安装后环境损坏使用容器G10双 Spark TP 挂起只用 DDP/FSDP绝不用 TPG1CUDA 12/13 ABI 不匹配症状ImportError: undefined symbol报某个 CUDA 函数名或第一次.cuda()调用即段错误无有效 traceback。原因大部分 PyPI wheel 链接libcudart.so.12而 Spark 出厂自带 CUDA 13。pip 的解析器只检查版本约束、从不检查 CUDA ABI所以问题要到 import 或首次 kernel 启动时才暴露。检查命令见 gotcha-checks.md G1python3 -c import torch; print(torch.version.cuda) python -c import ctypes; ctypes.CDLL(libcudart.so.13) ldconfig -p | grep libcudart判定要点torch.version.cuda是权威信号应报告13.x不要依赖pip show torch | grep cu130NGC 容器如nvcr.io/nvidia/pytorch:25.11-py3内部针对 CUDA 13 构建 torch、不带cu130wheel tag因此该命令查不到cu130本身不构成失败ctypes加载用于确认libcudart.so.13确实存在于系统中若抛出OSError问题出在驱动/运行时安装而非 wheelldconfig -p列出所有已注册的 CUDA 运行时版本——libcudart.so.12与libcudart.so.13并存是早期安装留下的常见残留也是 ABI 不匹配的最可能来源。修复从download.pytorch.org/whl/cu130重装cu130 标签的 aarch64 构建或改用已内建匹配构建的容器。更完整的五假设排查顺序运行时/标志 → 设备可见性 → 权限 → CUDA init 状态 → ABI见 stack-matrix.md其中 ABI 是唯一一个 wheel 重装能解决的假设应在排除前四项之后再动 wheel。G2flash-attn——跳过 pip 构建警惕 Unsloth 的自动探测症状pip install flash-attn依旧失败或挂起或显式请求 SDPA 后 Unsloth 仍静默用 flash-attn 训练。检查命令见 gotcha-checks.md G2python -c import flash_attn; print(flash_attn.__version__) 21 | tail -5 python -c import torch; print(torch.backends.cuda.flash_sdp_enabled())判定要点不要假设 import 一定失败取决于环境裸 pip 环境import 失败是预期行为——不存在 aarch64/sm_121 wheel这恰好证明没有任何训练代码路径静默依赖 flash-attnNGC PyTorch 容器已在nvcr.io/nvidia/pytorch:25.09-py3上确认flash-attn 2.7.4.post1 预置GB10能力(12, 1)上实际调用flash_attn_funckernel 成功且输出形状正确——没有 sm_121 kernel的说法只适用于自己从源码构建不适用于容器已携带的构建。真正的陷阱容器内 flash-attn 存在时Unsloth 的 import 时补丁横幅报告FA2 True并自动优先选择 flash-attn 而非 SDPA——即使调用方显式传了attn_implementationsdpa。Unsloth 的 loaderunsloth/models/llama.py2026.7.2调用其内部resolve_attention_implementation(...)时没有把调用方的attn_implementation作为该函数的requested_attn_implementation参数转发随后用# No need since we auto call it注释直接弹出该 kwarg静默丢弃调用方请求。已通过真实加载确认显式传入attn_implementationsdpa仍解析为model.config._attn_implementation flash_attention_2。该 Unsloth 版本上唯一可靠的覆盖方式针对任何经由 Unsloth llama 架构 loader 路由的模型且 flash-attn 可导入时是在调用from_pretrained前打 monkeypatchimport 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。而在纯 TRL/PEFT 路径完全绕过 Unsloth下AutoModelForCausalLM.from_pretrained显式传入的attn_implementationsdpa会被正确遵守——该缺陷是 Unsloth 特有的不是 TRL/transformers 的通用问题。G3UMA OOM——内存低于 128GB 就失败症状模型加载/训练期间 OOM而nvidia-smi仍报告 128GB 上限之下有剩余内存某些驱动/配置组合下干脆返回[N/A]。原因统一内存下 mmap 与 CUDA allocator 在 safetensors 加载期间双重计数页面QLoRA 的 bitsandbytes 反量化会产生瞬时分配可能比 bf16 更早 OOM。检查命令见 gotcha-checks.md G3free -g cat /proc/meminfo | grep -i huge判定要点真实内存压力读free -g不是nvidia-smi——UMA 下 CUDA 分配与主机 RAM 共享一个池nvidia-smi只报 CUDA 侧某些驱动/设置组合下nvidia-smi --query-gpumemory.used,memory.total --formatcsv不只是少报而是整个 GPU 内存查询直接返回[N/A], [N/A]。在这种硬件上据此 grep 数字的脚本什么都拿不到而不是拿到误导数字——不要把余量检查建在该查询上若负载失败时free -g显示 128GB 已被消耗大半回收内存sync echo 3 /proc/sys/vm/drop_caches需要 root且会系统级刷新 page cache——机器上所有进程不只是训练任务都会失去缓存的文件读取。应在两次运行之间、内存看起来被陈旧 mmap 页钉住时执行不要作为训练中的例行步骤。G4热降频Thermal Throttling症状多小时运行中途吞吐下降或持续负载下机器自发重启。原因持续功耗被压在约 100W相对额定 240W长时间运行推入该上限后降频极端情况下重启。检查命令见 gotcha-checks.md G4nvidia-smi --query-gputemperature.gpu,power.draw --formatcsv -l 5判定要点-l 5表示每 5 秒采样一次在代表性负载上至少连续运行 10–15 分钟再下结论额定功耗 240W若功耗在约 100W 处持平、而温度持续攀升或已在高位持平说明机器在降频温度上升但功耗仍接近峰值尚不是降频事件——继续观察完成时 Ctrl-C 中断即可此命令不需要 root。G5带宽天花板Bandwidth Ceiling症状内存受限负载尤其是 decode 密集的 RL 循环吞吐远低于预期。原因273 GB/s 是规格天花板而非持续可达值实测带宽在 180–192 GB/s。检查命令见 gotcha-checks.md G5注意本检查是侵入性的与本文其他检查不同——不要在活跃负载上运行。它在 UMA 系统上分配约 4GBGPU 与主机内存共享一个池并反复 clone 该张量。只在空闲主机上运行如果机器上已有任务占用了 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-utilization 0.5或更低启动的 vLLM 在同一台机器上和平共存。检查命令见 gotcha-checks.md G6nvidia-smi ps aux | grep -E vllm|ollama|python.*train | grep -v grep判定要点启动长任务前列出每个 GPU 常驻进程。nvidia-smi显示每个进程的内存ps过滤能抓住 vLLM、Ollama 等推理服务——它们在统一内存下可能不会清晰出现在nvidia-smi输出里一次一个重型任务规则适用于未设上限或接近容量的负载在需要完整 128GB 池、或与另一个未显式设内存上限的进程并行前先停掉无关服务该规则不适用于小型、设了内存上限的共存——判断是否需要停止某进程前检查的是对方进程自身的内存上限而不只是它存在。G7SM121 上 NVFP4 反而比 FP8 慢症状把推理负载从 FP8 切换到 NVFP4 后更慢而非更快。原因SM121 缺少原生cvt.e2m1x2转换路径未针对sm_121a目标编译的 NVFP4 kernel 会退回较慢路径约比 FP8 慢 32%。检查命令见 gotcha-checks.md G7python -c import torch; print(torch.cuda.get_device_capability())判定要点GB10 上应输出(12, 1)——确认 SM121。在假设 NVFP4 是本硬件上的更快选择之前先检查 kernel 构建的目标架构通常是TORCH_CUDA_ARCH_LIST或类似构建标志。sm_121与sm_121a的区别详见 stack-matrix.md 的 sm_121 vs sm_121a 一节NVFP4 原生cvt.e2m1x2需要sm_121a超集目标。G8官方 Playbook 过时症状照抄官方 DGX Spark playbook 仍然失败本地配置查不出原因。原因官方 playbook 曾出现过发布即损坏的情况堆栈演进速度快于文档。检查命令见 gotcha-checks.md G8gh issue list --repo NVIDIA/dgx-spark-playbooks --state open --limit 20需要已认证的ghCLI或用浏览器访问同一 URL 代替。在把某个 playbook 及其命令原样用于长时或昂贵运行之前先扫一遍 open issues 确认其未受影响。这一点在 stack-matrix.md 与 spark-environment-setup SKILL.md 中同样被列为标准 preflight 步骤。G9容器优先而非裸 pip症状昨天还能用的裸 pip 环境在一次无关的pip install后损坏或两个相同环境表现不同。原因裸 pip 让 Triton、xformers、transformers 各自漂移没有任何机制把它们钉在 GB10 的 SM121 目标上。检查命令见 gotcha-checks.md G9if [ -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 时才暴露。容器优先的根本原因是钉定而非便利Triton、xformers、transformers 与 GB10 的 SM121 目标和 CUDA 13 的交互很狭窄容器把三者锁在与本硬件已验证的组合上。NGC 容器启动方式含--runtimenvidia --gpus all、--ipchost与 memlock ulimit 等标志见 container-workflow.md。若确实无法避免裸 pip必须严格按 NVIDIA playbook 顺序安装包括 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与最后的torchao升级行都是不可省略的前者避免 pip 在 aarch64 上重新解析出不兼容的 torch/triton 构建后者因为 NGC 基础镜像自带的torchao过旧低于 0.16.0 会直接ImportError。完整版本矩阵见 stack-matrix.md 的 Known-Good Version Matrix。G10双 Spark 只能用 DDP/FSDP症状跨两台 Spark 做张量并行TP启动时挂起、比单机明显更慢或直接报错。原因ConnectX-7 对梯度/参数同步DDP、FSDP足够快但对 TP 的细粒度通信来说带宽太薄。检查命令见 gotcha-checks.md G10python -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 任务中任何匹配项都是配置错误——启动前切到 DDP 或 FSDP在本硬件的 ConnectX-7 链路上 TP 不可行。自动化preflight.sh 一键执行 G1/G3/G4/G7/G9preflight.sh 是 G1–G10 检查中可自动化子集的实现输出契约固定每行结果以 G 编号开头。运行方式bash assets/preflight.sh行为说明直接来自脚本头部注释与实现G1读取torch.version.cuda以13*前缀判定输出G1 PASS/FAIL/SKIPG3free -g的原始读数输出G3 INFO: free/used (GB): ...需人工判断参考 SKILL.md G3G4nvidia-smi --query-gputemperature.gpu,power.draw快照输出G4 INFO: ...nvidia-smi不可用时输出G4 SKIPG7torch.cuda.get_device_capability()是否为(12, 1)输出G7 PASS/WARN——注意它不验证 kernel 目标架构sm_121a该步保持人工检查G9容器标记文件 cgroup 回退检查输出G9 PASS/UNKNOWN/SKIPUNKNOWN 分支明确提示这不证明是裸主机。不可自动化的 gotchaG2 的 flash-attn 存在性/Unsloth 覆盖检查、G6 进程调查、G8 上游 issue 查询、G10 配置审查不在脚本内需按本指南对应小节人工执行。这套检查与 spark-environment-setup环境准备、ABI 规则、容器优先、spark-memory-thermal-ops运行期 UMA 与散热管理含 OOM Ladder 与内存核算表 uma-accounting.md共同构成完整的 DGX Spark 运维闭环dgx-spark-ops-engineer agent 按 spark-preflight 命令 的流程先跑 preflight再以pass/fail/warn/skip/info词汇逐项记录并输出env-report.json最终给出ready / ready-with-warnings / blocked三档结论。快速分诊跑这 3 条再看其他在深入任何一项之前先跑成本最低的三个检查同样列于 SKILL.md 的 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三条命令分别锁定 ABI、硬件身份与容器姿态三个最基础的变量其中任何一条失败都会让后续所有检查失去意义。全部通过后再按症状速查表定位到具体的 G 编号执行对应的检查命令并始终以该编号的 FIX 条目为准完成修复。【免费下载链接】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），仅供参考