环境变量列表
本手册描述开发者基于CANN构建AI应用和业务过程中可使用的环境变量。
环境变量支持通过命令、接口、配置等方式实现,包括export命令、putenv/getenv/setenv/unsetenv/clearenv函数、os.environ、os.getenv等。建议用户在应用进程拉起前设置环境变量,否则可能引起环境变量访问冲突,导致程序异常。
环境变量总览如下表所示:
环境变量 |
简介 |
---|---|
描述CANN软件安装完成后,系统通过“set_env.sh”脚本默认配置的程序编译、执行相关的基础环境变量,以及后续程序编译执行时,需要手工配置的跟安装包相关的环境变量。 |
|
落盘文件配置 |
|
若开发者期望编译运行过程中产生的文件落盘到归一路径,可通过此环境变量设置共享文件的存储路径,各组件编译运行过程中产生的可共享文件会存储到此环境变量定义的路径中。 |
|
若开发者期望编译运行过程中产生的文件落盘到归一路径,可通过此环境变量设置单机独享文件的存储路径,各组件编译运行过程中产生的单机独享文件会存储到此环境变量定义的路径中。 |
|
图编译 |
|
把整个流程中各个阶段的图描述信息打印到文件中,此环境变量控制dump图的内容多少。 |
|
把整个图编译流程中各个阶段的图描述信息打印到文件中,此环境变量可以控制dump图的个数。 |
|
指定DUMP图文件的保存路径,可配置为绝对路径或脚本执行目录的相对路径。 |
|
计算图在昇腾平台编译的过程中默认采用内存复用形式,在问题定位场景中,如果开发者怀疑是内存复用错误导致计算结果异常,可通过此环境变量指定为某算子单独分配内存。 |
|
单算子json文件转换成离线模型场景,如果希望模型转换时只使用TBE算子(不查找AI CPU算子,找不到TBE算子则报错),则需要使用该环境变量。 |
|
此环境变量用于指定图编译时可用的CPU核数。 |
|
此环境变量用于控制模型转换时是否使用单线程编译。 |
|
TensorFlow训练场景下,计算图编译失败时默认会终止训练流程,不会继续向Device下发剩余的图。若开发者希望图编译失败时,不终止训练流程,让TF Adapter可持续向Device下发计算图,可通过设置该环境变量实现。 |
|
算子编译 |
|
网络模型较大时,可通过配置此环境变量开启算子的并行编译功能。 |
|
启用算子编译缓存功能时,可通过此环境变量限制某个昇腾AI处理器下缓存文件夹的磁盘空间的大小。 |
|
启用算子编译缓存功能时,当编译缓存空间大小达到ASCEND_MAX_OP_CACHE_SIZE而需要删除旧的kernel文件时,需要保留缓存的空间大小比例,默认为50,单位为百分比。 |
|
资源配置 |
|
指定当前进程所用的昇腾AI处理器的逻辑ID。 |
|
指定哪些Device对当前进程可见,支持一次指定一个或多个Device ID。通过该环境变量,可实现不修改应用程序即可调整所用Device的功能。 |
|
算子执行 |
|
此环境变量用于配置单算子执行API在Host侧缓存的算子信息条目个数。缓存的算子信息包含workspace大小、算子计算的执行器、tiling信息等。 |
|
图执行 |
|
计算图执行时,开启多流并发执行功能在一定场景下可提升网络性能。当前多流并发执行功能默认关闭,动态shape图模式场景下,若开发者想开启多流并发执行功能,可通过此环境变量开启。 |
|
训练与在线推理场景下,针对动态shape图模式执行的网络,可通过设置此环境变量开启图执行器(Host侧)的多线程任务调度。 |
|
TF Adapter |
|
TensorFlow训练与在线推理场景下,通过此环境变量指定任务ID,用户自定义。 |
|
TensorFlow 1.15训练场景下,如果输入是动态shape,由于tf.case/tf.cond/tf.while_loop这些API对应TensorFlow V1版本的控制流算子(例如Switch、Merge、Enter、LoopCond、NextIteration、Exit、ControlTrigger等)不支持动态shape,仅TensorFlow V2版本的控制流算子(例如If、Case、While、For、PartitionedCall等)支持动态shape,因此,如果用户的训练脚本中使用了这些API,需要将V1版本的控制流算子转换为V2版本,用于支持动态shape功能。另外,如果网络中的分支结构较多,采用V1版本的控制流算子可能导致流数超限,此时也需要将V1版本的控制流算子转换成V2版本算子解决。 |
|
针对TensorFlow 1.15网络,是否启用HF32自动代替FP32数据类型的功能,当前版本此环境变量仅针对Conv类算子与Matmul类算子生效。 |
|
TensorFlow 2.6.5训练与在线推理场景下,用于开启TF Adapter的Debug级别执行日志。 |
|
TensorFlow 2.6.5训练与在线推理场景下,用于开启TF Adapter图Dump功能。 |
|
TensorFlow 2.6.5训练与在线推理场景下 ,用于开启TF Adapter图耗时打印功能。 |
|
TensorFlow 2.6.5训练与在线推理场景下,用于设置NPU上循环下沉的次数。 |
|
TensorFlow 1.15训练场景下,若通过“experimental_accelerate_train_mode”参数或者“accelerate_train_mode”参数触发了训练加速功能,可通过此环境变量设置NPU上当前的执行步数。 |
|
TensorFlow 1.15训练场景下,若通过“experimental_accelerate_train_mode”参数或者“accelerate_train_mode”参数触发了训练加速功能,可通过此环境变量设置NPU上总的训练步数。 |
|
TensorFlow 1.15训练场景下,若通过“experimental_accelerate_train_mode”参数或者“accelerate_train_mode”参数触发了训练加速功能,可通过此环境变量设置NPU上当前迭代的loss值。 |
|
TensorFlow 1.15训练场景下,若通过“experimental_accelerate_train_mode”参数或者“accelerate_train_mode”参数触发了训练加速功能,可通过此环境变量设置NPU上的目标训练loss值。 |
|
TensorFlow分布式训练或推理场景下,通过此环境变量指定参与集合通信的昇腾AI处理器的ranktable资源配置文件,包含ranktable文件路径和文件名。 |
|
TensorFlow分布式训练或推理场景下,通过此环境变量指定当前进程在集合通信进程组中对应的rank标识。 |
|
TensorFlow分布式训练或推理场景下,通过此环境变量指定当前训练进程对应的Device在本集群大小,即集群Device的数量。 |
|
TensorFlow分布式训练场景下,用户可以选择不使用ranktable文件,通过组合使用环境变量的方式自动生成资源信息,完成集合通信初始化。 本环境变量用于配置Master节点的监听Host IP。 |
|
本环境变量用于配置Master节点的监听端口。 |
|
本环境变量用于指定Master节点中统计Server端集群信息的Device逻辑ID。 |
|
本环境变量用于配置本次业务通信域Device的数量。 |
|
本环境变量用于配置当前Device和Master节点进行信息交换时所用的网卡IP。 |
|
Ascend Extension for PyTorch |
|
PyTorch训练与在线推理场景下,用于控制芯片对输入数据为Inf/NaN的处理能力,即控制芯片使用饱和模式还是INF_NAN模式。 |
|
PyTorch训练与在线推理场景下,可通过此环境变量设置combined标志。设置为0表示关闭此功能;设置为1表示开启,用于优化非连续两个算子组合类场景。 |
|
PyTorch训练或在线推理场景,可通过此环境变量控制算子执行时是否启动同步模式。 |
|
Pytorch训练或者在线推理场景,可以通过此环境变量配置算子编译磁盘缓存的目录。 |
|
Pytorch训练或者在线推理场景,可以通过此环境变量配置算子编译磁盘缓存模式。 |
|
PyTorch训练或在线推理场景,可通过此环境变量控制缓存分配器行为。 |
|
PyTorch训练或在线推理场景下,当使用HCCL作为通信后端时,可通过此环境变量控制是否开启异步错误处理。 |
|
PyTorch训练或在线推理场景下,当使用HCCL作为通信后端时,可通过此环境变量控制是否进行通信超时分析。 |
|
PyTorch训练或在线推理场景下,当使用HCCL作为通信后端时,可通过此环境变量设置等待Event完成的超时时间。 |
|
此环境变量用于控制是否开启点对点通信(torch.distributed.isend、torch.distributed.irecv和torch.distributed.batch_isend_irecv)使用独立通信域功能。 |
|
此环境变量用于控制是否关闭内存复用机制。 |
|
此环境变量用于控制在网络发生“NPU out of memory. Tried to allocate...”的内存不足报错时,是否保存内存数据,以供分析内存不足原因。 |
|
此环境变量用于配置在网络发生oom时内存数据保存路径。 |
|
此环境变量用于控制是否通过ranktable file进行集合通信域建链。 |
|
此环境变量用于控制Ascend Extension for PyTorch的告警信息是否打印。 |
|
此环境变量用于控制开启task_queue算子下发队列优化的等级。 |
|
集合通信 |
|
配置HCCL的初始化root通信网卡IP。 |
|
单算子模式下,使用Host网卡进行HCCL初始化或集合通信计算时,可以通过该环境变量指定Host网卡起始端口号,配置后系统默认占用以该端口起始的16个端口进行集群信息收集。 |
|
配置HCCL初始化Host侧root通信网卡名,HCCL可通过该网卡名获取Host IP,完成通信域创建。 |
|
该环境变量指定通信网卡使用的IP协议。 |
|
分布式训练或推理场景下,用于限制不同设备之间socket建链过程的超时等待时间。 |
|
不同设备进程在分布式训练或推理过程中存在卡间执行任务不一致的场景(如仅特定进程会保存checkpoint数据),通过该环境变量可控制设备间执行时同步等待的时间,在该配置时间内各设备进程等待其他设备执行通信同步。 |
|
用于配置Server内是否使用PCIe环路进行多卡间的通信。 |
|
用于配置Server内是否使用RoCE环路进行多卡间的通信。 |
|
配置在使用HCCL时是否开启通信白名单。 |
|
当通过HCCL_WHITELIST_DISABLE开启了通信白名单校验功能时,需要通过此环境变量配置指向HCCL通信白名单配置文件的路径,只有在通信白名单中的IP地址才允许进行集合通信。 |
|
用于配置RDMA网卡的traffic class。 |
|
用于配置RDMA网卡的service level,该值需要和网卡配置的PFC优先级保持一致,若配置不一致可能导致性能劣化。 |
|
RDMA网卡重传超时时间最小值的计算公式为:4.096 μs * 2 ^ timeout,其中timeout为该环境变量配置值,且实际重传超时时间与用户网络状况有关。 |
|
用于配置RDMA网卡的重传次数,需要配置为整数,取值范围为[1,7],默认值为7。 |
|
此环境变量用于控制两个NPU之间共享数据的缓存区大小。单位为M,需要配置为整数,取值大于等于1,默认值为200,单位M。 |
|
此环境变量用于配置集合通信Server间跨机通信算法,支持全局配置算法类型与按算子配置算法类型两种配置方式。 |
|
此环境变量用于配置集合通信是否缓存部分任务的详细信息,以便任务执行失败时,打印详细日志,用于问题定位。 |
|
此环境变量用于控制是否实时打印通信算子的调用行为日志。 |
|
此环境变量用于配置通信算法的编排展开位置。 |
|
此环境变量用于配置是否开启归约类通信算子的确定性计算,其中归约类通信算子包括AllReduce、ReduceScatter、Reduce。开启确定性计算后,算子在相同的硬件和输入下,多次执行将产生相同的输出。 |
|
AOE调优 |
|
可通过此环境变量指定调优后自定义知识库的存储路径。 |
|
是否重新发起调优,此环境变量在开启子图调优或算子调优的场景下生效。 |
|
在线推理与训练场景下,可通过此环境变量指定AOE调优模式。 |
|
AMCT模型压缩 |
|
控制日志文件(Pytorch框架:amct_pytorch.log;Caffe框架:amct_caffe.log,ONNX:amct_onnx.log)的信息级别以及生成精度仿真模型时,对应量化层生成的日志文件信息级别。 |
|
控制屏幕输出的信息级别。该环境变量仅适用于Pytorch框架、Caffe框架、ONNX网络模型的量化。 |
|
控制是否生成权重和数据的量化因子。该环境变量仅适用于MindSpore框架的模型压缩。 |
|
控制日志打屏或量化因子等信息输出到文件的环境变量。该环境变量仅适用于调用AscendCL接口(aclgrphCalibration)进行的量化。 |
|
性能数据采集 |
|
该环境变量用于控制是否开启Profiling功能。 |
|
训练或在线推理场景下,开发者可通过PROFILING_OPTIONS环境变量配置Profiling配置选项。 |
|
PyTorch训练场景Ascend PyTorch Profiler接口的dynamic_profile采集功能profiler_config.json配置文件路径环境变量。 |
|
日志 |
|
设置日志落盘路径。 |
|
是否开启日志打屏。开启后,日志将不会保存在log文件中,而是将产生的日志直接打屏显示。 |
|
设置应用类日志的日志级别及各模块日志级别,仅支持调试日志。 |
|
设置应用类日志的各模块日志级别,仅支持调试日志。 |
|
设置应用类日志是否开启Event日志。 |
|
业务进程退出前,系统有2000ms的默认延时将Device侧应用类日志回传到Host侧,超时后业务进程退出。未回传到Host侧的日志直接在Device侧落盘(路径为/var/log/npu/slog)。 Device侧应用类日志回传到Host侧的延时时间可以通过此环境变量进行设置。 |
|
EP场景下,设置应用类日志目录(plog和device-id)下存储每个进程日志文件的数量。 |
|
设置trace处理的coredump信号量。 |
|
故障信息收集 |
|
在复现问题场景下,使用该环境变量指定故障信息(包括dump图、算子编译.o文件、AI Core算子异常数据、算子编译过程信息等)的保存路径,可配置为绝对路径或相对路径(此处是相对执行程序或命令的路径),执行用户需对该路径具有读、写、可执行权限,若路径不存在,系统会自动创建该路径中的目录。 |
|
后续版本废弃环境变量 |
|
此环境变量用于配置网络运行时使用的内存分配方式。 |
|
图编译时,通过设置该环境变量,决定是否在图执行时调用算子注册的host执行函数实现host执行逻辑以及kernel下发。 |