华为云用户手册

ModelArts入门指引 本文旨在帮助您了解ModelArts的基本使用流程以及相关的常见问题，帮助您快速上手ModelArts服务。 面向不同AI基础的开发者，本文档提供了相应的入门教程，帮助用户更快速地了解ModelArts的功能，您可以根据经验选择相应的教程。 面向AI开发零基础的用户，您可以使用ModelArts在AI Gallery中预置的模型、算法、数据、Notebook等资产，零代码完成AI建模和应用。 如果您想了解如何使用ModelArts Standard一键部署现有的模型，并在线使用模型进行预测，您可以参考使用ModelArts Standard一键完成商超商品识别模型部署。 ModelArts Standard同时提供了自动学习功能，帮助用户零代码构建AI模型，详细介绍请参见使用ModelArts Standard自动学习实现垃圾分类。 面向AI工程师，熟悉代码编写和调测，您可以使用ModelArts Standard提供的在线代码开发环境，编写训练代码进行AI模型的开发。 如果您想了解如何在ModelArts Standard提供的Notebook开发环境中，完成AI开发全流程，您可以参考基于Codelab使用Standard Notebook实例进行AI开发。 如果您有自己的算法，想改造适配后迁移到ModelArts Standard平台上进行训练和推理，您可以参考使用自定义算法构建模型（手写数字识别）。 更多入门实践，请参考《ModelArts入门实践》章节。如果您有其他疑问，您也可以通过华为云社区问答频道来与我们联系探讨。

操作流程 开始使用如下样例前，请务必按准备工作指导完成必要操作。 Step1 准备训练数据：下载MNIST数据集。 Step2 准备训练文件和推理文件：编写训练与推理代码。 Step3 创建OBS桶并上传文件：创建OBS桶和文件夹，并将数据集和训练脚本，推理脚本，推理配置文件上传到OBS中。 Step4 创建训练作业：进行模型训练。 Step5 推理部署：训练结束后，将生成的模型导入ModelArts用于创建模型，并将模型部署为在线服务。 Step6 预测结果：上传一张手写数字图片，发起预测请求获取预测结果。 Step7 清除资源：运行完成后，停止服务并删除OBS中的数据，避免不必要的扣费。

准备工作 已 注册华为账号 并开通华为云，且在使用ModelArts前检查账号状态，账号不能处于欠费或冻结状态。 配置委托访问授权 ModelArts使用过程中涉及到OBS、SWR、IEF等服务交互，首次使用ModelArts需要用户配置委托授权，允许访问这些依赖服务。 使用华为云账号登录ModelArts管理控制台，在左侧导航栏单击“权限管理”，进入“权限管理”页面，单击“添加授权”。 在弹出的“添加授权”窗口中，选择： 授权对象类型：所有用户 委托选择：新增委托 权限配置：普通用户 选择完成后勾选“我已经详细阅读并同意《ModelArts服务声明》”，然后单击“创建”。 图1 配置委托访问授权 完成配置后，在ModelArts控制台的权限管理列表，可查看到此账号的委托配置信息。 图2 查看委托配置信息

Step1 准备训练数据 本案例使用的数据是MNIST数据集，您可以在浏览器中搜索“MNIST数据集”下载如图3所示的4个文件。 图3 MNIST数据集 “train-images-idx3-ubyte.gz”：训练集的压缩包文件，共包含60000个样本。 “train-labels-idx1-ubyte.gz”：训练集标签的压缩包文件，共包含60000个样本的类别标签。 “t10k-images-idx3-ubyte.gz”：验证集的压缩包文件，共包含10000个样本。 “t10k-labels-idx1-ubyte.gz”：验证集标签的压缩包文件，共包含10000个样本的类别标签。

Step3 创建OBS桶并上传文件 将上一步中的数据和代码文件、推理代码文件与推理配置文件，从本地上传到OBS桶中。在ModelArts上运行训练作业时，需要从OBS桶中读取数据和代码文件。 登录OBS管理控制台，按照如下示例创建OBS桶和文件夹。 {OBS桶} # OBS对象桶，用户可以自定义名称，例如：test-modelarts-xx -{OBS文件夹} # OBS文件夹，自定义名称，此处举例为pytorch - mnist-data # OBS文件夹，用于存放训练数据集，可以自定义名称，此处举例为mnist-data - mnist-code # OBS文件夹，用于存放训练脚本train.py，可以自定义名称，此处举例为mnist-code - infer # OBS文件夹，用于存放推理脚本customize_service.py和配置文件config.json - mnist-output # OBS文件夹，用于存放训练输出模型，可以自定义名称，此处举例为mnist-output 创建的OBS桶所在区域和后续使用ModelArts必须在同一个区域Region，否则会导致训练时找不到OBS桶。具体操作可参见查看OBS桶与ModelArts是否在同一区域。 创建OBS桶时，桶的存储类别请勿选择“归档存储”，归档存储的OBS桶会导致模型训练失败。 上传Step1 准备训练数据中下载的MNIST数据集压缩包文件到OBS的“mnist-data”文件夹中。 上传数据到OBS中时，请不要加密，否则会导致训练失败。 文件无需解压，直接上传压缩包至OBS中即可。 上传训练脚本“train.py”到“mnist-code”文件夹中。 上传推理脚本“customize_service.py”和推理配置文件“config.json”到“mnist-code”的“infer”文件中。

