高性能计算集群 HyperAcc 训练加速套件常见优化实践

完成 HyperAcc wheel 包安装后，您可以参考本文进行常见训练任务的接入与性能调优。
PyTorch 训练脚本无侵入接入
前提条件
已安装 HyperAcc wheel 包。
原训练脚本可在当前环境中正常运行。
注意事项
如果训练入口必须包含 from __future__ import ... ，请保留这些语句在最前面，再导入 hyperacc.auto。
如果先导入了 torch、训练框架、模型或 DataLoader 相关模块，部分透明替换能力可能无法覆盖已加载的目标组件。
首次接入生产任务时，建议先按单项能力启用，确认训练结果后再启用全部能力。
操作步骤
1. 设置需要启用的功能：
export HA_USE_ALL=1
# HA_USE_ALL启动的是无风险项， 有风险的都是默认关闭， 需要手动配置才打开
如需按需启用能力，可只设置单项开关：
export HA_USE_COMPILE=1
export HA_USE_GC=1
export HA_USE_DATALOADER=1
环境变量优先级从高到低依次为：HA_USE_<FEATURE> > HA_USE_ALL_HOOKS > HA_USE_ALL > 默认关闭。其中，单项功能开关 HA_USE_<FEATURE> 的优先级最高。显式设置为 0 时，可覆盖上层总开关的启用状态。
2. 在 Python 训练入口脚本开头导入 import hyperacc.auto。除 from __future__ import ... 等必须置于文件开头的语句外，建议将导入语句放置在 torch、训练框架、模型及 DataLoader 等相关模块导入之前：
import hyperacc.auto
﻿
# 原有训练入口
# main()
3. 启动训练：
python train.py
GC 优化实践
Python GC 在长时间训练和频繁创建临时对象的任务中可能带来停顿。HyperAcc 支持通过环境变量调整 GC 策略。
注意事项
disable 模式会关闭 GC，建议仅在充分验证后使用。
对内存敏感的任务，应监控内存使用情况，避免长期禁用 GC 导致内存占用升高。
操作步骤
export HA_USE_GC=1
export HA_GC_MODE=reduce_frequency
python train.py
参数说明
参数
默认值
说明
HA_GC_MODE
reduce_frequency
GC 策略，取值如下：
reduce_frequency ：降低 GC 频率。
disable ：禁用 GC。
custom：自定义 GC 策略。
HA_GC_MONITOR
0 或 false
是否启用 GC 监控。取值如下：
0 或 false：禁用 GC 监控。
1 或 true：启用 GC 监控。
HA_GC_GEN0
5000
第 0 代 GC 阈值。
HA_GC_GEN1
20
第 1 代 GC 阈值。
HA_GC_GEN2
20
第 2 代 GC 阈值。
DataLoader 调优实践
HyperAcc 可通过环境变量调整 DataLoader 参数，有助于减少数据加载瓶颈。
操作步骤
export HA_USE_DATALOADER=1
export HA_DATALOADER_WORKERS=16
export HA_DATALOADER_PREFETCH=2
python train.py
参数说明
参数
默认值
说明
HA_DATALOADER_NO_PIN_MEMORY
0
是否禁用pin_memory。取值如下：
0：启用 pin_memory。
1：禁用 pin_memory。
HA_DATALOADER_WORKERS
16
num_workers 数量。负数表示不修改用户配置。
HA_DATALOADER_PREFETCH
2
prefetch_factor，DataLoader 预取批次数。负数表示不修改用户配置。
注意事项
num_workers 过大可能增加 CPU 和内存压力。
共享内存较小或容器环境异常时，可尝试设置 HA_DATALOADER_NO_PIN_MEMORY=1。
torch.compile 自动编译实践
HyperAcc 可通过 HA_USE_COMPILE=1 启用基于 torch.compile 的自动编译能力。
操作步骤
export HA_USE_COMPILE=1
export HA_COMPILE_BACKEND=inductor
export HA_COMPILE_MODE=default
python train.py
参数说明
参数
默认值
说明
HA_COMPILE_BACKEND
inductor
编译后端，支持 inductor，cudagraphs 和 eager 等。
HA_COMPILE_MODE
default
编译模式，取值如下：
default：默认编译模式。
reduce-overhead：降低运行时开销模式。
max-autotune：最大自动调优模式。
HA_COMPILE_FULLGRAPH
false
是否要求捕获完整计算图。
HA_COMPILE_DYNAMIC
空
是否启用动态形状。
HA_COMPILE_EXPLAIN
0
是否输出计算图断裂（graph break）诊断信息。
HA_COMPILE_MAX_PARALLEL
2
后台并行编译线程数。
HA_COMPILE_DRILLDOWN_THRESHOLD
1000000000
大模型分层编译阈值。
调试建议
如遇到编译失败或训练启动变慢，可先使用默认模式并打开诊断：
export HA_USE_COMPILE=1
export HA_COMPILE_MODE=default
export HA_COMPILE_EXPLAIN=1
export HA_LOG_LEVEL=INFO
python train.py
CPU/NUMA 绑核实践
CPU/NUMA 绑核用于将训练进程绑定到 GPU 所在 NUMA 节点的 CPU，有助于降低跨 NUMA 访存开销。
操作步骤
export HA_USE_NUMABIND=1
python train.py
分布式训练中，HyperAcc 会读取 LOCAL_RANK、LOCAL_WORLD_SIZE、CUDA_VISIBLE_DEVICES 或 HIP_VISIBLE_DEVICES 等环境变量进行映射。
透明大页实践
透明大页配置可减少页表开销，有助于提升大内存训练任务的性能。
操作步骤
export HA_USE_THP=1
python train.py
注意事项
透明大页配置依赖 Linux 系统接口，通常需要写入 /sys/kernel/mm/transparent_hugepage/ 下的系统配置。
权限不足时，对应配置可能无法生效，但不会中断训练。
日志与调试
透明替换系统参数
参数
默认值
说明
HA_HOOKS_LAZY
1
目标组件加载时再应用透明替换能力。
HA_HOOKS_SILENT
1
减少透明替换过程中的日志输出。
日志参数
参数
默认值
说明
HA_LOG_LEVEL
INFO
日志级别，支持 DEBUG、INFO、WARNING、ERROR、CRITICAL。
HA_SHIFT_COMPARE
0
启用 shift patch 对比测试，主要用于调试验证。
支持的日志级别
取值
映射到的 Python logging 级别
DEBUG
logging.DEBUG 
INFO
logging.INFO       
INFO
logging.WARNING             
ERROR
logging.ERROR 
CRITICAL / FATAL
 logging.CRITICAL      
