华为云用户手册

使用限制 CodeLab默认打开，使用的是CPU计算资源。如需切换为GPU，请在右侧窗口，更换GPU规格。 在ModelArts控制台的“总览”界面打开CodeLab，使用的是CPU或GPU资源，无法使用Ascend资源。 如果是AI Gallery社区的Notebook案例，本身使用的资源是Ascend的，那么“Run in ModelArts”跳转到CodeLab，就可以使用昇腾卡进行训练，也支持切换规格。 自启动后，免费规格默认可使用1小时，请注意右上角的剩余时长。超过1小时后，可执行续期操作，且系统每隔一段时间，将提醒确认下续期。 免费的CodeLab主要用于体验，72小时内未使用，将释放资源。保存在其中的代码文档将丢失，请注意备份文件以及使用时长。

体验CodeLab 进入CodeLab主页。 从管理控制台总览页进入，展示CodeLab首页。 常用功能。 CodeLab的界面依托于JupyterLab，其相关的常见功能与JupyterLab相同。 常用操作指导可参见JupyterLab操作指导：JupyterLab常用功能介绍。 由于CodeLab的存储为系统默认路径，在使用“上传文件”或“下载文件至本地”时，只能使用JupyterLab页面提供的功能。 如需使用大文件上传和下载的功能，建议您前往Notebook，创建一个收费的实例进行使用。 切换规格。 CodeLab支持CPU和GPU两种规格，在右侧区域，单击切换规格，修改规格类型。 图2 切换规格 资源监控。 在使用过程中，如果想了解资源使用情况，可在右侧区域选择“Resource Monitor”，展示“CPU使用率”和“内存使用率”。 图3 资源监控 分享副本到AI Gallery。单击右上角的，将修改后的Notebook样例保存分享到AI Gallery中，供自己或他人学习使用。 图4 分享到AI Gallery 分享成功后，通过分享链接可以打开分享的副本，也可以在AI Gallery中找到分享的Notebook。 图5 发布成功

功能亮点 免费算力 CodeLab内置了免费算力，包含CPU和GPU两种。您可以使用免费规格，端到端体验ModelArts Notebook能力。也可使用此免费算力，在线完成您的算法开发。 即开即用 无需创建Notebook实例，打开即可编码。 高效分享 ModelArts在AI Gallery中提供的Notebook样例，可以直接通过Run in ModelArts，一键打开运行和学习，并且可将样例修改后分享到AI Gallery中直接另存用于个人开发。 同时，您开发的代码，也可通过CodeLab快速分享到AI Gallery中给他人使用学习。

基于自定义镜像创建Notebook实例 从Notebook中保存的镜像可以在镜像管理中查询到，可以用于创建新的Notebook实例，完全继承保存状态下的实例软件环境配置。 方式一：在Notebook实例创建页面，镜像类型选择“自定义镜像”，名称选择上述保存的镜像。 图3 创建基于自定义镜像的Notebook实例 方式二：在“镜像管理”页面，单击某个镜像的镜像详情，在镜像详情页，单击“创建Notebook”，也会跳转到基于该自定义镜像创建Notebook的页面。

镜像保存时，哪些目录的数据可以被保存 可以保存的目录：包括容器构建时静态添加到镜像中的文件和目录，可以保存在镜像环境里。 例如：安装的依赖包、“/home/ma-user”目录 不会被保存的目录：容器启动时动态连接到宿主机的挂载目录或数据卷，这些内容不会被保存在镜像中。可以通过df -h命令查看挂载的动态目录，非“/”路径下的不会保存。 例如：持久化存储的部分“home/ma-user/work”目录的内容不会保存在最终产生的容器镜像中、动态挂载在“/data”下的目录不会被保存。

常见问题 镜像保存时报错“there are processes in 'D' status, please check process status using 'ps -aux' and kill all the 'D' status processes”如何解决？ 镜像保存时报错“container size %dG is greater than threshold %dG”如何解决？ 保存镜像时报错“too many layers in your image”如何解决？ 镜像保存时报错“The container size (xG) is greater than the threshold (25G)”如何解决？

什么是动态挂载OBS并行文件系统 并行文件系统（Parallel File System）是 对象存储服务 （Object Storage Service，OBS）提供的一种经过优化的高性能文件系统，详细介绍可以参见并行文件系统。 在ModelArts运行态的Notebook容器中，采用动态挂载特性，将OBS对象存储模拟成本地文件系统。其本质是通过挂载工具，将对象协议转为POSIX文件协议。挂载后应用层可以在容器中正常操作OBS对象。

