华为云用户手册

前提条件 已开通Lite Server资源，并确保机器已开通，密码已获取，能通过SSH登录，不同机器之间网络互通。 （多机运行分布式训练）已购买可挂载的存储硬盘资源，以实现多机共同访问同一存储硬盘资源，存储方案请参考配置Lite Server存储；支持在裸金属服务器中挂载的有弹性文件服务SFS和云硬盘EVS。 安装过程需要连接互联网git clone，确保容器可以访问公网。 当容器需要提供服务给多个用户，或者多个用户共享使用该容器时，应限制容器访问Openstack的管理地址（169.254.169.254），以防止容器获取宿主机的元数据。具体操作请参见禁止容器获取宿主机元数据。

performance problem analysis模块介绍 perfomance problem analysis中会细分为计算（computation），下发（schedule），通信（communication）、内存（memory）和数据加载（dataloader）五个维度，根据训练作业卡数、训练实际性能问题有不同的呈现，并非所有训练任务都有上述五个维度的分析。 图10 html报告总览-性能分析五维度 computation 计算维度通常包含如下几类问题： 降频：对应html中的'AI CORE Frequency Issues'。NPU AICORE主频降低，导致flash attention和matmul类算子计算性能严重劣化。 AICPU算子：对应html中的'AICPU Issues'。部分算子因NPU支持度或者输入数据shape/dtype等原因，无法在AICORE上运行，因此会放在AICPU上进行计算，部分AICPU算子会存在明显的性能劣化。 动态shape：对应html中的'Operator Dynamic Shape Issues'。动态shape场景，部分昇腾算子会重复编译，导致计算延后，影响性能。 operator bound等问题：算子未打满AICORE的核数，导致计算利用率较低。 具体介绍如下： AI CORE Frequency Issues 下图展示了高优先级的降频问题，从表格中可以看到flash attention算子耗时最长且降频比率最高，因此降频严重影响了整体的训练性能。对于降频问题，用户通常无法自行解决，需要联系服务方如华为云技术支持排查机器的温度和功耗。 图11 降频分析 AICPU Issues 下图展示了高优先级的AICPU问题，AICPU算子单步计算耗时313秒，GridSample2D算子单步计算耗时208秒，因此需要重点关注该算子。可以通过html中提供的堆栈信息查看源码中对该算子的调用是否可以替换成其他torch api，如果分析后无法替换可以求助昇腾算子侧的算子开发人员进行算子优化分析。 图12 AICPU算子分析 Operator Dynamic Shape Issues 下图展示了低优先级的动态shape问题，在NPU上动态shape可能导致频繁的算子编译从而影响训练性能，可以按照html中的提示在训练脚本开头加上如下红框中的两行代码（分布式训练请确保分布式训练的每个进程都可以使能这两行代码）。 图13 动态shape分析 schedule 下发维度通常包含如下几类问题 同步流：对应html中的'Synchronize Stream Issues'。用户设置了ASCEND_LAUNCH_BLOCKING环境变量，打断了CPU侧算子的异步下发，严重影响训练性能。 GC：对应html中的'GC Analysis'。python garbage collection机制，大规模集群训练时GC任务会导致部分step训练耗时异常增大。 算子下发：对应html中的'Operator Dispatch Issues'。训练时如果频繁进行算子编译会严重影响训练性能，可以增加两行python代码关闭算子编译。 亲和API：对应html中的'Affinity API Issues'。通过使能亲和API（NPU融合算子API如rms_norm，NPU亲和优化器如NPUFusedAdamw）可以减少算子下发数量，从而提升训练性能。 syncBatchNorm：对应html中的'SyncBatchNorm Issues'。多卡DDP训练时如果使用syncBatchNorm，会存在明显的算子下发和通信瓶颈。 具体介绍如下： Synchronize Stream Issues 下图展示了高优先级的同步流问题，html中提示发现大量同步算子，可以尝试`unset ASCEND_LAUNCH_BLOCKING` 环境变量后再进行训练。 图14 异常同步流分析 GC Analysis 下图展示了中优先级的GC问题，html中提示发现单步训练中存在200ms左右的空闲时间且在该时间窗内cpu侧没有进行训练算子下发，怀疑是GC导致，可以尝试加上`gc.disable()`关闭GC。 图15 python垃圾回收（GC）分析 Operator Dispatch Issues 下图展示了中优先级的算子下发问题，html中提示识别到单步训练中存在6678个算子进行了算子编译，编译耗时149ms，可以在训练脚本最开头加上suggestion中的两行代码关闭算子编译（分布式训练请确保每个进程都可以使能这两行代码）。 图16 算子编译分析 Affinity API Issues 下图展示了低优先的亲和API替换，通常仅在首次将训练任务从GPU迁移至NPU时需要关注这部分内容。已经在NPU上进行长训的任务出现性能问题，可以忽略该部分。html中提示存在torch_npu.confusion_transpose, 梯度裁剪和亲和优化器等多个可替换的API，用户可根据代码堆栈找到需要替换的具体源码，然后根据API instruction跳转后的参考文档修改源代码，从而使能亲和API提升训练性能。注意这里提示的亲和API并非都能提升训练性能，需要用户替换后实测，由于有一定代码修改和测试成本，因此优先级可以视作最低。 图17 亲和API分析 SyncBatchNorm Issues 下图展示了高优先级的syncBatchNorm问题，html中提示可以通过去除convert_sync_batchnorm代码使能普通的batchNorm，如果模型开发者评估认为对训练精度存在影响，可以使用html中给出的代码段替换torch_npu中syncbatchnorm.py文件的forward方法（可以在训练环境中执行`pip show torch_npu`查看torch_npu的安装路径）。这类优化通常可以较显著地提升训练速度。 图18 SyncBatchNorm分析 memory 内存维度当前识别的问题较为简单，通常是NPU HBM占用过大或者存在内存碎片导致自动触发昇腾内存释放/重整算子（Memory Operator Issues），进而影响了训练性能。 下图展示了高优先级的内存算子问题，html中提示对于1号卡存在大量aclrtFree和aclMalloc算子，导致存在较大的空闲时间。按照建议，对于aclrtFree算子类问题，首先观察NPU HBM是否已经打满，如果打满则尝试减小micro batch size或者调整训练策略，例如训练LLM模型时使用ZeRO 3优化内存。其次采集profiling时设置“with_stack=True参数”，然后基于MindInsight Studio可视化profiling数据查看代码中是否存在empty_cache操作，如果存在则注释对应代码。对于aclMalloc算子类问题，按照建议设置环境变量即可减少内存碎片。 图19 内存算子分析 dataloader 数据加载维度（Slow Dataloader Issues）通常包含如下几类问题： 数据放在读写性能较差的存储盘上，如云上的EVS和EFS。 多卡训练时使用单进程dataloader，即num_workers参数默认为0。 存在其他多进程操作影响了数据多进程读取。 数据格式问题，例如zip、tar.gz等压缩包。 dataloader参数设置不合理，如没有配置锁页内存pin_memory=True。 下图中展示了高优先级的dataloader问题，较慢的数据加载将会严重影响训练速度。html中提示分别从数据盘、多进程、dataloader参数设置、数据格式等不同方向进行排查。 图20 数据加载分析 communication 通信维度当前支持检测如下几类问题。 通信计算并行时抢占通信带宽：对应html中的'BandWidth Contention Analysis'。在LLM类模型训练过程中，对于megatron类框架可以配置overlap相关参数使能计算和通信互相掩盖，进而提升训练性能。但部分场景中计算抢占通信带宽反而会导致性能劣化。 小包分析：对应html中的'Packet Analysis'。当BatchSize较小或其他场景，并没有打慢NPU HBM，卡间通信数据包较小，没有充分利用通信带宽。 RDMA重传（跨节点通信）：对应html中的“Communication Retransmission Analysis”。当网络通信配置出现冲突情况下，RDMA通信传输可能出现重传，导致通信耗时异常大幅增加。 具体介绍如下： BandWidth Contention Analysis 下图展示了低优先级的通信带宽抢占问题，大部分场景中通信计算互相掩盖是有较大训练性能收益的，可以通过修改overlap或其他相关参数来测试是否存在性能提升。 图21 通信带宽抢占分析 Packet Analysis 下图展示了低优先级的通信小包问题，html中提示SDMA（机内通信）带宽相对较小，可以尝试增大batchSize或者梯度累积参数，如果配置了ZeRO3则推荐使用ZeRO1或者ZeRO2（如果内存够）。 图22 通信小包分析 Communication Retransmission Analysis 单次通信重传将会耗时4秒以上，会导致较严重的通信性能劣化，这类问题通常是由于节点网络配置错误导致，可以联系服务方如华为云技术支持排查网络配置。 图23 通信重传分析

