DGX Spark ML 环境组件矩阵实战GB10/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/references/stack-matrix.md为主体系统梳理 NVIDIA DGX SparkGB10 Grace Blackwell、SM121、aarch64、CUDA 13平台上 ML 训练/推理栈的组件兼容状态、已知可用版本矩阵、GPU 检测假阴性的逐假设排查流程以及 sm_121 与 sm_121a 的架构差异。读完本文你将掌握在此平台上选择 PyTorch/Unsloth/Triton/vLLM 等组件、钉定版本组合、定位 CUDA ABI 故障与设备不可见问题的完整方法并能直接复用仓库中现成的验证命令。一、为什么 DGX Spark 需要一份组件矩阵DGX Spark 搭载 GB10 Grace Blackwell 芯片aarch64 CPU、SM121 GPU、128GB 统一内存UMA、CUDA 13 运行时。与常见的 x86 CUDA 12 平台相比这是一个更窄、更年轻的目标平台——aarch64 CUDA 13的 wheel 生态仍在补全过程中pip 的版本解析器只检查版本约束、不检查 CUDA ABI因此装上了但跑不起来是常态而非例外。stack-matrix.md正是为这一现实而生的逐组件状态明细表它是SKILL.md中Component Quick Table的展开版记录每个组件在当前平台上的可用性、获取渠道、构建参数与已知陷阱。其头部标注Last verified: 2026-07-14并明确要求在CUDA、PyTorch 或 Unsloth 发布新的大版本时刷新——这份矩阵是有时效性的快照不是永久承诺。在进入明细之前先记住整个spark-environment-setupskill 的总纲见 SKILL.md匹配容器/wheel 组合到 CUDA 13 与 SM121不要与 ABI 对抗。矩阵中的每一行都是这一原则的具体化。二、逐组件状态矩阵可用性、渠道与陷阱下表完整复刻原文档的组件状态并结合仓库内 SKILL.md 与 container-workflow.md 的细节逐项展开。组件状态说明PyTorchcu130, aarch64✅官方 wheel 位于download.pytorch.org/whl/cu130与系统 CUDA 13 ABI 匹配bitsandbytes✅0.48 开箱即用Triton✅需环境变量必须设置TRITON_PTXAS_PATH/usr/local/cuda/bin/ptxas否则内核编译找不到ptxasflash-attn❌ 跳过尚无 sm_121 内核可用或可编译该硬件上 PyTorch 的 SDPA 后端反而更快xformers仅源码构建无 aarch64/SM121 预编译 wheel构建时需设TORCH_CUDA_ARCH_LIST12.1否则会编译到错误架构vLLM仅 nightly wheel使用wheels.vllm.ai/nightly/cu130SM121 修复约在 2026-06 进入 nightly 通道stable/release wheel 早于此修复TransformerEngine / NVFP4 训练仅容器裸 pip 不现实使用 NGC PyTorch 容器NVFP4BlockScaling面向 SM100SM121 支持仅属可商用但未保证Unsloth✅推荐容器官方镜像unsloth/unsloth:dgxspark-latestmoving tag需解析并钉住 digest裸 pip 可能踩中 torchcodec 与 GPU 检测问题Axolotl / TRL / PEFT✅标准安装无需特殊处理LLaMA-Factory / NeMo脆弱 / 进行中该平台已知不可靠依赖前务必检查上游 issue2.1 PyTorch认准 cu130 通道矩阵要求从download.pytorch.org/whl/cu130拉取 aarch64 构建。这正是 SKILL.md 中ABI Rule的落点PyPI 上多数 torch wheel 链接libcudart.so.12而 Spark 系统只有libcudart.so.13装完必炸。需要特别留意的是NGC 容器内构建的 torch 不携带cu130wheel 标签如nvcr.io/nvidia/pytorch:25.09-py3内置 torch2.9.0a050eac811a6.nv25.09、CUDA 13.0因此pip show torch里看不到cu130并不代表失败——判断 ABI 的权威信号是torch.version.cuda以13开头详见第四节。2.2 Triton一个环境变量的事Triton 在裸 pip 下可用但内核编译阶段需要找到ptxas。若训练启动时 Triton 内核编译失败设置并重试export TRITON_PTXAS_PATH/usr/local/cuda/bin/ptxas矩阵与 SKILL.md 的 Verification Commands 均记录了这条 workaround。2.3 flash-attn明确跳过 pip 构建矩阵的结论很直接不要在裸 pip 上浪费时间追 flash-attn 构建——没有 sm_121 内核也暂时不可构建。且 PyTorch 的 SDPA 后端在这块硬件上更快。需要补充的上下文是这个无 sm_121 内核的说法仅适用于自行构建。在 NGC PyTorch 容器25.09-py3上验证过中flash-attn 2.7.4.post1 是预置的flash_attn_func内核在 GB10capability(12, 1)上可正常执行。真正需要警惕的是容器场景下 Unsloth 的自动检测会覆盖显式指定的attn_implementationsdpa详见 gotcha-checks.md G2。2.4 xformers源码构建必须指定架构无预编译 aarch64/SM121 wheel。源码构建时必须设置TORCH_CUDA_ARCH_LIST12.1不设置的话构建会面向错误架构结果要么直接失败要么静默产出不可用的内核——第二种情况比失败更难排查。2.5 vLLM只用 nightly 通道SM121 的修复大约在 2026-06 才进入 nightly 通道stable/release wheel 都早于此。因此pip install vllm --pre --extra-index-url https://wheels.vllm.ai/nightly/cu130具体安装方式以官方 nightly 通道说明为准这里强调的核心事实是不要在 stable 通道上找 SM121 支持。2.6 TransformerEngine / NVFP4 训练容器专属通过裸 pip 安装 TransformerEngine 在此平台上不现实。使用 NGC PyTorch 容器。另需注意NVFP4BlockScaling的设计目标架构是 SM100对 SM121 的支持应视为有条件的、未保证的不要默认可用。2.7 Unsloth容器优先裸 pip 有坑官方 Docker 镜像unsloth/unsloth:dgxspark-latest是moving tag——直接按 tag 运行只适合做发现性验证任何可复现/CI 场景都应先解析并钉住其 digest完整 pull→inspect→pin 流程见 container-workflow.md# 1. 发现步骤拉取 moving tag 并确认能启动 docker pull unsloth/unsloth:dgxspark-latest # 2. 将 tag 解析为当前 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镜像内置了已经针对该硬件验证过的 Triton/xformers/transformers 组合。若走裸 pip则需完整复刻 NVIDIA playbook 的安装序列见下一节裸 pip 曾踩中 torchcodec 与 GPU 检测相关的坑。2.8 其余组件Axolotl / TRL / PEFT 走标准安装即可无特殊处理。而LLaMA-Factory 与 NeMo 在平台上已知不可靠把它俩纳入依赖链之前先去上游 issue 区确认当前状态不要默认可用。三、已知可用版本矩阵一份带日期的快照矩阵接下来给出的是一份已验证可用的版本组合。它存在的直接原因值得展开SKILL.md的裸 pip 序列之所以显式钉住datasets/trl是因为一条未钉版本的安装命令pip install transformers peft hf_transfer datasets trl accelerate会解析出当前 PyPI 上的最新transformers/trl/datasets——这些版本很可能超出某个 Unsloth 发行版声明的支持范围而 pip 会照装不误只在事后给出警告。已验证可用组合截至Last verified: 2026-07-14在nvcr.io/nvidia/pytorch:25.09-py3上完成端到端验证bf16 LoRA 加载 挂载 完整 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当前 stable依赖前先读下文弃用说明对应到 SKILL.md 中的可执行安装序列每条钉定都是承重的顺序不可打乱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这不是警告是硬阻塞。若裸 pip 安装落到的组合与上表不一致pip resolver 漂移在新版本发布后是可预期的在信任环境前务必重跑 SKILL.md Verification Commands 中的 loadLoRA-attach 冒烟测试并用gh issue list --repo NVIDIA/dgx-spark-playbooks核对是否已有匹配症状的版本错配报告。3.1 hf_transfer 弃用迁移到 HF_XET_HIGH_PERFORMANCE矩阵明确记录了一个迁移节点HF_HUB_ENABLE_HF_TRANSFER在huggingface_hub1.23 已被弃用。现在设置它只会得到FutureWarning: The HF_HUB_ENABLE_HF_TRANSFER environment variable is deprecated ... Please use HF_XET_HIGH_PERFORMANCE instead下载会无视该变量改走 Xet 通道且依然成功、依然快。这对旧文档/旧配方是一个语义警示仍引用hf_transfer环境变量设置的陈旧指令应理解为让下载变快的意图而非字面 API 要求。在huggingface_hub1.23 上应改为设置export HF_XET_HIGH_PERFORMANCE1四、GPU 检测假阴性逐假设排查手册矩阵给出了 SKILL.md Verification Commands 中假设表的完整判别流程共五个假设必须按以下顺序逐个排查——因为其中只有第 5 项能靠重装 wheel 修复跳过前四项直接重装是在浪费一个完整排查周期。验证环境是否真的能看到 GPU 的基准命令import torch print(torch.cuda.is_available(), torch.version.cuda)预期输出单行bool cuda-versionTrue 13.0若输出False按以下顺序排查假设 1运行时/启动参数Runtime/flags如果docker run缺少--runtimenvidia --gpus all那么容器内运行nvidia-smi会失败或显示无设备而宿主侧看 GPU 完全正常。# 修复两条 flag 一起带上 docker run --runtimenvidia --gpus all ...注意 container-workflow.md 对完整调用的补充--ipchost --ulimit memlock-1 --ulimit stack67108864用于避免 PyTorch DataLoader 工作进程的共享内存饥饿-v $(pwd)/finetuning:/workspace/finetuning让 checkpoint 与日志落在宿主文件系统而非临时容器层--rm会在退出时删除容器内一切未挂载出去的内容。假设 2设备可见性Device visibilityecho $CUDA_VISIBLE_DEVICES两种情况都会隐藏全部/部分设备显式设置为空字符串注意是显式设置而非未设置会隐藏所有设备过期的索引如单 GPU 机器上残留1会隐藏唯一存在的设备。修复unset CUDA_VISIBLE_DEVICES或将其设为0。假设 3权限Permissionsls -l /dev/nvidia*缺失条目或读取时Permission denied说明容器/用户无法打开设备节点——常见于 rootless 运行或受限的 seccomp/AppArmor profile。修复与宿主的 device-cgroup 规则对齐或不要在 GPU 工作负载上使用 rootless 运行。假设 4CUDA 初始化状态CUDA init state先前在内核中途崩溃的进程可能把驱动对该进程树的 CUDA context 卡死。在全新 shell 或全新启动的容器而非同一 shell 里的新 Python 进程中重试能以最低成本排除此项然后再去怀疑更深层的问题。假设 5ABI 不匹配ABI mismatch通常的元凶这是最后一个假设而不是第一个python3 -c import torch; print(torch.version.cuda)输出不以13开头即确认一个链接了libcudart.so.12的 wheel 被装到了仅提供 CUDA 13 的系统上——参见 SKILL.md 的 ABI Rule。五项中只有这一项能靠 wheel 重装修复在排除 1-4 之前就重装如果真实原因是 flag、环境变量或权限结果不会改变只是白费一轮。矩阵还提示在这块硬件上torchcodec/驱动交互是 (5) 最常被报告的实例——动手前先用gh issue list --repo NVIDIA/dgx-spark-playbooks查当前报告不要假设自己遇到了全新原因。4.1 配套的自动化子集preflight.sh仓库提供的 preflight.sh 可以自动化执行上述检查的子集G1/G3/G4/G7/G9输出契约是每行以 G-number 开头与spark-training-gotchas的 G1–G10 编号体系对齐G1torch.version.cuda是否以13开头对应本节假设 5PASS/FAIL/SKIPG3free -g输出 UMA 余量原始读数INFO 行G4nvidia-smi温/功耗快照INFO 行G7torch.cuda.get_device_capability()是否为(12, 1)PASS/WARNG9通过/.dockerenv、/run/.containerenv与 cgroup 标记判定容器/裸机姿态PASS/UNKNOWN/SKIP。注意 G7 只确认硬件能力不验证内核目标架构sm_121a后者需按 gotcha-checks.md G7 手动核查构建 flag。G2/G6/G8/G10 因无法自动化需按该文件的命令人工执行。五、sm_121 与 sm_121a一个字母的架构差异GB10 的 GPU 标识为sm_121。但部分较新的内核特性——尤其是 NVFP4 的原生cvt.e2m1x2转换指令——需要按sm_121asm_121的超集目标编译的代码而不是普通sm_121。由此产生一个可复现的性能规律如果 NVFP4 推理在这块硬件上比 FP8 慢约 32%原因很可能就在这里——内核没有用带a变体编译。行动要点检查所用 wheel/容器的构建 flag常见于TORCH_CUDA_ARCH_LIST一类变量在把锅甩给硬件之前先确认内核目标架构。对照检查命令来自 gotcha-checks.md G7python -c import torch; print(torch.cuda.get_device_capability())GB10 上预期输出(12, 1)确认 SM121。它与spark-training-gotchas的 G7 完全对应除非构建目标为sm_121a否则在 Spark 上坚持用 FP8NVFP4 不会更快。六、权威资源与使用纪律矩阵最后列出 Canonical resources作为文档记录的参考清单均为公开仓库/页面名github.com/NVIDIA/dgx-spark-playbooks官方 playbook 主仓库build.nvidia.com/spark/unslothgithub.com/natolambert/dgx-spark-setupgithub.com/albond/DGX_Spark_Unsloth_Lossless_Speedupgithub.com/NvMayMay/nvfp4-lora-spark文档给出了一条重要的使用纪律官方 playbook 曾经发过坏版本。在开始长任务之前检查每个仓库的近期 issue而不是等失败后再查。这条纪律在 SKILL.md 中被列为正式 preflight 步骤在 gotcha-checks.md G8 中给出可执行命令gh issue list --repo NVIDIA/dgx-spark-playbooks --state open --limit 20七、把矩阵用起来完整决策与验证工作流综合本文内容与配套仓库文件一次规范的 DGX Spark 环境搭建与验证流程如下平台身份确认来自 dgx-spark-ops-engineer.mdnvidia-smi、uname -m预期aarch64、torch.cuda.get_device_capability()预期(12, 1)。任何一项不匹配后续所有检查都失去意义。容器优先决策SKILL.md 的 Container-First Rule通用训练/推理用nvcr.io/nvidia/pytorch:25.09-py3Unsloth 微调用unsloth/unsloth:dgxspark-latest先解析并钉 digest两者都不适用自定义系统包、本地 IDE 解释器才走裸 pip并严格按第三节序列执行。GPU 可见性验证容器启动后立刻运行第四节基准命令预期True 13.0若为False按五个假设顺序排查运行时 flag → 设备可见性 → 权限 → CUDA 初始化状态 → ABI重装 wheel 只在确认 ABI 后执行。版本组合核验裸 pip 场景对照第三节已知可用版本矩阵运行bash assets/preflight.sh见 preflight.sh获取 G1/G3/G4/G7/G9 的自动化判定其余 gotcha 按 gotcha-checks.md 手动执行。上游状态检查长任务前查各权威资源仓库的近期 issue第六节避免复现官方 playbook 已报告的坏版本。环境保鲜矩阵头部日期2026-07-14即下一次复审的触发点CUDA、PyTorch 或 Unsloth 任一发布大版本就重新验证并更新这份矩阵。这套流程把组件矩阵从一份静态表格变成了可操作的环境健康检查闭环——这也正是它在dgx-spark-ops插件中作为 SKILL.md 的细节表存在的意义快速决策看 SKILL.md 的 Quick Table深挖原因看 stack-matrix落地执行看 container-workflow故障复现看 gotcha-checks。【免费下载链接】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），仅供参考 DGX Spark ML 环境组件矩阵实战：GB10/CUDA 13 平台上的版本兼容与 ABI 排查指南
DGX Spark ML 环境组件矩阵实战GB10/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/references/stack-matrix.md为主体系统梳理 NVIDIA DGX SparkGB10 Grace Blackwell、SM121、aarch64、CUDA 13平台上 ML 训练/推理栈的组件兼容状态、已知可用版本矩阵、GPU 检测假阴性的逐假设排查流程以及 sm_121 与 sm_121a 的架构差异。读完本文你将掌握在此平台上选择 PyTorch/Unsloth/Triton/vLLM 等组件、钉定版本组合、定位 CUDA ABI 故障与设备不可见问题的完整方法并能直接复用仓库中现成的验证命令。一、为什么 DGX Spark 需要一份组件矩阵DGX Spark 搭载 GB10 Grace Blackwell 芯片aarch64 CPU、SM121 GPU、128GB 统一内存UMA、CUDA 13 运行时。与常见的 x86 CUDA 12 平台相比这是一个更窄、更年轻的目标平台——aarch64 CUDA 13的 wheel 生态仍在补全过程中pip 的版本解析器只检查版本约束、不检查 CUDA ABI因此装上了但跑不起来是常态而非例外。stack-matrix.md正是为这一现实而生的逐组件状态明细表它是SKILL.md中Component Quick Table的展开版记录每个组件在当前平台上的可用性、获取渠道、构建参数与已知陷阱。其头部标注Last verified: 2026-07-14并明确要求在CUDA、PyTorch 或 Unsloth 发布新的大版本时刷新——这份矩阵是有时效性的快照不是永久承诺。在进入明细之前先记住整个spark-environment-setupskill 的总纲见 SKILL.md匹配容器/wheel 组合到 CUDA 13 与 SM121不要与 ABI 对抗。矩阵中的每一行都是这一原则的具体化。二、逐组件状态矩阵可用性、渠道与陷阱下表完整复刻原文档的组件状态并结合仓库内 SKILL.md 与 container-workflow.md 的细节逐项展开。组件状态说明PyTorchcu130, aarch64✅官方 wheel 位于download.pytorch.org/whl/cu130与系统 CUDA 13 ABI 匹配bitsandbytes✅0.48 开箱即用Triton✅需环境变量必须设置TRITON_PTXAS_PATH/usr/local/cuda/bin/ptxas否则内核编译找不到ptxasflash-attn❌ 跳过尚无 sm_121 内核可用或可编译该硬件上 PyTorch 的 SDPA 后端反而更快xformers仅源码构建无 aarch64/SM121 预编译 wheel构建时需设TORCH_CUDA_ARCH_LIST12.1否则会编译到错误架构vLLM仅 nightly wheel使用wheels.vllm.ai/nightly/cu130SM121 修复约在 2026-06 进入 nightly 通道stable/release wheel 早于此修复TransformerEngine / NVFP4 训练仅容器裸 pip 不现实使用 NGC PyTorch 容器NVFP4BlockScaling面向 SM100SM121 支持仅属可商用但未保证Unsloth✅推荐容器官方镜像unsloth/unsloth:dgxspark-latestmoving tag需解析并钉住 digest裸 pip 可能踩中 torchcodec 与 GPU 检测问题Axolotl / TRL / PEFT✅标准安装无需特殊处理LLaMA-Factory / NeMo脆弱 / 进行中该平台已知不可靠依赖前务必检查上游 issue2.1 PyTorch认准 cu130 通道矩阵要求从download.pytorch.org/whl/cu130拉取 aarch64 构建。这正是 SKILL.md 中ABI Rule的落点PyPI 上多数 torch wheel 链接libcudart.so.12而 Spark 系统只有libcudart.so.13装完必炸。需要特别留意的是NGC 容器内构建的 torch 不携带cu130wheel 标签如nvcr.io/nvidia/pytorch:25.09-py3内置 torch2.9.0a050eac811a6.nv25.09、CUDA 13.0因此pip show torch里看不到cu130并不代表失败——判断 ABI 的权威信号是torch.version.cuda以13开头详见第四节。2.2 Triton一个环境变量的事Triton 在裸 pip 下可用但内核编译阶段需要找到ptxas。若训练启动时 Triton 内核编译失败设置并重试export TRITON_PTXAS_PATH/usr/local/cuda/bin/ptxas矩阵与 SKILL.md 的 Verification Commands 均记录了这条 workaround。2.3 flash-attn明确跳过 pip 构建矩阵的结论很直接不要在裸 pip 上浪费时间追 flash-attn 构建——没有 sm_121 内核也暂时不可构建。且 PyTorch 的 SDPA 后端在这块硬件上更快。需要补充的上下文是这个无 sm_121 内核的说法仅适用于自行构建。在 NGC PyTorch 容器25.09-py3上验证过中flash-attn 2.7.4.post1 是预置的flash_attn_func内核在 GB10capability(12, 1)上可正常执行。真正需要警惕的是容器场景下 Unsloth 的自动检测会覆盖显式指定的attn_implementationsdpa详见 gotcha-checks.md G2。2.4 xformers源码构建必须指定架构无预编译 aarch64/SM121 wheel。源码构建时必须设置TORCH_CUDA_ARCH_LIST12.1不设置的话构建会面向错误架构结果要么直接失败要么静默产出不可用的内核——第二种情况比失败更难排查。2.5 vLLM只用 nightly 通道SM121 的修复大约在 2026-06 才进入 nightly 通道stable/release wheel 都早于此。因此pip install vllm --pre --extra-index-url https://wheels.vllm.ai/nightly/cu130具体安装方式以官方 nightly 通道说明为准这里强调的核心事实是不要在 stable 通道上找 SM121 支持。2.6 TransformerEngine / NVFP4 训练容器专属通过裸 pip 安装 TransformerEngine 在此平台上不现实。使用 NGC PyTorch 容器。另需注意NVFP4BlockScaling的设计目标架构是 SM100对 SM121 的支持应视为有条件的、未保证的不要默认可用。2.7 Unsloth容器优先裸 pip 有坑官方 Docker 镜像unsloth/unsloth:dgxspark-latest是moving tag——直接按 tag 运行只适合做发现性验证任何可复现/CI 场景都应先解析并钉住其 digest完整 pull→inspect→pin 流程见 container-workflow.md# 1. 发现步骤拉取 moving tag 并确认能启动 docker pull unsloth/unsloth:dgxspark-latest # 2. 将 tag 解析为当前 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镜像内置了已经针对该硬件验证过的 Triton/xformers/transformers 组合。若走裸 pip则需完整复刻 NVIDIA playbook 的安装序列见下一节裸 pip 曾踩中 torchcodec 与 GPU 检测相关的坑。2.8 其余组件Axolotl / TRL / PEFT 走标准安装即可无特殊处理。而LLaMA-Factory 与 NeMo 在平台上已知不可靠把它俩纳入依赖链之前先去上游 issue 区确认当前状态不要默认可用。三、已知可用版本矩阵一份带日期的快照矩阵接下来给出的是一份已验证可用的版本组合。它存在的直接原因值得展开SKILL.md的裸 pip 序列之所以显式钉住datasets/trl是因为一条未钉版本的安装命令pip install transformers peft hf_transfer datasets trl accelerate会解析出当前 PyPI 上的最新transformers/trl/datasets——这些版本很可能超出某个 Unsloth 发行版声明的支持范围而 pip 会照装不误只在事后给出警告。已验证可用组合截至Last verified: 2026-07-14在nvcr.io/nvidia/pytorch:25.09-py3上完成端到端验证bf16 LoRA 加载 挂载 完整 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当前 stable依赖前先读下文弃用说明对应到 SKILL.md 中的可执行安装序列每条钉定都是承重的顺序不可打乱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这不是警告是硬阻塞。若裸 pip 安装落到的组合与上表不一致pip resolver 漂移在新版本发布后是可预期的在信任环境前务必重跑 SKILL.md Verification Commands 中的 loadLoRA-attach 冒烟测试并用gh issue list --repo NVIDIA/dgx-spark-playbooks核对是否已有匹配症状的版本错配报告。3.1 hf_transfer 弃用迁移到 HF_XET_HIGH_PERFORMANCE矩阵明确记录了一个迁移节点HF_HUB_ENABLE_HF_TRANSFER在huggingface_hub1.23 已被弃用。现在设置它只会得到FutureWarning: The HF_HUB_ENABLE_HF_TRANSFER environment variable is deprecated ... Please use HF_XET_HIGH_PERFORMANCE instead下载会无视该变量改走 Xet 通道且依然成功、依然快。这对旧文档/旧配方是一个语义警示仍引用hf_transfer环境变量设置的陈旧指令应理解为让下载变快的意图而非字面 API 要求。在huggingface_hub1.23 上应改为设置export HF_XET_HIGH_PERFORMANCE1四、GPU 检测假阴性逐假设排查手册矩阵给出了 SKILL.md Verification Commands 中假设表的完整判别流程共五个假设必须按以下顺序逐个排查——因为其中只有第 5 项能靠重装 wheel 修复跳过前四项直接重装是在浪费一个完整排查周期。验证环境是否真的能看到 GPU 的基准命令import torch print(torch.cuda.is_available(), torch.version.cuda)预期输出单行bool cuda-versionTrue 13.0若输出False按以下顺序排查假设 1运行时/启动参数Runtime/flags如果docker run缺少--runtimenvidia --gpus all那么容器内运行nvidia-smi会失败或显示无设备而宿主侧看 GPU 完全正常。# 修复两条 flag 一起带上 docker run --runtimenvidia --gpus all ...注意 container-workflow.md 对完整调用的补充--ipchost --ulimit memlock-1 --ulimit stack67108864用于避免 PyTorch DataLoader 工作进程的共享内存饥饿-v $(pwd)/finetuning:/workspace/finetuning让 checkpoint 与日志落在宿主文件系统而非临时容器层--rm会在退出时删除容器内一切未挂载出去的内容。假设 2设备可见性Device visibilityecho $CUDA_VISIBLE_DEVICES两种情况都会隐藏全部/部分设备显式设置为空字符串注意是显式设置而非未设置会隐藏所有设备过期的索引如单 GPU 机器上残留1会隐藏唯一存在的设备。修复unset CUDA_VISIBLE_DEVICES或将其设为0。假设 3权限Permissionsls -l /dev/nvidia*缺失条目或读取时Permission denied说明容器/用户无法打开设备节点——常见于 rootless 运行或受限的 seccomp/AppArmor profile。修复与宿主的 device-cgroup 规则对齐或不要在 GPU 工作负载上使用 rootless 运行。假设 4CUDA 初始化状态CUDA init state先前在内核中途崩溃的进程可能把驱动对该进程树的 CUDA context 卡死。在全新 shell 或全新启动的容器而非同一 shell 里的新 Python 进程中重试能以最低成本排除此项然后再去怀疑更深层的问题。假设 5ABI 不匹配ABI mismatch通常的元凶这是最后一个假设而不是第一个python3 -c import torch; print(torch.version.cuda)输出不以13开头即确认一个链接了libcudart.so.12的 wheel 被装到了仅提供 CUDA 13 的系统上——参见 SKILL.md 的 ABI Rule。五项中只有这一项能靠 wheel 重装修复在排除 1-4 之前就重装如果真实原因是 flag、环境变量或权限结果不会改变只是白费一轮。矩阵还提示在这块硬件上torchcodec/驱动交互是 (5) 最常被报告的实例——动手前先用gh issue list --repo NVIDIA/dgx-spark-playbooks查当前报告不要假设自己遇到了全新原因。4.1 配套的自动化子集preflight.sh仓库提供的 preflight.sh 可以自动化执行上述检查的子集G1/G3/G4/G7/G9输出契约是每行以 G-number 开头与spark-training-gotchas的 G1–G10 编号体系对齐G1torch.version.cuda是否以13开头对应本节假设 5PASS/FAIL/SKIPG3free -g输出 UMA 余量原始读数INFO 行G4nvidia-smi温/功耗快照INFO 行G7torch.cuda.get_device_capability()是否为(12, 1)PASS/WARNG9通过/.dockerenv、/run/.containerenv与 cgroup 标记判定容器/裸机姿态PASS/UNKNOWN/SKIP。注意 G7 只确认硬件能力不验证内核目标架构sm_121a后者需按 gotcha-checks.md G7 手动核查构建 flag。G2/G6/G8/G10 因无法自动化需按该文件的命令人工执行。五、sm_121 与 sm_121a一个字母的架构差异GB10 的 GPU 标识为sm_121。但部分较新的内核特性——尤其是 NVFP4 的原生cvt.e2m1x2转换指令——需要按sm_121asm_121的超集目标编译的代码而不是普通sm_121。由此产生一个可复现的性能规律如果 NVFP4 推理在这块硬件上比 FP8 慢约 32%原因很可能就在这里——内核没有用带a变体编译。行动要点检查所用 wheel/容器的构建 flag常见于TORCH_CUDA_ARCH_LIST一类变量在把锅甩给硬件之前先确认内核目标架构。对照检查命令来自 gotcha-checks.md G7python -c import torch; print(torch.cuda.get_device_capability())GB10 上预期输出(12, 1)确认 SM121。它与spark-training-gotchas的 G7 完全对应除非构建目标为sm_121a否则在 Spark 上坚持用 FP8NVFP4 不会更快。六、权威资源与使用纪律矩阵最后列出 Canonical resources作为文档记录的参考清单均为公开仓库/页面名github.com/NVIDIA/dgx-spark-playbooks官方 playbook 主仓库build.nvidia.com/spark/unslothgithub.com/natolambert/dgx-spark-setupgithub.com/albond/DGX_Spark_Unsloth_Lossless_Speedupgithub.com/NvMayMay/nvfp4-lora-spark文档给出了一条重要的使用纪律官方 playbook 曾经发过坏版本。在开始长任务之前检查每个仓库的近期 issue而不是等失败后再查。这条纪律在 SKILL.md 中被列为正式 preflight 步骤在 gotcha-checks.md G8 中给出可执行命令gh issue list --repo NVIDIA/dgx-spark-playbooks --state open --limit 20七、把矩阵用起来完整决策与验证工作流综合本文内容与配套仓库文件一次规范的 DGX Spark 环境搭建与验证流程如下平台身份确认来自 dgx-spark-ops-engineer.mdnvidia-smi、uname -m预期aarch64、torch.cuda.get_device_capability()预期(12, 1)。任何一项不匹配后续所有检查都失去意义。容器优先决策SKILL.md 的 Container-First Rule通用训练/推理用nvcr.io/nvidia/pytorch:25.09-py3Unsloth 微调用unsloth/unsloth:dgxspark-latest先解析并钉 digest两者都不适用自定义系统包、本地 IDE 解释器才走裸 pip并严格按第三节序列执行。GPU 可见性验证容器启动后立刻运行第四节基准命令预期True 13.0若为False按五个假设顺序排查运行时 flag → 设备可见性 → 权限 → CUDA 初始化状态 → ABI重装 wheel 只在确认 ABI 后执行。版本组合核验裸 pip 场景对照第三节已知可用版本矩阵运行bash assets/preflight.sh见 preflight.sh获取 G1/G3/G4/G7/G9 的自动化判定其余 gotcha 按 gotcha-checks.md 手动执行。上游状态检查长任务前查各权威资源仓库的近期 issue第六节避免复现官方 playbook 已报告的坏版本。环境保鲜矩阵头部日期2026-07-14即下一次复审的触发点CUDA、PyTorch 或 Unsloth 任一发布大版本就重新验证并更新这份矩阵。这套流程把组件矩阵从一份静态表格变成了可操作的环境健康检查闭环——这也正是它在dgx-spark-ops插件中作为 SKILL.md 的细节表存在的意义快速决策看 SKILL.md 的 Quick Table深挖原因看 stack-matrix落地执行看 container-workflow故障复现看 gotcha-checks。【免费下载链接】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），仅供参考