AutoGPTQ 官方示例全解析：从 GPTQ 量化、效果评估到生成速度基准与 PEFT 微调的完整实战指南

• 模型量化
• 大模型
• 模型优化

本指南以 AutoGPTQ 仓库examples目录下的官方示例脚本为主线，系统讲解如何用量化、评估、基准测试与 PEFT 微调四大类脚本完成一套完整的 GPTQ 量化工作流：先对模型进行 4-bit 量化，再在语言建模、序列分类、文本摘要等下游任务上对比量化前后效果，最后用生成速度基准验证收益，并通过 LoRA/AdaLoRA/AdaptionPrompt 对量化模型做轻量级指令微调。读完本文，你将掌握 AutoGPTQ 每个示例脚本的启动命令、全部命令行参数含义，以及它们背后对应的源码实现原理。

环境准备：先安装 auto_gptq

运行examples下的所有脚本，前提是先安装好auto_gptq包本身。AutoGPTQ 目前仅支持 Linux 与 Windows 平台，推荐直接安装 PyPI 上的预编译稳定版本（以 CUDA 12.1 为例）：

pip install auto-gptq --no-build-isolation

如需使用 Triton 推理后端（仅支持 Linux，且不支持 3-bit 量化），可安装带 Triton 依赖的版本：

pip install auto-gptq[triton] --no-build-isolation

如需从源码安装，则先克隆仓库，再执行：

git clone https://github.com/PanQiWei/AutoGPTQ.git && cd AutoGPTQ pip install -vvv --no-build-isolation -e .

examples目录按功能划分为quantization（量化）、evaluation（评估）、benchmark（基准测试）、peft（参数高效微调）四个子目录，下文各节命令均需在对应子目录下运行。

一、Quantization：三种量化脚本实战

quantization目录提供了三条量化路径：basic_usage.py（最简快速上手）、basic_usage_wikitext2.py（使用 WikiText2 校准）、quant_with_alpaca.py（使用 Alpaca 指令数据集校准，可配置参数最多）。三者共享同一个核心 API 调用链：AutoGPTQForCausalLM.from_pretrained→model.quantize(examples)→model.save_quantized(...)→AutoGPTQForCausalLM.from_quantized(...)，区别仅在校准样本的构造方式与可调参数粒度。

1.1 basic_usage.py：最短路径完成量化与推理

在quantization目录下执行：

python basic_usage.py

该脚本用facebook/opt-125m作为预训练模型，核心流程如下：