html总览 html中包括总体性能分析（overall）、快慢卡算子性能比对（comparison）和性能问题分析（performance problem analysis）三大模块。overall模块包含对单卡或者集群的性能统计数据，comparison模块包含目标集群profiling与标杆集群profiling或目标集群内部快慢卡的算子比对数据，performance problem analysis模块包含计算（computation）、下发（schedule）、通信（communication）、内存（memory）和数据加载（dataloader）五个维度的具体分析。用户首先需要查看overall模块初步明确是否存在计算维度的慢卡和下发维度慢卡，然后再重点关注performance problem analysis中对应维度的各项分析及其优先级。 红色为高优先级，黄色为中等优先级，绿色为低优先级。参考html进行分析调优时，请按照优先级从高到低依次进行并测试调优后性能，快速解决重点问题。 图1 html报告总览-三大模块 当前advisor的performance problem analysis中包含如下分析项。 表1 性能分析能力概览 分析维度 分析项 释义 overall overall summary 对于单卡profiling进行性能拆解，获取单步计算、下发和通信耗时。 slow rank 对于集群profiling进行性能统计，获取每张卡不同step的计算、下发和通信耗时。 slow link 对于集群profiling进行性能统计，获取每张卡不同step的带宽信息。 environment variable 识别错误配置且会影响性能的环境变量，如P LOG 日志级别，HCCL相关环境变量，依赖24年930版本的pta。 comparison kernel compare 两张卡NPU侧计算算子对比。 api compare 两张卡CPU侧torch aten算子下发对比。 performance problem analysis computation - AI CORE frequency 计算维度，识别降频的节点，节点降频会导致flash attention和matmul类算子计算性能变差。 computation - AICPU 计算维度，识别AICPU算子，部分AICPU算子计算性能较差。 computation - operator dynamic shape 计算维度，检测动态shape，动态shape会触发频繁的算子编译。 computation - operator bound 计算维度，算子计算性能分析，例如算子是否充分使用AICORE核数。 schedule - synchronize stream 下发维度，异常同步流分析，过多同步流会打断CPU侧任务异步下发。 schedule - garbage collection(GC) 下发维度，识别异常耗时的垃圾回收，垃圾回收会造成大段空闲。 schedule - operator dispatch 下发维度，算子下发时编译分析，大量算子编译会导致整体训练性能变差。 schedule - syncBatchNorm 下发维度，NPU上分布式训练使用syncBN性能较差。 schedule - affinity api 下发维度，自动识别可替换的亲和API（融合算子API如rms_norm，亲和优化器如NpuFusedAdamw）。 communication - small packet 通信维度，识别因batch过小或者梯度累积较少导致的未充分利用机内通信带宽。 communication - bandwidth contention 通信维度，识别计算和通信相互掩盖，可能会抢占通信带宽。 communication - retransmission 通信维度，识别通信重传问题，单次重传耗时4秒以上。 memory 内存维度，识别异常内存算子。 dataloader 数据加载维度，异常耗时的数据读取将会导致明显的训练性能劣化。

overall模块介绍 单卡overall summary 下图展示了单卡上一个step的端到端耗时为1353ms，其中计算耗时（昇腾硬件上算子执行耗时）是57ms，未掩盖通信耗时为0ms，空闲耗时（硬件上没有进行计算和通信的其他时间）为1295ms。基于这三项数据可以初步判断当前训练任务的主要耗时瓶颈为空闲耗时。空闲耗时通常是任务下发(schedule)、数据加载(dataloader)和内存(memory)三个维度问题导致的，因此可以重点关注performance problem analysis中对应三个维度的分析。同理如果计算耗时占比较大，则应该重点关注计算维度的分析。 图2 单卡性能拆解总体描述 图3 单卡性能拆解详情 多卡slow rank & slow link 下图展示了多卡profiling分析的overall模块，包含集群快慢卡统计数值(slow rank，用于分析计算和任务下发的快慢卡)和集群带宽统计数值(slow link，用于分析集群中的网络通信慢链路)。点开slow rank模块，html中会基于表格展示每张卡不同step的计算耗时、通信耗时和空闲耗时。基于该表格，通常关注计算耗时(compute)和空闲耗时(free)这两列，可以初步分析当前瓶颈点是计算还是任务下发，以及是否存在计算快慢卡和下发快慢卡。如下图所示，可以看到8号卡的计算耗时明显大于其他卡，因此8号卡的“短板效应”将会拖慢集群的整体训练速度，后续性能分析需要重点关注8号卡的计算维度。 图4 多卡不同step计算、下发和通信耗时统计值 图5 多卡不同step通信带宽统计值 环境变量Environment Variable Issues 识别模型训练环境中设置的昇腾相关环境变量并给出建议。 图6 环境变量分析 表2 当前支持的环境变量 环境变量名称 释义 ASCEND_GLOBAL_LOG_LEVEL plog日志级别，推荐设置为2（warning级别），低级别日志等级会导致cpu侧性能问题。 HCCL_RDMA_TC HCCL通信相关环境变量，通常无需设置该环境变量，建议unset该环境变量。具体参考拥塞控制与纠错配置策略 HCCL_RDMA_SL HCCL通信相关环境变量，通常无需设置该环境变量，建议unset该环境变量。具体参考拥塞控制与纠错配置策略 ACLNN_CACHE_LIMIT 用于缓存cann侧的aclnn算子，当空闲时间（free）较大时，可以尝试设置一个较大的数值，如export ACLNN_CACHE_LIMIT=100000 HOST_CACHE_CAPACITY 用于动态shape缓存，当存在动态shape时，设置一个非零正整数，如export HOST_CACHE_CAPACITY=20 ASCEND_ENHANCE_ENABLE 使能HCCL的FFTS+模式，export ASCEND_ENHANCE_ENABLE=1 PYTORCH_NPU_ALLOC_CONF 控制缓存分配，当存在内存碎片时，执行export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True ASCEND_LAUNCH_BLOCKING 是否启动同步下发，同步下发会导致严重的性能劣化，建议执行unset ASCEND_LAUNCH_BLOCKING