如需输出详细调试信息：
export HA_LOG_LEVEL=DEBUG
export HA_HOOKS_SILENT=0
python train.py
如需减少日志输出：
export HA_HOOKS_SILENT=1
export HA_LOG_LEVEL=WARNING
python train.py
透明替换能力
透明替换能力用于在不改造训练框架的情况下，将部分训练组件替换为 HyperAcc 优化实现。
适用场景
自动编译。
channels_last 内存格式转换。
Lightning Trainer 相关优化。
DataLoader 参数调优。
NVIDIA 或海光 DCU 的部分算子替换。
使用建议
先启用单项能力验证训练正确性，再逐步扩大到组合能力。
如果训练任务依赖的第三方库版本较特殊，建议在验证环境中先完成回归测试。
通过 HA_LOG_LEVEL=INFO 或 DEBUG 查看初始化信息。
透明替换功能开关
环境变量
默认值
平台
说明
HA_USE_COMPILE
0
全平台
启用自动编译能力。
HA_USE_CHANNELS_LAST
0
全平台
启用 channels_last 内存格式转换。
HA_USE_LIGHTNING
0
全平台
启用 Lightning Trainer 相关优化。
HA_USE_DATALOADER
0
全平台
启用 DataLoader 优化。
HA_USE_SYNCBN
0
NVIDIA GPU/海光 DCU
启用 SyncBatchNorm 优化。
HA_USE_VOXEL
0
NVIDIA GPU
启用点云体素化和动态散射优化。
HA_USE_DEFORM_AGG
0
NVIDIA GPU
启用多相机可变形特征聚合优化。
HA_USE_RASTERIZER
0
NVIDIA GPU
启用光栅化相关优化。
HA_USE_DEFORM_ATTN
0
海光 DCU
启用多尺度可变形注意力优化。
HA_USE_DROPOUT
0
海光 DCU
启用 Dropout 融合优化。
HA_USE_FOCAL_LOSS
0
海光 DCU
启用 Softmax Focal Loss 融合优化。
HA_USE_RMSNORM
0
海光 DCU
启用 RMSNorm 优化。
HA_USE_ROPE
0
海光 DCU
启用 RoPE 旋转位置编码优化。
HA_USE_FAST_GELU
0
海光 DCU
启用 FastGELU 优化。
﻿