Step6 预测结果 在“在线服务”页面，单击在线服务名称，进入服务详情页面。 单击“预测”页签，请求类型选择“multipart/form-data”，请求参数填写“image”，单击“上传”按钮上传示例图片，然后单击“预测”。 预测完成后，预测结果显示区域将展示预测结果，根据预测结果内容，可识别出此图片的数字是“2”。 本案例中使用的MNIST是比较简单的用做demo的数据集，配套算法也是比较简单的用于教学的神经网络算法。这样的数据和算法生成的模型仅适用于教学模式，并不能应对复杂的预测场景。即生成的模型对预测图片有一定范围和要求，预测图片必须和训练集中的图片相似（黑底白字）才可能预测准确。 图8 示例图片 图9 预测结果展示

多模态模型 ModelArts针对以下主流的多模态模型进行了基于昇腾NPU的适配工作，可以直接使用适配过的模型在NPU上进行推理或训练。 表4 多模态模型基于Ascend-vLLM框架的推理 支持模型 支持模型参数量 应用场景 软件技术栈 指导文档 internVL2 internVL2-8B internVL2-26B internVL2-40B internVL2-Llama3-76B 推理 Ascend-vLLM 主流开源大模型基于Lite Server适配Ascend-vLLM PyTorch NPU推理指导 主流开源大模型基于Standard适配PyTorch NPU推理指导（6.3.911） 主流开源大模型基于Lite Cluster适配PyTorch NPU推理指导（6.3.911） MiniCPM MiniCPM-v2.6 推理 Ascend-vLLM qwen2-vl qwen2-vl-2B qwen2-vl-7B qwen2-vl-72B 推理 Ascend-vLLM llava llava-1.5-7b llava-1.5-13b llava-v1.6-7b llava-v1.6-13b llava-v1.6-34b 推理 Ascend-vLLM llava-onevision-qwen2 llava-onevision-qwen2-0.5b-ov-hf llava-onevision-qwen2-7b-ov-hf 推理 Ascend-vLLM 表5 多模态模型基于PyTorch的训练推理 模型名称 应用场景 软件技术栈 指导文档 Qwen-VL 训练 推理 PyTorch Qwen-VL基于Standard+OBS+SFS适配PyTorch NPU训练指导（6.3.912） Qwen-VL模型基于Standard+OBS适配PyTorch NPU训练指导（6.3.912） Qwen-VL基于Lite Server适配PyTorch NPU的Finetune训练指导(6.3.912) Qwen-VL基于Lite Server适配PyTorch NPU的推理指导（6.3.909） MiniCPM-V2.6 训练 PyTorch MiniCPM-V2.6基于Lite Server适配PyTorch NPU训练指导（6.3.912） MiniCPM-V2.0 训练 推理 PyTorch MiniCPM-V2.0推理及LoRA微调基于Lite Server适配PyTorch NPU指导（6.3.910） InternVL2 训练 PyTorch InternVL2基于LIte Server适配PyTorch NPU训练指导（6.3.912） LLaVA-NeXT 训练 PyTorch LLaVA-NeXT基于Lite Server适配PyTorch NPU训练微调指导（6.3.912） LLaVA 训练 推理 PyTorch LLaVA模型基于Lite Server适配PyTorch NPU预训练指导（6.3.912） LLaVA模型基于Lite Server适配PyTorch NPU推理指导（6.3.906） LLama 3.2-Vision 训练 PyTorch Llama 3.2-Vision基于Lite Server适配Pytorch NPU训练微调指导（6.3.912） LLaMA-VID 推理 PyTorch LLaMA-VID基于Lite Server适配PyTorch NPU推理指导（6.3.910） moondream2 推理 PyTorch moondream2基于Lite Server适配PyTorch NPU推理指导