comparison模块介绍 当同时指定目标集群profiling和标杆集群profiling或者目标集群内部存在快慢卡时，advisor会针对计算和下发性能存在差异的卡（快慢卡）进行算子级的对比。 如下图所示，当分析时显式指定了标杆集群profiling数据，advisor识别到两次训练任务中0号卡的step12存在计算性能差异，则会对目标集群的0号卡step12与标杆集群的0号卡step12进行kernel（npu侧计算的算子）性能对比。基于该对比数据，可以判断两张卡上的npu算子是否存在计算性能差异。 图7 目标集群profiling数据与标杆集群profiling数据的kernel算子对比 如下图所示，当分析时显式指定了标杆集群profiling数据，advisor识别到两次训练任务中6号卡的step16存在api下发性能差异，对目标集群的6号卡step16与标杆集群的6号卡step16进行了api（cpu侧的torch aten算子任务下发）的性能对比。基于该对比数据，可以判断两张卡上的aten算子是否存在下发性能差异。 图8 目标集群profiling数据与标杆集群profiling数据的api下发对比 如下图所示，分析时并没有指定标杆集群profiling数据，但advisor识别到目标集群存在任务下发快慢卡（16和19号卡）现象，因此对比了16号卡step175和19号卡step172的api下发性能。 图9 目标集群（无标杆集群profiling）内部快慢卡api下发对比

步骤五：CogVideo微调 下载模型权重 下载CogVideoX1.5 5b模型，huggingface地址如下 https://huggingface.co/THUDM/CogVideoX1.5-5B 准备数据集 数据集可参考使用如下数据集 https://huggingface.co/datasets/Wild-Heart/Tom-and-Jerry-VideoGeneration-Dataset 进行data cache 由于CogVideoX1.5对显存需求较大，直接训练显存不足，训练采用data cache，将text encoder和vae两个不参与训练的模型对数据集进行预编码处理。 cd /home/ma-user/finetrainers 对/home/ma-user/finetrainers/prepare_dataset.sh文件进行修改，配置对应的参数： MODEL_ID="path/CogVideoX1.5-5B" # 模型路径 DATA_ROOT="path/Tom-and-Jerry-VideoGeneration-Dataset" # 数据集路径 CAPTION_COLUMN="captions.txt" # 数据集提示词文件名 VIDEO_COLUMN="videos.txt" # 数据集视频名文件名 OUTPUT_DIR="path/preprocessed-Tom-dataset" # 预编码处理的tensor数据集输出路径 修改后，执行prepare_dataset.sh脚本 bash prepare_dataset.sh 进行模型训练 cd /home/ma-user/finetrainers 对finetrainers/train_text_to_video_sft.sh文件进行修改，配置训练使用的超参数： MAX_TRAIN_STEPS=("20000") # 最大训练步数 DATA_ROOT="path/preprocessed-Tom-dataset" # 预编码处理的tensor数据集路径，即data cache的输出路径 CAPTION_COLUMN="prompts.txt" # 数据集提示词文件名 VIDEO_COLUMN="videos.txt" # 数据集视频名文件名 MODEL_PATH="THUDM/CogVideoX1.5-5B" # 模型路径 output_dir="/path/to/my/models/cogvideox-sft # 模型输出路径 修改后，执行train_text_to_video_sft.sh脚本 bash train_text_to_video_sft.sh 以上微调文档提示来自官方文档，有关可用微调脚本参数及其功能的全面文档，您可以参考官方finetrainers中CogVideo训练文档。

步骤三：启动容器镜像 启动容器镜像。启动前请先按照参数说明修改${}中的参数。 export work_dir="自定义挂载的工作目录" export container_work_dir="自定义挂载到容器内的工作目录" export container_name="自定义容器名称" export image_name="镜像名称或ID" // 启动一个容器去运行镜像 docker run -itd --net=bridge \ --device=/dev/davinci0 \ --device=/dev/davinci1 \ --device=/dev/davinci2 \ --device=/dev/davinci3 \ --device=/dev/davinci4 \ --device=/dev/davinci5 \ --device=/dev/davinci6 \ --device=/dev/davinci7 \ --device=/dev/davinci_manager \ --device=/dev/devmm_svm \ --device=/dev/hisi_hdc \ --shm-size=256g \ -v /usr/local/dcmi:/usr/local/dcmi \ -v /usr/local/Ascend/driver:/usr/local/Ascend/driver \ -v /var/log/npu/:/usr/slog \ -v /usr/local/sbin/npu-smi:/usr/local/sbin/npu-smi \ -v ${work_dir}:${container_work_dir} \ --name ${container_name} \ ${image_name} \ /bin/bash 参数说明： -v ${work_dir}:${container_work_dir}：代表需要在容器中挂载宿主机的目录。宿主机和容器使用不同的文件系统。work_dir为宿主机中工作目录，目录下可存放项目所需代码、数据等文件。container_work_dir为要挂载到的容器中的目录。为方便两个地址可以相同。 容器不能挂载到/home/ma-user目录，此目录为ma-user用户家目录。如果容器挂载到/home/ma-user下，拉起容器时会与基础镜像冲突，导致基础镜像不可用。 driver及npu-smi需同时挂载至容器。 --name ${container_name}：容器名称，进入容器时会用到，此处可以自己定义一个容器名称。 ${image_name}：容器镜像的名称。 --device=/dev/davinci0 ：挂载对应卡到容器，当需要挂载多卡，请依次添加多项该配置 通过容器名称进入容器中。默认使用ma-user用户，后续所有操作步骤都在ma-user用户下执行。 docker exec -it ${container_name} bash

步骤四：安装依赖和软件包 git clone和git lfs下载大模型可以参考如下操作。 由于欧拉源上没有git-lfs包，所以需要从压缩包中解压使用，在浏览器中输入如下地址下载git-lfs压缩包并上传到容器的/home/ma-user目录下。 https://github.com/git-lfs/git-lfs/releases/download/v3.2.0/git-lfs-linux-arm64-v3.2.0.tar.gz 或直接下载到容器，这样在容器中可以直接使用。 cd /home/ma-user wget https://github.com/git-lfs/git-lfs/releases/download/v3.2.0/git-lfs-linux-arm64-v3.2.0.tar.gz 进入容器，执行安装git lfs命令。 cd /home/ma-user tar -zxvf git-lfs-linux-arm64-v3.2.0.tar.gz cd git-lfs-3.2.0 sudo sh install.sh 设置git配置去掉ssl校验。 git config --global http.sslVerify false 从github拉取finetrainers代码。 cd /home/ma-user git clone https://github.com/a-r-r-o-w/finetrainers.git cd /home/ma-user/finetrainers git checkout 80d1150a0e233a1 若进行训练微调需依赖decord包，arm版本可参考附录安装编译。 由于当前CogVideoX1.5版本依赖的diffuser暂未合入主线，需安装分支版本diffuser cd /home/ma-user git clone https://github.com/zRzRzRzRzRzRzR/diffusers cd /home/ma-user/diffusers/ git checkout cogvideox1.1-5b git checkout ea166f85ad0090d182ec5f0 pip install -e . 安装CogVideo Ascend软件包。 将获取到的CogVideo Ascend软件包AscendCloud-AIGC-*.zip文件上传到容器的/home/ma-user目录下。获取路径参见获取软件和镜像。 解压AscendCloud-AIGC-*.zip文件，解压后将里面指定文件与对应CogVideo文件进行替换，执行以下命令即可。 cd /home/ma-user unzip AscendCloud-AIGC-*.zip -d ./AscendCloud cd AscendCloud/multimodal_algorithm/CogVideoX_1_5/ dos2unix install.sh bash install.sh AscendCloud-AIGC-*.zip后面的*表示时间戳，请按照实际替换。 CogVideo Ascend软件包内容如下： . |---- install.sh 安装torch-npu适配修改脚本 |---- modify.patch 适配CogVideo训练代码git patch文件 |---- README.md 适配文档基于官方代码commit id说明 |---- requirements.txt python依赖包