Notebook选择存储说明 不同存储的实现方式都不同，在性能、易用性、成本的权衡中可以有不同的选择，没有一个存储可以覆盖所有场景，了解下云上开发环境中各种存储使用场景说明，更能提高使用效率。 表6 云上开发环境中各种存储使用场景说明 存储类型 建议使用场景 优点 缺点 云硬盘EVS 比较适合只在开发环境中做数据、算法探索，性能较好。 块存储SSD，可以理解为一个磁盘，整体IO性能比NFS要好，可以动态扩充，最大可以到4096GB。 云硬盘EVS作为持久化存储挂载在/home/ma-user/work目录下，该目录下的内容在实例停止后会被保留，存储支持在线按需扩容。 只能在单个开发环境中使用 。 并行文件系统PFS 说明： 并行文件系统PFS为白名单功能，如需使用，请联系华为技术支持开通。 仅支持挂载同一区域下的OBS并行文件系统（PFS）。 适合直接使用PFS桶作为持久化存储进行AI开发和探索，使用场景如下。 数据集的存储。将存储在PFS桶的数据集直接挂载到Notebook进行浏览和数据处理，在训练时直接使用。直接在创建Notebook的时候选择并行文件系统PFS。 或在实例运行后，将承载数据集的OBS并行文件系统动态挂载至Notebook中，详细操作请参考动态挂载OBS并行文件系统。 代码的存储。在Notebook调测完成，可以直接指定对应的对象存储路径作为启动训练的代码路径，方便临时修改。 训练观测。可以将训练日志等输出路径进行挂载，在Notebook中实时查看和观测，特别是利用TensorBoard可视化功能完成对训练输出的分析。 PFS是一种经过优化的高性能对象存储文件系统，存储成本低，吞吐量大，能够快速处理高性能计算（HPC）工作负载。在需要使用对象存储服务场景下，推荐使用PFS挂载。 说明： 建议上传时按照128MB或者64MB打包或者切分，使用时边下载边解压后在本地存储读取，以获取更好的读写与吞吐性能。 小文件频繁读写性能较差，例如直接作为存储用于模型重型训练，大文件解压等场景慎用。 说明： PFS挂载需要用户对当前桶授权给ModelArts完整读写权限，Notebook删除后，此权限策略不会被删除。 对象存储服务OBS 说明： OBS对象存储为白名单功能，如需使用，请联系华为技术支持开通。 仅支持挂载同一区域下的OBS对象存储。 在开发环境中做大规模的数据上传下载时，可以通过OBS桶做中转。 存储成本低，吞吐量大，但是小文件读写较弱。建议上传时按照128MB或者64MB打包或者切分，使用时边下载边解压后在本地读取。 对象存储语义，和Posix语义有区别，需要进一步理解。 弹性文件服务SFS 目前只支持在专属资源池中使用；针对探索、实验等非正式生产场景，建议使用这种。开发环境和训练环境可以同时挂载一块SFS存储，省去了每次训练作业下载数据的要求，一般来说重IO读写模型，超过32卡的大规模训练不适合。 实现为NFS，可以在多个开发环境、开发环境和训练之间共享，如果不需要重型分布式训练作业，特别是启动训练作业时，不需要额外再对数据进行下载，这种存储便利性可以作为首选。 性能比EVS云硬盘块存储低。 OceanStor Pacific存储（SFS容量型2.0） 目前只支持在天工资源池中使用。 适合直接使用SFS容量型2.0提供的文件系统作为训练作业所需的存储进行AI模型的训练和探索。同时提供OBS接口，支持从云外导入训练数据。 提供高性能文件客户端，满足重型训练作业中对存储高带宽诉求，同时提供OBS访问功能，同一份训练数据通过OBS接口导入到存储之后不需要再进相关转化，即可支持模型训练。 提供对象存储语义，和Posix语义有区别，需要进一步理解。 本地存储 重型训练作业首选 运行所在虚拟机或者裸金属机器上自带的SSD高性能存储，文件读写的吞吐量大，建议对于重型训练作业先将数据准备到对应目录再启动训练。 默认在容器/cache目录下进行挂载，/cache目录可用空间请参考开发环境中不同Notebook规格资源“/cache”目录的大小。 存储生命周期和容器生命周期绑定，每次训练都要下载数据。

常见问题 在开发环境中如何使用云硬盘EVS块存储？ 例如，在创建Notebook实例时选择云硬盘EVS存储小容量，Notebook运行过程中如果发现存储容量不够，可以扩容，请参考动态扩充云硬盘EVS容量。 在开发环境中如何使用OBS并行文件系统？ 例如，在Notebook中训练时，可直接使用挂载至Notebook容器中的数据集，在运行过程中可以动态挂载OBS并行文件系统。 使用JupyterLab 4.3.1版本时启动出现问题，如何切换回JupyterLab 3.2.3版本？ 在Notebook实例列表的“操作”列，单击目标实例对应的“启动”，在弹出的对话框中，选择JupyterLab 3.2.3版本，单击“确定”后即可启动JupyterLab 3.2.3版本。 可以在一个项目中同时使用JupyterLab 3.2.3和4.3.1版本吗？ 不建议在同一个项目中同时使用两个版本。每个JupyterLab实例独立运行，因此需要为每个版本分别创建实例。如果您希望尝试不同版本，可以在不同的容器或环境中分别启动它们，但请注意以下几点： 不同版本的配置文件和数据路径可能不同，需确保数据和配置的独立性。 同时运行多个版本可能会导致端口冲突或其他资源竞争问题。 Notebook是否支持使用gdb工具？ Notebook目前不支持gdb工具的使用。gdb工具的运行依赖开启特权容器（privileged container）的Docker，而开发环境的容器出于安全考虑，无法开启特权容器，因此不支持在Notebook中使用gdb工具。

JupyterLab 4.3.1版本更新说明 JupyterLab 4.3.1版本在用户体验、功能完善和性能提升方面均有显著改进，以下是该版本的主要更新内容。关于4.3.1版本的更多功能信息，请参见JupyterLab 4.x官方文档。 表4 功能更新说明 功能模块 功能描述 工作区（Workspaces）特性 支持多个工作区，您可以在不同的工作空间中组织和管理不同的项目和文件，提升项目管理效率。 新增Launcher创建工具栏 添加新的工具栏，提供了更多的功能访问方式，使操作更加便捷。 主题框架优化 改进主题框架，增强主题的灵活性和兼容性。您可以根据需求进行个性化的界面调整。 设置界面优化 优化设置界面的用户体验，使配置更加直观和易于使用。 性能优化和调试功能增强 对系统性能进行全面优化，调试功能也得到增强，提升开发体验。 代码编辑器增强 对代码编辑器进行改进，增加更多功能和性能优化，提升代码编写和编辑的体验。 搜索功能增强 增强搜索功能，您可以更快速、更准确地查找所需内容。 性能增强 整体性能得到提升，系统的响应速度和稳定性都有显著提高。 支持自定义 CSS 样式表 支持自定义 CS S样式表，以便调整界面外观，满足个性化需求。 Markdown支持图表 在Markdown文档中支持图表功能，使图文并茂的文档编写变得更加方便。 虚拟滚动条 引入虚拟滚动条，改善大文件或大量内容的滚动体验。 Workspace UI 改进工作区用户界面，提供了更好的可视化效果和操作体验，增强界面友好性。 文件访问记录 支持查看最近打开和关闭文件，便于快速访问常用文件，提升工作效率。 键盘快捷键改进 改进键盘快捷键，提高操作的效率和便捷性。