from transformers import AutoTokenizer, TextGenerationPipeline from auto_gptq import AutoGPTQForCausalLM, BaseQuantizeConfig pretrained_model_dir = "facebook/opt-125m" quantized_model_dir = "opt-125m-4bit-128g" tokenizer = AutoTokenizer.from_pretrained(pretrained_model_dir, use_fast=True) examples = [ tokenizer( "auto-gptq is an easy-to-use model quantization library with user-friendly apis, based on GPTQ algorithm." ) ] quantize_config = BaseQuantizeConfig( bits=4, # 量化到 4-bit group_size=128, # 分组量化，官方建议设为 128 desc_act=False, # 关闭激活重排可显著加速推理，但困惑度可能略有变差 ) # 加载未量化模型，默认总是加载到 CPU 内存 model = AutoGPTQForCausalLM.from_pretrained(pretrained_model_dir, quantize_config) # 量化模型，examples 必须是 dict 列表，键只能是 "input_ids" 和 "attention_mask" model.quantize(examples) # 保存量化模型 model.save_quantized(quantized_model_dir) # 用 safetensors 格式保存 model.save_quantized(quantized_model_dir, use_safetensors=True) # 加载量化模型到第一块 GPU model = AutoGPTQForCausalLM.from_quantized(quantized_model_dir, device="cuda:0") # 用 model.generate 推理 print(tokenizer.decode(model.generate(**tokenizer("auto_gptq is", return_tensors="pt").to(model.device))[0])) # 或用 pipeline 推理 pipeline = TextGenerationPipeline(model=model, tokenizer=tokenizer) print(pipeline("auto-gptq is")[0]["generated_text"])

注意脚本中默认只使用 1 个校准样本（脚本顶部的注释也提醒过：如此少量样本得到的量化模型质量可能不佳），其主要作用是演示 API 用法。

该脚本还演示了与 🤗 Hub 的交互：如需把量化模型上传到 Hub，可先执行huggingface-cli login登录，然后取消注释以下代码块：

repo_id = f"YourUserName/{quantized_model_dir}" commit_message = f"AutoGPTQ model for {pretrained_model_dir}: {quantize_config.bits}bits, gr{quantize_config.group_size}, desc_act={quantize_config.desc_act}" model.push_to_hub(repo_id, commit_message=commit_message, use_auth_token=True) # 也可以保存与上传同时进行 model.push_to_hub(repo_id, save_dir=quantized_model_dir, use_safetensors=True, commit_message=commit_message, use_auth_token=True) # 从 Hub 下载量化模型并加载 model = AutoGPTQForCausalLM.from_quantized(repo_id, device="cuda:0", use_safetensors=True, use_triton=False)

1.2 basic_usage_wikitext2.py：用标准语料库校准

在quantization目录下执行：

python basic_usage_wikitext2.py

与basic_usage.py的最大区别是：校准样本从 WikiText2 数据集的训练集随机截取（默认 128 个样本，序列长度 2048），数据加载与预处理逻辑见脚本中的get_wikitext2()函数（从wikitext-2-raw-v1数据集加载，通过random.randint随机切分连续 token 片段并构造input_ids与全 1 的attention_mask）。量化配置同样为bits=4, group_size=128, desc_act=False。

脚本随后还内置了一个opt_eval()函数，用 WikiText2 测试集计算量化后模型的困惑度（perplexity），其做法是逐层（layer-by-layer）把隐藏状态搬上 GPU 计算负对数似然，最终用torch.exp汇总得到 PPL。这也解释了文档中的提示：使用 AutoGPTQ 在 opt-125m 模型上的 PPL 相比 GPTQ-for-LLaMa 约有 0.6 的退化，这是在相同设置下进行对比的经验参考值，实际数值会随校准样本与随机种子变化。

值得注意的两点实现细节：

• model.quantize(traindataset, use_triton=False)：显式关闭 Triton；
• AutoGPTQForCausalLM.from_quantized(quantized_model_dir, device="cuda:0", use_triton=False)：目前from_quantized只支持 CPU 或单 GPU 加载。

1.3 quant_with_alpaca.py：Alpaca 校准 + 最完整的命令行参数

在quantization目录下执行（文档给出的官方示例命令）：

python quant_with_alpaca.py --pretrained_model_dir "facebook/opt-125m" --per_gpu_max_memory 4 --quant_batch_size 16

--per_gpu_max_memory 4表示每块 GPU 最多使用 4 GiB 显存加载模型，--quant_batch_size 16表示量化阶段校准样本的批大小。脚本使用的校准数据是本仓库examples/quantization/dataset/alpaca_data_cleaned.json，这是 gururise 提供的 AlpacaDataCleaned 清理版 Alpaca 数据集，脚本会从中随机采样（默认 128 条）构造训练样本。

运行python quant_with_alpaca.py --help可查看全部参数，结合源码examples/quantization/quant_with_alpaca.py，各参数含义如下：

脚本在量化完成后会随机抽取 4 条样本，用TextGenerationPipeline对比 golden 输出与量化模型的生成结果，并打印生成耗时与 tokens/s 速度：

generated_text = pipeline(example["prompt"], return_full_text=False, num_beams=1, max_length=len(example["input_ids"]) + 128)[0]["generated_text"] print(f"generate {num_new_tokens} tokens using {end-start:.4f}s, {num_new_tokens / (end - start)} tokens/s.")

1.4 量化配置的源码级解读

三个脚本共同依赖BaseQuantizeConfig，其完整字段定义在 auto_gptq/quantization/config.py：

@dataclass class BaseQuantizeConfig(PushToHubMixin): bits: int = field(default=4, metadata={"choices": [2, 3, 4, 8]}) group_size: int = field(default=-1) damp_percent: float = field(default=0.01) desc_act: bool = field(default=True) static_groups: bool = field(default=False) sym: bool = field(default=True) true_sequential: bool = field(default=True) quant_method: str = field(default=QUANT_METHOD.GPTQ) checkpoint_format: str = field(default=CHECKPOINT_FORMAT.GPTQ)

其中几个对量化质量与推理速度影响最大的字段：

• bits：只能取 2/3/4/8，超出会抛ValueError；
• group_size：-1表示不分组，否则必须大于 0；
• damp_percent：GPTQ 算法中的 Hessian 阻尼比例，必须位于 (0, 1) 之间；
• desc_act：是否按激活值对列进行重排，True时量化精度更好但推理更慢；
• sym：是否使用对称量化；
• true_sequential：是否按真实执行顺序逐层量化；
• checkpoint_format：支持gptq/marlin/gemm（AWQ）等格式，from_quant_config()中会对量方法、格式、位宽、分组等做合法性校验，并兼容旧版w_bit、q_group_size等键名（见QUANT_CONFIG_ARG_SYNONYMS）。

量化配置最终会以quantize_config.json形式随模型一起保存（save_pretrained），加载时由BaseQuantizeConfig.from_pretrained()依次尝试quantize_config.json、quant_config.json、config.json（transformers 格式时读取quantization_config子字段）。这也是为什么generation_speed.py支持用--quantize_config_save_dir单独指定配置文件目录。

二、Evaluation：三类下游任务评估脚本

evaluation目录下的三个脚本展示了如何使用auto_gptq.eval_tasks中的LanguageModelingTask、SequenceClassificationTask、TextSummarizationTask，在量化前后分别评估模型性能。三者共享同一个骨架：先用AutoGPTQForCausalLM.from_pretrained加载基础模型评估一次，然后torch.cuda.empty_cache()释放显存，再用AutoGPTQForCausalLM.from_quantized加载量化模型评估第二次。所有评估命令均需在evaluation目录下运行，且都支持--help查看参数。

三个脚本共有的命令行参数：

2.1 语言建模任务：PPL 指标

运行命令：

CUDA_VISIBLE_DEVICES=0 python run_language_modeling_task.py --base_model_dir PATH/TO/BASE/MODEL/DIR --quantized_model_dir PATH/TO/QUANTIZED/MODEL/DIR

脚本使用tatsu-lab/alpaca数据集，通过ds_refactor_fn把 instruction/input/output 重构成Instruction:\n...\n\nInput:\n...\n\nOutput:\n提示模板（无 input 时使用无 Input 模板），得到prompt与output两列。LanguageModelingTask内部会自动把 prompt 与 label 合并（merge_prompt_label=True），核心实现见 auto_gptq/eval_tasks/language_modeling_task.py：_predict直接取model(**batch)的 loss，_metric对平均 loss 取指数得到困惑度：

def _metric(self, pred, label): return {"ppl": math.exp(sum(pred) / len(pred))}

因此脚本最终打印形如eval result for base model: {'ppl': 12.34}的结果，可直接对比量化前后 PPL 变化。

2.2 序列分类任务：准确率指标

运行命令：

CUDA_VISIBLE_DEVICES=0 python run_sequence_classification_task.py --base_model_dir PATH/TO/BASE/MODEL/DIR --quantized_model_dir PATH/TO/QUANTIZED/MODEL/DIR

脚本使用cardiffnlp/tweet_sentiment_multilingual数据集的英文子集（通过partial(datasets.load_dataset, name="english")指定），标签为negative/neutral/positive三类。提示模板为：

Question:What's the sentiment of the given text? Choices are {labels}. Text: {text} Answer:

SequenceClassificationTask的核心逻辑见 auto_gptq/eval_tasks/sequence_classification_task.py：

• 根据类别词条目的 token 数自动确定max_new_tokens；
• 模型生成后通过get_closest_label把生成文本映射到最近的类别；
• 最终指标为准确率{"acc": ...}。

BaseTask.run()会在内部自动设置generation_config，并对每一批数据做torch.inference_mode()+autocast推理，公共执行框架见 auto_gptq/eval_tasks/_base.py。

2.3 文本摘要任务：ROUGE 指标

运行命令：

CUDA_VISIBLE_DEVICES=0 python run_text_summarization_task.py --base_model_dir PATH/TO/BASE/MODEL/DIR --quantized_model_dir PATH/TO/QUANTIZED/MODEL/DIR

脚本使用samsum对话摘要数据集，提示模板为：

Instruction: Summarize the conversation into one sentence. Input: {diag} Output:

脚本首次运行会先执行pip install py7zr（samsum 数据集以 7z 压缩包发布）。TextSummarizationTask的实现见 auto_gptq/eval_tasks/text_summarization_task.py：调用model.generate生成摘要，用postprocess_generation_ids去掉输入部分只保留新增 token，指标由rouge库计算，返回{"rouge-1": ..., "rouge-2": ..., "rouge-l": ...}的平均分数。该脚本在task.run()中显式传入GenerationConfig(max_new_tokens=32)控制生成长度。

2.4 评估框架的通用机制

三个 Task 都继承自BaseTask（auto_gptq/eval_tasks/_base.py），构造时通过get_dataloader结合make_data_block实现"面向文本生成的智能分块"（见 auto_gptq/utils/data_utils.py）：按 prompt（或 prompt+label）长度排序，把长度相近的样本拼进同一个 block，再在 block 内部 padding，从而最大化显存利用率。truncate_prompt决定样本超过sample_max_len时截断 prompt 还是截断 label。数据加载与预处理通过load_fn、preprocess_fn两个回调注入，因此可以很方便地替换成自定义数据集。

三、Benchmark：生成速度基准

benchmark目录下的generation_speed.py用于衡量模型生成速度（单位 tokens/s），支持对 AutoGPTQ 支持的所有预训练/量化模型进行测速。在benchmark目录下运行：

CUDA_VISIBLE_DEVICES=0 python generation_speed.py --model_name_or_path PATH/TO/MODEL/DIR

默认从../quantization/dataset/alpaca_data_cleaned.json随机采样 10 条样本（--num_samples 10）作为测试 prompt，强制每个 prompt 生成 512 个新 token（--max_new_tokens 512），统计总生成 token 数与总耗时，最终输出generation speed: xx.xx tokens/s。

脚本全部命令行参数（源码见 examples/benchmark/generation_speed.py）：

脚本中的关键机制：

1. 自定义 LogitsProcessor：CustomizedMinNewTokensLogitsProcessor在生成的前min_new_tokens步内屏蔽 EOS token，保证每次都生成足量 token，使测速结果可比；
2. 模型加载开关：load_model_tokenizer()中对量化模型默认启用inject_fused_attention=True、inject_fused_mlp=True、use_cuda_fp16=True，并支持disable_exllama关闭默认的 exllamav2 int4×fp16 内核；使用 Triton 时先执行model.warmup_triton()预热；
3. 统计口径：num_generated_tokens只统计输入长度之后、且非 pad token 的新 token，最终以total_tokens / total_seconds报告 tokens/s。

README 中的官方测速示例（llama-7b 在 1×A100-40G 上，beam=1 时 fp16 约 18.87 tokens/s、gptq-int4 约 25.53 tokens/s）即由该脚本产生，可作为复现时的对照参考。

四、PEFT：三种适配器微调脚本

peft目录下的三个脚本展示了如何在 GPTQ 量化模型上做参数高效微调（PEFT），全部使用auto_gptq.utils.peft_utils中的工具与 🤗 peft 库，在清理版 Alpaca 数据集上进行指令微调，命令均需在peft目录下运行。

三个脚本共有的参数：

4.1 LoRA 微调

在peft目录下运行：

CUDA_VISIBLE_DEVICES=0 python peft_lora_clm_instruction_tuning.py --model_name_or_path PATH/TO/MODEL/DIR

脚本默认学习率3e-5。核心差异在于使用GPTQLoraConfig（定义于 auto_gptq/utils/peft_utils.py）而非原生LoraConfig：

peft_config = GPTQLoraConfig( r=16, lora_alpha=32, lora_dropout=0.1, task_type=TaskType.CAUSAL_LM, inference_mode=False, )

加载量化模型时需以trainable=True进入可训练模式，并通过get_gptq_peft_model(model, peft_config=..., auto_find_all_linears=True, train_mode=True)完成适配器注入。auto_find_all_linears=True时，find_all_linear_names会自动收集模型中除 lm_head 外的全部线性层作为target_modules。

peft_utils.py之所以需要自定义GPTQLoraConfig/GPTQLoraModel/GPTQLoraLinear，是因为量化模型的线性层是QuantLinear系列（如qlinear_cuda、qlinear_exllama、qlinear_triton等），而非标准torch.nn.Linear，其权重存储在qweight等专用字段中；GPTQLoraLinear通过_get_weight读取weight或qweight适配这些层。同时由于量化权重无法合并回主权重，merge_adapter / merge_and_unload均被显式禁止（抛NotImplementedError）。底层通过hijack_peft_mappings()上下文管理器临时改写 peft 的 LORA/ADALORA 映射，训练结束后恢复。

训练流程与标准 transformers 微调一致：AdamW 优化器 + 线性 warmup 调度器，全程torch.cuda.amp.autocast()混合精度，每个 epoch 结束计算 train/eval loss 并打印train_ppl、eval_ppl，最终把适配器保存到{model_name_or_path}/gptq_lora_adapter：

model.save_pretrained(os.path.join(model_name_or_path, f"gptq_{peft_config.peft_type.value}_adapter"))

数据预处理同样通过make_data_block（merge_prompt_label=True、add_eos_token=True），提示模板为### Instruction:\n{instruction}\n\n### Input:\n{input}\n\n### Output:\n，训练/验证集按 9:1 切分（test_size=len(ds)//10）。

4.2 AdaLoRA 微调

在peft目录下运行：

CUDA_VISIBLE_DEVICES=0 python peft_adalora_clm_instruction_tuning.py --model_name_or_path PATH/TO/MODEL/DIR

脚本默认学习率3e-3，使用GPTQAdaLoraConfig（继承自 peft 的AdaLoraConfig），通过 SVD 分解 + 重要性打分动态分配秩预算：

peft_config = GPTQAdaLoraConfig( init_r=20, target_r=16, beta1=0.85, beta2=0.85, tinit=200, tfinal=1000, deltaT=10, lora_alpha=32, lora_dropout=0.1, task_type=TaskType.CAUSAL_LM, inference_mode=False, )

与 LoRA 脚本的差异在于训练循环中额外执行了：

model.base_model.peft_config["default"].total_step = len(train_dataloader) * num_epochs ... model.base_model.update_and_allocate(global_step)

前者告诉 AdaLoRA 总训练步数以推进秩预算调度，后者在每个全局步更新低秩矩阵的重要性并重新分配秩预算。对应的量化层替换类为GPTQSVDLinear。

4.3 AdaptionPrompt（llama-adapter）微调

在peft目录下运行：

CUDA_VISIBLE_DEVICES=0 python peft_adaption_prompt_clm_instruction_tuning.py --model_name_or_path PATH/TO/MODEL/DIR

脚本使用 peft 自带的AdaptionPromptConfig（llama-adapter 风格），默认学习率3e-3，并额外提供两个参数：

peft_config = AdaptionPromptConfig( adapter_len=args.adapter_len, adapter_layers=args.adapter_layers, task_type=TaskType.CAUSAL_LM, inference_mode=False, )

注意该脚本加载量化模型时关闭了 fused attention 注入（inject_fused_attention=False），因为get_gptq_peft_model对 ADAPTION_PROMPT 类型明确不支持 fused attention（源码中会抛NotImplementedError），并且如果adapter_layers超过模型实际层数，会自动重置为model.config.num_hidden_layers。

从 README 的模型支持表看，adaption_prompt完整支持 llama 系模型；bloom、gpt2、opt 等则不适用此适配器类型。若要在非 llama 模型上尝试 AdaptionPrompt，需要安装 peft 源码中的多模态适配分支，且该分支还提供ADAPTION_PROMPT_V2类型（llama-adapter-v2），只需把脚本中的AdaptionPromptConfig换成AdaptionPromptV2Config即可，训练与评估循环无需改动。

4.4 PEFT 与量化结合的注意事项

综合三个脚本与 auto_gptq/utils/peft_utils.py 的源码逻辑，实践中有几点必须注意：

• 加载量化模型必须传trainable=True，否则无法注入可训练适配器；
• fused attention 的一致性：训练适配器时若基础模型注入了 fused attention，推理加载适配器时也必须保持相同的注入状态，否则适配器可能无法正确挂载（get_gptq_peft_model会对此给出告警）；
• fused MLP 与 PEFT 互斥：注入了 fused MLP 的 GPTQ 模型暂不支持与 peft 集成，训练脚本因此统一设置inject_fused_mlp=False；
• 量化权重不可合并：LoRA/AdaLoRA 适配器训练完成后只能以旁路方式叠加使用，merge_adapter系列方法均不可用；
• 训练前需执行model.warmup_triton()预热 Triton 内核，且三个脚本都设置了os.environ["TOKENIZERS_PARALLELISM"] = "false"以避免 tokenizer 并行警告。

总结：一套完整的 AutoGPTQ 量化工作流

将四类脚本串联起来，即可形成一套端到端的量化落地流程：先用quantization/quant_with_alpaca.py以真实指令数据校准并量化模型 → 用evaluation/下的三个脚本在语言建模（PPL）、分类（acc）、摘要（ROUGE）任务上对比量化前后效果 → 用benchmark/generation_speed.py量化推理速度收益 → 若下游任务表现不足，用peft/下的 LoRA/AdaLoRA/AdaptionPrompt 脚本对量化模型做轻量级指令微调。所有脚本均支持--help查看参数，其背后的BaseQuantizeConfig、BaseTask、peft_utils等实现均可直接在 auto_gptq 源码目录中继续深入阅读。

• 模型量化
• 大模型
• 模型优化