---
name: ascend-llm-training
description: 使用 LLaMA-Factory 或 ms-swift 在 ModelArts 训练作业中使用昇腾 NPU 交付大模型微调，包括离线资产、训练镜像、SWR 与 OBS 准备、数据格式、单机与多节点启动、checkpoint 及 LoRA 导出。面向 ModelArts 昇腾训练，不用于独立 Docker 训练、GPU 训练、vLLM 推理部署或 CV 训练。
license: MIT
metadata:
  version: 0.2.1
  author: xuopoj
---

# ModelArts 昇腾大模型训练

本技能面向 ModelArts 平台上的昇腾 NPU 训练作业。
按客户选择使用 LLaMA-Factory 或 ms-swift，不为同一任务同时引入两套框架。
LLaMA-Factory 流程提取自用户确认已验证的 trainmaster；验证范围见
[来源与验收](references/validation.md)。ms-swift 为官方文档适配路线，尚无本项目硬件验证。

## 确认范围

在询问区域、SWR 或 OBS 详情之前，先确认连通性与交付方式：

> 当前环境能否访问您的华为云或私有云端点，以便我们直接准备并上传资产？还是先在这里生成交付包，由您离线转移到目标环境？

- **直接访问：** 在准备上传资产或创建作业时，按需确认目标端点、区域、SWR 组织、
  镜像 tag 及 OBS 输入 / 输出路径。
- **离线转交：** 先生成自包含交付包，包含脚本、配置、依赖要求和转移说明。
  目标地址使用明确占位符，将区域、SWR 和 OBS 问题推迟到目标环境实际准备上传或创建作业时；
  不因这些信息尚未填写而阻塞本地打包。

确认框架及版本、模型快照与模板、训练目标（SFT / DPO 等）、LoRA / 全参等方式、
芯片和 CPU 架构、节点与每节点设备数量、现有镜像及 ModelArts 训练作业的资源规格与通道配置。
不要将推理 1.0 / 2.0 的限制套用到训练作业。
确认数据来源、格式、训练 / 验证划分、输出空间、是否续训，以及联网条件。
缺少信息时先完成独立准备，将影响启动的缺口明确记录，不猜镜像标签或模型支持。
LoRA 任务主动建议随包提供 adapter 推理、合并配置和合并后推理配置，便于快速验收；
用户已要求完整验证时直接包含，明确只要训练时不扩展交付范围。

## 交付流程

1. 按框架读取 [LLaMA-Factory](references/llamafactory.md) 或
   [ms-swift](references/ms-swift.md)。先确认已安装版本支持模型、模板和训练方式。
2. 阅读 [ModelScope 模型准备](references/modelscope.md) 和
   [ModelArts 与存储](references/modelarts.md)，准备镜像、完整模型、数据和脚本。
   默认从 ModelScope 下载，优先复用已核对完整的 OBS 快照；用户指定其他来源时遵循其选择。
   按所选交付方式，由当前环境或接收方在目标环境将镜像推送到目标 SWR 组织，
   将权重、数据及外置脚本上传 OBS，
   在 ModelArts 训练作业中配置模型和数据输入通道、代码目录与输出保存。
3. 根据目标生成自包含目录：配置、必要启动脚本、中文 README、meta.yaml。
   LLaMA-Factory 的 LoRA 验收包包含 train.yaml、infer.yaml、export.yaml 和 infer_merged.yaml，
   路径、模型快照、模板与实际 adapter 保持一致；其他框架使用各自已确认版本的接口。
   不打包真实权重、批量数据、安装包、凭证或本机项目路径。
4. 验证离线输入和可写输出；按单卡、单机多卡、所需多节点范围进行短跑，
   检查 checkpoint、恢复和导出。验收记录见 [来源与验收](references/validation.md)。

ModelArts 训练的 OBS 输入以 `/home/ma-user/modelarts/inputs/` 为基础目录，
模型和数据使用页面实际分配的输入通道名称，例如 MODEL_0、DATASET_1。
代码使用作业页面的“代码目录”，下载到 `/home/ma-user/modelarts/user-job-dir`，
不额外配置 SCRIPTS 输入通道；.sh 入口使用 bash 执行。
输入通道编号不固定，生成配置时确认实际路径。
模型输入只读，缓存放本地可写盘；训练输出使用
`/home/ma-user/modelarts/outputs/OUTPUT_0`，可按实验名建子目录，明确平台如何保存到 OBS。
构建通用镜像时可使用已安装的 ascend-npu-image-build；没有该技能也按存储参考中的要求交付。

## 核心约束

- 保留已验证的 CANN / torch / torch_npu 配套。所有依赖在构建期准备，启动时不安装。
- 模型、tokenizer、processor、数据及多模态附件提前准备，运行时不隐式下载。
- 普通 DDP 每卡复制模型；增加节点不会自动合并显存。LoRA 仍需加载基础模型。
  分片、量化及融合算子必须确认框架、版本与 NPU 支持，不能照搬 CUDA 配置。
- 训练 rank table 默认使用 `/user/config/jobstart_hccl.json` 的顶层
  `server_list` / `server_id` 结构，详见存储与分布式参考。
- 每节点启动一次框架 launcher，由它派生每卡进程，避免 torchrun 嵌套。
  使用平台分配的设备，不固定宿主机设备编号。
- 示例参数是短跑起点，不是所有模型的最优值。数据和模型模板不得跨框架机械复制。
- 已验证来源不代表新模型、新镜像或新拓扑已验证；分别记录构建、设备、训练、恢复与导出状态。