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

#背景

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

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

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

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

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

#开始之前

请确保集群已经提供可用的 Ascend runtime。实际上，这意味着 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 都会创建转换后的模型权重、预处理输出、日志和检查点，因此 workspace 应使用持久化存储，并为原始 HuggingFace model 以及转换后的 Megatron/MCore 权重预留足够的可用容量。

基于 PyTorch 的 notebook 在执行期间会从 https://gitcode.com/ascend/MindSpeed-LLM.git 克隆 MindSpeed-LLM。如果 workbench 无法访问该仓库，请在 workspace 中放置本地副本，并更新第一个参数单元中的 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。请将 workspace 保持在持久化存储上，以便 notebook、转换后的权重和训练输出在重启后仍可用。如果你遵循 notebook 的默认配置，请申请足够的 NPU 资源，以满足已配置的 tensor parallelism 和 pipeline parallelism。

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

#导入验证 Notebook

将你计划使用的 notebook 上传到 JupyterLab workspace 并在其中打开。如果你的镜像发行版已经在 workspace 中暴露了这些 notebook，则可以直接使用它们。否则，请从上方链接下载，并通过 JupyterLab file browser 上传。JupyterLab 上传流程请参阅 创建 Workbench。

#准备基础模型

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

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

如果你希望该模型可以进行版本管理并在多个 workbench 之间复用，请先将其上传到平台 model repository，然后再克隆或复制到 workspace 中。基于 repository 的上传流程记录在 使用 Notebook 上传模型。

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

#准备数据集

微调和预训练 notebook 需要不同类型的输入数据。

#微调数据

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

默认情况下，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 会回退到一个内置的小样本，以便仍然可以验证预处理和训练流程。

#将数据导入 Workspace

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

#运行微调 Notebook

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

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

默认配置是有意设置得较为保守的。它使用较短的序列长度和较少的迭代次数，因此该 notebook 更适合作为环境验证工具，而不是长时间的生产训练任务。一旦该路径能够正常工作，就可以切换到真实数据集，并针对实际工作负载调整参数。

最重要的参数包括：

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

对于真实微调，建议将 SEQ_LENGTH 增加到与模型上下文窗口匹配的值，将 TRAIN_ITERS 增加到生产规模，并根据可用 NPU 数量和训练集大小调整并行度和 batch 大小。如果你希望定期保存 checkpoint，还需要更新训练单元中的保存间隔。

#运行 MindSpore 微调 Notebook

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

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

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

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

• HF_MODEL_DIR
• 诸如 ALPACA_PARQUET 之类的数据集路径变量
• OUTPUT_DIR
• TP 和 PP
• SEQ_LENGTH
• TRAIN_ITERS

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

#输出与持久化

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

请将这些目录保留在持久化存储上。输出可能非常大，在大多数真实工作流中，你会希望在 workbench 重启后继续保留这些内容，或者将其发布以供后续使用。如果你想将生成的模型推回 model repository，请遵循 使用 Notebook 上传模型 中的 Git LFS 工作流。

#运维说明

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