FastChat GPTQ 4bit 推理实战：安装、参数解析与源码级加载链路

FastChat 通过集成 GPTQ-for-LLaMa 项目，为 LLaMA 系模型（如 Vicuna）提供了 4bit 权重量化推理能力，可在显存占用降低约 3 倍的情况下保持可接受的困惑度损失。本文基于 FastChat 官方文档 docs/gptq.md 完整展开 GPTQ 4bit 推理的环境安装、CLI 与模型 Worker 两种运行方式的全部命令，并深入 fastchat/modules/gptq.py 与 fastchat/model/model_adapter.py 的源码，讲清 --gptq-wbits、--gptq-groupsize、--gptq-act-order 等参数的默认值、取值范围以及量化模型在单卡/多卡下的实际加载链路。

为什么需要 GPTQ 4bit 量化推理

以 13B 参数、FP16 精度部署的 LLaMA 模型需要约 26GB 显存（见文末基准表），对单卡部署门槛很高。GPTQ 是一种逐层优化的权重量化方法：用少量校准数据逐列求解量化权重，把 16bit 权重压缩到 4bit（甚至 2/3/8bit）存储，推理时在 CUDA 内核中边反量化边计算。FastChat 自身不实现量化算法，而是通过 sys.path 注入外部项目 GPTQ-for-LLaMa 的 llama.load_quant 接口来加载量化权重——这一设计决定了安装步骤必须先完成外部依赖的编译，下面先看官方文档给出的完整安装流程。

环境安装（完整继承官方文档步骤）

GPTQ 量化推理支持依赖外部项目 GPTQ-for-LLaMa，官方文档对两类操作系统给出了分支建议：

1. Windows 用户：使用 old-cuda 分支；
2. Linux 用户：推荐使用 fastest-inference-4bit 分支。

安装量化依赖

在 FastChat 仓库根目录下，将 GPTQ-for-LLaMa 克隆到约定位置 repositories/GPTQ-for-LLaMa（这个目录不是随意指定的，FastChat 源码会硬编码到这里加载模块，见下文源码分析），然后在 FastChat 的虚拟环境中编译安装 quant-cuda 扩展：

# cd /path/to/FastChat
git clone https://github.com/qwopqwop200/GPTQ-for-LLaMa.git repositories/GPTQ-for-LLaMa
cd repositories/GPTQ-for-LLaMa
# Windows 用户应改用 `old-cuda` 分支
git switch fastest-inference-4bit
# 在 FastChat 的虚拟环境中安装 `quant-cuda` 包
python3 setup_cuda.py install
pip3 install texttable

两个容易踩坑的点：

• python3 setup_cuda.py install 必须在激活了 FastChat 虚拟环境的前提下执行，否则编译出的 quant-cuda Python 包 FastChat 进程 import 不到；
• 该步骤会现场编译 CUDA 内核，要求本机 CUDA 工具链与已安装的 PyTorch 版本匹配。

下载量化权重

推理需要预先量化好的 GPTQ 权重。以 TheBloke 发布的 Vicuna-7B 1.1 版 4bit/128 分组量化权重为例（克隆 HuggingFace 仓库前请确认已安装 git-lfs）：

# 确保已安装 git-lfs
git lfs install
git clone https://huggingface.co/TheBloke/vicuna-7B-1.1-GPTQ-4bit-128g models/vicuna-7B-1.1-GPTQ-4bit-128g

命令行参数详解

FastChat 的所有 GPTQ 相关参数定义在 fastchat/model/model_adapter.py 的 add_model_args 中，并被 fastchat/serve/cli.py、fastchat/serve/model_worker.py、fastchat/serve/multi_model_worker.py、fastchat/serve/launch_all_serve.py 等入口共享，参数说明如下：