常见问题 模型转换失败怎么办？ 常见的模型转换失败原因可以通过查询转换失败错误码来确认具体导失败的原因。Stable Diffusion新推出的模型在转换中可能会遇到算子不支持的问题，您可以到华为云管理页面上提交工单来寻求帮助。 图片大Shape性能劣化严重怎么办？ 在昇腾设备上，可能由于GPU内存墙导致在大shape下遇到性能问题。MindSporeLite提供了Flash Attention编译优化机制，您可以考虑升级最新版本的MindSporeLite Convertor来进行编译器的算子优化，在大Shape场景下会有明显的改善。 同样功能的PyTorch Pipeline，因为指导要求适配onnx pipeline，两个pipeline本身功能就有差别，如何适配？ 由于Diffusers社区的“single model file policy”设计原则，不同的pipeline是不同路径在独立演进的。请先确保应用输出符合预期后，再进入到MindSpore Lite模型转换的过程，否则迁移昇腾后还是会遇到同样的问题。 AOE的自动性能调优使用上完全没有效果怎么办？ 在MindSpore Lite Convertor2.1版本之前可能出现的调优不生效的场景，建议您直接使用MindSpore Lite Convertor2.1及以后的版本。配置文件指定选项进行AOE调优。使用转换工具配置config参数，具体如下所示，其中“subgraph tuning”表示子图调优，“operator tuning”表示算子调优。 其中，“ge.op_compiler_cache_mode”在该场景下必须设置为“force”，表示该场景下要强制刷新缓存，保证AOE调优后的知识库能够命中，实现模型调优。 # config.ini [ascend_context] aoe_mode="subgraph tuning, operator tuning" [acl_init_options] ge.op_compiler_cache_mode="force" 迁移后应用出图效果相比GPU无法对齐怎么办？ 扩散模型在噪音和随机数上的生成，本身就有一定的随机性，GPU和NPU（Ascend）硬件由于存在一定细小的差别，很难确保完全一致，较难达成生成图片100%匹配，建议通过盲测的方式对效果进行验证。 模型精度有问题怎么办？ 首先考虑通过FP16的方式进行转换和执行，再通过精度诊断工具来进行分析，更进一步可以到华为云官网上提交工单处理。 模型转换失败时如何查看日志和定位原因？ 在模型转换的过程，如果出现模型转换失败，可以参考以下步骤查看日志并定位原因： 设置DEBUG日志。 设置MindSpore日志环境变量。 # shell export G LOG _v=0 # 0-DEBUG、1-INFO、2-WARNING、3-ERROR 设置CANN日志环境变量。 # shell export ASCEND_GLOBAL_LOG_LEVEL=1 # 0：表示DEBUG、1：表示INFO、2：表示WARNING、3：表示ERROR 4: 表示NONE export ASCEND_SLOG_PRINT_TO_STDOUT=1 # 表示日志打印。 设置DUMP模型转换中间图。 设置DUMP中间图环境变量。 # shell export DUMP_GE_GRAPH=2 # 1：表示dump图全量内容。 2：表示不dump权重数据的基础图。 3：表示只dump节点关系的精简图。 export DUMP_GRAPH_LEVEL=2 # 1：表示dump图所有图。 2：表示dump除子图外的所有图。 3：表示只dump最后一张图。 问题分析。 配置以上的环境变量之后，再重新转换模型，导出对应的日志和dump图进行分析： 报错日志中搜到“not support onnx data type”，表示MindSpore暂不支持该算子。 报错日志中搜到“Convert graph to om failed”，表示CANN模块进行图编译存在保存，需要结合CANN的报错日志和dump图进行具体分析。 Stable Diffusion WebUI如何适配？ WebUI一般可以分为前端和后端实现两部分，后端的实现模式种类多样，并且依赖了多个的第三方库，当前在WebUI适配时，并没有特别好的方式。在对后端实现比较理解的情况下，建议针对具体的功能进行Diffusers模块的适配与替换，然后针对替换上去的Diffusers，对其pipeline进行昇腾迁移适配，进而替代原有WebUI的功能。针对很多参数以及三方加速库（如xformers）的适配，当前没有特别好的处理方案。 LoRA适配流是怎么样的？ 因为现在PyTorch-npu推理速度比较慢（固定shape比mindir慢4倍），在现在pth-onnx-mindir的模型转换方式下，暂时只能把lora合并到unet主模型内，在每次加载模型前lora特性就被固定了（无法做到PyTorch每次推理都可以动态配置的能力）。 目前临时的静态方案可参考sd-scripts， 使用其中的“networks/merge_lora.py”把lora模型合入unet和text-encoder模型。 数据类型不匹配问题如何处理？ 报错“data type not equal”时，按照堆栈信息，将对应的行数的数据类型修改为匹配的类型。 图1 报错信息 处理该问题时，pipeline_onnx_stable_diffusion_img2img_mslite.py文件的第454行修改如下： 图2 修改内容 父主题： 案例：SD1.5推理迁移

步骤五：训练生成权重转换成可以支持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字段，做出回答。

步骤四：执行训练 安装完成后，执行： 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文件

核心概念 推理业务昇腾迁移整体流程及工具链 图1 推理业务昇腾迁移整体路径 推理业务昇腾迁移整体分为七个大的步骤，并以完整工具链覆盖全链路： 迁移评估：针对迁移可行性、工作量，以及可能的性能收益进行大致的预估。 环境准备：利用ModelArts提供的开发环境一键式准备好迁移、调测需要的运行环境与工具链。 模型适配：针对昇腾迁移模型必要的转换和改造。 模型准备，导出和保存确定格式的模型。 转换参数准备，准备模型业务相关的关键参数。 模型转换，包含模型转换、优化和量化等。 应用集成。 针对转换的模型运行时应用层适配。 数据预处理。 模型编排。 模型裁剪。 精度校验。 精度对比误差统计工具。 自动化精度对比工具。 网络结构可视化工具。 性能调优。 性能测试。 性能调优三板斧。 性能分析与诊断。 迁移测试报告。 推理迁移验收表。 ModelArts开发环境 ModelArts作为华为云上的 AI开发平台 ，提供交互式云上开发环境，包含标准化昇腾算力资源和完整的迁移工具链，帮助用户完成昇腾迁移的调测过程，进一步可在平台上将迁移的模型一键部署成为在线服务向外提供推理服务，或者运行到自己的运行环境中。 MindSpore Lite 华为自研的AI推理引擎，后端对于昇腾有充分的适配，模型转换后可以在昇腾上获得更好的性能，配合丰富的适配工具链，降低迁移成本，该工具在推理迁移工作的预置镜像已安装，可在镜像中直接使用（见环境准备）。关于MindSpore Lite详细介绍可参考MindSpore Lite文档。在使用MindSpore Lite过程中遇到问题时，可参考MindSpore Lite官网提供的问题定位指南进行问题定位。

迁移路线介绍 当前推理迁移时，不同的模型类型可能会采取不同的迁移技术路线。主要分为以下几类： CV类小模型例如yolov5，以及部分AIGC场景的模型迁移，目前推荐使用MindSpore-Lite推理路线，可以利用MindSpore提供的图编译和自动调优能力，达到更好的模型性能。 LLM大语言模型场景，在GPU下通常会使用vLLM等大模型推理框架，因此迁移到昇腾时，推荐使用PyTorch + ascend-vllm技术路线进行迁移。 如果您使用的模型在上述案例文档中已包含，建议您直接使用案例中迁移好的模型，如果您的模型不在已提供的范围内，或者您因业务要求需要自行完成端到端的迁移，可以参考本迁移指导书介绍的步骤进行操作。 本文的迁移指导及快速入门案例均针对路线1也即MindSpore-Lite迁移路线进行介绍。使用ascend-vllm路线的迁移指导会在后续提供，您可以从上面的案例中下载相关代码并直接参考实现源码。

