1. 主页

使用 NeMo 进行微调

使用 NVIDIA NeMo 在本地微调模型

基本思路

本指南将指导您如何在 NVIDIA Spark 设备上设置和使用 NVIDIA NeMo AutoModel，以微调大型语言模型和视觉语言模型。NeMo AutoModel 为 Hugging Face 模型提供 GPU 加速的端到端训练，并原生支持 PyTorch，从而实现即时微调，避免转换延迟。该框架支持从单 GPU 到多节点集群的分布式训练，并针对 ARM64 架构和 Blackwell GPU 系统优化了内核和内存高效的方案。

您将完成

您将使用 NVIDIA Spark 设备上的 NeMo AutoModel 为大型语言模型（1-700 亿参数）和视觉语言模型搭建一个完整的微调环境。最终，您将拥有一个支持参数高效微调 (PEFT)、有监督微调 (SFT) 和分布式训练（支持 FP8 精度优化）的可用安装环境，同时保持与 Hugging Face 生态系统的兼容性。

前置知识

  • 在 Linux 终端环境和 SSH 中工作

  • 具备 Python 虚拟环境和包管理的基础知识

  • 熟悉 GPU 计算概念和 CUDA工具包的使用

  • 具备容器化工作流和 Docker/Podman 操作的经验

  • 理解机器学习模型训练概念和微调工作流程

先决条件

  • 基于 Blackwell 架构的 NVIDIA Spark 设备

  • 已安装并配置 CUDA toolkit 12.0+：nvcc --version

  • 提供 Python 3.10+ 环境：python3 --version

  • 为确保模型高效加载和训练，系统至少需要 32GB 内存

  • 用于下载模型和软件包的有效互联网连接

  • 已安装用于仓库克隆的 Git：git --version

  • 已配置对 NVIDIA Spark 设备的 SSH 访问权限

辅助文件

所需所有文件均可在 GitHub 找到。

时间和风险

  • 预计时间：完成所有设置和初始模型微调需要 45-90 分钟

  • 风险等级：模型下载文件可能很大（数GB），ARM64软件包兼容性问题可能需要故障排除，多节点配置会增加分布式训练设置的复杂性。

  • 回滚：虚拟环境可以完全移除；除了软件包安装之外，不会对主机系统进行任何系统级更改。

  • 最后更新时间：2026 年 1月 15 日

    • 修复 qLoRA 微调工作流程

第 1 步 – 验证系统要求

检查您的 NVIDIA Spark 设备是否满足安装 NeMo AutoModel 先决条件。此步骤在主机系统上运行，以确认 CUDA 工具包的可用性和 Python 版本兼容性。

# Verify CUDA installation
nvcc --version

# Check Python version (3.10+ required)
python3 --version

# Verify GPU accessibility
nvidia-smi

# Check available system memory
free -h

第 2 步 – 配置 Docker 权限

要轻松管理容器而无需使用 sudo，您必须处于 docker 组中。如果您选择跳过此步骤，则需要使用 sudo 运行 Docker 命令。

打开一个新的终端并测试 Docker 访问权限。在终端中运行：

docker ps

如果您看到权限被拒绝错误（例如尝试连接到 Docker 守护程序套接字时出现权限被拒绝的错误），请将您的用户添加到 docker 组，这样您就不需要使用 sudo 运行命令了。

sudo usermod -aG docker $USER
newgrp docker

第 3 步 - 获取容器镜像

docker pull nvcr.io/nvidia/nemo-automodel:26.02

第 4 步 - 启动 Docker

docker run \
  --gpus all \
  --ulimit memlock=-1 \
  -it --ulimit stack=67108864 \
  --entrypoint /usr/bin/bash \
  --rm nvcr.io/nvidia/nemo-automodel:26.02

第 5 步 - 查看可用示例

请查看针对不同模型类型和训练场景提供的预配置训练方案。这些方案针对 ARM64 和 Blackwell 架构提供了优化的配置。

# Navigate to the repository
cd /opt/Automodel

# List LLM fine-tuning examples
ls examples/llm_finetune/

# View example recipe configuration
cat examples/llm_finetune/finetune.py | head -20

第 6 步 - 运行样本微调

以下命令展示了如何使用 LoRA 和 QLoRA 执行完全微调 (SFT) 和参数高效微调 (PEFT)。

首先，导出您的 HF_TOKEN，以便可以下载门控模型。

export HF_TOKEN=<your_huggingface_token>

警告：

替换为个人的 Hugging Face 访问令牌。下载任何受限模型都需要有效的令牌。

