本文介绍腾讯云 HyperAcc 训练加速套件的环境变量配置接口，包括自动激活入口、功能开关（总开关、透明替换能力、算子加速能力、系统级优化能力）及功能参数（编译、GC、DataLoader、日志等）的详细说明。HyperAcc 通过环境变量统一控制所有功能，您在训练入口 Python 脚本开头导入
hyperacc.auto 即可完成自动激活。使用说明
将所有配置写入训练任务启动脚本、容器启动命令或调度平台环境变量配置中。
环境变量应在训练进程启动前设置。
设置环境变量后，需要在训练入口 Python 脚本开头导入
hyperacc.auto 才会自动激活对应能力。系统级优化能力在权限不足或环境不满足时，可能无法生效，建议结合日志确认。
自动激活入口
推荐在训练入口 Python 脚本开头导入。除
from_future_ 等必须位于文件开头的语句外，import hyperacc.auto 应放在 torch、训练框架、模型和 DataLoader 相关导入之前：import hyperacc.auto
导入后，HyperAcc 会读取当前进程的
HA_* 环境变量，并按配置启用对应能力。注意：
未设置环境变量时，
import hyperacc.auto 默认不做任何操作。自非主进程场景下，部分自动激活逻辑可能跳过，以避免影响 DataLoader worker 等子进程。
环境变量 API
功能开关总开关
环境变量 | 默认值 | 说明 |
HA_USE_ALL | 0 | 启用所有能力，支持0（关闭）和1（开启）。 |
HA_USE_ALL_HOOKS | 0 | 启用所有透明替换能力，不影响系统级优化，支持0（关闭）和1（开启）。 |
通用透明替换能力
环境变量 | 默认值 | 说明 |
HA_USE_COMPILE | 0 | 启用自动编译，支持0（关闭）和1（开启）。 |
HA_USE_CHANNELS_LAST | 0 | 启用 channels_last 内存格式转换，支持0（关闭）和1（开启）。 |
HA_USE_LIGHTNING | 0 | 启用 Lightning Trainer 相关能力，支持0（关闭）和1（开启）。 |
HA_USE_DATALOADER | 0 | 启用 DataLoader 优化，支持0（关闭）和1（开启）。 |
HA_USE_SYNCBN | 0 | 启用 SyncBatchNorm 优化，支持0（关闭）和1（开启）。 |
系统级优化能力
环境变量 | 默认值 | 说明 |
HA_USE_GC | 1 | 启用 GC 优化。 |
HA_USE_NUMABIND | 0 | 启用 CPU/NUMA 绑定。 |
HA_USE_THP | 0 | 启用透明大页。 |
功能参数
环境变量 | 默认值 | 说明 |
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_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 | DataLoader worker 数量。负数表示不修改用户配置。 |
HA_DATALOADER_PREFETCH | 2 | DataLoader 预取批次数。负数表示不修改用户配置。 |
HA_HOOKS_LAZY | 1 | 是否在目标组件加载时再应用透明替换能力。 |
HA_HOOKS_SILENT | 1 | 是否减少透明替换相关日志。 |
HA_LOG_LEVEL | INFO | 日志级别。支持 DEBUG、INFO、WARNING、ERROR、CRITICAL。 |
HA_SHIFT_COMPARE | 0 | 启用 shift patch 对比测试，主要用于调试验证。 |
