#使用 Workbench 在 Ascend NPU 上微调和预训练 LLM

#背景

本指南介绍了基于 Workbench 的解决方案，用于在搭载 Huawei Ascend NPU 的 arm64 节点上运行大模型微调和预训练。主要验证流程使用 PyTorch CANN workbench 镜像，该镜像面向 Ascend 环境构建，包含 Python 3.12、CANN 8.5.0、PyTorch 2.9.0 和 torch_npu 2.9.0。本页还包含一个基于 MindSpore 的微调流程，使用 MindSpore CANN workbench 镜像。

该工作流围绕三个验证 notebook 展开：

• 下载 qwen3_finetune_verify.ipynb，用于在 PyTorch CANN Jupyter 镜像中对 Qwen3-8B 进行全参数监督微调
• 下载 qwen25_pretrain_verify.ipynb，用于在 PyTorch CANN Jupyter 镜像中预训练 Qwen2.5-7B
• 下载 qwen3_0.6b_finetune_verify.ipynb，用于在 MindSpore CANN Jupyter 镜像中对 Qwen3-0.6B 进行基于 MindSpore 的全参数微调

所有 notebook 都被设计为“先验证”的示例。它们从轻量级配置开始，以便你在将相同工作流扩展到真实训练任务之前，先确认运行时、模型加载、预处理和分布式启动路径是否正常。基于 PyTorch 的 notebook 在 MindSpeed-LLM 之上运行，而 MindSpore notebook 则验证镜像中随附的 MindSpeed-Core-MS 和 MindSpeed-LLM 源码树。

与某些其他示例中使用的 VolcanoJob 流程不同，此解决方案直接在一个连接了多个 Ascend NPU 的单个 Workbench 容器内运行训练。

#开始之前

请确保集群已经提供可用的 Ascend 运行时。实际上，这意味着 Ascend driver、CANN runtime 和 Kubernetes device plugin 已经安装并正常工作，并且你的 workbench 可以调度到具有 Ascend NPU 资源的 arm64 节点。

按照 创建 Workbench 中的说明，使用与要运行的 notebook 匹配的镜像创建 workbench：

• 对于 qwen3_finetune_verify.ipynb 和 qwen25_pretrain_verify.ipynb，使用 PyTorch CANN。
• 对于 qwen3_0.6b_finetune_verify.ipynb，使用 MindSpore CANN。

对于默认 notebook 设置，PyTorch 示例至少需要 4 个 NPU。MindSpore 验证 notebook 针对 2 个 Ascend 910B 32G NPU 进行了调优，配置为 TP=1、PP=1 和 MBS=2。所有 notebook 都会创建转换后的模型权重、预处理输出、日志和 checkpoint，因此工作区应使用持久化存储，并预留足够空间以同时保存原始 HuggingFace 模型和转换后的 Megatron/MCore 权重。

基于 PyTorch 的 notebook 在执行期间会从 https://gitcode.com/ascend/MindSpeed-LLM.git 克隆 MindSpeed-LLM。如果 workbench 无法访问该仓库，请在工作区中放置一份本地副本，并更新第一个参数单元格中的 notebook 路径。MindSpore notebook 在运行时不会额外克隆仓库，而是使用 /opt/app-root/share/MindSpeed-Core-MS 下随附的源码树。

#创建 Workbench

在 Ascend 节点池上创建一个 JupyterLab workbench，并选择与计划运行的 notebook 匹配的镜像。对于 Qwen3-8B 微调和 Qwen2.5-7B 预训练 notebook，使用 PyTorch CANN；对于 Qwen3-0.6B 的 MindSpore 微调 notebook，使用 MindSpore CANN。将工作区保留在持久化存储上，以便在重启后 notebook、转换后的权重和训练输出仍可使用。如果按 notebook 默认值运行，请申请足够的 NPU 资源以满足配置的 tensor parallel 和 pipeline parallel。

有关详细创建步骤和镜像选择，请参见 创建 Workbench。

#导入验证 Notebook