对于您使用的任何其他受限模型，步骤相同：访问 Hugging Face 上的模型页，请求访问权限，接受许可，然后等待批准。

LoRa 微调示例：

执行一个基本的微调示例来验证完整的设置。这将演示如何使用适合测试的小型模型进行高效的参数微调。以下示例中，我们使用 YAML 进行配置，参数覆盖通过命令行参数传递。

python3 examples/llm_finetune/finetune.py \
-c examples/llm_finetune/qwen/qwen2_5_7b_squad_peft.yaml \
--model.pretrained_model_name_or_path Qwen/Qwen2.5-7B\
--step_scheduler.max_steps 20

这些设置确保 Qwen2.5-7B LoRA 运行符合预期：

  • --model.pretrained_model_name_or_path: 从 Hugging Face 模型中心选择 Qwen2.5-7B 模型进行微调（权重通过您的 Hugging Face token 获取）。

  • --step_scheduler.max_steps：设置最大训练步数。为了演示目的，我们将其设置为 20，请根据您的需要进行调整。

QLoRA 微调示例：

我们可以使用 QLoRA 以节省内存的方式微调大型模型。

python3 examples/llm_finetune/finetune.py \
-c examples/llm_finetune/qwen/qwen1_5_moe_a2_7b_qlora.yaml \
--model.pretrained_model_name_or_path Qwen/Qwen2.5-32B \ 
--loss_fn._target_ nemo_automodel.components.loss.te_parallel_ce.TEParallelCrossEntropy \
--step_scheduler.local_batch_size 1 \
--step_scheduler.max_steps 20

这些设置确保 Qwen2.5-7B LoRA 运行符合预期：

  • --model.pretrained_model_name_or_path: 选择 Qwen2.5-32B 基础模型进行微调（权重通过您的 Hugging Face token获取）。

  • --loss_fn._target_：使用与大型 LLM张量并行训练兼容的 TransformerEngine-parallel 交叉熵损失变体。
  • --step_scheduler.local_batch_size：将每个 GPU 的微批次大小设置为 1；整体有效批次大小仍由配置文件中梯度累积和数据/张量并行设置驱动。
  • --step_scheduler.max_steps：设置最大训练步数。为了演示目的，我们将其设置为 20，请根据您的需要进行调整。

全参微调示例：

进入从 GitHub 克隆的 Automodel 目录后，运行：

python3 examples/llm_finetune/finetune.py \
-c examples/llm_finetune/qwen/qwen3_8b_squad_spark.yaml \
--model.pretrained_model_name_or_path Qwen/Qwen3-8B \
--step_scheduler.local_batch_size 1 \
--step_scheduler.max_steps 20 \
--packed_sequence.packed_sequence_size 1024

这些覆盖设置确保 Qwen3-8B SFT 运行符合预期：

  • --model.pretrained_model_name_or_path：从 Hugging Face 模型中心选择 Qwen/Qwen3-8B 模型进行微调（权重通过您的 Hugging Face token 获取）。如果您想微调其他模型，请调整此设置。

  • --step_scheduler.max_steps：设置最大训练步数。为了演示目的，我们将其设置为 20，请根据需要进行调整。
  • --step_scheduler.local_batch_size：将每个 GPU 的微批次大小设置为 1 以适应内存；整体有效批次大小仍然由配置文件中的梯度累积和数据/张量并行设置驱动。

第 7 步 - 验证训练是否成功完成

通过检查 checkpoint 目录中包含的文件来验证微调后的模型。

# Inspect logs and checkpoint output.
# The LATEST is a symlink pointing to the latest checkpoint.
# The checkpoint is the one that was saved during training.
# below is an example of the expected output (username and domain-users are placeholders).
ls -lah checkpoints/LATEST/

# $ ls -lah checkpoints/LATEST/
# total 32K
# drwxr-xr-x 6 username domain-users 4.0K Oct 16 22:33 .
# drwxr-xr-x 4 username domain-users 4.0K Oct 16 22:33 ..
# -rw-r--r-- 1 username domain-users 1.6K Oct 16 22:33 config.yaml
# drwxr-xr-x 2 username domain-users 4.0K Oct 16 22:33 dataloader
# drwxr-xr-x 2 username domain-users 4.0K Oct 16 22:33 model
# drwxr-xr-x 2 username domain-users 4.0K Oct 16 22:33 optim
# drwxr-xr-x 2 username domain-users 4.0K Oct 16 22:33 rng
# -rw-r--r-- 1 username domain-users 1.3K Oct 16 22:33 step_scheduler.pt