步骤一：准备环境 请参考Lite Server资源开通，购买Server资源，并确保机器已开通，密码已获取，能通过SSH登录，不同机器之间网络互通。 当容器需要提供服务给多个用户，或者多个用户共享使用该容器时，应限制容器访问Openstack的管理地址（169.254.169.254），以防止容器获取宿主机的元数据。具体操作请参见禁止容器获取宿主机元数据。 SSH登录机器后，检查NPU设备检查。运行如下命令，返回NPU设备信息。 npu-smi info # 在每个实例节点上运行此命令可以看到NPU卡状态 npu-smi info -l | grep Total # 在每个实例节点上运行此命令可以看到总卡数 如出现错误，可能是机器上的NPU设备没有正常安装，或者NPU镜像被其他容器挂载。请先正常安装固件和驱动，或释放被挂载的NPU。 检查docker是否安装。 docker -v #检查docker是否安装 如尚未安装，运行以下命令安装docker。 yum install -y docker-engine.aarch64 docker-engine-selinux.noarch docker-runc.aarch64 配置IP转发，用于容器内的网络访问。执行以下命令查看net.ipv4.ip_forward配置项的值，如果为1，可跳过此步骤。 sysctl -p | grep net.ipv4.ip_forward 如果net.ipv4.ip_forward配置项的值不为1，执行以下命令配置IP转发。 sed -i 's/net\.ipv4\.ip_forward=0/net\.ipv4\.ip_forward=1/g' /etc/sysctl.conf sysctl -p | grep net.ipv4.ip_forward

获取软件和镜像 表2 获取软件和镜像 分类 名称 获取路径 插件代码包 AscendCloud-6.5.901软件包中的AscendCloud-AIGC-6.5.901-xxx.zip 说明： 包名中的xxx表示具体的时间戳，以包名的实际时间为准。 获取路径：Support-E，在此路径中查找下载ModelArts 6.5.901 版本。 说明： 如果上述软件获取路径打开后未显示相应的软件信息，说明您没有下载权限，请联系您所在企业的华为方技术支持下载获取。 基础镜像 西南-贵阳一： swr.cn-southwest-2.myhuaweicloud.com/atelier/pytorch_2_1_ascend:pytorch_2.1.0-cann_8.0.rc3-py_3.9-hce_2.0.2409-aarch64-snt9b-20241213131522-aafe527 从SWR拉取。

工具总览 ModelArts集成了多个昇腾迁移调优工具，方便您在ModelArts平台环境中进行训练推理迁移、精度调试、性能调优等工作，您可在下表中查看当前ModelArts支持的昇腾迁移调优工具及对应指导。 表格中的部分工具已集成到ModelArts基础镜像中（镜像地址详见基础镜像章节）。如果您使用的是ModelArts基础镜像，可先尝试直接使用工具命令，如果相关命令不存在则需要参考工具安装指导自行安装。 表1 ModelArts昇腾迁移调优工具总览表 使用场景 类别 工具名称 工具描述 工具安装 使用指导 PyTorch GPU训练迁移至PyTorch NPU训练 训练迁移 Transfer2NPU 代码自动迁移工具，通过简单import命令可将PyTorch训练脚本从GPU平台迁移至NPU平台运行。 包含在torch_npu包中。 自动迁移工具使用指导 训练业务代码适配昇腾PyTorch代码适配 PyTorch Analyse 迁移分析工具，可以使用工具扫描用户的训练脚本，识别出源码中不支持的torch API和cuda API信息。 包含在cann toolkit中。 分析工具使用指导 精度调优 msprobe msprobe是MindStudio Training Tools工具链下精度调试部分的工具包。主要包括精度预检、溢出检测和精度比对等功能，目前适配PyTorch和MindSpore框架。这些子工具侧重不同的训练场景，可以定位模型训练中的精度问题。 支持精度预检，可扫描训练模型中的所有API进行API复现，给出精度情况的诊断和分析。 精度比对，对PyTorch整网API粒度的数据dump、精度比对，进而定位训练场景下的精度问题 支持溢出检测功能，判断是否存在输入正常但输出存在溢出的API，从而判断是否为正常溢出。 梯度状态监控，用于采集梯度数据并进行梯度相似度比对，可以精准定位出现问题的step。 执行pip install mindstudio-probe msprobe使用手册 性能调优 PyTorch Profiler 性能采集工具，在训练脚本中调用Ascend PyTorch Profiler接口，可在训练过程中采集性能数据文件，包括PyTorch层算子信息、CANN层算子信息、底层NPU算子信息、以及算子内存占用信息等。 包含在torch_npu包中。 Ascend PyTorch Profiler数据采集与分析 MA-Advisor 性能自动诊断工具，采集好的Profiling数据通过该工具进行自动扫描分析，可给出性能瓶颈的诊断和修改建议。当迁移开箱性能较低时，通过该工具给出的建议修改代码后，通常可提升10%~30%。 执行pip install msprof-analyze 昇腾性能自动诊断工具使用说明 compare_tools 性能比对工具，将在GPU和NPU采集的Profiling数据进行性能拆解和分类比对，展示算子、通信、内存等类别的性能比对数据。 下载工具源码使用。 性能比对工具 cluster_analyse 集群性能分析工具，采集好的多机Profiling数据可通过该工具分析集群通信耗时、通信带宽矩阵等内容，从而辅助定位慢卡、慢节点等问题。工具的输出数据为csv格式，可直接拖入Ascend Insight进行可视化查看。 下载工具源码使用。 集群分析工具 MindStudio-Insight 性能可视化工具，采集好的profiling数据可通过该工具进行可视化展示，辅助人工进行profiling数据查看和分析。 windows版本工具，下载链接见教程内。 MindStudio-Insight用户指南 PyTorch GPU推理迁移至MindSpore Lite NPU推理 模型迁移 Tailor Mindspore-lite模型转换、精度误差分析、性能分析。 whl包，地址见教程中下载链接。 Tailor使用指导 性能调优 msprof msprof命令行工具提供了AI任务运行性能数据、昇腾AI处理器系统数据等性能数据的采集和解析能力。 包含在cann toolkit中。 msprof AOE 自动调优工具，提供子图调优和算子调优功能，在静态shape场景下有较好的调优效果。推荐在mindspore-lite离线推理场景下使用。 包含在cann toolkit中。 AOE性能自动调优 AKG MindSpore自动调优工具，提供算子自动优化和算子自动融合的功能，推荐在mindspore-lite离线推理场景下使用。 下载工具源码使用。 AKG PyTorch GPU推理迁移至PyTorch ascend-vllm /atb/torchair推理 模型迁移 - 需要用户自行代码适配，或者使用ModelArts迁移好的模型。 - ModelArts迁移好的模型可参考最佳实践中的案例，使用AscendCloud软件包中的模型，例如：主流开源大模型基于DevServer适配PyTorch NPU推理指导。 模型量化 modelslim 模型量化工具，通过量化提升模型的推理性能。 包含在cann toolkit中。 ModelSlim 精度调试 msit llm 大模型精度调试工具，支持加速库（atb）和torchair的大模型推理的精度数据dump及比对功能，辅助大模型推理精度问题定位。 下载工具whl包安装使用，推荐使用最新版本。 大模型推理精度工具 父主题： 迁移调优工具链