pipeline应用准备 当前迁移路径是从ONNX模型转换到MindIR模型，再用MindSpore Lite做推理， 所以迁移前需要用户先准备好自己的ONNX pipeline。下文以官方开源的图生图的Stable Diffusion v1.5的onnx pipeline代码为例进行说明。 进入容器环境，创建自己的工作目录。 由于在Snt9B裸金属服务器环境配置指南的配置环境步骤中，在启动容器时将物理机的home目录挂载到容器的“/home_host”目录下，该目录可以直接使用上传到物理机“home”目录下的文件。本文中，将基于容器的“/home_host”目录创建工作目录。 mkdir -p /home_host/work cd /home_host/work 在迁移onnx pipeline前，首先需要确保原始的onnx pipeline能在昇腾机器的ARM CPU上正常执行。进入容器环境后，安装依赖包。 pip install torch==1.11.0 onnx transformers==4.27.4 accelerate onnxruntime diffusers==0.11.1 下载git lfs，用于下载git仓中的大文件。 由于欧拉源上没有git-lfs包，所以需要从压缩包中解压使用，在浏览器中输入如下地址下载git-lfs压缩包并上传到服务器的/home目录。 https://github.com/git-lfs/git-lfs/releases/download/v3.2.0/git-lfs-linux-arm64-v3.2.0.tar.gz 安装git lfs。 tar -zxvf git-lfs-linux-arm64-v3.2.0.tar.gz cd git-lfs-3.2.0 sh install.sh rm -rf git-lfs-linux-arm64-v3.2.0.tar.gz git-lfs-3.2.0 通过git下载sd PyTorch模型。 该模型用于获取模型shape，也可以转换生成onnx模型。后文中的modelarts-ascend仓库已经给出了模型shape，可以直接使用，onnx模型也可以单独下载。 # git clone sd模型。 git lfs install mkdir -p /home_host/work/runwayml cd /home_host/work/runwayml git clone https://huggingface.co/runwayml/stable-diffusion-v1-5/ -b main # 将下载的文件夹重命名，以便后续脚本中引用。 mv stable-diffusion-v1-5 pytorch_models 此处由于Huggingface网站的限制以及模型文件的大小原因，很可能会下载失败。您可以登录Huggingface网站，从浏览器下载模型后，再手动上传到物理机/home/pytorch_models目录下。 通过git下载sd onnx模型。 # git clone sd模型。 git lfs install cd /home_host/work/runwayml git clone https://huggingface.co/runwayml/stable-diffusion-v1-5 -b onnx # 将下载的文件夹重命名，以便后续脚本中引用。 mv stable-diffusion-v1-5 onnx_models 此处由于Huggingface网站的限制以及模型文件的大小原因，很可能会下载失败。您可以登录Huggingface网站，从浏览器下载模型后，再手动上传到物理机/home/onnx_models目录下。 下载好模型后，需要编写推理脚本。为了便于操作，本指导中所需的代码已发布在ModelArts代码仓，可以使用如下命令下载推理脚本样例代码： cd /home_host/work git clone https://gitee.com/ModelArts/modelarts-ascend.git ll modelarts-ascend/examples/AIGC/stable_diffusion 代码目录如下图所示，onnx_pipeline.py是图生图推理脚本。mslite_pipeline.py、mslite_model_proxy.py、pipeline_onnx_stable_diffusion_img2img_mslite.py是迁移后的文件，其中mslite_model_proxy.py是代理模型类，pipeline_onnx_stable_diffusion_img2img_mslite.py是从Stable Diffusion源码中的pipeline复制并修改的，这些文件在后续的章节中会使用并进一步介绍。 图1 代码目录 将“modelarts-ascend/examples/AIGC/stable_diffusion/onnx_pipeline.py”文件中的“onnx_model_path”改为步骤6中下载的onnx_models地址“/home_host/work/runwayml/onnx_models”。执行推理脚本进行测试，此处使用的推理硬件是CPU。由于CPU执行较慢，验证待迁移的代码可能需要大约15分钟左右才能完成。 cd modelarts-ascend/examples/AIGC/stable_diffusion # 必须执行该命令，否则会报错找不到sketch-mountains-input.jpg python onnx_pipeline.py 生成的图片fantasy_landscape.png会保存在当前路径下，该图片也可以作为后期精度校验的一个对比。 图2 生成图片 父主题： 案例：SD1.5推理迁移

自动高性能算子生成工具AKG AKG（Auto Kernel Generator）对深度神经网络中的算子进行优化，并提供特定模式下的算子自动融合功能。提升在昇腾硬件后端上运行网络的性能。 AKG由三个基本的优化模块组成：规范化、自动调度和后端优化。 规范化： 为了解决polyhedral表达能力的局限性（只能处理静态的线性程序），需要首先对计算公式IR进行规范化。规范化模块中的优化主要包括自动运算符inline、自动循环融合和公共子表达式优化等。 自动调度： 自动调度模块基于polyhedral技术，主要包括自动向量化、自动切分、thread/block映射、依赖分析和数据搬移等。 后端优化： 后端优化模块的优化主要包括TensorCore使能、双缓冲区、内存展开和同步指令插入等。