参数	默认值	说明
`HA_GC_MODE`	`reduce_frequency`	GC 策略，取值如下： `reduce_frequency` ：降低 GC 频率。 `disable` ：禁用 GC。 `custom`：自定义 GC 策略。
`HA_GC_MONITOR`	`0` 或 `false`	是否启用 GC 监控。取值如下： `0` 或 `false`：禁用 GC 监控。 `1` 或 `true`：启用 GC 监控。
`HA_GC_GEN0`	`5000`	第 0 代 GC 阈值。
`HA_GC_GEN1`	`20`	第 1 代 GC 阈值。
`HA_GC_GEN2`	`20`	第 2 代 GC 阈值。

参数	默认值	说明
`HA_DATALOADER_NO_PIN_MEMORY`	`0`	是否禁用`pin_memory`。取值如下： 0：启用 `pin_memory`。 1：禁用 `pin_memory`。
`HA_DATALOADER_WORKERS`	`16`	`num_workers` 数量。负数表示不修改用户配置。
`HA_DATALOADER_PREFETCH`	`2`	`prefetch_factor`，DataLoader 预取批次数。负数表示不修改用户配置。

参数	默认值	说明
`HA_COMPILE_BACKEND`	`inductor`	编译后端，支持 `inductor`，`cudagraphs` 和 `eager` 等。
`HA_COMPILE_MODE`	`default`	编译模式，取值如下： `default`：默认编译模式。 `reduce-overhead`：降低运行时开销模式。 `max-autotune`：最大自动调优模式。
`HA_COMPILE_FULLGRAPH`	`false`	是否要求捕获完整计算图。
`HA_COMPILE_DYNAMIC`	空	是否启用动态形状。
`HA_COMPILE_EXPLAIN`	`0`	是否输出计算图断裂（graph break）诊断信息。
`HA_COMPILE_MAX_PARALLEL`	`2`	后台并行编译线程数。
`HA_COMPILE_DRILLDOWN_THRESHOLD`	`1000000000`	大模型分层编译阈值。

参数	默认值	说明
`HA_LOG_LEVEL`	`INFO`	日志级别，支持 `DEBUG`、`INFO`、`WARNING`、`ERROR`、`CRITICAL`。
`HA_SHIFT_COMPARE`	`0`	启用 shift patch 对比测试，主要用于调试验证。

取值	映射到的 Python logging 级别
`DEBUG`	logging.DEBUG
`INFO`	logging.INFO
`INFO`	logging.WARNING
`ERROR`	logging.ERROR
`CRITICAL / FATAL`	logging.CRITICAL

环境变量	默认值	平台	说明
`HA_USE_COMPILE`	0	全平台	启用自动编译能力。
`HA_USE_CHANNELS_LAST`	0	全平台	启用 `channels_last` 内存格式转换。
`HA_USE_LIGHTNING`	0	全平台	启用 Lightning Trainer 相关优化。
`HA_USE_DATALOADER`	0	全平台	启用 DataLoader 优化。
`HA_USE_SYNCBN`	0	NVIDIA GPU/海光 DCU	启用 SyncBatchNorm 优化。
`HA_USE_VOXEL`	0	NVIDIA GPU	启用点云体素化和动态散射优化。
`HA_USE_DEFORM_AGG`	0	NVIDIA GPU	启用多相机可变形特征聚合优化。
`HA_USE_RASTERIZER`	0	NVIDIA GPU	启用光栅化相关优化。
`HA_USE_DEFORM_ATTN`	0	海光 DCU	启用多尺度可变形注意力优化。
`HA_USE_DROPOUT`	0	海光 DCU	启用 Dropout 融合优化。
`HA_USE_FOCAL_LOSS`	0	海光 DCU	启用 Softmax Focal Loss 融合优化。
`HA_USE_RMSNORM`	0	海光 DCU	启用 RMSNorm 优化。
`HA_USE_ROPE`	0	海光 DCU	启用 RoPE 旋转位置编码优化。
`HA_USE_FAST_GELU`	0	海光 DCU	启用 FastGELU 优化。

HyperAcc 训练加速套件常见优化实践

本页目录：

PyTorch 训练脚本无侵入接入

前提条件

注意事项

操作步骤

GC 优化实践

注意事项

操作步骤

参数说明

DataLoader 调优实践

操作步骤

参数说明

注意事项

torch.compile 自动编译实践

操作步骤

参数说明

调试建议

CPU/NUMA 绑核实践

操作步骤

透明大页实践

操作步骤

注意事项

日志与调试

透明替换系统参数

日志参数

支持的日志级别

透明替换能力

适用场景

使用建议

透明替换功能开关