调优流程 PyTorch在昇腾AI处理器的加速实现方式是以算子为粒度进行调用（OP-based），即通过Python与C++调用CANN层接口Ascend Computing Language（AscendCL）调用一个或几个亲和算子组合的形式，代替原有GPU的实现方式，具体逻辑模型请参考PyTorch自动迁移。 在PyTorch模型迁移后进行训练的过程中，CPU只负责算子的下发，而NPU负责算子的执行，算子下发和执行异步发生，性能瓶颈在此过程中体现。在PyTorch的动态图机制下，算子被CPU逐个下发到NPU上执行。一方面，理想情况下CPU侧算子下发会明显比NPU侧算子执行更快，此时性能瓶颈主要集中在NPU侧；另一方面，理想情况下NPU侧算子计算流水线一直执行，不会出现NPU等待CPU算子下发即NPU空转的场景，如果存在，则CPU侧算子下发存在瓶颈。 图1 Host算子下发和Device算子执行 综上所述，性能优化的总体原则为：减少Host算子下发时间、减少Device算子执行时间。 训练代码迁移完成后，如存在性能不达标的问题，可参考下图所示流程进行优化。建议按照单卡、单机多卡、多机多卡的流程逐步做性能调优。 图2 性能调优总体思路 性能调优可以先将重点放在NPU不亲和的问题处理上，确保一些已知的性能问题和优化方法得到较好的应用。通用的训练任务调优、参数调优可以通过可观测数据来进行分析与优化，一般来说分段对比GPU的运行性能会有比较好的参考。算子级的调优某些情况下如果是明显的瓶颈或者性能攻坚阶段，可以联系华为工程师获得帮助。 为了便于用户快速进行迁移调优，降低调优门槛，ModelArts提供了MA-Adivisor性能自动诊断工具。用户采集性能profiling数据后，可通过该工具自动扫描profiling数据，工具分析完数据后会给出可能的性能问题点及调优建议，用户可以根据调优建议做相应的修改适配。目前该工具对CV类模型给出的调优建议较多，LLM类建议稍少，但是总体都有性能提升，实测大约可提升10%~30%的性能，并且已经在多个迁移性能调优项目中实际应用。 父主题： 性能调优

迁移环境简介 ModelArts开发环境针对推理昇腾迁移的场景提供了云上可以直接访问的开发环境，具有如下优点： 利用云服务的资源使用便利性，可以直接使用到不同规格的昇腾设备。 通过指定对应的运行镜像，可以直接使用预置的、在迁移过程中所需的工具集，且已经适配到最新的版本可以直接使用。 开发者可以通过浏览器入口以Notebook方式访问，也可以通过VSCode远程开发的模式直接接入到云上环境中完成迁移开发与调测，最终生成适配昇腾的推理应用。 当前支持以下两种迁移环境搭建方式： ModelArts Standard：在Notebook中，使用预置镜像进行。 ModelArts Lite DevServer：在裸金属服务器中 ，自助配置好存储、安装固件、驱动、配置网络等。

支持数据简介 MindSpeed-LLM框架常用数据集格式： alpaca格式 sharegpt格式 moss格式 本教程使用到的训练数据集样例是Alpaca数据集。您也可以自行准备数据集。 Alpaca数据集下载链接如下： 预训练(MindSpeed-LLM)：train-00000-of-00001-a09b74b3ef9c3b56.parquet，数据大小：24M左右。 微调：alpaca_gpt4_data.json，数据大小：43.6 MB。

步骤四：安装依赖和软件包 git clone和git lfs下载大模型可以参考如下操作。 由于欧拉源上没有git-lfs包，所以需要从压缩包中解压使用，在浏览器中输入如下地址下载git-lfs压缩包并上传到容器的/home/ma-user目录下。 https://github.com/git-lfs/git-lfs/releases/download/v3.2.0/git-lfs-linux-arm64-v3.2.0.tar.gz 或直接下载到容器，这样在容器中可以直接使用。 cd /home/ma-user wget https://github.com/git-lfs/git-lfs/releases/download/v3.2.0/git-lfs-linux-arm64-v3.2.0.tar.gz 进入容器，执行安装git lfs命令。 cd /home/ma-user tar -zxvf git-lfs-linux-arm64-v3.2.0.tar.gz cd git-lfs-3.2.0 sudo sh install.sh 设置git配置去掉ssl校验。 git config --global http.sslVerify false 从github拉取finetrainers代码。 cd /home/ma-user git clone https://github.com/a-r-r-o-w/finetrainers.git cd /home/ma-user/finetrainers git checkout 80d1150a0e233a1 若进行训练微调需依赖decord包，arm版本可参考附录安装编译。 由于当前CogVideoX1.5版本依赖的diffuser暂未合入主线，需安装分支版本diffuser cd /home/ma-user git clone https://github.com/zRzRzRzRzRzRzR/diffusers cd /home/ma-user/diffusers/ git checkout cogvideox1.1-5b git checkout ea166f85ad0090d182ec5f0 pip install -e . 安装CogVideo Ascend软件包。 将获取到的CogVideo Ascend软件包AscendCloud-AIGC-*.zip文件上传到容器的/home/ma-user目录下。获取路径参见获取软件和镜像。 解压AscendCloud-AIGC-*.zip文件，解压后将里面指定文件与对应CogVideo文件进行替换，执行以下命令即可。 cd /home/ma-user unzip AscendCloud-AIGC-*.zip -d ./AscendCloud cd AscendCloud/multimodal_algorithm/CogVideoX_1_5/ dos2unix install.sh bash install.sh AscendCloud-AIGC-*.zip后面的*表示时间戳，请按照实际替换。 CogVideo Ascend软件包内容如下： . |---- install.sh 安装torch-npu适配修改脚本 |---- modify.patch 适配CogVideo训练代码git patch文件 |---- README.md 适配文档基于官方代码commit id说明 |---- requirements.txt python依赖包