精度测试 benchmark工具用于精度验证，主要工作原理是：固定模型的输入，通过benchmark工具进行推理，并将推理得到的输出与标杆数据进行相似度度量（余弦相似度和平均相对误差），得到模型转换后的精度偏差信息。使用benchmark进行精度比对的基本流程如下： 将模型输入保存二进制文件。 # 数据读取，预处理 image = img_preprocess(image_path) image = np.array(image, dtype=np.float32) image = np.frombuffer(image.tobytes(), np.float32) # 保存网络输入为二进制文件 image.tofile("input_data.bin") 将基准模型的输出保存到文本文件。 本例中输出节点名称为output_node_name，输出节点的shape为“(1, 1000)”，因此一共有两维，对应的输出文件为“output_node_name 2 1 1000”，再加上输出的值即可。 # 基于原始pth模型前向推理。 output = model_inference(input_data) # 保存网络输出节点名称、维度、shape及输出到本地文件。 with open("output_data.txt", "w") as f: f.write("output_node_name 2 1 1000\n") f.write(" ".join([str(i) for i in output])) 使用benchmark工具进行精度对比。 # shell benchmark --modelFile=model.mindir --inputShapes=1,3,224,224 --inDataFile=input_data.bin --device=Ascend --benchmarkDataFile=output_data.txt --accuracyThreshold=5 --cosineDistanceThreshold=0.99 其中，--accuracyThreshold=5表示平均绝对误差的容忍度最大为5%，--cosineDistanceThreshold =0.99表示余弦相似度至少为99%，--inputShapes可将模型放入到netron官网中查看。 图1 benchmark对接结果输出示例图 为了简化用户使用，ModelArts提供了Tailor工具便于用户进行Benchmark精度测试，具体使用方式参考Tailor指导文档。

环境准备 迁移环境准备有以下两种方式： 表1 迁移环境准备方式 方式 说明 ModelArts Notebook 该环境为在线调试环境，主要面向演示、体验和快速原型调试场景。 环境开通指导请参考Notebook环境创建。 ModelArts Lite DevServer 该环境为裸机开发环境，主要面向深度定制化开发场景。 环境开通指导请参考DevServer资源开通；环境配置指导请参考Snt9B裸金属服务器环境配置指南。 本文基于ModelArts Lite DevServer进行操作，请参考上表说明在贵阳一环境开通和配置指导完成裸机和容器开发初始化配置。 镜像地址为swr.cn-southwest-2.myhuaweicloud.com/atelier/pytorch_2_1_ascend: pytorch_2.1.0-cann_8.0.rc2-py_3.9-hce_2.0.2312-aarch64-snt9b-20240727152329-0f2c29a。 请注意业务基础镜像选择Ascend+PyTorch镜像。

场景介绍 DiT（Diffusion Transformers）模型是一种将Transformer架构引入扩散模型的新方法。传统的扩散模型通常使用U-Net架构，而DiT模型则用Transformer替代了U-Net，处理图像生成和去噪等任务。核心思想是通过Transformer的自注意力机制来捕捉序列中的依赖关系，从而提高生成图像的质量。研究表明，具有较高GFLOPs的DiT模型在图像生成任务中表现更好，尤其是在ImageNet 512×512和256×256的测试中，DiT-XL/2模型实现了2.27的FID值。 下文以Dit模型为例，介绍如何在昇腾设备上如何进行模型迁移，精度及性能调优。

性能诊断 MA-Advisor是一款迁移性能问题自动诊断工具，其集成了昇腾自动诊断工具msprof-analyze，并在ModelArts Standard的Jupyter lab平台进行了插件化，能快速分析和诊断昇腾场景下PyTorch性能劣化问题并给出相关调优建议。 在过往性能调优场景中，如果性能profiling数据在OBS上，通常需要将TB或者GB级别的profiling数据下载至本地后才能使用msprof-analyze进行分析，大量数据的下载耗时以及对本地大规格存储盘的要求容易导致分析受阻。为了能自动串联高性能挂载OBS至ModelArts环境和msprof-analyze的分析能力，ModelArts Standard 场景下对外提供一种插件化的 advisor 分析能力，详细的操作方式请参见基于advisor的昇腾训练性能自助调优指导。 对于GPU和NPU性能比对、NPU多次训练之间性能比对的场景，昇腾提供了性能比对工具compare_tools，通过对训练耗时和内存占用的比对分析，定位到具体劣化的算子，帮助用户提升性能调优的效率。工具将训练耗时拆分为计算、通信、调度三大维度，并针对计算和通信分别进行算子级别的比对；将训练占用的总内存，拆分成算子级别的内存占用进行比对。 对于集群训练场景，昇腾提供了集群分析工具cluster_analysis，当前主要对基于通信域的迭代内耗时分析、通信时间分析以及通信矩阵分析为主，从而定位慢卡、慢节点以及慢链路问题。 父主题： 性能调优

步骤二：非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 参数解释如表1所示。 当转换为sharegpt格式时，prefix和input会拼接成一段文字，作为human字段，提出问题，而output字段会作为gpt字段，做出回答。 表1 数据集转换为sharegpt格式阶段（可选） py文件名称 配置项 取值类型 配置说明 convert_to_sharegpt.py --input_file_path str 预训练json文件地址。 --out_file_name int 输出的sharegpt格式文件地址。 --prefix_name str 预训练json文件的前缀字段名称，例如：您是一个xxx专家，您需要回答下面问题。prefix_name可设置为None，此时预训练数据集只有input和output两段输入。 --input_name str 预训练json文件的指令输入字段名称，例如：请问苹果是什么颜色。 --output_name str 预训练json文件的output字段名称，例如：苹果是红色的。 --code_type str 预训练json文件编码，默认utf-8。

