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

基于 Workbench 的配方，用于在搭载华为 Ascend NPU 的 arm64 节点上运行全参数 SFT 和预训练。这些 notebook 会直接在单个挂载了多个 NPU 的 workbench 容器内执行训练（不使用 VolcanoJob）。

这三个 notebook 都采用 先验证后扩展 的方式：默认使用较短的序列和较少的迭代次数，便于你在扩展规模之前先确认运行时、模型加载、预处理和分布式启动路径是否正常。PyTorch CANN 镜像包含 Python 3.12、CANN 8.5.0、PyTorch 2.9.0 和 torch_npu 2.9.0。

#开始之前

• 已安装 Ascend driver、CANN runtime 和 Kubernetes device plugin；你的 workbench 可以调度到 arm64 Ascend 节点。
• PyTorch 示例建议至少准备 ≥ 4 个 NPU；MindSpore notebook 针对 2× Ascend 910B 32G 进行了调优，参数为 TP=1、PP=1、MBS=2。
• 工作区使用持久化存储，并预留了 HuggingFace 模型以及转换后的 Megatron / MCore 权重所需的空间。
• 网络要求：PyTorch notebook 会在运行时从 https://gitcode.com/ascend/MindSpeed-LLM.git 克隆 MindSpeed-LLM。如果 workbench 无法访问该地址，请在工作区中放置一份本地副本，并更新第一段代码单元中的路径。MindSpore notebook 使用 /opt/app-root/share/MindSpeed-Core-MS 下内置的代码树，不会执行任何克隆操作。

请按照 创建 Workbench 创建 workbench（PyTorch CANN 或 MindSpore CANN），并通过 JupyterLab 文件浏览器上传 notebook。

#准备基础模型

每个 notebook 都期望在以下路径提供 HuggingFace 格式模型：

你可以将模型文件直接放到这些路径下，或者在第一个参数单元中修改 HF_MODEL_DIR。如果是可版本化、可复用的模型，建议先推送到平台模型仓库，再按 通过 Notebook 上传模型 的方式从仓库中拉取。

这三个 notebook 都会在训练前将 HF 转换为 Megatron / MCore；因此磁盘上应预留第二份较大的权重目录。

#准备数据集

#微调数据（Alpaca 风格 JSONL）

两个微调 notebook 都期望以下数据：

• ALPACA_PARQUET = /opt/app-root/src/datasets/alpaca/train-00000-of-00001-a09b74b3ef9c3b56.parquet
• RAW_DATA_FILE = .../finetune_dataset/alpaca_sample.jsonl（位于 notebook 的工作目录下）

如果 parquet 文件存在，notebook 会自动将其转换为 JSONL。如果你已经有 JSONL 文件，请将其放到 RAW_DATA_FILE 对应位置，或者更新该变量。期望的记录格式如下：

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

你也可以通过修改参数单元中的 handler，在 ShareGPT 和 Pairwise 格式之间切换。

#预训练数据（原始文本）

MindSpeed-LLM 的预处理支持 .parquet、.json、.jsonl 和 .txt。结构化格式需要包含 text 字段；纯文本则要求每行一个片段。默认使用相同的 ALPACA_PARQUET 路径；如果该文件缺失，notebook 会回退到内置样本，以便你仍然可以验证整个 pipeline。

对于更大的数据集，可以挂载 PVC 或从平台数据仓库拉取——参见 使用 Workbench 进行 LLM 微调。

#运行 notebook

每个 notebook 的流程基本一致：

1. 环境检查 — 确认 torch_npu（或 mindspore + msadapter）、MindSpeed 和 MindSpeed-LLM 可以导入，并且可用的 NPU 数量与 TP × PP 一致。
2. 数据集准备 — 将 parquet 转换为 JSONL（或者在预训练时回退到内置样本）。
3. HF → MCore 权重转换 — 将权重写入与 TP/PP 对应的输出目录。
4. 数据预处理 — 生成 MindSpeed 所需的 .bin / .idx 文件。
5. 训练 — SFT 使用 posttrain_gpt.py，预训练使用 pretrain_gpt.py。MindSpore notebook 使用 msrun，并带上 --ai-framework mindspore --ckpt-format msadapter，日志写入 .../logs。
6. 验证 — 检查 latest_checkpointed_iteration.txt，列出 iter_* 目录，并且（对于 PyTorch SFT）执行一次快速推理 smoke test。

MindSpore SFT notebook 与上游 Qwen3 路径保持一致：

• 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

MindSpore 默认参数：TP=1、PP=1、MBS=2、SEQ_LENGTH=2048、TRAIN_ITERS=100、ENABLE_THINKING=true。

#需要检查的参数

所有 notebook 通用的参数如下：

• HF_MODEL_DIR、OUTPUT_DIR
• ALPACA_PARQUET 或 RAW_DATA_FILE
• TP、PP（以及 MindSpore 的 MBS）
• SEQ_LENGTH、TRAIN_ITERS
• ENABLE_THINKING（Qwen3）
• MASTER_ADDR、MASTER_PORT、NNODES、NODE_RANK（多节点 MindSpore）

对于正式运行，请将 SEQ_LENGTH 提高到模型的上下文窗口大小，将 TRAIN_ITERS 提高到生产级数值，并根据可用 NPU 数量和数据集大小调整并行度 / batch size。如果你修改了 TP 或 PP，请重新执行权重转换，以确保 checkpoint 布局匹配。

#输出路径

请将这些输出保存在持久化存储中。若要将结果推送到模型仓库，请使用 通过 Notebook 上传模型 中介绍的 Git LFS 工作流。

#说明

• 这些 notebook 执行的是全参数 SFT，而不是 LoRA。请将默认配置视为 smoke test，并在正式运行前进行调优。
• MindSpore notebook 只验证 checkpoint 生成；不包含稳定的推理步骤。
• 对于离线 / 受限集群：请提前在工作区中预置 MindSpeed-LLM 仓库以及模型 / 数据集文件（PyTorch notebooks）。MindSpore notebook 仅使用内置源码树。