将计划使用的 notebook 上传到 JupyterLab 工作区并在其中打开。如果你的镜像分发版本已经在工作区中暴露了这些 notebook，则可以直接使用。否则，请从上方链接下载它们，并通过 JupyterLab 文件浏览器上传。JupyterLab 上传流程详见 创建 Workbench。

#准备基础模型

这三个 notebook 都要求工作区中存在 HuggingFace 格式的基础模型。默认路径如下：

你可以将模型文件放在这些目录中，或在第一个参数单元格中修改 HF_MODEL_DIR。运行 notebook 之前，请确认目标目录中包含预期的模型配置、tokenizer 文件和权重文件。

如果你希望模型可版本化并可在多个 workbench 之间复用，请先将其上传到平台模型仓库，然后再克隆或复制到工作区。基于仓库的模型上传流程记录在 使用 Notebook 上传模型。

注意： 这三个 notebook 都会在训练开始前将 HuggingFace 权重转换为 Megatron/MCore 格式。此转换会生成另一组大文件，因此存储规划非常重要。

#准备数据集

微调和预训练 notebook 所期望的输入数据类型不同。

#微调数据

微调 notebook 使用 instruction-tuning 数据。其验证路径基于 Alpaca 风格样本；如果你将文件放入工作区并更新参数单元格中的路径变量，它也可以使用真实数据集。

默认情况下，notebook 会查找：

• ALPACA_PARQUET = /opt/app-root/src/datasets/alpaca/train-00000-of-00001-a09b74b3ef9c3b56.parquet
• RAW_DATA_FILE = /opt/app-root/src/Qwen3-8B-work-dir/finetune_dataset/alpaca_sample.jsonl

MindSpore 微调 notebook 使用相同的 Alpaca 风格 schema，但会将转换后的 JSONL 写入不同的工作目录：

• ALPACA_PARQUET = /opt/app-root/src/datasets/alpaca/train-00000-of-00001-a09b74b3ef9c3b56.parquet
• RAW_DATA_FILE = /opt/app-root/src/Qwen3-0.6B-work-dir/finetune_dataset/alpaca_sample.jsonl

如果 parquet 文件存在，notebook 会自动将其转换为 JSONL。如果你已经有 JSONL instruction 数据，请将其放在 RAW_DATA_FILE 指定的位置，或将变量更新为你的实际路径。

预期的 Alpaca 风格 JSONL 记录如下：

{"instruction": "...", "input": "...", "output": "..."}

还可以通过修改参数部分中的 handler，将 notebook 调整为其他 instruction 格式，例如 ShareGPT 或 Pairwise 数据集。

#预训练数据

预训练 notebook 使用原始文本数据。MindSpeed-LLM 预处理支持 .parquet、.json、.jsonl 和 .txt。对于 parquet、json 或 jsonl 等结构化格式，数据应包含 text 字段。对于纯文本输入，请每行提供一个文本片段。

验证 notebook 使用以下默认输入路径：

• ALPACA_PARQUET = /opt/app-root/src/datasets/alpaca/train-00000-of-00001-a09b74b3ef9c3b56.parquet

如果该文件不存在，notebook 会回退到一个小型内置样本，以便仍可验证预处理和训练流程。

#将数据导入工作区

对于较小的测试文件，直接在 JupyterLab 中上传通常已经足够。对于更大的数据集，更实用的方式是挂载 PVC，或将数据从平台数据集仓库拉取到工作区。如果你希望采用基于仓库的数据集工作流，请参见 使用 Workbench 进行 LLM 微调。

#运行微调 Notebook

在使用 PyTorch CANN Jupyter 镜像的 workbench 中打开 qwen3_finetune_verify.ipynb，并从第一个参数单元格开始。该单元格控制模型路径、数据集路径、输出位置、sequence length、训练迭代次数，以及在权重转换和训练期间使用的 tensor 和 pipeline parallel。