Notebook容器挂载目录说明 创建Notebook实例，存储选择EVS时，Notebook会使用/home/ma-user/work目录作为用户的工作空间持久化存储。 存放在work目录的内容，在实例停止、重新启动后依然保留，其他目录下的内容不会保留，使用开发环境时建议将需要持久化的数据放在/home/ma-user/work目录。 更多Notebook实例的目录挂载情况（以下挂载点在保存镜像的时候不会保存）如表5所示。 表5 Notebook挂载目录说明 挂载点 是否只读 备注 /home/ma-user/work/ 否 客户数据的持久化目录。 /data 否 客户PFS的挂载目录。 /cache 否 裸机规格时支持，用于挂载宿主机NVMe的硬盘。 /train-worker1-log 否 兼容训练作业调试过程。 /dev/shm 否 用于PyTorch引擎加速。

打开Notebook实例 针对创建好的Notebook实例（即状态为“运行中”的实例），可以打开Notebook并在开发环境中启动编码。 pytorch、tensorflow、mindspore、tensorflow-mindspore、cylp-cbcpy、rlstudio-ray、mindquantum-mindspore镜像支持以下2种方式访问： 在线JupyterLab访问，具体参见通过JupyterLab在线使用Notebook实例。 本地IDE使用PyCharm工具，远程连接访问，具体参见通过PyCharm远程使用Notebook实例。 本地IDE使用VS Code工具，远程连接访问，具体参见通过VS Code远程使用Notebook实例。 本地IDE使用SSH工具，远程连接访问，具体参见通过SSH工具远程使用Notebook。 ModelArts提供的Notebook实例默认是以ma-user启动。用户进入实例后，工作目录默认是/home/ma-user/work。 图7 工作目录示例 专属池的部分Notebook实例以root用户身份启动。具体说明如下： 当以root用户身份登录终端时，系统会自动执行source /home/ma-user/.bashrc命令，以同步ma-user用户的环境变量。如果需要禁用此功能，可以通过在自定义镜像中设置环境变量export DISABLE_MA_USER_BASHRC=true，即可阻止加载/home/ma-user/.bashrc文件。 以root用户启动的实例，仅支持使用root用户进行SSH远程连接。 图8 使用root用户进行SSH远程连接

背景信息 Notebook使用涉及到计费，具体收费项如下： 处于“运行中”状态的Notebook，会消耗资源，产生费用。根据您选择的资源不同，收费标准不同，价格详情请参见产品价格详情。当您不需要使用Notebook时，建议停止Notebook，避免产生不必要的费用。 创建Notebook时，如果选择使用云硬盘EVS存储配置，实例不删除，云硬盘EVS会一直收费，建议及时停止并删除Notebook，避免产品不必要的费用。 在创建Notebook时，默认会开启自动停止功能，在指定时间内停止运行Notebook，避免资源浪费。 只有处于“运行中”状态的Notebook，才可以执行打开、停止操作。 一个账户最多创建10个Notebook。

Notebook使用场景 ModelArts提供灵活开放的开发环境，您可以根据实际情况选择。 ModelArts提供了CodeLab功能，一方面，一键进入开发环境，同时预置了免费的算力规格，可直接 免费体验 Notebook功能；另一方面，针对AI Gallery社区发布的Notebook样例（.ipynb格式文件），可直接在CodeLab中打开，查看他人分享的样例代码，具体请参见使用CodeLab免费体验Notebook。 ModelArts提供了云化版本的Notebook，无需关注安装配置，即开即用，具体参见创建Notebook实例。 ModelArts Notebook支持以下几种使用方式，用于开发基于PyTorch、TensorFlow和MindSpore等引擎的AI模型。 支持通过JupyterLab工具在线打开Notebook，具体请参见通过JupyterLab在线使用Notebook实例。 支持本地IDE的方式开发模型，通过开启SSH连接，用户本地IDE可以远程连接到ModelArts的Notebook开发环境中，调试和运行代码。本地IDE方式不影响用户的编码习惯，并且可以方便快捷地使用云上的Notebook开发环境。 本地IDE当前支持VS Code、PyCharm、SSH工具。PyCharm和VS Code还分别有专门的插件PyCharm Toolkit、VS Code Toolkit，让远程连接操作更便捷。具体参见通过PyCharm远程使用Notebook实例、通过VS Code远程使用Notebook实例、通过SSH工具远程使用Notebook。 在AI开发过程中，如何将文件方便快速地上传到Notebook几乎是每个开发者都会遇到的问题。ModelArts提供了多种文件上传方式，在文件上传过程中，可以查看上传进度和速度。 将本地文件上传，请参考支持上传本地文件； GitHub的开源仓库的文件上传，请参考支持Clone GitHub开源仓库； 存放在OBS中的文件上传，请参考支持上传OBS文件； 类似开源数据集这样的远端文件上传，请参考支持上传远端文件； 在Notebook的使用中，可以快速查找实例，可以在同一个Notebook实例中切换镜像，方便用户灵活调整实例的AI引擎；可以切换节点运行规格，方便用户灵活调整规格资源；可以初期存储使用量较小时选择小存储，可以在创建完成后根据需要扩充EVS容量；使用动态挂载OBS将OBS对象存储模拟成本地文件系统；还可以在Notebook异常时查看实例的事件定位等，具体参见管理Notebook实例。 ModelArts CLI，集成在ModelArts开发环境Notebook中，用于连接ModelArts服务并在ModelArts资源上执行管理命令。ma-cli支持用户在ModelArts Notebook及线下虚拟机中与云端服务交互，使用ma-cli命令可以实现命令自动补全、鉴权、镜像构建、提交ModelArts训练作业、提交 DLI Spark作业、OBS数据复制等，具体参见ModelArts CLI命令参考。 ModelArts Notebook内置MoXing Framework模块，ModelArts mox.file提供了一套更为方便地访问OBS的API，允许用户通过一系列模仿操作本地文件系统的API来操作OBS文件。具体参见在Notebook中使用MoXing命令。 父主题： 使用Notebook进行AI开发调试

