环境变量列表

本手册描述开发者基于CANN构建AI应用和业务过程中可使用的环境变量。

环境变量支持通过命令、接口、配置等方式实现，包括export命令、putenv/getenv/setenv/unsetenv/clearenv函数、os.environ、os.getenv等。建议用户在应用进程拉起前设置环境变量，否则可能引起环境变量访问冲突，导致程序异常。

环境变量总览如下表所示：

表1 环境变量列表
环境变量	简介
安装包相关	描述CANN软件安装完成后，系统通过“set_env.sh”脚本默认配置的程序编译、执行相关的基础环境变量，以及后续程序编译执行时，需要手工配置的跟安装包相关的环境变量。
落盘文件配置
ASCEND_CACHE_PATH	若开发者期望编译运行过程中产生的文件落盘到归一路径，可通过此环境变量设置共享文件的存储路径，各组件编译运行过程中产生的可共享文件会存储到此环境变量定义的路径中。
ASCEND_WORK_PATH	若开发者期望编译运行过程中产生的文件落盘到归一路径，可通过此环境变量设置单机独享文件的存储路径，各组件编译运行过程中产生的单机独享文件会存储到此环境变量定义的路径中。
图编译
DUMP_GE_GRAPH	把整个流程中各个阶段的图描述信息打印到文件中，此环境变量控制dump图的内容多少。
DUMP_GRAPH_LEVEL	把整个图编译流程中各个阶段的图描述信息打印到文件中，此环境变量可以控制dump图的个数。
DUMP_GRAPH_PATH	指定DUMP图文件的保存路径，可配置为绝对路径或脚本执行目录的相对路径。
OP_NO_REUSE_MEM	计算图在昇腾平台编译的过程中默认采用内存复用形式，在问题定位场景中，如果开发者怀疑是内存复用错误导致计算结果异常，可通过此环境变量指定为某算子单独分配内存。
ASCEND_ENGINE_PATH	单算子json文件转换成离线模型场景，如果希望模型转换时只使用TBE算子（不查找AI CPU算子，找不到TBE算子则报错），则需要使用该环境变量。
MAX_COMPILE_CORE_NUMBER	此环境变量用于指定图编译时可用的CPU核数。
MULTI_THREAD_COMPILE	此环境变量用于控制模型转换时是否使用单线程编译。
ENABLE_NETWORK_ANALYSIS_DEBUG	TensorFlow训练场景下，计算图编译失败时默认会终止训练流程，不会继续向Device下发剩余的图。若开发者希望图编译失败时，不终止训练流程，让TF Adapter可持续向Device下发计算图，可通过设置该环境变量实现。
算子编译
TE_PARALLEL_COMPILER	网络模型较大时，可通过配置此环境变量开启算子的并行编译功能。
ASCEND_MAX_OP_CACHE_SIZE	启用算子编译缓存功能时，可通过此环境变量限制某个昇腾AI处理器下缓存文件夹的磁盘空间的大小。
ASCEND_REMAIN_CACHE_SIZE_RATIO	启用算子编译缓存功能时，当编译缓存空间大小达到ASCEND_MAX_OP_CACHE_SIZE而需要删除旧的kernel文件时，需要保留缓存的空间大小比例，默认为50，单位为百分比。
资源配置
ASCEND_DEVICE_ID	指定当前进程所用的昇腾AI处理器的逻辑ID。
ASCEND_RT_VISIBLE_DEVICES	指定哪些Device对当前进程可见，支持一次指定一个或多个Device ID。通过该环境变量，可实现不修改应用程序即可调整所用Device的功能。
算子执行
ACLNN_CACHE_LIMIT	此环境变量用于配置单算子执行API在Host侧缓存的算子信息条目个数。缓存的算子信息包含workspace大小、算子计算的执行器、tiling信息等。
图执行
ENABLE_DYNAMIC_SHAPE_MULTI_STREAM	计算图执行时，开启多流并发执行功能在一定场景下可提升网络性能。当前多流并发执行功能默认关闭，动态shape图模式场景下，若开发者想开启多流并发执行功能，可通过此环境变量开启。
MAX_RUNTIME_CORE_NUMBER	训练与在线推理场景下，针对动态shape图模式执行的网络，可通过设置此环境变量开启图执行器（Host侧）的多线程任务调度。
TF Adapter
JOB_ID	TensorFlow训练与在线推理场景下，通过此环境变量指定任务ID，用户自定义。仅支持大小写字母，数字，中划线，下划线。不建议使用以0开始的纯数字作为JOB_ID。
ENABLE_FORCE_V2_CONTROL	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版本算子解决。
ENABLE_HF32_EXECUTION	针对TensorFlow 1.15网络，是否启用HF32自动代替FP32数据类型的功能，当前版本此环境变量仅针对Conv类算子与Matmul类算子生效。
NPU_DEBUG	TensorFlow 2.6.5训练与在线推理场景下，用于开启TF Adapter的Debug级别执行日志，该变量需要在import npu_device前设置。
NPU_DUMP_GRAPH	TensorFlow 2.6.5训练与在线推理场景下，用于开启TF Adapter图Dump功能，该变量需要在import npu_device前设置。
NPU_ENABLE_PERF	TensorFlow 2.6.5训练与在线推理场景下，用于开启TF Adapter图耗时打印功能。
NPU_LOOP_SIZE	TensorFlow 2.6.5训练与在线推理场景下，用于设置NPU上循环下沉的次数，该变量需要在import npu_device前设置。
STEP_NOW	TensorFlow 1.15训练场景下，用于设置NPU上当前的执行步数。取值为int类型，无默认值。
TOTAL_STEP	TensorFlow 1.15训练场景下，用于设置NPU上总的训练步数。取值为int类型，无默认值。
LOSS_NOW	TensorFlow 1.15训练场景下，用于设置NPU上当前迭代的loss值。取值为浮点类型，无默认值。
TARGET_LOSS	TensorFlow 1.15训练场景下，用于设置NPU上的目标训练loss值。取值为浮点类型，无默认值。
Ascend Extension for PyTorch
INF_NAN_MODE_ENABLE	PyTorch训练与在线推理场景下，用于控制芯片对输入数据为Inf/NaN的处理能力，即控制芯片使用饱和模式还是INF_NAN模式。
COMBINED_ENABLE	PyTorch训练与在线推理场景下，可通过此环境变量设置combined标志。设置为0表示关闭此功能；设置为1表示开启，用于优化非连续两个算子组合类场景。
ASCEND_LAUNCH_BLOCKING	PyTorch训练或在线推理场景，可通过此环境变量控制算子执行时是否启动同步模式。
ACL_OP_COMPILER_CACHE_DIR	Pytorch训练或者在线推理场景，可以通过此环境变量配置算子编译磁盘缓存的目录。
ACL_OP_COMPILER_CACHE_MODE	Pytorch训练或者在线推理场景，可以通过此环境变量配置算子编译磁盘缓存模式。
PYTORCH_NPU_ALLOC_CONF	PyTorch训练或在线推理场景，可通过此环境变量控制缓存分配器行为。
HCCL_ASYNC_ERROR_HANDLING	PyTorch训练或在线推理场景下，当使用HCCL作为通信后端时，可通过此环境变量控制是否开启异步错误处理。
HCCL_DESYNC_DEBUG	PyTorch训练或在线推理场景下，当使用HCCL作为通信后端时，可通过此环境变量控制是否进行通信超时分析。
HCCL_EVENT_TIMEOUT	PyTorch训练或在线推理场景下，当使用HCCL作为通信后端时，可通过此环境变量设置等待Event完成的超时时间。
P2P_HCCL_BUFFSIZE	此环境变量用于控制是否开启点对点通信（torch.distributed.isend、torch.distributed.irecv和torch.distributed.batch_isend_irecv）使用独立通信域功能。
PYTORCH_NO_NPU_MEMORY_CACHING	此环境变量用于控制是否关闭内存复用机制。
HCCL资源信息配置
RANK_TABLE_FILE	分布式训练或推理场景下，通过此环境变量指定昇腾AI处理器的ranktable资源配置文件，包含ranktable文件路径和文件名。
RANK_ID	TensorFlow分布式训练或推理场景下，通过此环境变量指定当前进程在集合通信进程组中对应的rank标识。
RANK_SIZE	TensorFlow分布式训练或推理场景下，通过此环境变量指定当前进程对应的Device在本集群大小，即集群Device的数量。
CM_CHIEF_IP	TensorFlow分布式训练场景下，用户可以选择不使用ranktable文件，通过组合使用环境变量的方式自动生成资源信息，完成集合通信初始化。本环境变量用于配置Master节点的监听Host IP。
CM_CHIEF_PORT	本环境变量用于配置Master节点的监听端口。
CM_CHIEF_DEVICE	本环境变量用于指定Master节点中统计Server端集群信息的Device逻辑ID。
CM_WORKER_SIZE	本环境变量用于配置本次业务通信域Device的数量。
CM_WORKER_IP	本环境变量用于配置当前Device和Master节点进行信息交换时所用的网卡IP。
集合通信相关配置
HCCL_IF_IP	配置HCCL的初始化root通信网卡IP。
HCCL_IF_BASE_PORT	单算子模式下，使用Host网卡进行HCCL初始化或集合通信计算时，可以通过该环境变量指定Host网卡起始端口号，配置后系统默认占用以该端口起始的16个端口进行集群信息收集。
HCCL_SOCKET_IFNAME	配置HCCL初始化Host侧root通信网卡名，HCCL可通过该网卡名获取Host IP，完成通信域创建。
HCCL_SOCKET_FAMILY	该环境变量指定通信网卡使用的IP协议。
HCCL_CONNECT_TIMEOUT	分布式训练或推理场景下，用于限制不同设备之间socket建链过程的超时等待时间。
HCCL_EXEC_TIMEOUT	不同设备进程在分布式训练或推理过程中存在卡间执行任务不一致的场景（如仅特定进程会保存checkpoint数据），通过该环境变量可控制设备间执行时同步等待的时间，在该配置时间内各设备进程等待其他设备执行通信同步。
HCCL_INTRA_PCIE_ENABLE	用于配置Server内是否使用PCIe环路进行多卡间的通信。
HCCL_INTRA_ROCE_ENABLE	用于配置Server内是否使用RoCE环路进行多卡间的通信。
HCCL_WHITELIST_DISABLE	配置在使用HCCL时是否开启通信白名单。
HCCL_WHITELIST_FILE	当通过HCCL_WHITELIST_DISABLE开启了通信白名单校验功能时，需要通过此环境变量配置指向HCCL通信白名单配置文件的路径，只有在通信白名单中的IP地址才允许进行集合通信。
HCCL_RDMA_TC	用于配置RDMA网卡的traffic class。
HCCL_RDMA_SL	用于配置RDMA网卡的service level，该值需要和网卡配置的PFC优先级保持一致，若配置不一致可能导致性能劣化。
HCCL_RDMA_TIMEOUT	RDMA网卡重传超时时间最小值的计算公式为：4.096 μs * 2 ^ timeout，其中timeout为该环境变量配置值，且实际重传超时时间与用户网络状况有关。 RDMA网卡重传超时时间最小值的计算公式为：4.096 μs * 2 ^ timeout，其中timeout为该环境变量配置值，且实际重传超时时间与用户网络状况有关。
HCCL_RDMA_RETRY_CNT	用于配置RDMA网卡的重传次数，需要配置为整数，取值范围为[1,7]，默认值为7。
HCCL_BUFFSIZE	此环境变量用于控制两个NPU之间共享数据的缓存区大小。单位为M，需要配置为整数，取值大于等于1，默认值为200，单位M。
HCCL_ALGO	此环境变量用于配置集合通信Server间跨机通信算法，支持全局配置算法类型与按算子配置算法类型两种配置方式。
HCCL_DIAGNOSE_ENABLE	此环境变量用于配置集合通信是否缓存部分任务的详细信息，以便任务执行失败时，打印详细日志，用于问题定位。
HCCL_ENTRY_LOG_ENABLE	此环境变量用于控制集合通信算子调用行为日志的打印方式。
HCCL_OP_EXPANSION_MODE	此环境变量用于配置通信算法的编排展开位置。
HCCL_DETERMINISTIC	此环境变量用于配置是否开启归约类通信算子的确定性计算，其中归约类通信算子包括AllReduce、ReduceScatter、Reduce。开启确定性计算后，算子在相同的硬件和输入下，多次执行将产生相同的输出。
AOE调优
TUNE_BANK_PATH	可通过此环境变量指定调优后自定义知识库的存储路径。
REPEAT_TUNE	是否重新发起调优，此环境变量在开启子图调优或算子调优的场景下生效。
AOE_MODE	在线推理与训练场景下，可通过此环境变量指定AOE调优模式。
AMCT模型压缩
AMCT_LOG_FILE_LEVEL	控制日志文件（Pytorch框架：amct_pytorch.log；Caffe框架：amct_caffe.log，ONNX：amct_onnx.log）的信息级别以及生成精度仿真模型时，对应量化层生成的日志文件信息级别。
AMCT_LOG_LEVEL	控制屏幕输出的信息级别。该环境变量仅适用于Pytorch框架、Caffe框架、ONNX网络模型的量化。
DUMP_AMCT_RECORD	控制是否生成权重和数据的量化因子。该环境变量仅适用于MindSpore框架的模型压缩。
AMCT_LOG_DUMP	控制日志打屏或量化因子等信息输出到文件的环境变量。该环境变量仅适用于调用AscendCL接口（aclgrphCalibration）进行的量化。
性能数据采集
PROFILING_MODE	该环境变量用于控制是否开启Profiling功能。
PROFILING_OPTIONS	训练与在线推理场景下，开发者可通过PROFILING_OPTIONS环境变量配置Profiling配置选项。
PROF_CONFIG_PATH	PyTorch训练场景Ascend PyTorch Profiler接口的dynamic_profile采集功能profiler_config.json配置文件路径环境变量。
日志
ASCEND_PROCESS_LOG_PATH	设置日志落盘路径。
ASCEND_SLOG_PRINT_TO_STDOUT	是否开启日志打屏。开启后，日志将不会保存在log文件中，而是将产生的日志直接打屏显示。
ASCEND_GLOBAL_LOG_LEVEL	设置应用类日志的日志级别及各模块日志级别，仅支持调试日志。
ASCEND_MODULE_LOG_LEVEL	设置应用类日志的各模块日志级别，仅支持调试日志。
ASCEND_GLOBAL_EVENT_ENABLE	设置应用类日志是否开启Event日志。
ASCEND_LOG_DEVICE_FLUSH_TIMEOUT	业务进程退出前，系统有2000ms的默认延时将Device侧应用类日志回传到Host侧，超时后业务进程退出。未回传到Host侧的日志直接在Device侧落盘（路径为/var/log/npu/slog）。 Device侧应用类日志回传到Host侧的延时时间可以通过此环境变量进行设置。
ASCEND_HOST_LOG_FILE_NUM	EP场景下，设置应用类日志目录（plog和device-id）下存储每个进程日志文件的数量。
ASCEND_COREDUMP_SIGNAL	设置trace处理的coredump信号量。
故障信息收集
NPU_COLLECT_PATH	在复现问题场景下，使用该环境变量指定故障信息（包括dump图、算子编译.o文件、AI Core算子异常数据、算子编译过程信息等）的保存路径，可配置为绝对路径或相对路径，配置的路径需要为已存在的目录，且执行用户具有读、写、可执行权限。
后续版本废弃环境变量
GE_USE_STATIC_MEMORY	此环境变量用于配置网络运行时使用的内存分配方式。
ENABLE_ACLNN	图编译时，通过设置该环境变量，决定是否在图执行时调用算子注册的host执行函数实现host执行逻辑以及kernel下发。