附录

边缘容器日志输出指导

使用背景

由于边缘设备（如Atlas 500 A2 智能小站）存储空间有限，并且边缘设备多采用eMMC等flash作为存储介质，该介质存在使用寿命的限制。为避免存储空间过快被写满从而影响业务或存储介质过快达到使用寿命，用户可以参考本章节边缘容器日志的输出建议，使边缘容器以合适的方式输出日志。

输出方式

当前Atlas硬件上运行的边缘容器应用一般是通过K8s兼容的边缘管理平台来进行管理，如华为云IEF或基于KubeEdge搭建的第三方边缘平台等。在该平台下，容器日志的输出方式主要分为以下三种：

• 容器控制台标准输出（STDOUT和STDERR）方式
• （推荐）挂载到主机目录方式
• 容器日志直接输出到日志服务

容器控制台标准输出方式

在这种方式下，应用将容器的日志输出到标准输出。缺省情况下，Docker引擎捕捉所有容器的标准输出，使用JSON格式写入到文件里，该文件会保存到主机的/var/lib/docker/containers/{containerid}目录下，如图1所示。

图 1 {containerid}-json.log文件所在路径示例

（推荐）挂载到主机目录方式

该方式下边缘平台日志收集的方式如图2所示。

图 2 方案架构

应用将容器日志挂载到边缘主机上。边缘管理平台提供主机上日志收集能力，并将主机文件日志进行绕接。

容器日志直接输出到日志服务

如图3所示，应用环境里如果有日志服务器，可以将日志直接输出到外部日志服务器，使日志不在边缘环境里落盘，最大限度减少对硬件和其他业务的影响。

图 3 方案架构

Ascend Docker Runtime默认挂载内容

Ascend Docker Runtime会根据实际环境情况默认以只读方式挂载以下目录和文件到容器中。挂载的文件对other用户不能有写权限，对同组内的其他用户也不能有写权限。

表 1 默认挂载目录和文件（Atlas 200 AI加速模块（RC场景））

表 2 默认挂载目录和文件（Atlas 200I SoC A1 核心板）

表 3 默认挂载目录和文件（Atlas 200I A2 加速模块和Atlas 200I DK A2 开发者套件）

表 4 默认挂载目录和文件（Atlas 500 智能小站（型号 3000））

表 5 默认挂载目录和文件（Atlas 500 A2 智能小站）

表 6 默认挂载目录和文件（Atlas 350 标卡）

表 7 默认挂载目录和文件（其他设备）

Ascend Docker Runtime默认挂载白名单

Ascend Docker Runtime通过ASCEND_RUNTIME_MOUNTS参数，提供了配置自定义默认挂载项的特性，具体操作请参考（可选）配置自定义挂载内容章节。Ascend Docker Runtime的默认挂载项受白名单限制，具体白名单列表如表1所示。

表 1 默认挂载白名单列表

Ascend Docker Runtime命令说明

Ascend Docker Runtime安装后，会在安装目录生成可执行工具，涉及到的指令为内部命令，用户请勿直接使用，相关指令如表1所示。

表 1 命令说明

镜像和二进制部署差异

表 1 组件两种安装方式差异

使用ServiceAccount和KubeConfig差异

表 1 K8s认证授权方式差异

高可用集群中的调度组件

生产环境中，Kubernetes集群通常会部署多个管理节点，以避免单个管理节点故障导致整个集群不可用。Kubernetes官方提供了两种高可用的集群搭建方案，请参见Kubernetes文档中高可用拓扑选项。集群调度组件基于官方“Stacked etcd topology”方案进行验证，各组件能够在多个管理节点场景下正常运行，且功能正常。

多管理节点场景需要保证所有管理节点配置一致，如集群调度组件镜像、日志目录、运行用户、节点标签等配置需一致。多管理节点下集群调度组件的安装请参见安装部署章节。多管理节点的安装请参见K8s官方文档利用kubeadm创建高可用集群。

使用Containerd的集群调度组件

Kubernetes 1.20版本之后，将不再支持使用Docker作为CRI（container runtime interface）。生产环境中，如果对使用的K8s有高版本要求时，需要考虑改用其它CRI。集群调度组件基于主流CRI Containerd的1.4.4版本进行安装和验证，各组件能够在Containerd + Kubernetes场景下正常运行，且功能正常。

Containerd安装流程请参见官方资料。集群调度组件安装时默认使用Ascend Docker Runtime，可以配置Containerd使用Ascend Docker Runtime替代runc，用于在启动容器时自动挂载设备，对Containerd需要做的配置请参见安装部署章节的Containerd场景下安装Ascend Docker Runtime。

模型训练任务说明