查看训练日志 提交训练作业时，系统将自动在您配置的OBS Path中，使用作业名称创建一个新的文件夹，用于存储训练输出的模型、日志和代码。 例如“train-job-01”作业，提交作业时会在“test-modelarts2”桶下创建一个命名为“train-job-01”的文件夹，且此文件夹下分别新建了三个文件夹“output”、“log”、“code”，分别用于存储输出模型、日志和训练代码。“output”文件夹还会根据您的训练作业版本再创建子文件夹，结构示例如下。 test-modelarts2 |---train-job-01 |---output |---V0001 |---V0002 |---... |---log |---code 查看训练日志有2种方式，在OBS查看和在PyCharm ToolKit工具中查看。 在OBS查看训练日志 训练作业运行结束后，系统将日志存储至对应OBS路径下的log目录中。 在PyCharm工具的ModelArts Explorer区域，双击对应训练作业的版本名称，将在ModelArts Training Job区域展示此训练作业的详细配置。 您可以在详细配置中，找到训练日志输出路径，即OBS路径。 图5 查找日志存储路径 使用当前账号登录OBS管理控制台，根据上一个步骤获取的OBS路径，找到对应文件夹，查看训练作业的详细日志。

支持在ModelArts控制台上直接查看的监控指标 支持在ModelArts控制台训练作业详情页中直接查看的监控指标请参见表1。 支持在ModelArts控制台总览页中查看的训练相关监控指标请参见表1。 表1 训练作业任务级的指标说明 指标 说明 查看方式 训练作业资源利用率 每个训练作业的CPU、GPU或NPU资源利用率。 在ModelArts控制台总览页的“训练作业资源利用情况”版块查看。 卡时 每个训练作业运行时长和占用卡数。 在ModelArts控制台总览页的“训练作业资源利用情况”版块查看。

使用SDK上报自定义监控指标到 AOM 通过在代码中集成SDK，手动上传指标数据到AOM。 该方案适用于监控高度定制化的指标，例如自定义维度或复杂计算，需要在代码层面直接控制指标的上报，适合复杂的业务逻辑。 准备训练代码，在训练代码中增加指标监控的代码。具体代码示例如下。准备训练代码的其它要求请参见准备模型训练代码。 代码中倒数第2行的region = "cn-southwest-2"参数值请替换成实际region值，region取值可以参考终端节点。 代码中增加监控指标数据，具体参数解释参考AOM文档。 # coding: utf-8 import os from huaweicloudsdkaom.v2 import * from huaweicloudsdkaom.v2.region.aom_region import AomRegion from huaweicloudsdkcore.auth.credentials import BasicCredentials from huaweicloudsdkcore.exceptions import exceptions from moxing.framework import cloud_utils def report2Aom(request,region): auth = cloud_utils.get_auth() #AK、SK和临时TOKEN值，系统会自动获取无需在代码中填写。 ak = auth.AK sk = auth.SK securityToken = auth.TOKEN projectId = os.environ.get("MA_ IAM _PROJECT_ID") credentials = BasicCredentials(ak, sk, projectId).with_security_token(securityToken) client = AomClient.new_builder() \ .with_credentials(credentials) \ .with_region(AomRegion.value_of(region)) \ .build() try: response = client.add_metric_data(request) print(response) except Exception as e: print(e) if __name__ == "__main__": request = AddMetricDataRequest() listValuesBody = [ #下面填上对应的指标名称、类型、单位、数值，比如step_time、loss值等 ValueData( metric_name="step_time", #监控指标名称，例如step_time type="float", #指标的数据类型，取值范围只能是"int"或"float"。 unit="ms", #数据的单位。长度不超过32个字符，此处举例为ms value=135.572 #指标数据的值。取值范围有效的数值类型。最小值0 ), ValueData( metric_name="loss", type="float", value=0.6932 ) ] listDimensionsMetric = [ #下面填上想查看的指标维度，比如线程、host等等 Dimension2( name="cluster_name",#此处仅为举例示意，请替换为实际需要查看的指标维度 value="fab2c5cf438b4f0c851fdcdf"# 此处仅为举例示意，请替换为实际参数值 ), Dimension2( name="user_name", value="modelarts_02" # 此处仅为举例示意，请替换为实际参数值 ), Dimension2( name="user_id", value="04f258c8fb00d42a1f6xxx" # 此处仅为举例示意，请替换为实际参数值 ) ] metricBody = MetricItemInfo( dimensions=listDimensionsMetric, namespace="NOPAAS.ESC" #保持默认值即可，无需修改 ) listBodybody = [ MetricDataItem( collect_time=int(round(time.time()*1000)), #监控指标数据收集时间，为最新的时间戳，ms为单位 metric=metricBody, values=listValuesBody ) ] request.body = listBodybody region = "cn-southwest-2" #请根据实际region替换 response = report2Aom(request,region) 在训练代码中加入命令，用于加载对应的依赖包。如果使用的是自定义镜像，也可以在制作镜像时安装以下依赖，具体参见开发用于自定义镜像训练的代码。 pip install huaweicloudsdkaom pip install huaweicloudsdkcore 创建训练作业并运行，具体参考创建生产训练作业章节。 登录AOM控制台，在“指标浏览”页面，通过指定“指标”查看上报的指标数据。 图1 AOM上查看指标数据 参考告警上报配置方法章节设置AOM告警和通知机制。