第 8 步 - 清理和回滚（可选）

如有需要，请卸载并恢复原始环境。这些命令会安全地移除所有已安装的组件。

警告：

此操作将删除所有虚拟环境和已下载的模型。请确保您已备份所有重要的训练检查点。

# Remove virtual environment
rm -rf .venv

# Remove cloned repository
cd ..
rm -rf Automodel

# Remove uv (if installed with --user)
pip3 uninstall uv

# Clear Python cache
rm -rf ~/.cache/pip

第 9 步 -（可选）在 Hugging Face Hub 上发布您微调后的模型 checkpoint 

在 Hugging Face Hub 上发布您微调的模型checkpoint。

注意：

这是一个可选步骤，并非使用微调模型所必需。如果您想与他人共享微调后的模型或将其用于其他项目，此步骤非常有用。您也可以通过克隆存储库并使用检查点在其他项目中使用微调后的模型。要在其他项目中使用微调后的模型，您需要安装 Hugging Face CLI。您可以通过运行 pip install huggingface-cli 来安装 Hugging Face CLI。更多信息，请参阅 Hugging Face CLI 文档。

提示：

您可以使用 hf 命令上传微调模型 checkpoint 至 Hugging Face Hub。更多信息，请参阅 Hugging Face CLI 文档。

# Publish the fine-tuned model checkpoint to Hugging Face Hub
# will be published under the namespace <your_huggingface_username>/my-cool-model, adjust name as needed.
hf upload my-cool-model checkpoints/LATEST/model

提示：

如果您没有使用 HF_TOKEN 对 Hugging Face Hub 的写入权限，则上述命令可能会失败。错误信息示例：

akoumparouli@1604ab7-lcedt:/mnt/4tb/auto/Automodel8$ hf upload my-cool-model checkpoints/LATEST/model
Traceback (most recent call last):
  File "/home/akoumparouli/.local/lib/python3.10/site-packages/huggingface_hub/utils/_http.py", line 409, in hf_raise_for_status
    response.raise_for_status()
  File "/home/akoumparouli/.local/lib/python3.10/site-packages/requests/models.py", line 1024, in raise_for_status
    raise HTTPError(http_error_msg, response=self)
requests.exceptions.HTTPError: 403 Client Error: Forbidden for url: https://huggingface.co/api/repos/create

要解决这个问题，你需要创建一个访问令牌。有关 write 权限，请参阅 Hugging Face 指南的使用说明。

第 10 步 - 后续步骤

开始使用 NeMo AutoModel 来完成您的特定微调任务。首先使用提供的模板，然后根据您的模型需求和数据集进行自定义。

# Copy a recipe for customization
cp recipes/llm_finetune/finetune.py my_custom_training.py

# Edit configuration for your specific model and data
# Then run: uv run my_custom_training.py

探索 NeMo AutoModel GitHub 仓库更多示例、文档和社区案例，请参阅相关文档。您还可以考虑设置自定义数据集、尝试不同的模型架构，以及针对大型模型扩展到多节点分布式训练。

错误
原因
修复
nvcc: command not found
CUDA toolkit 不在 PATH 环境变量中
将 CUDA toolkit 添加到 PATH 环境变量中：export PATH=/usr/local/cuda/bin:$PATH
pip install uv permission denied
系统 pip 限制
使用 pip3 install --user uv 并更新路径
训练过程中未检测到 GPU
CUDA 驱动/ runtime 不匹配
请验证驱动兼容性：nvidia-smi
如有需要，请重新安装 CUDA
训练过程中内存不足
模型过大，超出可用GPU内存限制
减小批处理大小、启用梯度检查点或使用模型并行
ARM64 软件包兼容性问题
ARM架构无可用软件包
使用源代码安装或使用 ARM64 标志从源代码构建
无法访问 URL 的受限存储库
部分 HuggingFace 模型访问权限受限
恢复你的 HuggingFace 令牌并在浏览器上请求访问门控模型

注意：

DGX Spark 使用统一内存架构 (UMA)，支持 GPU 和 CPU 之间的动态内存共享。由于许多应用程序仍在更新以利用 UMA，即使在 DGX Spark 的内存容量范围内，您也可能会遇到内存问题。如果发生这种情况，请手动刷新缓冲区缓存：

sudo sh -c 'sync; echo 3 > /proc/sys/vm/drop_caches'

资源

DGX Spark 文档

DGX Spark 论坛

DGX Spark 用户性能指南