1. 主页

使用 NeMo 进行微调

使用 NVIDIA NeMo 在本地微调模型

基本思路

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

您将完成

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

前置知识

  • 在 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

export MODELSCOPE_CACHE="$HOME/.cache/modelscope"
export HF_CACHE="$HOME/.cache/huggingface"
mkdir -p "$MODELSCOPE_CACHE" "$HF_CACHE"
docker run \
--gpus all \
--ulimit memlock=-1 \
-it --ulimit stack=67108864 \
-v "$MODELSCOPE_CACHE:/root/.cache/modelscope" \
-v "$HF_CACHE:/root/.cache/huggingface" \
-e MODELSCOPE_CACHE=/root/.cache/modelscope \
--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)。

首先，安装 ModelScope CLI 并创建本地缓存目录，以便可以从 ModelScope 下载模型和数据集。

\# 运行基本的LLM微调示例  
python3 -m pip install --upgrade modelscope export MODELSCOPE_CACHE="$HOME/.cache/modelscope" mkdir -p "$MODELSCOPE_CACHE/Qwen"

警告：

替换下面使用的三个 ModelScope 模型均为公开仓库，下载不需要访问令牌。

  • 下载说明： ModelScope 模型下载文档

  • 在尝试下载之前，请确认目标模型仓库可以访问

    • Qwen2.5-7B：Qwen/Qwen2.5-7B

    • Qwen3-8B：Qwen/Qwen3-8B

    • Qwen2.5-32B：Qwen/Qwen2.5-32B

对于您使用的任何其他私有模型，步骤相同：先使用 modelscope login --token "<your_modelscope_token>" 登录，然后下载模型。

LoRa 微调示例：

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

# 运行基本的LLM微调示例

modelscope download --model "Qwen/Qwen2.5-7B" --local_dir "$MODELSCOPE_CACHE/Qwen/Qwen2.5-7B"
python3 examples/llm_finetune/finetune.py \
-c examples/llm_finetune/qwen/qwen2_5_7b_squad_peft.yaml \
--model.pretrained_model_name_or_path "$MODELSCOPE_CACHE/Qwen/Qwen2.5-7B" \
--step_scheduler.max_steps 20

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

  • -- model.pretrained_model_name_or_path: 从 Modelscope模型中心选择 Qwen2.5-7B 模型进行微调。

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

QLoRA 微调示例：

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

modelscope download --model "Qwen/Qwen2.5-32B" --local_dir "$MODELSCOPE_CACHE/Qwen/Qwen2.5-32B"
python3 examples/llm_finetune/finetune.py \
-c examples/llm_finetune/qwen/qwen1_5_moe_a2_7b_qlora.yaml \
--model.pretrained_model_name_or_path "$MODELSCOPE_CACHE/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

这些设置确保 32B QLoRA 运行符合预期：

  • --model.pretrained_model_name_or_path: 选择 Qwen2.5-32B 基础模型进行微调。

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

全参微调示例：

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

modelscope download --model "Qwen/Qwen3-8B" --local_dir "$MODELSCOPE_CACHE/Qwen/Qwen3-8B"
python3 examples/llm_finetune/finetune.py \
-c examples/llm_finetune/qwen/qwen3_8b_squad_spark.yaml \
--model.pretrained_model_name_or_path "$MODELSCOPE_CACHE/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：从 Modelscope 模型中心选择 Qwen/Qwen3-8B 模型进行微调。如果您想微调其他模型，请调整此设置。

  • --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 步 - 后续步骤

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

# 复制配置文件以进行自定义
cp recipes/llm_finetune/finetune.py my_custom_training.py

# 编辑特定的模型和数据配置
# 然后运行：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 标志从源代码构建

注意：

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 用户性能指南