设置训练存储加速 当完成上传数据至OBS并预热到SFS Turbo中步骤后，在ModelArts Standard中创建训练作业时，设置训练“SFS Turbo”，在“文件系统”中选择SFS Turbo实例名称，并指定“存储位置”和“云上挂载路径”。系统会在训练作业启动前，自动将存储位置中的文件目录挂载到训练容器中指定路径。 图2 设置训练“SFS Turbo” 当前训练作业支持挂载多个弹性文件服务SFS Turbo，文件系统支持重复挂载，但挂载路径不可重复。文件系统目录需指定已存在的目录，否则会导致训练作业异常。

什么是增量训练 增量训练（Incremental Learning）是机器学习领域中的一种训练方法，它允许人工智能（AI）模型在已经学习了一定知识的基础上，增加新的训练数据到当前训练流程中，扩展当前模型的知识和能力，而不需要从头开始。 增量训练不需要一次性存储所有的训练数据，缓解了存储资源有限的问题；另一方面，增量训练节约了重新训练中需要消耗大量算力、时间以及经济成本。 增量训练特别适用于以下情况： 数据流更新：在实际应用中，数据可能会持续更新，增量训练允许模型适应新的数据而不必重新训练。 资源限制：如果重新训练一个大型模型成本过高，增量训练可以是一个更经济的选择。 避免灾难性遗忘：在传统训练中，新数据可能会覆盖旧数据的知识，导致模型忘记之前学到的内容。增量训练通过保留旧知识的同时学习新知识来避免这个问题。 增量训练在很多领域都有应用，比如自然语言处理、计算机视觉和推荐系统等。它使得AI系统能够更加灵活和适应性强，更好地应对现实世界中不断变化的数据环境。

ModelArts Standard中如何实现增量训练 增量训练是通过Checkpoint机制实现。 Checkpoint的机制是：在模型训练的过程中，不断地保存训练结果（包括但不限于EPOCH、模型权重、优化器状态、调度器状态）。当需要增加新的数据继续训练时，只需要加载Checkpoint，并用Checkpoint信息初始化训练状态即可。用户需要在代码里加上reload ckpt的代码，使能读取前一次训练保存的预训练模型。 在ModelArts训练中实现增量训练，建议使用“训练输出”功能。 在创建训练作业时，设置训练“输出”参数为“train_url”，在指定的训练输出的数据存储位置中保存Checkpoint，且“预下载至本地目录”选择“下载”。选择预下载至本地目录时，系统在训练作业启动前，自动将数据存储位置中的Checkpoint文件下载到训练容器的本地目录。 图1 训练输出设置

构建自定义训练镜像 图1 训练作业的自定义镜像制作流程 场景一：预置镜像满足ModelArts训练平台约束，但不满足代码依赖的要求，需要额外安装软件包。 具体案例参考使用预置镜像制作自定义镜像用于训练模型。 场景二：已有本地镜像满足代码依赖的要求，但是不满足ModelArts训练平台约束，需要适配。 具体案例参考已有镜像迁移至ModelArts用于训练模型。 场景三： 当前无可使用的镜像，需要从0制作镜像（既需要安装代码依赖，又需要制作出的镜像满足ModelArts平台约束）。具体案例参考： 从0制作自定义镜像用于创建训练作业（Pytorch+Ascend） 从0制作自定义镜像用于创建训练作业（PyTorch+CPU/GPU） 从0制作自定义镜像用于创建训练作业（MPI+CPU/GPU） 从0制作自定义镜像用于创建训练作业（Tensorflow+GPU） 从0制作自定义镜像用于创建训练作业（MindSpore+Ascend）

训练作业的预置框架介绍 ModelArts中预置的训练基础镜像如下表所示。 表1 ModelArts训练基础镜像列表 引擎类型 版本名称 PyTorch pytorch_1.8.0-cuda_10.2-py_3.7-ubuntu_18.04-x86_64 TensorFlow tensorflow_2.1.0-cuda_10.1-py_3.7-ubuntu_18.04-x86_64 Horovod horovod_0.20.0-tensorflow_2.1.0-cuda_10.1-py_3.7-ubuntu_18.04-x86_64 horovod_0.22.1-pytorch_1.8.0-cuda_10.2-py_3.7-ubuntu_18.04-x86_64 MPI mindspore_1.3.0-cuda_10.1-py_3.7-ubuntu_1804-x86_64 Ascend-Powered-Engine tensorflow_1.15-cann_5.1.0-py_3.7-euler_2.8.3-aarch64 mindspore_1.7.0-cann_5.1.0-py_3.7-euler_2.8.3-aarch64

训练作业在容器中的挂载点说明 使用自定义镜像训练模型时，训练作业在容器中的挂载点参考如表2所示。 表2 训练作业挂载点介绍 挂载点 是否只读 备注 /xxx 否 专属池使用SFS盘挂载的目录，路径由客户自己指定。 /home/ma-user/modelarts 否 空文件夹，建议用户主要用这个目录。 /cache 否 裸机规格支持，挂载宿主机NVMe的硬盘。 /dev/shm 否 用于PyTorch引擎加速。 /usr/local/nvidia 是 宿主机的nvidia库。