步骤五：CogVideo微调 下载模型权重 下载CogVideoX1.5 5b模型，huggingface地址如下 https://huggingface.co/THUDM/CogVideoX1.5-5B 准备数据集 数据集可参考使用如下数据集 https://huggingface.co/datasets/Wild-Heart/Tom-and-Jerry-VideoGeneration-Dataset 进行data cache 由于CogVideoX1.5对显存需求较大，直接训练显存不足，训练采用data cache，将text encoder和vae两个不参与训练的模型对数据集进行预编码处理。 cd /home/ma-user/finetrainers 对/home/ma-user/finetrainers/prepare_dataset.sh文件进行修改，配置对应的参数： MODEL_ID="path/CogVideoX1.5-5B" # 模型路径 DATA_ROOT="path/Tom-and-Jerry-VideoGeneration-Dataset" # 数据集路径 CAPTION_COLUMN="captions.txt" # 数据集提示词文件名 VIDEO_COLUMN="videos.txt" # 数据集视频名文件名 OUTPUT_DIR="path/preprocessed-Tom-dataset" # 预编码处理的tensor数据集输出路径 修改后，执行prepare_dataset.sh脚本 bash prepare_dataset.sh 进行模型训练 cd /home/ma-user/finetrainers 对finetrainers/train_text_to_video_sft.sh文件进行修改，配置训练使用的超参数： MAX_TRAIN_STEPS=("20000") # 最大训练步数 DATA_ROOT="path/preprocessed-Tom-dataset" # 预编码处理的tensor数据集路径，即data cache的输出路径 CAPTION_COLUMN="prompts.txt" # 数据集提示词文件名 VIDEO_COLUMN="videos.txt" # 数据集视频名文件名 MODEL_PATH="THUDM/CogVideoX1.5-5B" # 模型路径 output_dir="/path/to/my/models/cogvideox-sft # 模型输出路径 修改后，执行train_text_to_video_sft.sh脚本 bash train_text_to_video_sft.sh 以上微调文档提示来自官方文档，有关可用微调脚本参数及其功能的全面文档，您可以参考官方finetrainers中CogVideo训练文档。

步骤三：启动容器镜像 启动容器镜像。启动前请先按照参数说明修改${}中的参数。 export work_dir="自定义挂载的工作目录" export container_work_dir="自定义挂载到容器内的工作目录" export container_name="自定义容器名称" export image_name="镜像名称或ID" // 启动一个容器去运行镜像 docker run -itd --net=bridge \ --device=/dev/davinci0 \ --device=/dev/davinci1 \ --device=/dev/davinci2 \ --device=/dev/davinci3 \ --device=/dev/davinci4 \ --device=/dev/davinci5 \ --device=/dev/davinci6 \ --device=/dev/davinci7 \ --device=/dev/davinci_manager \ --device=/dev/devmm_svm \ --device=/dev/hisi_hdc \ --shm-size=256g \ -v /usr/local/dcmi:/usr/local/dcmi \ -v /usr/local/Ascend/driver:/usr/local/Ascend/driver \ -v /var/log/npu/:/usr/slog \ -v /usr/local/sbin/npu-smi:/usr/local/sbin/npu-smi \ -v ${work_dir}:${container_work_dir} \ --name ${container_name} \ ${image_name} \ /bin/bash 参数说明： -v ${work_dir}:${container_work_dir}：代表需要在容器中挂载宿主机的目录。宿主机和容器使用不同的文件系统。work_dir为宿主机中工作目录，目录下可存放项目所需代码、数据等文件。container_work_dir为要挂载到的容器中的目录。为方便两个地址可以相同。 容器不能挂载到/home/ma-user目录，此目录为ma-user用户家目录。如果容器挂载到/home/ma-user下，拉起容器时会与基础镜像冲突，导致基础镜像不可用。 driver及npu-smi需同时挂载至容器。 --name ${container_name}：容器名称，进入容器时会用到，此处可以自己定义一个容器名称。 ${image_name}：容器镜像的名称。 --device=/dev/davinci0 ：挂载对应卡到容器，当需要挂载多卡，请依次添加多项该配置 通过容器名称进入容器中。默认使用ma-user用户，后续所有操作步骤都在ma-user用户下执行。 docker exec -it ${container_name} bash

获取软件和镜像 表2 获取软件和镜像 分类 名称 获取路径 插件代码包 AscendCloud-6.3.912-xxx.zip软件包中的AscendCloud-AIGC-6.3.912-xxx.zip 说明： 包名中的xxx表示具体的时间戳，以包名的实际时间为准。 获取路径：Support-E，在此路径中查找下载ModelArts 6.3.912 版本。 说明： 如果上述软件获取路径打开后未显示相应的软件信息，说明您没有下载权限，请联系您所在企业的华为方技术支持下载获取。 基础镜像 西南-贵阳一： swr.cn-southwest-2.myhuaweicloud.com/atelier/pytorch_2_1_ascend:pytorch_2.1.0-cann_8.0.rc3-py_3.9-hce_2.0.2409-aarch64-snt9b-20241213131522-aafe527 从SWR拉取。

步骤一：准备环境 请参考Lite Server资源开通，购买Server资源，并确保机器已开通，密码已获取，能通过SSH登录，不同机器之间网络互通。 当容器需要提供服务给多个用户，或者多个用户共享使用该容器时，应限制容器访问Openstack的管理地址（169.254.169.254），以防止容器获取宿主机的元数据。具体操作请参见禁止容器获取宿主机元数据。 SSH登录机器后，检查NPU设备检查。运行如下命令，返回NPU设备信息。 npu-smi info # 在每个实例节点上运行此命令可以看到NPU卡状态 npu-smi info -l | grep Total # 在每个实例节点上运行此命令可以看到总卡数 如出现错误，可能是机器上的NPU设备没有正常安装，或者NPU镜像被其他容器挂载。请先正常安装固件和驱动，或释放被挂载的NPU。 检查docker是否安装。 docker -v #检查docker是否安装 如尚未安装，运行以下命令安装docker。 yum install -y docker-engine.aarch64 docker-engine-selinux.noarch docker-runc.aarch64 配置IP转发，用于容器内的网络访问。执行以下命令查看net.ipv4.ip_forward配置项的值，如果为1，可跳过此步骤。 sysctl -p | grep net.ipv4.ip_forward 如果net.ipv4.ip_forward配置项的值不为1，执行以下命令配置IP转发。 sed -i 's/net\.ipv4\.ip_forward=0/net\.ipv4\.ip_forward=1/g' /etc/sysctl.conf sysctl -p | grep net.ipv4.ip_forward