使用其他调度器时，根据服务器类型，对训练任务的约束如下。当使用集群调度组件的Volcano作为调度器时，调度任务时已经满足如下使用约束。

表 1 训练任务使用说明

Ascend Device Plugin通信文件

Socket文件通信

在Ascend Device Plugin插件中，会生成用于通信的sock文件，sock文件的类型如下所示。

• npu.sock
• Ascend910.sock
• Ascend310.sock
• Ascend310P.sock
• davinci-mini.sock
• Ascend910-X.sock：X可取值为2c、4c、8c、16c、12c.3cpu.32g、12c.3cpu.32g.dvpp、12c.3cpu.32g.ndvpp、6c.1cpu.16g、3c.0.5cpu.8g、10c.3cpu.16g、10c.3cpu.16g.dvpp、10c.3cpu.16g.ndvpp、5c.1cpu.8g、4c.1cpu.5g、10c.3cpu.32g、10c.3cpu.32g.dvpp、10c.3cpu.32g.ndvpp和5c.1cpu.16g
• Ascend310P-X.sock：X可取值1c、2c、4c、2c.1cpu、4c.3cpu、4c.3cpu.ndvpp、4c.4cpu.dvpp

上述sock文件仅用于和本机的K8s通信。

芯片故障码参考文档

各个产品芯片故障码的详细说明，可以参见表1。

表 1 产品故障码参考文档

节点故障码参考文档

各个产品节点故障码的详细说明，可以参见表1。

表 1 节点故障码参考文档

名词说明

本章节介绍了集群调度组件用户指南中部分名词，方便用户更好的理解文档内容和步骤，名词介绍如表1所示。

表 1 名词解释

公网地址

表 1 集群调度组件代码非公网地址说明

安全说明

断点续训展示的代码为开源代码，其中涉及到的脚本（Python以及shell）需要设置相同的用户和用户组。出于安全的考虑，建议用户对其中的输入参数、文件目录、文件路径等信息进行校验。

输入参数校验项目包括但不限于：

• 涉及使用外部变量作为命令的一部分都进行严格的参数校验和防注入措施。
• 从环境变量中获取的外部变量在用于命令拼接之前都要做严格的校验和防注入措施。
• 所有的进程理应最小权限原则，避免由于注入导致严重后果。
• 代码中不存在直接使用外部变量作为命令。
• 遵守各类编程语言安全规范。

文件路径校验项目包括但不限于：

• 路径长度有做限制。
• 路径有做特殊字符过滤和防绕过机制。
• 不存在命令注入。
• 进程满足最小权限原则。
• 白名单中不存在高危路径。
• 文件路径真实性有校验，有做抛异常处理。
• 命令注入是可控外部变量导致的非预期行为。
• 恢复策略只支持Python 3.7和Python 3.9版本。
• 脚本适配中，用户需要根据情况对异常进行捕获并按照业务逻辑处理。

用户信息列表

请周期性地更新用户的密码，避免长期使用同一个密码带来的风险。

系统用户

集群调度组件容器内用户

nginx容器内用户（非安全加固场景不涉及）

Dockerfile示例中alpha基础镜像中的用户

Dockerfile示例中Ubuntu基础镜像中的用户

K8s的ServiceAccount

表 1 组件在K8s中创建的ServiceAccount列表

mindcluster-deploy开源仓版本说明

mindcluster-deploy为MindCluster集群调度组件的开源仓库，仓库提供MindCluster示例代码和脚本仅供参考，不能用于生产环境。

代码仓版本配套关系说明如下：

表 1 mindcluster-deploy代码仓版本配套说明

进程级在线恢复验证

本章节通过在训练代码中打桩构造片上内存的UCE故障，指导用户完成进程级在线恢复验证的适配步骤。

MindCluster适配

1. 拉取MindCluster代码。

   mkdir -p /data/atlas_dls/public/code
   cd /data/atlas_dls/public/code
   git clone https://gitcode.com/Ascend/mind-cluster.git
   cd ./mind-cluster/component/clusterd
   git checkout v26.0.0   # v26.0.0是代码仓版本tag，请自行切换到目标版本
   