常见问题 在训练时发生找不到“$ANACONDA_DIR/envs/$DEFAULT_CONDA_ENV_NAME/lib ”目录下“.so”文件的相关报错如何处理？ 如果在训练时发生找不到“$ANACONDA_DIR/envs/$DEFAULT_CONDA_ENV_NAME/lib ”目录下“.so”文件的相关报错，可以尝试将该目录加入到“LD_LIBRARY_PATH”，将以下命令放在上述启动方式命令前： export LD_LIBRARY_PATH=$ANACONDA_DIR/envs/$DEFAULT_CONDA_ENV_NAME/lib:$LD_LIBRARY_PATH; 例如，方式一的启动命令示例此时变为： export LD_LIBRARY_PATH=$ANACONDA_DIR/envs/$DEFAULT_CONDA_ENV_NAME/lib:$LD_LIBRARY_PATH; python /home/ma-user/modelarts/user-job-dir/code/train.py

使用Ascend自定义镜像训练时的训练代码适配规范 使用NPU资源创建训练作业时，系统会在训练容器里自动生成Ascend HCCL RANK_TABLE_FILE文件。当使用预置框架创建训练作业时，在训练过程中预置框架会自动解析Ascend HCCL RANK_TABLE_FILE文件，当使用自定义镜像创建训练作业时，就要适配训练代码使得训练过程中在代码里读取解析Ascend HCCL RANK_TABLE_FILE文件。 Ascend HCCL RANK_TABLE_FILE文件说明 Ascend HCCL RANK_TABLE_FILE文件提供Ascend分布式训练作业的集群信息，用于Ascend芯片分布式通信，可以被HCCL集合通信库解析。该文件格式有模板一和模板二两个版本。 ModelArts提供的是模板二格式。ModelArts训练环境的Ascend HCCL RANK_TABLE_FILE文件名为jobstart_hccl.json，获取方式可以通过预置的RANK_TABLE_FILE环境变量实现。 表1 RANK_TABLE_FILE环境变量说明 环境变量 说明 RANK_TABLE_FILE 该环境变量指示Ascend HCCL RANK_TABLE_FILE文件所在目录，值为/user/config。 算法开发者可通过 “${RANK_TABLE_FILE}/jobstart_hccl.json”，路径获取该文件。 ModelArts训练环境jobstart_hccl.json文件内容（模板二）示例： { "group_count": "1", "group_list": [{ "device_count": "1", "group_name": "job-trainjob", "instance_count": "1", "instance_list": [{ "devices": [{ "device_id": "4", "device_ip": "192.1.10.254" }], "pod_name": "jobxxxxxxxx-job-trainjob-0", "server_id": "192.168.0.25" }] }], "status": "completed" } jobstart_hccl.json文件中的status字段的值在训练脚本启动时，并不一定为completed状态。因此需要训练脚本等待status字段的值等于completed之后，再去读取文件的剩余内容。 通过训练脚本，可以使用模板一格式的jobstart_hccl.json文件，在等待status字段的值等于completed之后，将模板二格式jobstart_hccl.json文件转换为模板一格式的jobstart_hccl.json文件。 转换后的jobstart_hccl.json文件格式（模板一）示例： { "server_count": "1", "server_list": [{ "device": [{ "device_id": "4", "device_ip": "192.1.10.254", "rank_id": "0" }], "server_id": "192.168.0.25" }], "status": "completed", "version": "1.0" } 转换功能的实现，可参考从0制作自定义镜像用于创建训练作业（MindSpore+Ascend）中所述的Ascend训练脚本的启动脚本。

自定义镜像的启动命令规范 用户遵循ModelArts镜像的规范要求制作镜像，选择自己的镜像，并且通过指定代码目录（可选）和启动命令的方式来创建的训练作业。 图1 创建训练作业选择自定义方式 当使用完全自定义镜像创建训练作业时，“启动命令”必须在“/home/ma-user”目录下执行，否则训练作业可能会运行异常。 对于启动命令，当存在输入管道、输出管道、或是超参的情况下，请保证启动命令的最后一条命令是运行训练脚本，否则执行会报错。 完全使用自定义镜像创建训练作业需要通过指定的“conda env”启动训练。 由于训练作业运行时不是shell环境，因此无法直接使用“conda activate”命令激活指定的 “conda env”，需要使用其他方式以达成使用指定“conda env”来启动训练的效果。假设您的自定义镜像中的“conda”安装于“/home/ma-user/anaconda3”目录“conda env”为“python-3.7.10”，训练脚本位于“/home/ma-user/modelarts/user-job-dir/code/train.py”。可通过以下方式使用指定的“conda env”启动训练： 方式一：为镜像设置正确的“DEFAULT_CONDA_ENV_NAME”环境变量与“ANACONDA_DIR”环境变量。 ANACONDA_DIR=/home/ma-user/anaconda3 DEFAULT_CONDA_ENV_NAME=python-3.7.10 您可以使用Python命令启动训练脚本。启动命令示例如下： python /home/ma-user/modelarts/user-job-dir/code/train.py 方式二：使用“conda env python”的绝对路径。 您可以使用“/home/ma-user/anaconda3/envs/python-3.7.10/bin/python”命令启动训练脚本。启动命令示例如下： /home/ma-user/anaconda3/envs/python-3.7.10/bin/python /home/ma-user/modelarts/user-job-dir/code/train.py 方式三：设置PATH环境变量。 您可以将指定的“conda env bin”目录配置到PATH环境变量中。您可以使用Python命令启动训练脚本。启动命令示例如下： export PATH=/home/ma-user/anaconda3/envs/python-3.7.10/bin:$PATH; python /home/ma-user/modelarts/user-job-dir/code/train.py 方式四：使用“conda run -n”命令。 您可以使用“/home/ma-user/anaconda3/bin/conda run -n python-3.7.10”命令来执行训练命令，启动命令示例如下： /home/ma-user/anaconda3/bin/conda run -n python-3.7.10 python /home/ma-user/modelarts/user-job-dir/code/train.py 启动命令的最后一条命令必须为运行训练脚本命令。 对于启动命令，当存在输入管道、输出管道、或是超参的情况下，请保证启动命令的最后一条命令是运行训练脚本。 原因：系统会将输入管道、输出管道、以及超参添加到启动命令的末尾，如果最后一条命令不是运行训练脚本则会报错。 例如：启动命令的最后一条是python train.py，且存在--data_url超参，系统正常运行会执行python train.py --data_url=/input。但是当启动命令python train.py后面有其他命令时，如下所示： python train.py pwd #反例，启动命令的最后一条命令不是运行训练脚本，而是pwd 此时，如果拼接了输入管道、输出管道、以及超参，系统运行实际执行的是python train.py pwd --data_url=/input，就会报错。