参数	类型	默认值	取值范围	说明
--gptq-ckpt	str	None（回退为 --model-path）	本地路径/目录	GPTQ 量化 checkpoint 路径。为文件时直接使用；为目录时按 *.pt、*.safetensors 顺序 glob 取最后一个匹配文件
--gptq-wbits	int	16	2, 3, 4, 8, 16	量化位数。只有小于 16 时 GPTQ 加载分支才会被触发（源码中判断条件为 gptq_config.wbits < 16）
--gptq-groupsize	int	-1	正整数或 -1	量化分组大小，-1 表示按整行（full row）量化，即不做分组
--gptq-act-order	flag	False	开/关	是否启用 activation order 重排启发式。源码注释指出只有 fastest-inference-4bit 分支支持该参数，其他分支不会透传

注意 --gptq-wbits 的默认值是 16，这意味着如果忘了加量化参数，FastChat 会按普通 FP16 模型加载并大概率因为权重格式不匹配而报错——这是最常见的排错起点。

参数在入口层被组装成 GptqConfig 数据类（字段为 ckpt、wbits、groupsize、act_order，与命令行默认值一一对应），并以 ckpt=args.gptq_ckpt or args.model_path 的形式兜底：未显式指定 checkpoint 时直接使用模型目录。

用法一：CLI 直接对话

最简使用方式，单进程内完成加载与对话：

python3 -m fastchat.serve.cli \
    --model-path models/vicuna-7B-1.1-GPTQ-4bit-128g \
    --gptq-wbits 4 \
    --gptq-groupsize 128

fastchat/serve/cli.py 中 main 把四个 gptq 参数打包为 GptqConfig 后传入 chat_loop，chat_loop（fastchat/serve/inference.py）再调用统一的 load_model 完成加载，因此 CLI 的对话循环本身对量化模型完全无感知。

用法二：启动 Model Worker（服务端模式）

在多机架构下，量化模型以独立的 model worker 进程注册到 controller：

python3 -m fastchat.serve.model_worker \
    --model-path models/vicuna-7B-1.1-GPTQ-4bit-128g \
    --gptq-wbits 4 \
    --gptq-groupsize 128

当模型目录中存在多个量化 checkpoint（例如不同 groupsize 各量化了一份），可以显式指定 checkpoint 文件，并配合 --gptq-act-order 启用重排：

python3 -m fastchat.serve.model_worker \
    --model-path models/vicuna-7B-1.1-GPTQ-4bit-128g \
    --gptq-ckpt models/vicuna-7B-1.1-GPTQ-4bit-128g/vicuna-7B-1.1-GPTQ-4bit-128g.safetensors \
    --gptq-wbits 4 \
    --gptq-groupsize 128 \
    --gptq-act-order

--gptq-ckpt 也可以指向目录，此时 find_gptq_ckpt 会先按 *.pt、再按 *.safetensors 做 glob，对结果排序后取最后一个匹配文件——目录里混放多份权重时，实际加载哪一份取决于文件名字典序，建议生产环境始终显式传文件路径。

源码解析：量化模型是如何加载的

模块注入：硬编码的外部依赖路径

load_gptq_quantized 的第一步是把 ../repositories/GPTQ-for-LLaMa 插入 sys.path 后 from llama import load_quant：

script_path = os.path.dirname(os.path.dirname(os.path.realpath(__file__)))
module_path = os.path.join(script_path, "../repositories/GPTQ-for-LLaMa")
sys.path.insert(0, module_path)
from llama import load_quant

这解释了安装章节为何要求克隆到固定的 repositories/ 子目录：如果 import 失败，进程会打印错误提示并 sys.exit(-1)。从源码结构看，该依赖是强耦合的本地路径依赖而非 pip 包，FastChat 升级或移动目录后需重新确认该路径。

act_order 的分支差异

源码中有一段针对性处理：只有 fastest-inference-4bit 分支的 load_quant 签名接受 act_order 关键字，因此 gptq.py 按 gptq_config.act_order 的真值分成两条调用路径——为真时透传 act_order=...，为假时按"其他分支"的旧签名调用。这也印证了文档中"Linux 推荐 fastest-inference-4bit 分支"的原因：该分支同时支持 act-order 重排和更快的反量化内核。

加载分支与多卡切分

在 fastchat/model/model_adapter.py 的 load_model 中，GPTQ 分支的触发条件是 gptq_config and gptq_config.wbits < 16，随后：