2. 修改ClusterD代码。

   1. 打开“pkg/application/faultmanager/jobprocess/faultrank/job_fault_rank_processor.go”文件。

      vi pkg/application/faultmanager/jobprocess/faultrank/job_fault_rank_processor.go
      

   2. 按“i”进入编辑模式，添加如下加粗代码。

       package faultrank
       
       import (
       …
           "clusterd/pkg/domain/faultdomain/collector"
       …
       )
       …
       func (processor *jobRankFaultInfoProcessor) findFaultRankForJob(
       …
               if deviceDetail, ok := processor.retryInBusinessPlane(podInfo.jobId, nodeName, deviceName); ok {
             faultRankList = append(faultRankList, constant.FaultRank{RankId: deviceInfo.RankID, PodUid: podUid,
               PodRank: podRankStr, FaultCode: faultdomain.GetRetryCodeByFaultType(deviceDetail.FaultType),
               FaultLevel:  constant.RestartBusiness,
               DoStepRetry: processor.canDoStepRetry(podInfo.jobId, nodeName, deviceName),
               DeviceId:    deviceInfo.DeviceID,
             })
             collector.ReportInfoCollector.ReportRetryInfo(podInfo.jobId, deviceInfo.RankID, constant.JobNotRecover, constant.UceFaultType)   // 业务面故障时间设置为无效时间，避免单次故障重复触发进程级在线恢复
           }
       …

   3. 按“Esc”键，输入:wq!，按“Enter”保存并退出编辑。

3. 编译ClusterD。

   cd ./build/
   chmod +x build.sh && dos2unix build.sh
   sed -i 's|build_version="v[^"]\+"|build_version="xxx"|g' build.sh  # xxx替换为版本号，如v26.0.0
   sed -i 's|export CGO_ENABLED=0|export CGO_ENABLED=1|g' build.sh  # 开启CGO功能
   ./build.sh # 编译ClusterD，需要go 1.21及以上版本，建议使用1.21版本
   

   编译成功后，会在“../output/”目录下生成相关文件，可执行如下命令进行查看：

   ll ../output/
   

   回显示例如下：

   -r-x------. 1 root root 45891128 Aug 13 10:52 clusterd
   -r--------. 1 root root     4021 Aug 13 10:52 clusterd-v26.0.0.yaml
   -r--------. 1 root root      946 Aug 13 10:52 Dockerfile
   -r--------. 1 root root      209 Aug 13 10:52 faultDuration.json
   -r--------. 1 root root      207 Aug 13 10:52 fdConfig.yaml
   -r--------. 1 root root      467 Aug 13 10:52 publicFaultConfiguration.json
   -r--------. 1 root root      756 Aug 13 10:52 relationFaultCustomization.json
   

4. 进入output目录，制作ClusterD镜像。

   cd ../output/
   docker build --no-cache -t clusterd:{tag} ./  # {tag}与步骤3中build_version="xxx"的取值保持一致
   

5. （可选）保存镜像，并将保存后的镜像文件和clusterd-{tag}.yaml文件上传到主节点。若步骤1到步骤4在主节点执行，可跳过该步骤。

   docker save -o clusterd.tar clusterd:{tag}  # 保存镜像
   docker load -i clusterd.tar  # 在主节点导入镜像
   

6. 在主节点重新拉起ClusterD。

   kubectl delete -f  clusterd-{tag}.yaml  # 删除旧ClusterD容器
   kubectl apply -f  clusterd-{tag}.yaml  # 拉起新容器
   

脚本适配

PyTorch场景适配示例（基于MindSpeed-LLM）

1. 搭建训练环境，拉起训练，详细请参见PyTorch场景适配示例（基于MindSpeed-LLM）。

2. 开启进程级在线恢复，详细请参见配置进程级在线恢复。

3. 在“QWEN3_for_PyTorch_2.7_code/mindspeed_llm/training/training.py”代码中增加如下加粗内容，打桩注入故障，新增代码根据环境变量“RAISE_UCE_ERROR_STEP_AND_RANK”获取注入故障迭代位置和故障rank信息。

    import os
    import ast
    …
    GLB_CNT = 0
     
    def train(forward_step_func, model, optimizer, opt_param_scheduler,
              train_data_iterator, valid_data_iterator,
              process_non_loss_data_func, config):
        """Train the model function."""
        args = get_args()
    timers = get_timers()
    …
        while iteration < args.train_iters:
            …
            num_microbatches = get_num_microbatches()
            update_num_microbatches(args.consumed_train_samples, consistency_check=True)
     
            global GLB_CNT
            cur_rank = torch.distributed.get_rank()
            uce_env = os.getenv("RAISE_UCE_ERROR_STEP_AND_RANK", "{}")
            uce_step_rank = ast.literal_eval(uce_env)
            if iteration in uce_step_rank and cur_rank == uce_step_rank[iteration] and GLB_CNT < iteration:
                GLB_CNT = iteration
                print(f"############# rank:{cur_rank} start UCE error #############")       
                raise RuntimeError('UCE ERROR')
     
            args.curr_iteration = iteration
            …

4. 修改启动脚本“QWEN3_for_PyTorch_2.7_code/scripts/train_start.sh”。

   …
   export RAISE_UCE_ERROR_STEP_AND_RANK="{3:1,10:2}"  # 配置故障注入的迭代和卡号，在第3个迭代的rank 1卡和第10个迭代的rank 2卡上注入UCE故障
   sed -i 's/check_memory_result = torch_npu.npu.check_uce_in_memory(device)/check_memory_result = ha_constant.UCE_HIGH_LEVEL/g' /job/code/mindspeed_llm/core/high_availability/tft_stop_clean.py #修改PTA接口返回值，将训练代码抛出的异常识别为UCE故障
   …
   

MindSpore场景适配示例（基于MindFormers）

1. 搭建训练环境，拉起训练，详细请参见MindSpore场景适配示例（基于MindFormers）。

2. 开启进程级在线恢复，详细请参见配置进程级在线恢复。

3. 在“QWEN3_for_MS_code/mindformers/core/callback/callback.py”代码中增加如下加粗内容，打桩注入故障。

    import json
    import os
    ...
    import ast
    GLB_CNT = 0
    EPOCH_CNT = 0
    ...
        def print_output_info(self, cb_params, cur_epoch_num, origin_epochs, throughput,
                              cur_step_num, steps_per_epoch, loss, per_step_seconds,
                              overflow, scaling_sens, time_remain, percent, global_norm):
            """print output information."""
            ...
            logger.info("  %4.1f%% %s %.5f samples/s/p  %s }", percent, show_str, throughput,
                        datetime.timedelta(seconds=int(time_remain)))
            global GLB_CNT
            global EPOCH_CNT
            if EPOCH_CNT < cur_epoch_num: 
               GLB_CNT = 0
               EPOCH_CNT = cur_epoch_num
            uce_env = os.getenv("RAISE_UCE_ERROR_STEP_AND_RANK", "{}")
            uce_step_rank = ast.literal_eval(uce_env)
            if cur_step_num in uce_step_rank and get_rank() == uce_step_rank[cur_step_num] and GLB_CNT < cur_step_num: 
               GLB_CNT = cur_step_num
               print(f"############# rank:{get_rank()} start UCE error #############")
               raise RuntimeError('UCEError occured.')
            if self.tensor_writer is not None:
                ...

4. 修改启动脚本“QWEN3_for_MS_code/scripts/msrun_launcher.sh”。

   …
   export RAISE_UCE_ERROR_STEP_AND_RANK="{3:1,10:2}"  # 配置故障注入的迭代和卡号，在第3个迭代的rank 1卡和第10个迭代的rank 2卡上注入UCE故障
   sed -i 's/err_strategy = _get_uce_process_strategy()/err_strategy = "RS_UCE_LOWLEVEL"/g' $(pip3 show mindspore | grep Location | awk -F ' ' '{print $2}')/mindspore/train/callback/_train_fault_tolerance.py #修改UCE处理策略
   …
   

K8s集群基础性能调优

MindCluster集群调度组件是基于K8s生态的功能组件，因此训练任务调度基于K8s平台时才支持使用断点续训。断点续训支持的K8s版本与MindCluster集群调度组件一致，当前为1.17.x~1.34.x（推荐使用1.19.x及以上版本）。

表 1 配置说明

--max-request-inflight=20000
--max-mutating-requests-inflight=2000

--watch-cache=true 
--watch-cache-sizes=node#1000,pod#2000,event#200,namespace#100,service#200

resources:
  requests:
    cpu: 35000m

--quota-backend-bytes=8589934592

--auto-compaction-retention

resources:
  requests:
    cpu: 20000m
    memory: 10000Mi

resources:
  requests:
    cpu: 20000m
    memory: 8Gi

kubectl edit deployment -n volcano-system volcano-scheduler

自定义指标开发

支持通过如下两种方式开发自定义指标。

• 通过文件方式开发自定义指标

  用户根据自定义指标文件，创建符合要求的自定义指标文件。启动NPU Exporter时，配置“-textMetricsFilePath”参数，指定该自定义指标文件的路径。详情请参见NPU Exporter启动参数。NPU Exporter会在每个数据采集周期读取自定义指标文件，并将文件内容上报给Prometheus或Telegraf。

  开发示例如下：

  使用NPU Exporter集成并采集Devkit工具生成的hccs_bandwidth指标，详情请参见NPU Exporter集成Devkit部署指南。关于hccs_bandwidth指标信息的说明请参见HCCS带宽监控。

• 通过插件方式开发自定义指标

  用户可通过编写插件的方式自定义指标，使用该插件前，开发者需要自行学习了解cgo、go相关语言特性，并阅读README了解使用方法。

[!NOTICE]

• 自定义的指标不能与已有的指标名重复。
• 开发者需对自定义插件的稳定性负责，确保不引入运行时panic等问题。
• 开发者需要对自定义指标文件格式的正确性负责。