常见问题 在torchrun初始化分布式一致性协商阶段出现“RuntimeError：Socket Timeout”错误时，如何解决？ 如果在torchrun初始化分布式一致性协商阶段出现RuntimeError：Socket Timeout错误时，可以通过增加如下环境变量再次创建训练作业以查看torchrun初始化阶段的详细信息，进一步排查问题。 LOG LEVEL=INFO TORCH_CPP_LOG_LEVEL=INFO TORCH_DISTRIBUTED_DEBUG=DETAIL 出现RuntimeError: Socket Timeout错误，一般是因为不同任务执行torchrun命令的时机差距过大导致的。torchrun命令执行时机差距过大，又多是因为在torchrun命令被执行之前任务还有一些初始化动作，例如下载训练数据集、CKPT等。这些初始化动作执行耗时差距过大会直接导致出现Socket Timeout错误。所以遇到Socket Timeout问题时首先需要排查的是各个任务执行torchrun的时间点差距是否在合理范围内，如果时间点差距过大，需要优化执行torchrun命令之前的初始化动作，使其时间点差距在合理范围内。

Ascend-Powered-Engine框架启动 在ModelArts创建训练作业界面选择AI框架时，有一个AI框架是“Ascend-Powered-Engine”，它既不是一个AI框架（如：PyTorch、TensorFlow）也不是一个并行执行框架（如：MPI），而是适配加速芯片Ascend的一组AI框架+运行环境+启动方式的集合。 由于主流的Snt9系列Ascend加速卡都跑在ARM CPU规格的机器上，因此上层Docker镜像也都是ARM镜像。相对于GPU场景的镜像中安装了与GPU驱动适配的CUDA（由英伟达推出的统一计算架构）计算库，Ascend-Powered-Engine引擎的镜像中安装了与Ascend驱动适配的CANN（华为针对AI场景推出的异构计算架构）计算库。 提交训练作业后，ModelArts Standard平台会自动运行训练作业的启动文件。 Ascend-Powered-Engine框架单机启动命令和分布式启动命令无区别。 Ascend-Powered-Engine框架支持3种启动方式来启动“启动文件”，默认是基于“RANK_TABLE_FILE”启动，也可以通过配置环境变量“MA_RUN_METHOD”使用其他方式来启动。MA_RUN_METHOD环境变量支持torchrun和msrun。 启动方式一：使用RTF文件启动训练作业 在没有配置环境变量“MA_RUN_METHOD”时，ModelArts Standard平台默认使用rank table file（RTF）文件启动训练作业的“启动文件”。 每个训练作业的启动文件的运行次数取决于任务卡数，即在训练作业运行时，有N个任务卡数训练作业内就会运行N次启动文件。例如，单机1卡，则worker-0任务的启动文件会被运行1次；单机8卡，则worker-0任务的启动文件会被运行8次。因此需要避免在启动文件中进行端口监听。 启动文件会被自动设置如下环境变量： RANK_TABLE_FILE：RTF文件路径。 ASCEND_DEVICE_ID：逻辑device_id，例如单卡训练，该值始终为 0。 RANK_ID：可以理解为训练作业级的device逻辑（顺序）编号。 RANK_SIZE：根据RTF中device的数目设置该值，例如“4 * Snt9b”，则该值即为4。 当需要启动文件仍然在逻辑上仅运行1次时，则可以在启动文件中判断“ASCEND_DEVICE_ID”的值，当值为“0”则执行逻辑，当值为非0则直接退出。 当需要启用ranktable动态路由进行训练网络加速时，则可以添加环境变量“ROUTE_PLAN=true”。详细使用指导请参见训练作业动态路由加速。 Ascend-Powered-Engine框架对应的代码示例“mindspore-verification.py”，请参见训练mindspore-verification.py文件。 启动方式二：使用torchrun命令启动训练作业 当环境变量“MA_RUN_METHOD=torchrun”时，表示ModelArts Standard平台使用torchrun命令启动训练作业的“启动文件”。 要求PyTorch版本大于等于1.11.0。 单机时，ModelArts Standard平台使用如下命令启动训练作业的“启动文件”。 torchrun --standalone --nnodes=${MA_NUM_HOSTS} --nproc_per_node=${MA_NUM_GPUS} ${MA_EXTRA_TORCHRUN_PA RAM S} "启动文件" {arg1} {arg2} ... 多机时，ModelArts Standard平台使用如下命令启动训练作业的“启动文件”。 torchrun --nnodes=${MA_NUM_HOSTS} --nproc_per_node=${MA_NUM_GPUS} --node_rank=${VC_TASK_INDEX} --master_addr={master_addr} --master_port=${MA_TORCHRUN_MASTER_PORT} --rdzv_id={ma_job_name} --rdzv_backend=static ${MA_EXTRA_TORCHRUN_PARAMS} "启动文件" {arg1} {arg2} ... 参数说明如下： 表2 使用torchrun命令启动训练作业参数说明 参数名 参数解释 standalone 标识为单任务实例作业。 nnodes 任务实例个数。 nproc_per_node 每个任务实例启动的主进程数，设置为任务分配的NPU数相同。 node_rank 任务rank，用于多任务分布式训练。 master_addr 主任务（rank 0）的地址，设置为任务worker-0的通信 域名 。 master_port 在主任务（rank 0）上，用于分布式训练期间通信的端口。默认设置为18888端口。当遇到master_port冲突问题时，可通过设置MA_TORCHRUN_MASTER_PORT环境变量值修改端口配置。 rdzv_id Rendezvous标识，设置为带有训练作业ID的值。 rdzv_backend Rendezvous后端，固定设置为static，即不使用Rendezvous，而是使用master_addr和master_port配置。 另外，可通过设置MA_EXTRA_TORCHRUN_PARAMS环境变量值，以增加额外的torchrun命令参数，或是覆盖预设的torchrun命令参数。例如配置torchrun命令中rdzv_conf参数的训练作业API环境变量的部分示例如下： "environments": { "MA_RUN_METHOD": "torchrun", "MA_EXTRA_TORCHRUN_PARAMS": "--rdzv_conf=timeout=7200" } 如果在torchrun初始化分布式一致性协商阶段出现“RuntimeError：Socket Timeout”错误时，可以查看常见问题1，进一步排查问题。 启动方式三：使用msrun命令启动训练作业 当环境变量“MA_RUN_METHOD=msrun”时，表示ModelArts Standard平台使用msrun命令启动训练作业的“启动文件”。 要求MindSpore版本大于等于2.3.0。 该方案支持动态组网和基于rank table file文件组网两种方式。当配置了环境变量MS_RANKTABLE_ENABLE="True"，则msrun会读取rank table file文件内容进行组网。否则默认使用动态组网。 msrun使用如下命令启动训练作业的“启动文件”。 msrun --worker_num=${msrun_worker_num} --local_worker_num=${MA_NUM_GPUS} --master_addr=${msrun_master_addr} --node_rank=${VC_TASK_INDEX} --master_port=${msrun_master_port} --log_dir=${msrun_log_dir} --join=True --cluster_time_out=${MSRUN_CLUSTER_TIME_OUT} --rank_table_file=${msrun_rank_table_file} "启动文件" {arg1} {arg2} ... 参数说明如下： 表3 msrun命令启动训练作业参数说明 参数名 参数解释 worker_num 所有进程个数。因为一个卡起一个进程，所以也表示使用总卡数。 local_worker_num 当前节点进程个数，即当前节点使用的卡数。 master_addr msrun组网调度进程所在节点的IP地址，单机场景无需配置。 master_port msrun组网调度进程的端口。 node_rank msrun组网调度进程的端口。 log_dir msrun组网和各个进程的日志输出地址。 join 训练进程拉起后，msrun进程是否仍存在，默认配置为“True”，等待所有进程退出后再退出。 cluster_time_out 集群组网超时时间，默认是“600s”，可通过环境变量“MSRUN_CLUSTER_TIME_OUT”控制。 rank_table_file rank table file文件地址，如果配置了环境变量“MS_RANKTABLE_ENABLE="True"”，启动时会增加该参数。