步骤四：执行训练 安装完成后，执行： 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] 具体的参数解释如表3所示， 表3 执行训练阶段 py文件名称 配置项 取值类型 配置说明 eagle.train.main --tmpdir str 生成的训练所需数据的输出地址，即数据生成中的outdir --cpdir str 训练出的Eagle模型权重存放地址 --configpath str Eagle模型config文件地址，通常将对应LLM原始模型中的num_layers改为1即可。 --basepath str LLM原始模型权重地址 --bs int 训练模型的batch 其中，要获取模型config文件， 首先到https://github.com/SafeAILab/EAGLE/页找到对应Eagle模型地址。 图1 EAGLE Weights 以llama2-chat-7B为例，单击进入后 ，如下图所示config文件，即为对应模型的eagle config文件。 图2 eagle config文件

什么是Eagle投机小模型训练 2013年12月滑铁卢大学、加拿大向量研究院、北京大学等机构联合发布Eagle，旨在提升大语言模型的推理速度，同时保证模型输出文本的分布一致。这种方法外推LLM的第二顶层特征向量，能够显著提升生成效率。 Eagle训练了一个单层模型，使用input token和基模型推理出的hidden-state作为输入，输出hidden-state。然后根据这个输出的hidden-state使用基模型的原始LLM的分类头来预测下一个词。hidden-state比input token包含更多信息，使得回归hidden-state的任务比预测词的任务简单得多。总之，Eagle在hidden-state层面上进行外推，使用一个小型单层Eagle模型，然后利用基模型的冻结的分类头生成预测的token。 如此一来，Eagle投机推理可以带来如下优势： 更小的训练成本得到小模型：相较于训练独立的LLM大模型，Eagle仅需训练一个自回归层。这使得其训练成本相较于训练一个独立的LLM模型要小得多。 为每个模型提供针对性的投机模型： Eagle的模型大小及结构，与基模型的某一层完全相同，这使得它的大小远远小于其基模型。解决了对于部分原始LLM模型，找不到合适的投机模型的问题。

步骤五：训练生成权重转换成可以支持vLLM推理的格式 将训练完成后的权重文件（.bin文件或. safetensors文件），移动到下载好的开源权重目录下（即步骤四：执行训练中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 小模型权重文件名 具体参数解释如表4所示。 表4 训练后权重转换适配vllm阶段 py文件名称 配置项 取值类型 配置说明 convert_eagle_ckpt_to_vllm_compatible.py --base-path str LLM原始模型权重地址，例如 ./llama2-7b-chat --draft-path str Eagle模型权重存放地址，即步骤四：执行训练中config文件所在目录，例如 ./eagle_llama2-7b-chat --base-weight-name str 为大模型包含lm_head的权重文件名，可以在base-path目录下的model.safetensors.index.json文件获取，例如llama2-7b-chat的权重名为pytorch_model-00001-of-00002.bin --draft-weight-name str Eagle小模型权重文件名，其格式为.bin文件或者.safetensors文件，即刚才移动的.bin文件或者.safetensors文件。 图3 权重文件名

精度比对 精度比对功能主要针对两类场景的问题： 同一模型，从CPU或GPU移植到NPU中存在精度下降问题，对比NPU芯片中的API计算数值与CPU或GPU芯片中的API计算数值，进行问题定位。 同一模型，进行迭代（模型、框架版本升级或设备硬件升级）时存在的精度下降问题，对比相同模型在迭代前后版本的API计算数值，进行问题定位。 首先通过在PyTorch训练脚本中插入dump接口，跟踪计算图中算子的前向传播与反向传播时的输入与输出，然后再使用子命令compare进行比对生成比对表格。当前比对结果支持计算Cosine（余弦相似度）、MaxAbsErr（最大绝对误差）和MaxRelativeErr（最大相对误差）、One Thousandth Err Ratio（双千分之一）和Five Thousandths Err Ratio（双千分之五）这几种评价指标，工具通过阈值过滤筛选出不达标API的输入输出提示用户进行重点关注。使用步骤如下： 通过pip安装msprobe工具。 # shell pip install mindstudio-probe 获取NPU和标杆的dump数据。 PyTorch训练脚本插入dump接口方式如下： from msprobe.pytorch import PrecisionDebugger debugger = PrecisionDebugger(config_path='./config.json') ... debugger.start() # 一般在训练循环开头启动工具。 ... # 循环体 debugger.stop() # 一般在训练循环末尾结束工具。 debugger.step() # 在训练循环的最后需要重置工具，非循环场景不需要。 具体的config.json的配置要求请参见介绍。 创建比对compare.json文件。 单卡场景 { "npu_path": "./npu_dump/dump.json", "bench_path": "./bench_dump/dump.json", "stack_path": "./npu_dump/stack.json", "is_print_compare_log": true } 多卡场景 { "npu_path": "./npu_dump/step0", "bench_path": "./bench_dump/step0", "is_print_compare_log": true } 单卡场景npu_path、bench_path、stack_path分别表示从步骤2中NPU环境所生成的dump.json、标杆环境生成的dump.json及NPU环境生成的stack.json文件，is_print_compare_log配置是否开启日志打屏。 多卡场景区别于单卡场景会在步骤2按rank标号信息生成多个rank的dump文件结果，npu_path指定NPU环境生成包含多rank目录，gpu_path指定标杆环境包含多rank目录，is_print_compare_log配置是否开启日志打屏。 精度比对生成比对报告 msproe -f pytorch compare -i ./compare.json -o ./output -s 这里-i指定步骤3所创建compare.json文件，-o指定比对结果文件存盘目录，-s配置是否生成堆栈信息。生成结果为advisor_{timestamp}.txt和compare_result_{timestamp}.xlsx文件，advisor_{timestamp}.txt列出了可能存在精度问题的API的专家建议，compare_result_{timestamp}.xlsx文件列出了所有执行精度比对的API详细信息和比对结果。 详细工具的使用指导请参考Pytorch精度比对介绍。 父主题： 精度调试: msprobe