该 notebook 遵循一个直接的执行流程。首先检查 Ascend 运行时，并确认 torch_npu、MindSpeed 和 MindSpeed-LLM 可用。然后准备一个小型 Alpaca 风格数据集，或加载你的真实数据集；接着克隆 MindSpeed-LLM 仓库，将 HuggingFace checkpoint 转换为 Megatron/MCore 格式，将数据预处理为 MindSpeed-LLM 所需的格式，使用 posttrain_gpt.py 启动全参数 SFT，最后针对生成的 checkpoint 运行一次推理检查。

默认配置是有意保守的。它使用较短的 sequence length 和较少的迭代次数，因此 notebook 更适合作为环境验证工具，而不是长时间的生产训练。该路径工作正常后，再切换到真实数据集，并为实际工作负载调整参数。

最需要检查的参数包括：

• HF_MODEL_DIR
• ALPACA_PARQUET 或 RAW_DATA_FILE
• OUTPUT_DIR
• TP 和 PP
• SEQ_LENGTH
• TRAIN_ITERS
• ENABLE_THINKING

对于真实微调，建议将 SEQ_LENGTH 提高到与模型上下文窗口匹配，将 TRAIN_ITERS 提高到适合生产的值，并根据可用 NPU 数量和训练集大小调整 parallel 和 batch size。如果你希望周期性保存 checkpoint，还需要在训练单元格中更新保存间隔。

#运行 MindSpore 微调 Notebook

在使用 MindSpore CANN Jupyter 镜像的 workbench 中打开 qwen3_0.6b_finetune_verify.ipynb。该 notebook 验证官方 Qwen3 MindSpore 全参数微调路径，并复现 MindSpeed-LLM 中以下脚本实现的上游工作流：

• examples/mindspore/qwen3/ckpt_convert_qwen3_hf2mcore.sh
• examples/mindspore/qwen3/data_convert_qwen3_instruction.sh
• examples/mindspore/qwen3/tune_qwen3_0point6b_4K_full_ms.sh

与基于 PyTorch 的 notebook 不同，此流程使用镜像内置的源码树 /opt/app-root/share/MindSpeed-Core-MS。它会检查随附的 MindSpeed-LLM、MindSpeed、MSAdapter 和 Megatron-LM 目录，并在训练开始前验证镜像是否暴露了 Ascend 环境脚本以及预期的 PYTHONPATH 条目。

第一个参数单元格中的默认验证配置如下：

• HF_MODEL_DIR=/opt/app-root/src/models/Qwen3-0.6B
• WORK_DIR=/opt/app-root/src/Qwen3-0.6B-work-dir
• RAW_DATA_FILE=/opt/app-root/src/Qwen3-0.6B-work-dir/finetune_dataset/alpaca_sample.jsonl
• OUTPUT_DIR=/opt/app-root/src/Qwen3-0.6B-work-dir/output/qwen3_0.6b_finetuned
• TP=1, PP=1, MBS=2
• SEQ_LENGTH=2048
• TRAIN_ITERS=100
• ENABLE_THINKING=true

该 notebook 按以下顺序执行：

1. 验证运行时环境。
   它会检查 mindspore、msadapter、mindspeed 和 mindspeed_llm，确认模型目录包含 config.json、tokenizer 文件和 .safetensors 权重，并验证可用的 NPU 数量与配置的 TP 和 PP 兼容。
2. 准备 instruction 数据集。
   如果 ALPACA_PARQUET 存在，notebook 会将其转换为 Alpaca 风格 JSONL。否则，它会创建一个小型内置样本数据集，以便仍然可以验证完整流水线。
3. 将 HuggingFace 权重转换为 MindSpeed/MCore 格式。
   notebook 调用 mindspeed_llm/mindspore/convert_ckpt.py，并设置 --load-model-type hf、--save-model-type mg 和 --ai-framework mindspore，将转换后的权重写入与 TP 和 PP 相关的输出目录。
4. 预处理微调数据集。
   notebook 运行 preprocess_data.py，使用 AlpacaStyleInstructionHandler、PretrainedFromHF、prompt-type qwen3 和 enable-thinking true，然后检查是否生成了所需的 .bin 和 .idx 文件。