训练框架的自定义镜像约束 推荐自定义镜像使用ubuntu-18.04的操作系统，避免出现版本不兼容的问题。 自定义镜像的大小推荐15GB以内，最大不要超过资源池的容器引擎空间大小的一半。镜像过大会直接影响训练作业的启动时间。 ModelArts公共资源池的容器引擎空间为50G，专属资源池的容器引擎空间的默认为50G，支持在创建专属资源池时自定义容器引擎空间。 自定义镜像的默认用户必须为“uid”为“1000”的用户。 自定义镜像中不能安装GPU或Ascend驱动程序。当用户选择GPU资源运行训练作业时，ModelArts后台自动将GPU驱动程序放置在训练环境中的 /usr/local/nvidia目录；当用户选择Ascend资源运行训练作业时，ModelArts后台自动将Ascend驱动程序放置在/usr/local/Ascend/driver目录。 X86 CPU架构和ARM CPU架构的自定义镜像分别只能运行于对应CPU架构的规格中。 执行如下命令，查看自定义镜像的CPU架构。 docker inspect {自定义镜像地址} | grep Architecture ARM CPU架构的自定义镜像，上述命令回显如下。 "Architecture": "arm64" 规格中带有ARM字样的显示，为ARM CPU架构。 规格中未带有ARM字样的显示，为X86 CPU架构。 ModelArts后台暂不支持下载开源安装包，建议用户在自定义镜像中安装训练所需的依赖包。 自定义镜像需上传至 容器镜像服务 （SWR）才能在ModelArts上用于训练。

构建自定义训练镜像 图1 训练作业的自定义镜像制作流程 场景一：预置镜像满足ModelArts训练平台约束，但不满足代码依赖的要求，需要额外安装软件包。 具体案例参考使用预置镜像制作自定义镜像用于训练模型。 场景二：已有本地镜像满足代码依赖的要求，但是不满足ModelArts训练平台约束，需要适配。 具体案例参考已有镜像迁移至ModelArts用于训练模型。 场景三： 当前无可使用的镜像，需要从0制作镜像（既需要安装代码依赖，又需要制作出的镜像满足ModelArts平台约束）。具体案例参考： 从0制作自定义镜像用于创建训练作业（Pytorch+Ascend） 从0制作自定义镜像用于创建训练作业（PyTorch+CPU/GPU） 从0制作自定义镜像用于创建训练作业（MPI+CPU/GPU） 从0制作自定义镜像用于创建训练作业（Tensorflow+GPU） 从0制作自定义镜像用于创建训练作业（MindSpore+Ascend）