msprobe精度分析工具使用指导 msprobe是MindStudio Training Tools工具链下精度调试部分的工具包，其通过采集和对比标杆（GPU/CPU）环境和昇腾环境上运行训练时的差异点来判断问题所在，主要包括精度预检、精度比对和梯度监控等功能。更多内容请参考msprobe工具介绍。 一般场景的训练模型都是包括随机种子、数据集Shuffle、网络结构Dropout等操作的，目的是在网络阶段引入一定的随机性使得训练结果更加具有鲁棒性。然而在精度对齐阶段，这些随机性会导致训练运行结果每次表现不一致，无法进行和标杆的比对。因此在训练模型复现问题时，需要固定存在随机性的步骤，保证实验可重复性。存在随机性的步骤包括模型参数初始化，数据Batch加载顺序，Dropout层等。部分算子的计算结果也存在不确定性，需要固定。 当前固定随机性操作可分为工具固定和人工固定两种。 工具固定Seed 对于网络中随机性的固定，msprobe提供了固定Seed的方式，只需要在config.json文件中添加对应seed配置即可。 msprobe工具提供了seed_all接口用于固定网络中的随机数。如果客户使用了工具但取用了其他随机种子，则必须使用客户的随机种子固定随机性。 函数原型 from msprobe.pytorch.common import seed_all seed_all(seed=1234, mode=False) 表1 参数说明 参数名 说明 是否必选 seed 随机数种子。参数示例：seed=1000。默认值：1234。 否 mode 确定性计算模式。可配置True或False。参数示例：mode=True。默认值：False。 即使在相同的硬件和输入下，API多次执行的结果也可能不同，开启确定性计算是为了保证在相同的硬件和输入下，API多次执行的结果相同。 确定性计算会导致API执行性能降低，通常不需要在精度问题刚开始定位时就开启，而是建议在发现模型多次执行结果不同的情况下时再开启。 rnn类算子、ReduceSum、ReduceMean等算子可能与确定性计算存在冲突，如果开启确定性计算后多次执行的结果不相同，则考虑存在这些算子。 否 函数示例 seed_all函数的随机数种子，取默认值即可，无须配置；第二个参数默认关闭，不开启确定性计算时也无须配置。 确定性计算是NPU的一套机制，用于保证算子的计算确定性。之所以要有这个机制，是为了在Debug过程中，让所有的算子计算结果前后完全一致可复现，这是大多数精度问题分析的重要前提。因此，在精度问题定位过程中，确定性计算不是目的，而是手段。很多场景下需要在确定性计算使能的情况下，进行下一步的精度问题分析定位。Cuda对部分算子实现了确定性计算，但仍有部分算子无法固定。通常需要依赖确定性计算的场景是长稳问题，因为长稳问题需要通过多次长跑来分析Loss情况，这时候如果NPU本身计算结果不确定，就难以支撑和GPU结果的多次对比。 示例1：仅固定随机数，不开启确定性计算。 seed_all() 示例2：固定随机数，开启确定性计算。 seed_all(mode=True) 在多卡训练场景下由于通信算子计算累加计算顺序不确定，需要添加以下环境变量，固定通信算子计算的确定性： export HCCL_DETERMINISTIC=TRUE 固定随机数范围 seed_all函数可固定随机数的范围如下表所示。 API 固定随机数 os.environ['PYTHONHASHSEED'] = str(seed) 禁止Python中的hash随机化。 random.seed(seed) 设置random随机生成器的种子。 np.random.seed(seed) 设置numpy中随机生成器的种子。 torch.manual_seed(seed) 设置当前CPU的随机种子。 torch.cuda.manual_seed(seed) 设置当前GPU的随机种子。 torch.cuda.manual_seed_all(seed) 设置所有GPU的随机种子。 torch_npu.npu.manual_seed(seed) 设置当前NPU的随机种子。 torch_npu.npu.manual_seed_all(seed) 设置所有NPU的随机种子。 torch.backends.cudnn.enable=False 关闭cuDNN。 torch.backends.cudnn.benchmark=False cuDNN确定性地选择算法。 torch.backends.cudnn.deterministic=True cuDNN仅使用确定性的卷积算法。 工具固定（Dropout） Dropout的实质是以一定概率使得输入网络的数据某些位置元素的数值变为0，这样可以使得模型训练更加有效。但在精度问题的定位过程之中，需要避免产生这种问题，因此需要关闭Dropout。 在导入PrecisionDebugger后，工具会自动将如下接口参数p（丢弃概率）置为0。 torch.nn.functional.dropout torch.nn.functional.dropout2d torch.nn.functional.dropout3d torch.nn.Dropout torch.nn.Dropout2d torch.nn.Dropout3d 人工固定（硬件随机差异） 工具内部对于随机的控制，是通过设定统一的随机种子进行随机性固定的。但是由于硬件的差异，会导致同样的随机种子在不同硬件上生成的随机数不同。具体示例如下： 由上图可见，torch.randn在GPU和NPU上固定随机种子后，仍然生成不同的随机张量。 对于上述场景，用户需要将网络中的randn在CPU上完成后再转到对应device。例如，StableDiffusion中需要在forward过程中逐步生成随机噪声。 这样在Host侧生成的随机张量能够保证一样，搬移到NPU或者GPU设备上仍然一样。 固定随机性完成后，可以使用缩小的模型在单机环境进行问题复现。复现后使用msprobe工具进行问题定位。需要注意的是，部分模型算法本身存在固有的随机性，在使用上述方法固定随机性后，如果使用工具也未能找到出问题的API，需要分析是否由算法本身的随机性导致。 父主题： 精度调试

