DGX Spark 容器工作流实战NGC PyTorch 与 Unsloth 镜像的 docker run 规范、标签解析与可复现运行【免费下载链接】agentsMulti-harness agentic plugin marketplace for Claude Code, Codex, Cursor, OpenCode, GitHub Copilot, and Google Antigravity项目地址: https://gitcode.com/GitHub_Trending/agents24/agents本指南是 DGX Spark 环境技能包中容器工作流container-workflow参考文档的完整展开。它面向在 NVIDIA DGX SparkGB10 / aarch64 / SM121 / CUDA 13上进行 PyTorch 训练与 Unsloth 微调的工程师给出两条官方认可镜像的具体docker run调用、移动标签的摘要digest固定流程、拉取与本地重建的取舍以及裸 pip 兜底方案。读完本文你将能按可复现的标准在 Spark 上启动训练容器、把结果落盘到宿主机、并对容器优先Container-First规则背后的 ABI 匹配逻辑形成体系化认知。背景为什么 Spark 上容器优先是硬规则DGX Spark 搭载 GB10 Grace Blackwell 芯片aarch64 CPU、SM121 GPU、128GB 统一内存UMA、CUDA 13。相比常见的 x86 CUDA 12 服务器这是一个更窄、更年轻的平台——aarch64 CUDA 13 的 wheel 生态仍在逐步补齐依据 spark-environment-setup/SKILL.md 的定位描述。容器优先的核心理由是固定版本pinning而非便利。Triton、xformers、transformers 的版本与 GB10 的 SM121 目标和 CUDA 13 之间存在窄交互容器把三者锁定在一个已在当前硬件上验证过的组合里而裸 pip 把解析责任留给你自己代价是一次一个导入错误。仓库技能包甚至为这个决策预置了快速判定标准训练/推理工作 → NGC PyTorch 容器Unsloth 为中心的微调 → Unsloth 容器自带已验证的 Triton/xformers/transformers 组合两者都不合适自定义系统包、本地 IDE 解释器→ 按精确顺序执行裸 pip。判定细节可参见 SKILL.md 的 Container-First Rule而本文聚焦其中可落地的两条容器路径。NGC PyTorch 容器标准训练的通用底座NGC 镜像用于通用训练/推理底座。参考文档给出了如下具体调用docker run --runtimenvidia --gpus all -it --rm \ --ipchost --ulimit memlock-1 --ulimit stack67108864 \ -v $(pwd)/finetuning:/workspace/finetuning \ nvcr.io/nvidia/pytorch:25.09-py3每个参数的用途必须理解到位否则容器内环境会以隐蔽方式失败--runtimenvidia --gpus all将 GB10 GPU 暴露给容器。缺少该参数时容器内的 PyTorch 会报告无 CUDA 设备尽管宿主机侧一切正常。这与 gotcha-checks.md 的 GPU 检测五假设 中的第一项运行时/标志直接对应——在容器内执行nvidia-smi失败即指向这一项。--ipchost与--ulimit组合--ipchost避免共享内存饥饿--ulimit memlock-1解除内存锁上限--ulimit stack6710886464MB放宽栈空间。三者共同保护 PyTorch DataLoader 多进程 worker 的共享内存与栈需求。-v $(pwd)/finetuning:/workspace/finetuning把仓库的finetuning/运行目录挂载进容器。检查点与日志因此落在宿主机文件系统而非临时容器层——--rm标志在退出时删除容器以及一切未挂载出去的内容。若省略挂载训练产物会随容器销毁而丢失。标签Tag指引25.09 与更新 blessed tag 的取舍25.09-py3是在该硬件上实际验证过可工作的标签内置 torch2.9.0a050eac811a6.nv25.09、CUDA 13.0满足 ABI 规则预期对于微调工作流中实际用到的包未观察到功能差异。参考文档明确了一条务实原则当 SKILL.md 提到更新的 blessed tag如25.11-py3时应将其视为本地可用则拉取的指引而非硬性要求——如果引用的新 tag 未在本地缓存且拉取不现实就回退到最新可用的25.xtag并在运行记录run notes中注明这个缺口不要阻塞在 tag 上。同时要注意 NGC 构建的一个特性其 PyTorch 是在容器内部针对 CUDA 13 编译的没有cu130wheel 标签——因此pip show torch不会出现cu130字样这个缺失本身不是失败详见 stack-matrix.md 与 ABI 规则。Unsloth 容器移动标签必须先固定摘要再运行对于以 Unsloth 为中心的微调运行应优先使用专门镜像而非通用 NGC 镜像——它自带了为该硬件验证过的固定 Triton/xformers/transformers 组合。与 NGC 的带日期 tag25.09-py3不同unsloth/unsloth:dgxspark-latest是一个移动 tagmoving tag。直接把它当作正式运行的调用是不可靠的——必须先解析并固定它的 digest然后按 digest 运行。参考文档给出的完整三步流程# 1. Discovery step: pull the moving tag and confirm it starts. docker pull unsloth/unsloth:dgxspark-latest # 2. Resolve the tag to its current digest. docker inspect --format{{index .RepoDigests 0}} unsloth/unsloth:dgxspark-latest # - unsloth/unslothsha256:resolved digest # 3. Run by digest — this is the reproducible invocation. docker run --runtimenvidia --gpus all -it --rm \ --ipchost --ulimit memlock-1 --ulimit stack67108864 \ -v $(pwd)/finetuning:/workspace/finetuning \ unsloth/unslothsha256:resolved digest第 1 步的docker pull是发现步骤拉取移动 tag 并确认它能启动第 2 步用docker inspect把 tag 解析为当前 digestRepoDigests中的sha256:...第 3 步按 digest 运行这才是可复现的正式调用。在 CI 或任何可复现性重要的流水线中应把固定的sha256:...digest 替换掉 tag——如果运行记录只写了dgxspark-latest一旦 tag 移动这个运行将无法复现。每次接手新的 blessed release 时都要重新解析并重新固定 digest参见下文拉取 vs 重建。其余参数--runtimenvidia --gpus all、--ipchost、ulimit、finetuning/挂载的理由与 NGC 调用完全一致。这条移动 tag 必须先固定的约束同样被上游正式使用在 stack-matrix.md 的组件矩阵 中Unsloth 行明确标注unsloth/unsloth:dgxspark-latest是移动 tag并要求可复现/CI 场景下固定 digest。拉取 vs 重建什么时候该做什么参考文档给出了两条边界清晰的原则应当拉取新 tag 的场景有新 blessed release 发布或你在追查一个新 tag 的变更日志声称已修复的 bug。应当在本地重建的场景某个具体项目需要一个额外的系统包或 Python 依赖层以两条基础镜像之一为FROM起点且该依赖与固定的训练栈不冲突。明确禁止的场景不要为了升级基础镜像已经固定的某个组件而重建——那会重新引入容器存在本来就是为了规避的版本矩阵问题。这与技能包的 G9 教训一致裸 pip 环境里 Triton、xformers、transformers 各自漂移没有任何东西把它们钉在 GB10 的 SM121 目标上见 spark-training-gotchas/SKILL.md G9。裸 pip 逃生通道uv 隔离与 --override 强制固定当容器确实不合适参见 SKILL.md 的 Container-First Rule时参考文档要求用uv隔离环境而非系统 Python并在其中按 NVIDIA playbook 的安装顺序执行。其中的关键陷阱与对策如果uv坚持选择一个与 playbook 固定版本冲突的依赖版本在 aarch64/CUDA 13 wheel 生态尚年轻的当下很常见使用uv pip install --override强制固定版本通过而不是让解析器静默替换成不兼容的构建环境建立后必须先用 SKILL.md 的 Verification Commands 验证再信任该环境。完整的固定版本序列来自 SKILL.md对应 stack-matrix 的 dated 已知可用矩阵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不是可选项在 aarch64 上让 pip 重新解析 Unsloth 的依赖树是拉入不兼容 torch 或 triton 构建的常见途径第三条torchao0.17.0也不是可选项NGC 基础镜像内置的 torchao 对当前 peft 的 LoRA-attach 路径来说太旧ImportError: ... torchao ... only versions above 0.16.0 are supported这是硬阻塞不是警告所有固定都是承重的load-bearing取自 stack-matrix.md 的 dated 已知可用版本矩阵——未固定的安装会解析到当前 PyPI 版本远远超出该 Unsloth 版本声明支持的区间。一个值得注意的生态变化记录在 stack-matrix.mdHF_HUB_ENABLE_HF_TRANSFER在huggingface_hub1.23 已废弃设置它只会产生FutureWarning下载实际走 Xet。在 1.23 上应改为设置HF_XET_HIGH_PERFORMANCE1旧文档中提及hf_transfer的指令应理解为让下载变快的意图而非字面意义的当前 API 要求。启动前验证容器内环境是否真正就绪无论走哪条容器路径参考文档与技能包都要求在跑昂贵负载之前先验证 GPU 可见性。容器启动后立即执行import torch print(torch.cuda.is_available(), torch.version.cuda)预期输出为一行bool cuda-versionTrue 13.0如果输出False不要直接跳到重装 wheel——ABI 不匹配只是多种原因之一。技能包给出的排查假设表详见 stack-matrix.md 的逐假设细节假设快速检查运行时/标志容器内nvidia-smi同样失败设备可见性echo $CUDA_VISIBLE_DEVICES注意显式设为空串会隐藏所有设备权限ls -l /dev/nvidia*CUDA 初始化状态进程卡死用全新 shell/容器重试ABI 不匹配常见元凶torch.version.cuda不以13开头先查nvidia-smi如果它不显示 GPU问题属于前三类而非 ABI。只有确认是 ABI 问题后才重装 wheel——在排除 1–4 之前重装只会浪费一次循环而不改变结果。ABI 规则的详细内容CUDA 12/13 wheel 对libcudart.so.12/.so.13的链接错配、典型症状、修复路径可参见 spark-environment-setup/SKILL.md 的 ABI Rule 一节。另一个高频坑训练开始后如果 Triton 内核编译失败设置TRITON_PTXAS_PATH/usr/local/cuda/bin/ptxas重试组件矩阵中 Triton 一行的要求。组件矩阵与已知可用版本支撑上述决策的事实表stack-matrix.md 是本文所有容器/裸 pip 决策背后的逐组件事实表与 SKILL.md 的 Component Quick Table 一一对应组件状态说明PyTorchcu130, aarch64✅官方 wheel 位于download.pytorch.org/whl/cu130匹配系统 CUDA 13 ABIbitsandbytes✅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.1vLLM仅 nightly wheel使用wheels.vllm.ai/nightly/cu130SM121 修复约在 2026-06 进入 nightly 通道TransformerEngine / NVFP4 训练仅容器裸 pip 不现实NVFP4BlockScaling面向 SM100SM121 支持视为有保留Unsloth✅容器优先官方镜像unsloth/unsloth:dgxspark-latest移动 tag需固定 digest或 NVIDIA playbook pip 序列Axolotl / TRL / PEFT✅标准安装无需特殊处理LLaMA-Factory / NeMo脆弱/进行中在本平台不可靠先查上游 issue一个值得单独强调的硬件细节是sm_121 vs sm_121aGB10 的 GPU 识别为sm_121但部分较新内核特性尤其 NVFP4 的原生cvt.e2m1x2转换指令需要为超集目标sm_121a编译的代码。若 NVFP4 推理比 FP8 慢约 32%通常就是这个原因——检查所用 wheel/容器的构建标志再下结论说硬件是瓶颈对应训练 gotchas 的 G7。与技能包其他部分的衔接容器工作流是整个 DGX Spark 环境设置技能的落地执行层与同包其他文件形成闭环决策入口spark-environment-setup/SKILL.md 定义 Container-First Rule、ABI Rule 与 Verification Commands本文是其references/container-workflow.md的展开事实底座references/stack-matrix.md 提供逐组件状态与 dated 已知可用版本矩阵启动前预检spark-training-gotchas/SKILL.md 定义 G1–G10 失败模式其中 G1ABI 不匹配、G9容器优先 vs 裸 pip直接由本工作流解决其 assets/preflight.sh 可自动执行 G1/G3/G4/G7/G9 检查Agent 化执行dgx-spark-ops-engineer.md 描述环境医生型 Agent 的容器工作流引导职责——在推荐宿主机级改动之前先引导修复走向 NGC 或 Unsloth 容器镜像spark-preflight.md 则把预检编排成可调用的命令并产出env-report.json运行期运维spark-memory-thermal-ops/SKILL.md 承接环境已验证之后的阶段——UMA 内存头寸、OOM Ladder、热监控。结语容器工作流在 DGX Spark 环境设置中承担可执行层的角色NGC 镜像用带日期 tag 直接运行即可Unsloth 镜像必须先固定 digest 再运行本地重建只用于叠加不冲突的依赖而绝非升级已固定组件裸 pip 则是必须遵循固定顺序与--override纪律的兜底通道。所有路径共享同一条验证底线在启动任何昂贵负载之前确认torch.cuda.is_available()为True且torch.version.cuda以13开头。参考文档右上角的 Last verified: 2026-07-14 提醒所有 tag 与版本信息都是带日期快照——新 blessed tag 发布时应重新验证并更新决策这正是把固定版本当作流程而非一次性动作的正确姿势。【免费下载链接】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），仅供参考