PTQ-Level Efficiency, QAT-Level Accuracy | 训练后量化的效率,量化感知训练的精度
AutoRound 环境变量配置
English | 简体中文
本文档介绍 AutoRound 使用的环境变量及其配置说明。
概述
AutoRound 通过 envs.py 模块提供统一的环境变量管理系统,支持懒加载求值与程序化配置。
可用环境变量
AR_LOG_LEVEL
- 描述:控制 AutoRound 默认日志级别
- 默认值:
"INFO" - 有效值:
"TRACE"、"DEBUG"、"INFO"、"WARNING"、"ERROR"、"CRITICAL" - 用途:通过设置该变量控制 AutoRound 的日志详细程度
export AR_LOG_LEVEL=DEBUG
AR_ENABLE_COMPILE_PACKING
- 描述:启用编译打包优化
- 默认值:
False(等价于"0") - 有效值:
"1"、"true"、"yes"(不区分大小写)表示启用;其他值表示禁用 - 用途:启用后可在将 FP4 张量打包为
uint8时获得性能优化
export AR_ENABLE_COMPILE_PACKING=1
AR_NVFP4_FUSED_LAYER_GLOBAL_SCALE
- 描述:让 fused NVFP4 权重投影共用一个 weight global scale。该设置作用于
q_proj/k_proj/v_proj与gate_proj/up_proj,以满足 vLLM fused kernel 的要求。 - 默认值:
True(等价于"1") - 有效值:
"0"、"false"、"no"或"off"(不区分大小写)表示关闭共享;其他值表示启用。 - 用途:仅当导出的运行时不要求 fused 投影使用统一 global scale 时关闭。
export AR_NVFP4_FUSED_LAYER_GLOBAL_SCALE=0
AR_USE_MODELSCOPE
- 描述:控制是否使用 ModelScope 下载模型
- 默认值:
False - 有效值:
"1"、"true"(不区分大小写)表示启用;其他值表示禁用 - 用途:启用后将使用 ModelScope 替代 Hugging Face Hub 下载模型
export AR_USE_MODELSCOPE=true
AR_QUANTIZE_BAGEL_MOE_GEN
- 描述:启用 BAGEL
*_moe_gen图像生成专家层的量化。AutoRound 默认将这些模块保留为 BF16,因为实际测试发现量化它们可能降低图像生成质量。BAGEL 的普通 transformer attention 和 MLP 层默认仍会量化。 - 默认值:
False(等价于"0") - 有效值:
"1"、"true"或"yes"(不区分大小写)表示启用;其他值会让*_moe_gen保持 BF16 - 用途:仅在研究 checkpoint 大小与图像质量之间的取舍时启用
export AR_QUANTIZE_BAGEL_MOE_GEN=1
AR_WORK_SPACE
- 描述:设置 AutoRound 操作的工作目录
- 默认值:
"ar_work_space" - 用途:指定 AutoRound 存储临时文件和输出结果的自定义目录
export AR_WORK_SPACE=/path/to/custom/workspace
AR_DISABLE_OFFLOAD
- 描述:强制禁用
OffloadManager中的权重卸载功能。在开发和调试时可跳过所有卸载/重载开销。 - 默认值:
False(等价于"0") - 有效值:
"1"、"true"、"yes"(不区分大小写)表示禁用卸载;其他值保持默认行为 - 用途:设置后将完全绕过权重卸载
export AR_DISABLE_OFFLOAD=1
AR_DISABLE_DATASET_SUBPROCESS
- 描述:禁用子进程方式进行数据集预处理。默认情况下,AutoRound 使用子进程确保所有临时内存在进程退出后被操作系统回收。
- 默认值:
False - 有效值:
"1"、"true"(不区分大小写)表示禁用子进程;其他值表示启用子进程 - 用途:设置后数据集预处理将在主进程中运行
export AR_DISABLE_DATASET_SUBPROCESS=true
AR_DISABLE_GGUF_MTP_EXPORT
- 描述:导出 GGUF 模型时禁用多 token 预测(MTP)层。默认情况下,AutoRound 遵循 llama.cpp 转换器的行为,在模型提供 MTP 层时将其一并导出。
- 默认值:
False(等价于"0") - 有效值:
"1"、"true"、"yes"或"on"(不区分大小写)表示禁用 MTP 导出;其他值保持启用 MTP 导出 - 用途:当 checkpoint 使用支持 MTP 的模型架构,但实际不包含 MTP tensor 时启用
export AR_DISABLE_GGUF_MTP_EXPORT=1
AR_ACT_SCALE
- 描述:只用于研究性质,控制激活量化时对激活值最小/最大值的缩放系数。小于 1.0 的值会缩小裁剪范围,有助于减小离群值的影响。
- 默认值:
1.0 - 有效值:任意浮点数,如
0.8、0.9、1.0 - 用途:调整激活裁剪范围
export AR_ACT_SCALE=0.9
AR_ENABLE_ACT_MINMAX_TUNING
- 描述:只用于研究性质,使用激活量化中最小/最大缩放参数(
act_min_scale、act_max_scale)的调优。启用后,这些缩放参数将固定为 1.0。 - 默认值:
False(等同于"0") - 有效值:
"1"、"true"、"yes"(不区分大小写)表示禁用调优;其他值表示保持调优 - 用途:禁用激活最小-最大缩放参数的调优
export AR_ENABLE_ACT_MINMAX_TUNING=1
AR_SEARCH_SCALE_RATIO
- 描述:控制
auto_round.data_type.int.search_scales中对称 INT 量化 scale 搜索的范围比例。搜索上界为nmax * AR_SEARCH_SCALE_RATIO,其中nmax = 2^(bits-1)。值越小搜索范围越窄(更快,但可能漏掉较优解);值越大搜索范围越广(更慢,对离群权重可能更准)。 - 默认值:未设置 → 走内置默认值(
0.5,即nmax/2)。 - 有效值:正浮点数,如
0.25、0.5、0.75、1.0 - 用途:覆盖默认的 scale 搜索范围
export AR_SEARCH_SCALE_RATIO=0.75
AR_NEUQI_COARSE
- 描述:NeUQI 网格搜索(
--enable_neuqi,arXiv 2505.17595)粗阶段的候选数量。粗阶段扫描较宽的对数网格,细阶段在胜者附近细化(AR_NEUQI_FINE)。同时作用于非对称联合 (scale, zero-point) 搜索与对称两阶段 scale 搜索。 - 默认值:加速后端(Triton/torch.compile)为
256,eager 扫描为64—— eager 路径每 group 需评估约 coarse x fine 个候选,因此未显式指定时使用更窄的默认网格(两种网格的实测质量持平) - 取值:正整数
- 用法:调低可加快搜索,代价是网格覆盖范围变小。
export AR_NEUQI_COARSE=128
AR_NEUQI_FINE
- 描述:NeUQI 网格搜索细阶段的候选数量,在粗阶段胜者附近细化。参见
AR_NEUQI_COARSE。 - 默认值:加速后端(Triton/torch.compile)为
64,eager 扫描为32 - 取值:正整数
- 用法:调低可加快搜索,代价是最终分辨率下降。
export AR_NEUQI_FINE=32
AR_NEUQI_BACKEND
- 描述:NeUQI 候选扫描的后端覆盖。
auto选择最快的可用后端(扩展 Triton 内核 → torch.compile 融合 → eager),并在内核首次失败时永久回退。eager/compile/triton强制指定后端,用于调试或基准测试。 - 默认值:
auto - 取值:
auto、eager、compile、triton - 用法:驱动/硬件兼容性逃生口;推荐使用
auto。
export AR_NEUQI_BACKEND=eager
AR_DYNAMO_CACHE_SIZE_LIMIT
- 描述:在开启
torch.compile(除 Windows 外默认开启)时,将torch._dynamo的cache_size_limit、accumulated_cache_size_limit与recompile_limit提升到的最小值。同一个被编译的量化函数会被 transformer block 内的所有 linear 层(q/k/v/o_proj、gate/up/down_proj 等)复用,但每层权重 shape 不同,按层的静态重编译会很快超过 dynamo 默认上限(8),导致打印告警并退回 eager。提高该上限可保留静态 shape 编译(性能最佳),仅增加缓存条目数。多设备运行时目标值会乘以参与设备数(逐层 shape 与逐设备 guard 钉住相乘地增加特化条目);单设备运行直接使用该值。 - 默认值:
16(多设备运行时按参与设备数相乘) - 有效值:正整数
- 用途:当模型单个 block 内、每个参与设备的 linear 权重 shape 种类超过 16 时(较少见)可调大。
export AR_DYNAMO_CACHE_SIZE_LIMIT=32
AR_MODEL_FREE_SHARD_PARALLELISM
- 描述:控制 model-free 量化时同时处理的权重 shard 数量。增大该值可提高资源利用率,但会占用更多内存。
- 自动策略(变量未设置时):
shard_count // 4,最大 10,最小 1。例如:8 个 shard → 2 个 worker;40 个 shard → 10 个 worker。 - 实际并行数始终不超过 shard 总数。
- 自动策略(变量未设置时):
- 默认值:未设置 → 走自动策略(
shard_count // 4,最大 10,最小 1) - 有效值:任意正整数,不限于特定值,如
2、4、6、8;不能整除 shard 数时会自动均匀分配,末批处理剩余 shard,结果正确 - 用途:覆盖自动并行策略,手动指定并行数
export AR_MODEL_FREE_SHARD_PARALLELISM=4
AR_AUTO_SCHEME_NSAMPLES
- 描述:控制 AutoScheme 评分时使用的校准样本数默认值,仅在
AutoScheme.nsamples未显式设置时生效。 - 默认值:未设置 → 16
- 有效值:任意正整数,如
8、16、32 - 用途:覆盖 AutoScheme 的自动样本数选择
export AR_AUTO_SCHEME_NSAMPLES=1
AR_AUTO_SCHEME_BATCH_SIZE
- 描述:控制 AutoScheme 评分时使用的批大小默认值,仅在
AutoScheme.batch_size未显式设置时生效。 - 默认值:未设置 → 走内置启发式规则(低GPU内存模式为 8,普通模式为 1)
- 有效值:任意正整数,如
1、2、4 - 用途:覆盖 AutoScheme 的默认批大小
export AR_AUTO_SCHEME_BATCH_SIZE=1
AR_AUTO_SCHEME_SEQLEN
- 描述:控制 AutoScheme 评分时使用的校准序列长度默认值,仅在
AutoScheme.seqlen未显式设置时生效。 - 默认值:未设置 → 走内置启发式规则(MoE 模型为 128,其他为 256)
- 有效值:任意正整数,如
256、512、1024 - 用途:覆盖 AutoScheme 的默认序列长度(2-bit 方案通常在
1024时效果更好)
export AR_AUTO_SCHEME_SEQLEN=1024
AR_AUTO_SCHEME_NO_SERIAL_FALLBACK
- 描述:将并行评分失败变为硬错误,而不是回退到串行评分。当串行路径已知无法运行(或耗时会是 worker 数量的倍数)时非常有用:已完成的方案和批次会持久化在单方案缓存中,重新运行时只补打失败的部分。
- 默认值:未设置时,并行评分失败会回退到串行评分
- 有效值:
1、true、yes(不区分大小写) - 用法:设置该变量以在并行评分出错时快速失败
export AR_AUTO_SCHEME_NO_SERIAL_FALLBACK=1
AR_AUTO_SCHEME_CACHE
- 描述:存放可持久复用的 AutoScheme 单方案评分 JSON 文件。该目录独立于用于临时工作数据的
AR_WORK_SPACE。 - 默认值:
~/.cache/auto_round - 有效值:任意可写目录路径
- 用途:将可复用的 AutoScheme 评分结果保存到其他缓存目录
export AR_AUTO_SCHEME_CACHE=/path/to/auto_scheme_cache
AR_ENABLE_AUTO_SCHEME_PARALLEL
- 描述:启用 AutoScheme 候选方案之间的多进程并行。可与
AR_DISK_STREAM_MODEL=1同时使用;此时每个 worker 会构建独立的 meta 模型骨架并分别流式加载 block。当并发 worker 可能耗尽主机内存或显存时,请将其关闭。 - 默认值:
"1"(满足多进程要求时并行评分各方案) - 有效值:
"1"、"true"、"yes"(不区分大小写)表示启用并行评分;其他值表示关闭 - 用途:运行 AutoScheme 前将其设为
0,以强制串行评分候选方案
export AR_ENABLE_AUTO_SCHEME_PARALLEL=0
AR_SCHEME_MEM_INVENTORY
- 描述:启用后,AutoScheme 流式评分会在 block 边界打印当前 CUDA tensor 清单(
[mem-inv]行)——按 (shape, dtype) 分组、按大小降序——便于发现未释放的模块权重或被保留的计算图。与该变量无关,打分 worker 的 CUDA OOM 错误始终会附带更详细的清单(活动 tensor、持有它们的容器以及出错算子的 traceback)。 - 默认值:
False - 有效值:
"1"、"true"、"yes"(不区分大小写)表示启用;其他值表示禁用 - 用法:排查 AutoScheme 打分期间显存增长问题时启用
export AR_SCHEME_MEM_INVENTORY=1
AR_NVFP4_E5M3_CACHE_HP_WEIGHT
- 描述:控制
NVFP4E5M3QuantLinear是否在首次前向后缓存解量化得到的高精度权重,而不是每次调用都从打包的 FP4 权重重新解量化。 - 默认值:
False(等价于"0") - 有效值:
"1"、"true"、"yes"、"on"(不区分大小写)表示启用缓存;其他值表示禁用缓存 - 用途:当重复推理吞吐比内存占用更重要时可启用。当前实现会在缓存高精度权重后释放
weight_packed和weight_scale,因此稳态内存占用会增大,且之后无法再切回打包存储。
export AR_NVFP4_E5M3_CACHE_HP_WEIGHT=1
AR_DISK_STREAM_MODEL
- 描述:启用后,
AutoRound(model=<path>, ...)会将模型构建为 meta 设备骨架,而不是先把整个 checkpoint 完全加载到 CPU 内存;随后按需从 checkpoint 的 safetensors 分片中流式加载每个解码器块的真实权重——在该块被使用前(校准、调优或AutoScheme敏感度评分)才实体化,用完后立即释放回 meta。这样峰值 CPU 内存基本保持平稳,而不会随 checkpoint 大小成比例增长。非块参数(embedding、lm_head、最终归一化层)体积通常较小,仍会一次性加载。文本模型的 AutoScheme 评分也支持与默认启用的并行评分组合使用;每个 worker 会流式加载自己的 block 副本。 - 默认值:
False - 有效值:
"1"、"true"、"yes"(不区分大小写)表示启用;其他任何值表示禁用 - 用途:用于量化体积超过可用 CPU 内存 + GPU 显存总和的 checkpoint。仅在
model为字符串(本地目录)路径时生效,对已加载的模型对象无效。
export AR_DISK_STREAM_MODEL=1
AR_ALLOW_W8_ASYM
- 描述:允许在所有导出格式下使用 8 位非对称权重量化,跳过对无法提供服务的格式(原生
auto_round/auto_gptq/auto_awq/ marlin)的默认拒绝。未设置时,8 位非对称仅对llm_compressor格式(compressed-tensors,vLLM 可服务)开放,其他格式会被拒绝或回退为对称。使用该变量产出的模型可能无法在原生 vLLM GPTQ 格式服务中加载。 - 默认值:
0(关闭) - 有效值:
0/1 - 用法:面向 vLLM 之外推理框架的显式逃生开关。
AR_ALLOW_W8_ASYM=1 python -m auto_round --model ... --scheme W8A16 --asym --format auto_round
AR_DISABLE_BATCHED_SEARCH
- 描述:禁用批量量化搜索机制:SignRoundV2 的封装期 init-scale 搜索(iters>0)与 iters=0 的 optimized-RTN 搜索都将完全串行(GGUF DQ scale 搜索始终逐模块内联执行)、逐模块地在权重所在设备上执行。批量化将设备/形状/配置相同的模块堆叠为一次调用,逐模块结果比特级一致;设置该变量可回退到串行循环(例如用于调试,或二分定位疑似与批量化相关的差异)。堆叠也会改变瞬态显存占用(见
AR_SEARCH_BATCH_GB)。 - 默认值:
0(启用批量化) - 有效取值:
0/1 - 用法:批量/并行搜索机制的总开关。
AR_DISABLE_BATCHED_SEARCH=1 python -m auto_round --model ... --device_map 0,1,2,3
AR_PERF_COUNTERS
- 描述:为每个 block 输出一行
[perf] tune phasesINFO 日志,包含各调优阶段(wrap / prepare / loop / tail)的耗时,以及循环内部的采样器抽取、最优参数快照、梯度同步 + 优化器步进、剩余时间和串行 forward+loss+backward 时间。用于大型多设备量化运行的性能归因;开销可忽略。 - 默认值:
0(关闭) - 有效取值:
0/1 - 用法:在基准测试运行中设置,用于将 block 时间归因到封装搜索或调优循环。
AR_PERF_COUNTERS=1 python -m auto_round --model ... --device_map 0,1,2,3
AR_SEARCH_BATCH_GB
- 描述:显式覆盖批量量化搜索的堆叠批次大小,单位为每次调用堆叠 fp32 权重的 GiB 数。适用于所有批量 lane:iters=0 的 optimized-RTN 搜索、iters>0 的封装期搜索以及 NeUQI 网格锚定。未设置时批次大小按容量驱动:每个批次的大小使搜索的瞬态占用(批次的 fp32 拷贝链,NeUQI 场景另加封顶的内部临时量)不超过探测到的空闲显存的一半,且每个执行设备在调用时复查余量(过大的批次会减半而不是出错)。仅当需要把批次压到容量规划以下时才设置。
- 默认值:未设置(容量驱动)
- 有效取值:正浮点数(GiB)
- 用法:在显存紧张的多设备运行中缩小批次。
AR_SEARCH_BATCH_GB=0.5 python -m auto_round --model ... --device_map 0,1
AR_MOE_EXPERTS_IMPL
- 描述:MoE 调优阶段(模型已按专家拆分)使用的前向实现。
auto(默认)会在第一个 MoE 块之前预测 grouped-GEMM 调优路径的每卡显存占用,当 grouped 调优放不下时(qdq 堆叠保留 + 调优状态与各卡剩余显存比较)整个运行改用linear_loop;决策与各卡数值都会记录到日志。显式取值不会被auto覆盖。 - 默认值:
auto - 可选值:
auto、linear_grouped、linear_grouped_sliced、linear_loop - 用法:强制指定调优时的专家前向实现,或保持
auto由显存模型自动选择。
AR_MOE_EXPERTS_IMPL=linear_loop python -m auto_round --model ... --device_map 0,1,2,3
AR_DISABLE_CROSS_DEVICE_SEARCH
- 描述:将批量搜索批次限制在权重所在设备上。默认情况下,两条搜索 lane 会集中规划批次:每个批次先落在权重所在设备,再从过载设备向空闲的可用设备再平衡,使搜索尽量铺满所有有余量的可见设备(此类搜索只读取自身模块的权重与逐模块统计量,从不读取校准激活;每个执行设备由单个工作线程独占)。非 CUDA 设备族的批次始终留在权重所在设备。以下情况设为
1:机架 GPU 与其他任务共享(空闲显存探针无法看到其他任务的占用)、调试跨设备行为、或 PCIe 传输开销超过搜索收益的主机。当没有设备放得下时,批次留在权重所在设备并依赖逐批次的 OOM 回退。 - 默认值:
0(启用多 GPU 搜索,探针门控) - 有效取值:
0/1 - 用法:将搜索流量固定在权重所在设备。
AR_DISABLE_CROSS_DEVICE_SEARCH=1 python -m auto_round --model ... --iters 0
AR_RESUME_DIR
- 描述:设置为目录路径后,逐块调优循环会在每完成一个块后将进度写入该目录,并在针对同一目录的新一次运行中从第一个未完成的块继续——而不是在崩溃或被杀死后从第 0 块重新开始整个调优过程。
- 默认值:未设置(不支持断点续跑)
- 有效值:任意可写目录路径
- 用途:用于大 checkpoint 的长时间量化任务,避免运行中途崩溃导致从头重跑的高昂代价。
export AR_RESUME_DIR=/path/to/resume/state
使用示例
设置环境变量
通过 Shell 命令
# 将日志级别设置为 DEBUG
export AR_LOG_LEVEL=DEBUG
# 启用编译打包
export AR_ENABLE_COMPILE_PACKING=1
# 使用 ModelScope 下载模型
export AR_USE_MODELSCOPE=true
# 设置自定义工作目录
export AR_WORK_SPACE=/tmp/autoround_workspace
通过 Python 代码
from auto_round.envs import set_config
# 同时配置多个环境变量
set_config(
AR_LOG_LEVEL="DEBUG",
AR_USE_MODELSCOPE=True,
AR_ENABLE_COMPILE_PACKING=True,
AR_WORK_SPACE="/tmp/autoround_workspace",
)
查看环境变量
通过 Python 代码
from auto_round import envs
# 访问环境变量(懒加载求值)
log_level = envs.AR_LOG_LEVEL
use_modelscope = envs.AR_USE_MODELSCOPE
enable_packing = envs.AR_ENABLE_COMPILE_PACKING
workspace = envs.AR_WORK_SPACE
print(f"日志级别: {log_level}")
print(f"使用 ModelScope: {use_modelscope}")
print(f"启用编译打包: {enable_packing}")
print(f"工作目录: {workspace}")
检查变量是否显式设置
from auto_round.envs import is_set
# 检查环境变量是否被显式设置
if is_set("AR_LOG_LEVEL"):
print("AR_LOG_LEVEL 已被显式设置")
else:
print("AR_LOG_LEVEL 正在使用默认值")
配置最佳实践
- 开发环境:设置
AR_LOG_LEVEL=TRACE或AR_LOG_LEVEL=DEBUG以获取详细日志 - 生产环境:使用
AR_LOG_LEVEL=WARNING或AR_LOG_LEVEL=ERROR减少日志噪声 - 中国用户:建议设置
AR_USE_MODELSCOPE=true以获得更好的模型下载速度 - 性能优化:如有足够算力,可启用
AR_ENABLE_COMPILE_PACKING=1 - 自定义工作目录:将
AR_WORK_SPACE设置为磁盘空间充足的目录
AR_TUNE_DDP_MAX_COLLECT_FORWARD_DEVICES
- 描述:限制携带 hook 的分片采集前向并发使用的设备数(hook 前向会使编译后的执行器在图分段之间退回 Python 绑定,可能在 GIL 上形成串行瓶颈)。仅在 hook 前向出现串行瓶颈的主机上才需要调低;在验证机台上至 world=8 未复现。大于已启用 world 的值等效于不限制。
- 默认值:
0(不限制) - 取值:非负整数
- 用法:在弱 CPU 主机上限制并发分片前向线程数。
AR_TUNE_DDP_MAX_COLLECT_FORWARD_DEVICES=2 python -m auto_round --model ... --data_parallel 8
注意事项
- 环境变量采用懒加载方式,仅在首次访问时读取
set_config()函数提供了便捷的程序化多变量配置方式AR_USE_MODELSCOPE的布尔值会自动转换为适当的字符串表示- 所有环境变量名称区分大小写
- 通过
set_config()所做的修改将影响当前进程及其子进程