场景介绍 阅读本文前建议您先了解以下内容： Stable Diffusion的基础知识，可参考Stable Diffusion github、Stable Diffusion wikipedia、diffusers github、Stable Diffusion with diffusers。 推理业务迁移到昇腾的通用流程，可参考GPU推理业务迁移至昇腾的通用指导。 由于Huggingface网站的限制，访问Stable Diffusion链接时需使用代理服务器，否则可能无法访问网站。 在Stable Diffusion迁移适配时，更多的时候是在适配Diffusers和Stable Diffusion WebUI，使其能够在昇腾的设备上运行。其中，Diffusers遵循了Huggingface的“single-file policy”的设计原则，它的三个主要模块Pipeline、Schedulers和预训练模型中，Pipeline和Schedulers都完全遵循了“single-file policy”原则。该设计原则更推荐直接复制粘贴代码，而不是进行抽象处理。因此，与模型前向运算相关的所有源代码都被直接复制粘贴到同一个文件中，而不是调用某些抽象提取出的模块化库。Diffusers的这种设计原则的好处是代码简单易用、对代码贡献者友好。然而，这种反软件结构化的设计也有明显的缺点。由于缺乏统一的模块化库，对于昇腾适配而言变得更加复杂，必须针对每个不同业务的Pipeline进行单独适配。 本文以Stable Diffusion v1.5的图生图为例，通过可以直接执行的样例代码介绍Diffusers的昇腾迁移过程。对于其他pipeline的迁移，可以在充分理解其代码的基础上，参考本文的思路进行举一反三。Stable Diffusion WebUI的迁移不包含在本文中，具体原因详见Stable Diffusion WebUI如何适配。 AI推理应用运行在昇腾设备上一般有两种方式： 方式1：通过Ascend PyTorch，后端执行推理，又称在线推理。 方式2：通过模型静态转换后，执行推理，又称离线推理。 通常为了获取更好的推理性能，推荐使用方式2的离线推理。下文将以Diffusers img2img onnx pipeline为示例来讲解如何进行离线推理模式下的昇腾迁移。迁移的整体流程如下图所示： 图1 迁移流程图 父主题： 案例：SD1.5推理迁移

步骤三：上传代码包和权重文件 上传安装依赖软件训练代码AscendCloud-LLM-6.5.902-xxx.zip到主机中，包获取路径请参见表1。 将权重文件上传到Lite Server机器中。权重文件的格式要求为Huggingface格式。开源权重文件获取地址请参见支持的模型列表。 权重要求放在磁盘的指定目录，保证模型文件、权重文件（如LFS文件）已完整下载。 修改权重（tokenizer）文件，以下模型需修改，根据所选框架及模型修改相应文件，详情参考tokenizer文件说明。 Llama-Factory：glm4-9b模型

步骤六：启动容器镜像 启动容器镜像前请先按照参数说明修改${}中的参数，可以根据实际需要增加修改参数，启动容器命令如下，Snt9B环境为例： export work_dir="自定义挂载的工作目录" #容器内挂载的目录，例如/home/ma-user/ws export container_work_dir="自定义挂载到容器内的工作目录" export container_name="自定义容器名称" export image_name="镜像名称" docker run -itd \ --device=/dev/davinci_manager \ --device=/dev/devmm_svm \ --device=/dev/hisi_hdc \ --e ASCEND_VISIBLE_DEVI CES =0-7 \ -v /usr/local/sbin/npu-smi:/usr/local/sbin/npu-smi \ -v /usr/local/dcmi:/usr/local/dcmi \ -v /usr/local/Ascend/driver:/usr/local/Ascend/driver \ --cpus 192 \ --memory 1000g \ --shm-size 1024g \ --net=host \ -v ${work_dir}:${container_work_dir} \ --name ${container_name} \ $image_name \ /bin/bash 参数说明： --name ${container_name} 容器名称，进入容器时会用到，此处可以自己定义一个容器名称，例如ascendspeed。 -v ${work_dir}:${container_work_dir} 代表需要在容器中挂载宿主机的目录。宿主机和容器使用不同的文件系统。work_dir为宿主机中工作目录，目录下存放着训练所需代码、数据等文件。container_work_dir为要挂载到的容器中的目录。为方便两个地址可以相同。 容器不能挂载/home/ma-user目录，此目录为ma-user用户家目录。 driver及npu-smi需同时挂载至容器。 不要将多个容器绑到同一个NPU上，会导致后续的容器无法正常使用NPU功能。 ${image_name} 为docker镜像的ID，在宿主机上可通过docker images查询得到。 --shm-size：表示共享内存，用于多进程间通信。由于需要转换较大内存的模型文件，因此大小要求1024g及以上。 --cpus：宿主机的 CPU 核心数，一般Snt9B机型设置为192，Snt9B23机型设置为320。 --e ASCEND_VISIBLE_DEVICES=0-7 ：设置卡号ID,一般Snt9B机型设置0-7，Snt9B23机型设置为0-15。 通过容器名称进入容器中。启动容器时默认用户为ma-user用户。 docker exec -it ${container_name} bash

步骤一：检查环境 SSH登录机器后，检查NPU设备检查。运行如下命令，返回NPU设备信息。 npu-smi info # 在每个实例节点上运行此命令可以看到NPU卡状态 npu-smi info -l | grep Total # 在每个实例节点上运行此命令可以看到总卡数，用来确认对应卡数已经挂载 npu-smi info -t board -i 1 | egrep -i "software|firmware" #查看驱动和固件版本 如出现错误，可能是机器上的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

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