• 单卡：直接 model.to(device)；
• 多卡（num_gpus != 1）：用 accelerate.infer_auto_device_map 按 --max-gpu-memory（如 '13Gib'）推断切分方案，no_split_module_classes=["LlamaDecoderLayer"] 保证不把一个 decoder layer 拆开，再通过 accelerate.dispatch_model 完成分发。

所以部署 13B 量化模型到两张中端卡时，标准做法是 --num-gpus 2 --gpus 0,1 --max-gpu-memory 13Gib --gptq-wbits 4 --gptq-groupsize 128，显存上限字符串直接来自 add_model_args 的帮助文案。

与 AWQ / ExLlama 的互斥关系

同一 load_model 函数中，AWQ 分支（wbits == 4 时断言）与 GPTQ 分支是互斥的 elif 序列，同一进程只走一条路径；ExLlama、xFasterTransformer 是另一条独立的 4bit 方案线，可参考 docs/exllama_v2.md 与 docs/awq.md。

官方基准：显存、困惑度与速度

官方文档在 LLaMA-13B 上给出如下对比（FP16 基线为 1x）：

模型	分支	Bits	group-size	memory(MiB)	PPL(c4)	Median(s/token)	act-order	speed up
FP16	fastest-inference-4bit	16	-	26634	6.96	0.0383	-	1x
GPTQ	triton	4	128	8590	6.97	0.0551	-	0.69x
GPTQ	fastest-inference-4bit	4	128	8699	6.97	0.0429	true	0.89x
GPTQ	fastest-inference-4bit	4	128	8699	7.03	0.0287	false	1.33x
GPTQ	fastest-inference-4bit	4	-1	8448	7.12	0.0284	false	1.44x

从数据可以读出三个结论：

1. 显存收益明确：4bit 权重把 13B 模型显存从约 26.6GB 压到 8.4～8.7GB，约为 FP16 的 1/3，与 16bit→4bit 的理论压缩比一致；
2. act-order 是精度/速度权衡：开启 act-order 时 PPL 保持 6.97（与 FP16 几乎持平），但中位 token 时延升至 0.0429s；关闭后 PPL 略升到 7.03～7.12，token 时延降到 0.0284～0.0287s，反超 FP16 基线（1.33x～1.44x）。若部署环境对吞吐敏感且可接受轻微精度损失，fastest-inference-4bit 分支 + 关闭 act-order 是该文档给出的最优点；
3. group-size 128 与整行量化（-1）差异很小：整行量化显存略省（8448 vs 8699 MiB）、速度略快，但 PPL 损失稍大（7.12 vs 7.03），可按业务容忍度选择。

排错速查

现象	可能原因	依据
启动即退出并提示 Failed to load GPTQ-for-LLaMa	未按上文克隆到 repositories/GPTQ-for-LLaMa，或分支不对	fastchat/modules/gptq.py 的 ImportError 分支
gptq checkpoint not found	--gptq-ckpt/--model-path 指向的目录里没有 .pt 或 .safetensors 文件	fastchat/modules/gptq.py
加载了但走了 FP16 分支	忘记加 --gptq-wbits 4（默认 16，不满足 wbits < 16 触发条件）	fastchat/model/model_adapter.py
CUDA 相关运行时错误	quant-cuda 内核与当前 PyTorch/CUDA 版本不匹配，或 Windows 上误用了 fastest-inference-4bit 分支	docs/gptq.md 分支建议

小结

FastChat 的 GPTQ 支持是"文档定义流程 + 源码收敛参数"的典型结构：安装阶段需按 docs/gptq.md 固定克隆外部项目并编译 quant-cuda；运行阶段只需在 fastchat.serve.cli / fastchat.serve.model_worker 上追加 --gptq-wbits 4 --gptq-groupsize 128（可选 --gptq-ckpt、--gptq-act-order）；源码层面由 GptqConfig 承载参数、load_gptq_quantized 完成外部模块注入、load_model 统一处理单卡/多卡分发。配合官方基准，开发者可以在"显存优先"（4bit/groupsize 128）与"吞吐优先"（关闭 act-order）之间做出有数据支撑的取舍。