5. 启动全参数 SFT 训练。
   训练单元格结合 msrun 和 posttrain_gpt.py 使用，设置 --finetune、--stage sft、--is-instruction-dataset、--ai-framework mindspore 和 --ckpt-format msadapter，并将日志写入 /opt/app-root/src/Qwen3-0.6B-work-dir/logs。
6. 验证生成的 checkpoint。
   最后一个单元格检查 latest_checkpointed_iteration.txt，列出 iter_* checkpoint 目录，并确认训练日志文件存在。

最需要检查的参数包括：

• HF_MODEL_DIR
• ALPACA_PARQUET 或 RAW_DATA_FILE
• OUTPUT_DIR
• TP、PP 和 MBS
• SEQ_LENGTH
• TRAIN_ITERS
• ENABLE_THINKING
• MASTER_ADDR、MASTER_PORT、NNODES 和 NODE_RANK

当你从验证切换到真实训练任务时，请根据可用 NPU 内存和目标上下文长度，逐步提高 SEQ_LENGTH、TRAIN_ITERS 和数据集大小。如果你更改了 TP 或 PP，请重新执行权重转换，以便转换后的 checkpoint 布局与训练布局一致。对于多节点训练，请在再次运行训练单元格之前更新 MASTER_ADDR、MASTER_PORT、NNODES 和 NODE_RANK。

当前 notebook 仅验证 checkpoint 生成，不包含稳定的 MindSpore 推理步骤。

#运行预训练 Notebook

在使用 PyTorch CANN Jupyter 镜像的 workbench 中打开 qwen25_pretrain_verify.ipynb，并以相同方式检查第一个参数单元格。该 notebook 使用原始文本语料，而不是 instruction-response 记录，但整体结构类似。

它首先进行环境检查，准备一个样本文本数据集或加载你的真实数据集，克隆 MindSpeed-LLM 仓库，将 HuggingFace checkpoint 转换为 Megatron/MCore 格式，将原始文本预处理为 .bin 和 .idx 文件，然后使用 pretrain_gpt.py 启动预训练。

这里的验证配置同样是有意设置得较小。它适用于在开始更长时间的运行之前，验证 Ascend 运行时上的预处理、checkpoint 转换、分布式启动和输出写入是否都正常工作。

需要重点检查的参数包括：

• HF_MODEL_DIR
• ALPACA_PARQUET 等数据集路径变量
• OUTPUT_DIR
• TP 和 PP
• SEQ_LENGTH
• TRAIN_ITERS

当你从验证切换到真实预训练任务时，请增加 sequence length 和迭代次数，根据可用 NPU 和语料规模设置全局 batch size，并重新检查保存间隔。如果你更改了 TP 或 PP，请重新执行权重转换步骤，以确保转换后的 checkpoint 与训练布局匹配。

#输出与持久化

默认情况下，notebook 会将输出写入以下位置：

请将这些目录保留在持久化存储上。输出可能非常大，在大多数真实工作流中，你会希望在 workbench 重启后仍保留它们，或将其发布以供后续使用。如果你希望将生成的模型重新推送到模型仓库，请遵循 使用 Notebook 上传模型 中的 Git LFS 工作流。

#运维说明

• 这些 notebook 首先是验证示例。不要在真实训练中保持默认的迭代次数和 sequence length 不变。
• 微调 notebook 执行的是全参数 SFT，而不是 LoRA。
• qwen3_0.6b_finetune_verify.ipynb 需要 MindSpore CANN workbench 镜像以及随附的 MindSpeed-Core-MS 源码树。
• 所选 parallel 配置会影响内存使用、权重转换和运行时布局。如果你更改 TP 或 PP，请在训练前重新转换权重。
• 在离线或受限环境中，请为基于 PyTorch 的 notebook 准备好 MindSpeed-LLM 仓库，并将所需的模型和数据集文件直接放入工作区。MindSpore notebook 使用的是镜像中随附的源码树。