训练代码迁移 前提条件 要迁移的训练任务代码在GPU上多次训练稳定可收敛。训练业务代码和数据，应该确保在GPU环境中能够运行，并且训练任务有稳定的收敛效果。 本文只针对基于PyTorch的训练代码迁移。此处假设用户使用基于PyTorch的训练代码进行迁移。其他的AI引擎如TensorFlow、Caffe等不在本指导的讨论范围中。 已完成迁移环境准备，且代码、预训练模型、数据等训练必需内容已经上传到环境中。 约束和限制 安装插件后，大部分能力能够对标在GPU上的使用，但并不是所有行为和GPU上是一一对应的。例如在torch_npu下，当PyTorch版本低于2.1.0时，一个进程只能操作一张昇腾卡，不支持一个进程操作多卡的能力；在PyTorch2.1.0及以上版本中torch_npu才支持一个进程中使用多张昇腾卡。 基于PyTorch上的第三方开发库非常多，例如transformers、accelerate、deepspeed以及Megatron-LM等，这些三方库昇腾也做了类似PyTorch Adapter的适配插件库。您可以在Gitee的昇腾官方仓库按需使用插件库。部分三方库例如最新版本deepspeed已原生支持NPU，可以直接在昇腾设备上运行。 代码迁移基础知识 PyTorch 2.1以下版本时，PyTorch官方并不直接支持昇腾的后端，仅直接支持CUDA和AMD ROCm，因此PyTorch在GPU上的训练代码无法直接在昇腾设备运行。PyTorch 2.1版本提供了新硬件适配的插件机制，通过昇腾提供的Ascend Extension for PyTorch插件，NPU可以成为PyTorch支持的硬件直接使用。 Ascend Extension for PyTorch作为一个PyTorch插件，支持在不改变PyTorch表达层的基础上，动态添加昇腾后端适配，包含增加了NPU设备、hccl等一系列能力的支持。安装后可以直接使用PyTorch的表达层来运行在NPU设备上。 当前提供了自动迁移工具进行GPU到昇腾适配，原理是通过monkey-patch的方式将torch下的CUDA、nccl等操作映射为NPU和hccl对应的操作。如果没有用到GPU的高阶能力，例如自定义算子、直接操作GPU显存等操作，简单场景下可以直接使用自动迁移。 图1 torch_npu工作原理示意图 NPU（Neural Network Processing Unit）和GPU在构造结构上存在差异，因此迁移过程并不是完全平替的关系。昇腾训练芯片属于NPU的范畴，虽然在表达层可以通过torch.cuda和torch.npu的形式来替代，但是真实的算子下发、显存管理、集合通信等存在差异，用户需要了解NPU的运行机制才能更好的使用NPU设备，同时在遇到问题时快速找到原因。 代码迁移操作步骤 在训练任务启动的Python脚本入口初始化Ascend Extension for PyTorch（torch_npu）。 在torch_npu安装后，该部分并没有直接植入到PyTorch中生效，需要用户显式调用。 # torch npu初始化。 import torch_npu 调用后，前端会通过monkey-patch的方式注入到torch对象中，后端会注册NPU设备以及HCCL的参数面通信能力，这样就可以运行torch.npu相关接口。 图2 torch_npu导入 自动迁移完成GPU代码到昇腾的快速适配。 torch_npu初始化后，原则上需要用户将原来代码中CUDA相关的内容迁移到NPU相关的接口上，包含算子API、显存操作、数据集操作、分布式训练的参数面通信nccl等，手动操作修改点较多且较为分散，因此昇腾提供了自动迁移工具transfer_to_npu帮助用户快速迁移。 自动迁移的原理是：通过注入的方式将当前Python运行环境中，运行时的torch.cuda等需要适配的接口和操作都映射成为torch.npu对应的接口。所以理论上常见场景下的代码不需要额外手工适配就可以运行到昇腾设备上。 # 自动映射cuda API到NPU的代码。 from torch_npu.contrib import transfer_to_npu 图3 自动迁移后cuda映射为NPU相关的API 以chatGLM-6b为例，在使用自动迁移时，在开发环境中克隆对应的代码。假设数据和预训练权重已经配置好，可以直接在ptuning目录下，训练入口代码main.py中添加两行代码来完成昇腾适配。请注意添加位置为导入torch之后。启动训练脚本可以观察运行效果。 图4 chatGLM-6b pTuning训练入口导入自动迁移工具 自动迁移适合没有使用CUDA高阶能力的简单场景，如果涉及自定义算子、主动申请GPU显存等操作，则需要额外进行手动迁移适配。 手动迁移解决报错问题。 在完成代码自动迁移后，如果训练代码运行时还出现错误，则代表需要手动迁移适配。针对代码报错处，需要用户分析定位后将自动迁移未能迁移的GPU相关的代码调用修改为NPU对应的接口，请参考昇腾手工迁移文档进行操作。 常见问题 如何检测当前的torch_npu是否正确安装？ 您可以使用如下的python命令在对应的运行环境中初步校验torch_npu是否正常安装。 python3 -c "import torch;import torch_npu;print(torch_npu.npu.is_available())" torch_npu使用报错看不懂怎么办？应该怎么求助？ 如果报错可以首先在昇腾社区论坛以及Gitee的PyTorch Issues中查看是否有类似的问题找到相关线索。如果还无法解决，可以通过提交工单的形式从华为云ModelArts入口进行咨询以及求助对应的专业服务。 自动迁移似乎还要改很多脚本才能运行起来？ 因为自动迁移其实是对于torch运行环境中常用的GPU上的接口进行和昇腾设备的映射。原有的训练任务代码逻辑中例如数据集导入、预训练权重、GPU自定义算子的内容，以及对应的环境的超参数等内容都需要在实际的昇腾环境中进行调整。

性能可视化 对于高阶的调优用户，可以使用可视化工具MindStudio Insight查看profiling数据详情并分析可优化点，其提供了丰富的调优分析手段，可视化呈现真实软硬件运行数据，多维度分析性能瓶颈点，支持百卡、千卡及以上规模的可视化集群性能分析，助力开发者天级完成性能调优。 MindStudio-Insight提供时间线视图、内存、算子耗时、通信瓶颈分析等功能，借助于数据库支持超大性能数据处理，可以支持20GB的集群性能文件分析，并且能够支持大模型场景下的性能调优，相比于Chrometrace、tensorboard等工具提供了更优的功能和性能。 更多详细信息，请参见昇腾MindStudio-Insight用户指南。 父主题： 性能调优

训练迁移适配 完成环境准备之后，本节将详细介绍Dit模型训练迁移过程。 执行以下命令，下载代码。 git clone https://github.com/facebookresearch/DiT.git cd Dit 执行以下命令，安装依赖项。 pip install diffusers==0.28.0 accelerate==0.30.1 timm==0.9.16 准备数据集。 下载Kaggle官网提供的imagenet-mini数据集，解压之后文件大小4.1GB。该数据集是从[imagenet-2012]数据集中筛选的少量数据集。 准备预训练权重。 下载Hugging Face权重。 迁移适配。 入口函数train.py导入自动迁移接口。 执行以下命令，导入自动迁移接口。 import torch_npu from torch_npu.contrib import transfer_to_npu 将预训练模型指定为实际下载路径。 开始训练。 单卡训练启动方式： torchrun --nnodes=1 --nproc_per_node=1 train.py --model DiT-XL/2 --data-path imagenet/train --global-batch-size 16 多卡训练启动方式： torchrun --nnodes=1 --nproc_per_node=8 train.py --model DiT-XL/2 --data-path imagenet/train --global-batch-size 128 正常训练回显日志： 父主题： 案例：Dit模型训练迁移

步骤四：执行训练 安装完成后，执行： accelerate launch -m --mixed_precision=bf16 eagle.train.main \ --tmpdir [path of data] \ --cpdir [path of checkpoints] \ --configpath [path of config file] \ --basepath [path of base_model] --bs [batch size] tmpdir：即为步骤三中的outdir，训练data地址 cpdir：为训练生成权重的地址 configpath：为模型config文件的地址 basepath：为大模型权重地址 bs：为batch大小 其中，要获取模型config文件， 首先到https://github.com/SafeAILab/EAGLE/页找到对应eagle模型地址。 图1 EAGLE Weights 以llama2-chat-7B为例，单击进入后 ，如下图所示config文件，即为对应模型的eagle config文件。 图2 eagle config文件

步骤五：训练生成权重转换成可以支持vLLM推理的格式 将训练完成后的权重文件（.bin文件或. safetensors文件），移动到下载好的开源权重目录下（即步骤4中，config文件所在目录）。 然后在llm_tools/spec_decode/EAGLE文件夹，执行 python convert_eagle_ckpt_to_vllm_compatible.py --base-path 大模型权重地址 --draft-path 小模型权重地址 --base-weight-name 大模型包含lm_head的权重文件名 --draft-weight-name 小模型权重文件名 --base-path：为大模型权重地址，例如 ./llama2-7b-chat --draft-path：小模型权重地址，即步骤四中config文件所在目录，例如 ./eagle_llama2-7b-chat --base-weight-name：为大模型包含lm_head的权重文件名，可以在base-path目录下的 model.safetensors.index.json 文件获取，例如llama2-7b-chat的权重名为pytorch_model-00001-of-00002.bin 图3 权重文件名 --draft-weight-name 为小模型权重文件名，即刚才移动的.bin文件或者.safetensors文件。

步骤二：非sharegpt格式数据集转换（可选） 如果数据集json文件不是sharegpt格式，而是常见的如下格式，则需要执行convert_to_sharegpt.py 文件将数据集转换为share gpt格式。 { "prefix": "AAA" "input": "BBB", "output": "CCC" } 执行convert_to_sharegpt.py 文件。 python convert_to_sharegpt.py \ --input_file_path data_test.json \ --out_file_name ./data_for_sharegpt.json \ --prefix_name instruction \ --input_name input \ --output_name output \ --code_type utf-8 其中： input_file_path：预训练json文件地址。 out_file_name：输出的sharegpt格式文件地址。 prefix_name：预训练json文件的前缀字段名称，例如：您是一个xxx专家，您需要回答下面问题。prefix_name可设置为None，此时预训练数据集只有input和output两段输入。 input_name：预训练json文件的指令输入字段名称，例如：请问苹果是什么颜色。 output_name output：预训练json文件的output字段名称，例如：苹果是红色的。 code_type：预训练json文件编码，默认utf-8。 当转换为sharegpt格式时，prefix和input会拼接成一段文字，作为human字段，提出问题，而output字段会作为gpt字段，做出回答。

步骤三：sharegpt格式数据生成为训练data数据集 若使用开源数据集，推荐使用原论文代码仓数据集，下载地址：https://huggingface.co/datasets/Aeala/ShareGPT_Vicuna_unfiltered/blob/main/ShareGPT_V4.3_unfiltered_cleaned_split.json 否则使用第二步生成的开源数据集。 python allocation.py \ --outdir outdir0/sharegpt_0_99_mufp16 \ --end_num 100 \ --used_npus "0,1,2,3,4,5,6,7" \ --model_type llama \ --model_name ./llama-7B \ --data_path data_for_sharegpt.json \ --seed 42 \ --max_length 2048 \ --dtype bfloat16 其中 outdir：生成的训练data 地址 end_num：生成的data总条数 used_npus：使用哪些NPU model_type：使用模型类型 目前支持 qwen2 llama1 llama2 及 llama3，其中llama1、2及chat都填写llama model_name：模型地址 data_path：预训练数据集地址 即一中生成的文件地址 seed：生成训练data所使用的seed（此处42为开源训练设定参数） max_length：模型的max_length dtype：为模型dtype 默认为bfloat16

步骤二：非sharegpt格式数据集转换（可选） 如果数据集json文件不是sharegpt格式，而是常见的 { "prefix": "AAA" "input": "BBB", "output": "CCC" } 格式，则需要执行convert_to_sharegpt.py 文件将数据集转换为share gpt格式。 python convert_to_sharegpt.py \ --input_file_path data_test.json \ --out_file_name ./data_for_sharegpt.json \ --prefix_name instruction \ --input_name input \ --output_name output \ --code_type utf-8 其中： input_file_path：预训练json文件地址。 out_file_name：输出的sharegpt格式文件地址。 prefix_name：预训练json文件的前缀 字段名称 （可设置为None，此时预训练数据集只有 input output 两段）输入前缀，（例如：您是一个xxx专家,您需要回答下面问题） input_name：预训练json文件的指令输入 字段名称（例如：请问苹果是什么颜色） output_name output：预训练json文件的output字段名称，例如：苹果是红色的。 code_type：预训练json文件编码 默认utf-8 当转换为share gpt格式时，prefix和 input会拼接成一段文字，作为human字段，提出问题，而output字段会作为gpt字段，做出回答。

步骤四：执行训练 安装完成后，执行： accelerate launch -m --mixed_precision=bf16 eagle.train.main \ --tmpdir [path of data] \ --cpdir [path of checkpoints] \ --configpath [path of config file] \ --basepath [path of base_model] --bs [batch size] tmpdir：即为步骤三中的outdir，训练data地址 cpdir：为训练生成权重的地址 configpath：为模型config文件的地址 basepath：为大模型权重地址 bs：为batch大小 其中，要获取模型config文件， 首先到https://github.com/SafeAILab/EAGLE/页找到对应eagle模型地址。 图1 EAGLE Weights 以llama2-chat-7B为例，单击进入后 ，如下图所示config文件，即为对应模型的eagle config文件。

步骤五：训练生成权重转换成可以支持vLLM推理的格式 将训练完成后的权重文件（.bin文件或. safetensors文件），移动到下载好的开源权重目录下（即步骤4中，config文件所在目录）。 然后在llm_tools/spec_decode/EAGLE文件夹，执行 python convert_eagle_ckpt_to_vllm_compatible.py --base-path 大模型权重地址 --draft-path 小模型权重地址 --base-weight-name 大模型包含lm_head的权重文件名 --draft-weight-name 小模型权重文件名 --base-path：为大模型权重地址，例如 ./llama2-7b-chat --draft-path：小模型权重地址 即步骤四中config文件所在目录，例如 ./eagle_llama2-7b-chat --base-weight-name：为大模型包含lm_head的权重文件名，可以在 base-path 目录下的 model.safetensors.index.json 文件获取，例如llama2-7b-chat 的权重名为pytorch_model-00001-of-00002.bin --draft-weight-name 为小模型权重文件名，即刚才移动的.bin文件或者.safetensors 文件

迁移环境准备 迁移环境准备有以下两种方式： 表1 方式说明 序号 名称 说明 方式一 ModelArts Notebook 该环境为在线调试环境，主要面向演示、体验和快速原型调试场景。 优点：可快速、低成本地搭建环境，使用标准化容器镜像，官方Notebook示例可直接运行。 缺点：由于是容器化环境因此不如裸机方式灵活，例如不支持root权限操作、驱动更新等。 环境开通指导请参考Notebook环境创建；样例演示请参考Notebook样例：Stable Diffusion模型迁移到Ascend上进行推理。 方式二 ModelArts Lite DevServer 该环境为裸机开发环境，主要面向深度定制化开发场景。 优点：支持深度自定义环境安装，可以方便的替换驱动、固件和上层开发包，具有root权限，结合配置指导、初始化工具及容器镜像可以快速搭建昇腾开发环境。 缺点：资源申请周期长，购买成本高，管理视角下资源使用效率较低。 环境开通指导请参考DevServer资源开通；环境配置指导请参考Snt9B裸金属服务器环境配置指南。 本文基于方式二的环境进行操作，请参考方式二中的环境开通和配置指导完成裸机和容器开发初始化配置。注意业务基础镜像选择Ascend+PyTorch镜像。 配置好的容器环境如下图所示： 图1 环境配置完成 父主题： 案例：SD1.5推理迁移