1. AWQ 权重加载报错与精度偏差vLLM 本地推理部署的完整避坑路径AWQ 是 Activation-aware Weight Quantization 的缩写它把模型权重压到 4bit同时用激活值分布去校准量化误差让显存占用降到 FP16 的三成左右而精度损失通常控制在 1 个百分点内。vLLM 是当前本地推理吞吐表现最稳的引擎之一它原生支持 AWQ 的 GEMM 与 GEMV 两种 kernel。把这两者拼在一起就是很多人在单卡 24G 甚至 16G 显存上跑 7B、14B 模型的常规方案。但真正动手时问题往往不在“能不能跑”而在“跑起来之后对不对”。我见过太多人卡在两类场景第一类是权重加载阶段直接抛错比如ValueError: Unknown quantization method或者KeyError: qweight服务根本起不来第二类是服务起来了输出却明显发飘同一句 prompt 在 FP16 下答得规规矩矩AWQ 下却开始重复、漏字、甚至答非所问。前者是配置问题后者是精度对齐问题两者排查思路完全不同。这篇内容面向的是已经在本地或内网做推理部署的开发者假设你手里有一张 L40、A10 或者 4090已经装好 CUDA 12.x 和 vLLM 0.9.x想搞清楚 AWQ 权重从加载到输出到底该怎么验证。我会把启动参数、量化配置片段、逐层精度对比脚本都拆开讲重点放在“怎么确认它真的对”而不是“怎么把它跑起来”。如果你还没拿到可用的 API Key后面也会给出接入方式但技术主体会放在部署与验证上。先明确一个判断标准AWQ 在 vLLM 里的“成功”不是服务返回 200而是同一批 prompt 下量化模型的输出分布与 FP16 基线的 KL 散度足够小且 benchmark 的吞吐数字与精度指标同时可接受。接下来按这个标准一步步走。2. TaoToken 前置准备API Key 获取与 vLLM 环境对齐在开始折腾 AWQ 之前先把两件事分清楚一是本地 vLLM 服务本身的运行环境二是你用来做对照验证的在线推理通道。前者决定你能不能加载权重后者决定你有没有一个稳定的 FP16 基线来对比精度。很多人只盯着本地结果量化模型输出异常时没有参照物根本判断不了是量化本身的问题还是 prompt 的问题。本地环境这块vLLM 0.9.0 对 CUDA 和驱动有明确要求。驱动 550.54.15 配 CUDA 12.3 是经过验证的组合如果你用的是更新的驱动注意 vLLM 编译时的 CUDA 版本要和运行时一致否则会出现CUDA error: no kernel image is available for execution on the device。这个报错和 AWQ 无关但经常被误认为是量化 kernel 的问题。装 vLLM 时建议用官方 wheel不要自己从源码编译除非你明确需要改 kernel。在线通道这块如果你需要一个稳定的 FP16 基线来做输出对齐可以用 TaoToken 的模型对话能力。它的 API 地址是https://taotoken.net/api兼容 OpenAI 的/v1/chat/completions格式你可以在验证脚本里直接把它当成一个远端 FP16 参照。获取 Key 的入口在控制台的 API Keys 页面地址是https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content。拿到 Key 之后先别急着写代码用 curl 确认一下通道是通的curl https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -d { model: gpt-4o-mini, messages: [{role: user, content: 用一句话解释什么是量化}], temperature: 0 }返回里能看到choices[0].message.content就说明通道正常。注意temperature设成 0后面做精度对比时要保证两边都是确定性输出否则你分不清差异是量化带来的还是采样随机性带来的。环境对齐还有一步容易被忽略tokenizer 的一致性。AWQ 量化时用的 tokenizer 必须和推理时加载的 tokenizer 完全一致包括chat_template。如果你量化时用的是trust_remote_codeFalse推理时也保持False否则 Qwen 系列可能会因为 template 差异导致输出格式不同看起来像精度问题其实是模板问题。我试过在 Qwen2.5-7B 上因为 template 不一致导致 AWQ 模型把该输出的 JSON 变成了纯文本排查了半天才发现是 tokenizer 配置没对齐。最后确认一下显存预算。7B 模型 FP16 大约占 14G 权重加上 KV cache 和激活24G 卡跑长上下文会紧张。AWQ 4bit 权重约 4G同样的卡可以留出更多空间给 KV cache这也是量化的主要收益。但注意gpu_memory_utilization不要设太高0.85 到 0.9 之间比较稳设到 0.95 容易在长请求时 OOM。3. 可复制配置vLLM 启动参数与 AWQ 量化片段这一节给的是可以直接复制粘贴的配置。先看量化阶段如果你还没有 AWQ 权重用 AutoAWQ 生成一份。注意q_group_size和w_bit这两个参数决定了 kernel 的选择version选GEMM还是GEMV会影响推理时的计算路径。from awq import AutoAWQForCausalLM from transformers import AutoTokenizer model_path ./Qwen2.5-7B quant_path ./Qwen2.5-7B-awq-int4 quant_config { zero_point: True, q_group_size: 128, w_bit: 4, version: GEMM } model AutoAWQForCausalLM.from_pretrained( model_path, trust_remote_codeFalse, device_mapauto ) tokenizer AutoTokenizer.from_pretrained( model_path, trust_remote_codeFalse ) model.quantize(tokenizer, quant_configquant_config) model.save_quantized(quant_path) tokenizer.save_pretrained(quant_path) print(fModel is quantized and saved at {quant_path})量化完成后检查输出目录里是否有quant_config.json内容应该和上面quant_config一致。这个文件是 vLLM 识别量化方式的依据如果缺失或者字段不对加载时会报Unknown quantization method。接下来是 vLLM 启动。这里给一份完整的启动命令包含 AWQ 相关的关键参数vllm serve ./Qwen2.5-7B-awq-int4 \ --quantization awq \ --dtype half \ --max-model-len 8192 \ --gpu-memory-utilization 0.88 \ --disable-log-requests \ --port 8000 \ --served-model-name qwen-awq几个参数的解释--quantization awq是必须的不写的话 vLLM 会尝试从quant_config.json自动推断但显式指定更稳--dtype half要和量化时的计算精度一致AWQ 的 GEMM kernel 在 FP16 下表现最好用bfloat16也能跑但部分 kernel 会回退--max-model-len根据你的实际需求设设太大 KV cache 会吃掉大量显存--gpu-memory-utilization控制 vLLM 预分配的显存比例0.88 是个保守值。如果你用配置文件管理可以写一个vllm_config.yamlmodel: ./Qwen2.5-7B-awq-int4 quantization: awq dtype: half max_model_len: 8192 gpu_memory_utilization: 0.88 disable_log_requests: true port: 8000 served_model_name: qwen-awq然后vllm serve --config vllm_config.yaml启动。注意 YAML 里的 key 是下划线风格和命令行参数的连字符风格对应vLLM 会自动转换。还有一个容易踩的坑如果你用的是 Cline 或者 Claude Code 这类工具去连本地 vLLM需要填全三件套——Base URL、API Key、Model ID。Base URL 填http://localhost:8000/v1API Key 随便填一个非空字符串vLLM 默认不校验Model ID 填qwen-awq也就是--served-model-name的值。这三者缺一不可Model ID 填错会报The model does not exist。对于需要长期跑编码任务或 Agent 的场景本地 vLLM 适合做批量推理和精度验证但如果要稳定的长会话编码辅助可以考虑 Coding Plan 通道地址是https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content。它的定位是给编码类工具提供稳定的模型接入和本地 vLLM 不冲突可以一个做实验一个做日常。4. 验证请求与精度对齐从 benchmark 到逐层对比服务起来之后先做一次最简单的请求验证curl http://localhost:8000/v1/completions \ -H Content-Type: application/json \ -d { model: qwen-awq, prompt: 中国的首都是, max_tokens: 16, temperature: 0 }如果返回正常说明加载和推理链路是通的。但通不代表对接下来要做吞吐和精度的双重验证。吞吐验证用 vLLM 自带的benchmark_serving.pypython /vllm/benchmarks/benchmark_serving.py \ --backend vllm \ --model qwen-awq \ --endpoint /v1/completions \ --dataset-name sharegpt \ --dataset-path ./ShareGPT_V3_unfiltered_cleaned_split.json \ --num-prompts 1000跑完之后关注几个指标Request throughput反映并发能力Output token throughput反映生成速度Mean TTFT反映首 token 延迟。在 L40 上7B AWQ 的 output throughput 通常在 4000 tok/s 以上TTFT 在 10 秒左右取决于并发数。如果 throughput 明显偏低检查是不是--quantization awq没生效vLLM 回退到了 FP16 路径。精度验证分两层。第一层用lm_eval跑标准任务lm_eval --model vllm \ --model_args pretrained./Qwen2.5-7B-awq-int4,add_bos_tokentrue,gpu_memory_utilization0.5,quantizationAWQ,dtypehalf \ --tasks gsm8k \ --num_fewshot 5 \ --limit 250gsm8k 的exact_match在 0.83 左右属于正常范围如果掉到 0.7 以下说明量化配置可能有问题重点检查q_group_size是否和量化时一致。mmlu 的acc在 0.75 左右是 7B 模型的合理水平各子类里stem通常最低social sciences最高这个分布特征可以作为判断依据。第二层是逐层精度对比这一步才是真正定位问题的关键。思路是加载 FP16 模型和 AWQ 模型对同一批输入逐层比较 hidden states 的余弦相似度。如果某一层相似度骤降说明该层的量化误差过大。import torch from transformers import AutoModelForCausalLM, AutoTokenizer def get_hidden_states(model_path, prompts, layer_indices): tokenizer AutoTokenizer.from_pretrained(model_path, trust_remote_codeFalse) model AutoModelForCausalLM.from_pretrained( model_path, torch_dtypetorch.float16, device_mapauto, trust_remote_codeFalse ) model.eval() results {} with torch.no_grad(): for prompt in prompts: inputs tokenizer(prompt, return_tensorspt).to(model.device) outputs model(**inputs, output_hidden_statesTrue) for idx in layer_indices: hs outputs.hidden_states[idx][:, -1, :].float() results.setdefault(idx, []).append(hs.cpu()) return results prompts [ 解释一下注意力机制, 写一个快速排序, 什么是梯度下降 ] layer_indices [0, 8, 16, 24, 28] fp16_hs get_hidden_states(./Qwen2.5-7B, prompts, layer_indices) awq_hs get_hidden_states(./Qwen2.5-7B-awq-int4, prompts, layer_indices) for idx in layer_indices: sims [] for a, b in zip(fp16_hs[idx], awq_hs[idx]): cos torch.nn.functional.cosine_similarity(a, b, dim-1).item() sims.append(cos) print(fLayer {idx}: mean cosine similarity {sum(sims)/len(sims):.4f})正常情况下浅层0-8 层相似度应该在 0.99 以上中层16-24 层在 0.97 以上最后一层可能在 0.95 左右。如果某一层低于 0.9说明该层的量化误差偏大可以考虑对该层做混合精度处理或者调整q_group_size重新量化。输出对齐则是最后一步用同一批 prompt 分别请求本地 AWQ 服务和远端 FP16 基线比较生成文本的差异。这里可以用 TaoToken 的模型对话作为基线地址是https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content。对比时固定temperature0和max_tokens逐条看差异。如果差异集中在长尾 token 或者标点属于正常量化噪声如果出现语义级偏差比如数字算错、逻辑反转就要回到逐层对比去定位。5. 常见报错排查401、local proxy failed、reading choices、OAuth这一节按真实报错来组织每个报错给出触发条件和排查路径。401 Unauthorized这个报错在本地 vLLM 上通常不会出现因为 vLLM 默认不校验 API Key。如果你在客户端看到了 401大概率是客户端把请求发到了远端通道而 Key 没填对。检查客户端的 Base URL 是不是http://localhost:8000/v1以及 Authorization header 是否带了正确的 Key。如果你用的是 TaoToken 通道确认 Key 是从 API Keys 页面获取的并且没有多余空格。local proxy failed这个报错通常出现在客户端配置了代理但代理不可达的情况下。排查时先确认客户端是否设置了HTTP_PROXY或HTTPS_PROXY环境变量如果有临时 unset 掉再试。另外检查 Base URL 里的端口是否和 vLLM 启动端口一致localhost和127.0.0.1在某些环境下行为不同建议统一用127.0.0.1。Error reading choices这个报错说明请求发出去了但返回的 JSON 结构不符合客户端预期。常见原因是 vLLM 返回的是/v1/completions格式而客户端期望/v1/chat/completions格式。检查客户端的 endpoint 配置如果是聊天类工具确保请求的是 chat 接口。另外如果--served-model-name和客户端填的 Model ID 不一致vLLM 会返回错误信息而不是 choices也会触发这个报错。OAuth 相关报错如果你用的是 Claude Code 或类似工具可能会遇到 OAuth token 过期或无效的提示。这类工具通常有自己的认证流程和 vLLM 的 API Key 是两套机制。排查时先确认工具的认证配置是否指向了正确的通道。如果是接入本地 vLLM通常不需要 OAuth直接用 API Key 模式即可。如果工具强制要求 OAuth检查它的配置文件里 Base URL 是否被覆盖成了远端地址。Unknown quantization method这个报错在加载 AWQ 权重时出现说明 vLLM 没有识别出量化方式。检查模型目录下是否有quant_config.json以及quantization字段的值是否为awq。如果文件存在但报错依旧可能是 vLLM 版本不支持该量化格式升级到 0.9.0 以上再试。KeyError: qweight这个报错说明权重文件的结构和 vLLM 期望的不一致。常见原因是量化时用的 AutoAWQ 版本和 vLLM 内置的 AWQ 加载器版本不匹配。解决方法是统一版本或者用 vLLM 官方推荐的量化脚本重新生成权重。CUDA out of memoryAWQ 本身是为了省显存但如果gpu_memory_utilization设得太高或者max_model_len设得太大依然会 OOM。先把gpu_memory_utilization降到 0.8max_model_len降到 4096确认能跑起来之后再逐步往上调。另外注意如果同时跑了多个 vLLM 实例显存会叠加检查是否有残留进程。排查时的一个通用原则先确认是加载问题还是推理问题。加载问题的报错通常发生在服务启动阶段推理问题的报错发生在请求阶段。前者看 vLLM 启动日志后者看客户端返回。把这两类分开排查效率会高很多。6. 语义一致 CTA从验证到长期编码的通道选择AWQ 在 vLLM 里的部署核心不是“跑起来”而是“跑对”。从权重加载到精度对齐每一步都有可验证的动作quant_config.json确认量化配置benchmark_serving.py确认吞吐lm_eval确认标准任务精度逐层余弦相似度确认量化误差分布输出对齐确认语义一致性。这套流程走下来你对模型的实际表现会有清晰的判断而不是靠感觉。如果你在验证过程中需要一个稳定的 FP16 基线来做对照TaoToken 的模型对话通道可以直接用API 地址是https://taotoken.net/api接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content。文档里有完整的请求示例和参数说明照着改一下就能跑通。对于需要长期做编码任务或 Agent 开发的场景本地 vLLM 适合做实验和批量推理但日常的编码辅助可以考虑 Coding Plan地址是https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content。它的定位是给编码类工具提供稳定的模型接入和本地部署形成互补。最后给一个实用建议每次重新量化或者升级 vLLM 版本之后把逐层对比脚本再跑一遍。量化误差会随着 kernel 实现的变化而波动上一次相似度 0.98 的层下一次可能掉到 0.95。把这个脚本存成check_awq_alignment.py当成回归测试的一部分比事后排查省事得多。 vllm量化02—AWQ 部署避坑：从权重加载到推理精度对齐的完整验证
1. AWQ 权重加载报错与精度偏差vLLM 本地推理部署的完整避坑路径AWQ 是 Activation-aware Weight Quantization 的缩写它把模型权重压到 4bit同时用激活值分布去校准量化误差让显存占用降到 FP16 的三成左右而精度损失通常控制在 1 个百分点内。vLLM 是当前本地推理吞吐表现最稳的引擎之一它原生支持 AWQ 的 GEMM 与 GEMV 两种 kernel。把这两者拼在一起就是很多人在单卡 24G 甚至 16G 显存上跑 7B、14B 模型的常规方案。但真正动手时问题往往不在“能不能跑”而在“跑起来之后对不对”。我见过太多人卡在两类场景第一类是权重加载阶段直接抛错比如ValueError: Unknown quantization method或者KeyError: qweight服务根本起不来第二类是服务起来了输出却明显发飘同一句 prompt 在 FP16 下答得规规矩矩AWQ 下却开始重复、漏字、甚至答非所问。前者是配置问题后者是精度对齐问题两者排查思路完全不同。这篇内容面向的是已经在本地或内网做推理部署的开发者假设你手里有一张 L40、A10 或者 4090已经装好 CUDA 12.x 和 vLLM 0.9.x想搞清楚 AWQ 权重从加载到输出到底该怎么验证。我会把启动参数、量化配置片段、逐层精度对比脚本都拆开讲重点放在“怎么确认它真的对”而不是“怎么把它跑起来”。如果你还没拿到可用的 API Key后面也会给出接入方式但技术主体会放在部署与验证上。先明确一个判断标准AWQ 在 vLLM 里的“成功”不是服务返回 200而是同一批 prompt 下量化模型的输出分布与 FP16 基线的 KL 散度足够小且 benchmark 的吞吐数字与精度指标同时可接受。接下来按这个标准一步步走。2. TaoToken 前置准备API Key 获取与 vLLM 环境对齐在开始折腾 AWQ 之前先把两件事分清楚一是本地 vLLM 服务本身的运行环境二是你用来做对照验证的在线推理通道。前者决定你能不能加载权重后者决定你有没有一个稳定的 FP16 基线来对比精度。很多人只盯着本地结果量化模型输出异常时没有参照物根本判断不了是量化本身的问题还是 prompt 的问题。本地环境这块vLLM 0.9.0 对 CUDA 和驱动有明确要求。驱动 550.54.15 配 CUDA 12.3 是经过验证的组合如果你用的是更新的驱动注意 vLLM 编译时的 CUDA 版本要和运行时一致否则会出现CUDA error: no kernel image is available for execution on the device。这个报错和 AWQ 无关但经常被误认为是量化 kernel 的问题。装 vLLM 时建议用官方 wheel不要自己从源码编译除非你明确需要改 kernel。在线通道这块如果你需要一个稳定的 FP16 基线来做输出对齐可以用 TaoToken 的模型对话能力。它的 API 地址是https://taotoken.net/api兼容 OpenAI 的/v1/chat/completions格式你可以在验证脚本里直接把它当成一个远端 FP16 参照。获取 Key 的入口在控制台的 API Keys 页面地址是https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content。拿到 Key 之后先别急着写代码用 curl 确认一下通道是通的curl https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -d { model: gpt-4o-mini, messages: [{role: user, content: 用一句话解释什么是量化}], temperature: 0 }返回里能看到choices[0].message.content就说明通道正常。注意temperature设成 0后面做精度对比时要保证两边都是确定性输出否则你分不清差异是量化带来的还是采样随机性带来的。环境对齐还有一步容易被忽略tokenizer 的一致性。AWQ 量化时用的 tokenizer 必须和推理时加载的 tokenizer 完全一致包括chat_template。如果你量化时用的是trust_remote_codeFalse推理时也保持False否则 Qwen 系列可能会因为 template 差异导致输出格式不同看起来像精度问题其实是模板问题。我试过在 Qwen2.5-7B 上因为 template 不一致导致 AWQ 模型把该输出的 JSON 变成了纯文本排查了半天才发现是 tokenizer 配置没对齐。最后确认一下显存预算。7B 模型 FP16 大约占 14G 权重加上 KV cache 和激活24G 卡跑长上下文会紧张。AWQ 4bit 权重约 4G同样的卡可以留出更多空间给 KV cache这也是量化的主要收益。但注意gpu_memory_utilization不要设太高0.85 到 0.9 之间比较稳设到 0.95 容易在长请求时 OOM。3. 可复制配置vLLM 启动参数与 AWQ 量化片段这一节给的是可以直接复制粘贴的配置。先看量化阶段如果你还没有 AWQ 权重用 AutoAWQ 生成一份。注意q_group_size和w_bit这两个参数决定了 kernel 的选择version选GEMM还是GEMV会影响推理时的计算路径。from awq import AutoAWQForCausalLM from transformers import AutoTokenizer model_path ./Qwen2.5-7B quant_path ./Qwen2.5-7B-awq-int4 quant_config { zero_point: True, q_group_size: 128, w_bit: 4, version: GEMM } model AutoAWQForCausalLM.from_pretrained( model_path, trust_remote_codeFalse, device_mapauto ) tokenizer AutoTokenizer.from_pretrained( model_path, trust_remote_codeFalse ) model.quantize(tokenizer, quant_configquant_config) model.save_quantized(quant_path) tokenizer.save_pretrained(quant_path) print(fModel is quantized and saved at {quant_path})量化完成后检查输出目录里是否有quant_config.json内容应该和上面quant_config一致。这个文件是 vLLM 识别量化方式的依据如果缺失或者字段不对加载时会报Unknown quantization method。接下来是 vLLM 启动。这里给一份完整的启动命令包含 AWQ 相关的关键参数vllm serve ./Qwen2.5-7B-awq-int4 \ --quantization awq \ --dtype half \ --max-model-len 8192 \ --gpu-memory-utilization 0.88 \ --disable-log-requests \ --port 8000 \ --served-model-name qwen-awq几个参数的解释--quantization awq是必须的不写的话 vLLM 会尝试从quant_config.json自动推断但显式指定更稳--dtype half要和量化时的计算精度一致AWQ 的 GEMM kernel 在 FP16 下表现最好用bfloat16也能跑但部分 kernel 会回退--max-model-len根据你的实际需求设设太大 KV cache 会吃掉大量显存--gpu-memory-utilization控制 vLLM 预分配的显存比例0.88 是个保守值。如果你用配置文件管理可以写一个vllm_config.yamlmodel: ./Qwen2.5-7B-awq-int4 quantization: awq dtype: half max_model_len: 8192 gpu_memory_utilization: 0.88 disable_log_requests: true port: 8000 served_model_name: qwen-awq然后vllm serve --config vllm_config.yaml启动。注意 YAML 里的 key 是下划线风格和命令行参数的连字符风格对应vLLM 会自动转换。还有一个容易踩的坑如果你用的是 Cline 或者 Claude Code 这类工具去连本地 vLLM需要填全三件套——Base URL、API Key、Model ID。Base URL 填http://localhost:8000/v1API Key 随便填一个非空字符串vLLM 默认不校验Model ID 填qwen-awq也就是--served-model-name的值。这三者缺一不可Model ID 填错会报The model does not exist。对于需要长期跑编码任务或 Agent 的场景本地 vLLM 适合做批量推理和精度验证但如果要稳定的长会话编码辅助可以考虑 Coding Plan 通道地址是https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content。它的定位是给编码类工具提供稳定的模型接入和本地 vLLM 不冲突可以一个做实验一个做日常。4. 验证请求与精度对齐从 benchmark 到逐层对比服务起来之后先做一次最简单的请求验证curl http://localhost:8000/v1/completions \ -H Content-Type: application/json \ -d { model: qwen-awq, prompt: 中国的首都是, max_tokens: 16, temperature: 0 }如果返回正常说明加载和推理链路是通的。但通不代表对接下来要做吞吐和精度的双重验证。吞吐验证用 vLLM 自带的benchmark_serving.pypython /vllm/benchmarks/benchmark_serving.py \ --backend vllm \ --model qwen-awq \ --endpoint /v1/completions \ --dataset-name sharegpt \ --dataset-path ./ShareGPT_V3_unfiltered_cleaned_split.json \ --num-prompts 1000跑完之后关注几个指标Request throughput反映并发能力Output token throughput反映生成速度Mean TTFT反映首 token 延迟。在 L40 上7B AWQ 的 output throughput 通常在 4000 tok/s 以上TTFT 在 10 秒左右取决于并发数。如果 throughput 明显偏低检查是不是--quantization awq没生效vLLM 回退到了 FP16 路径。精度验证分两层。第一层用lm_eval跑标准任务lm_eval --model vllm \ --model_args pretrained./Qwen2.5-7B-awq-int4,add_bos_tokentrue,gpu_memory_utilization0.5,quantizationAWQ,dtypehalf \ --tasks gsm8k \ --num_fewshot 5 \ --limit 250gsm8k 的exact_match在 0.83 左右属于正常范围如果掉到 0.7 以下说明量化配置可能有问题重点检查q_group_size是否和量化时一致。mmlu 的acc在 0.75 左右是 7B 模型的合理水平各子类里stem通常最低social sciences最高这个分布特征可以作为判断依据。第二层是逐层精度对比这一步才是真正定位问题的关键。思路是加载 FP16 模型和 AWQ 模型对同一批输入逐层比较 hidden states 的余弦相似度。如果某一层相似度骤降说明该层的量化误差过大。import torch from transformers import AutoModelForCausalLM, AutoTokenizer def get_hidden_states(model_path, prompts, layer_indices): tokenizer AutoTokenizer.from_pretrained(model_path, trust_remote_codeFalse) model AutoModelForCausalLM.from_pretrained( model_path, torch_dtypetorch.float16, device_mapauto, trust_remote_codeFalse ) model.eval() results {} with torch.no_grad(): for prompt in prompts: inputs tokenizer(prompt, return_tensorspt).to(model.device) outputs model(**inputs, output_hidden_statesTrue) for idx in layer_indices: hs outputs.hidden_states[idx][:, -1, :].float() results.setdefault(idx, []).append(hs.cpu()) return results prompts [ 解释一下注意力机制, 写一个快速排序, 什么是梯度下降 ] layer_indices [0, 8, 16, 24, 28] fp16_hs get_hidden_states(./Qwen2.5-7B, prompts, layer_indices) awq_hs get_hidden_states(./Qwen2.5-7B-awq-int4, prompts, layer_indices) for idx in layer_indices: sims [] for a, b in zip(fp16_hs[idx], awq_hs[idx]): cos torch.nn.functional.cosine_similarity(a, b, dim-1).item() sims.append(cos) print(fLayer {idx}: mean cosine similarity {sum(sims)/len(sims):.4f})正常情况下浅层0-8 层相似度应该在 0.99 以上中层16-24 层在 0.97 以上最后一层可能在 0.95 左右。如果某一层低于 0.9说明该层的量化误差偏大可以考虑对该层做混合精度处理或者调整q_group_size重新量化。输出对齐则是最后一步用同一批 prompt 分别请求本地 AWQ 服务和远端 FP16 基线比较生成文本的差异。这里可以用 TaoToken 的模型对话作为基线地址是https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content。对比时固定temperature0和max_tokens逐条看差异。如果差异集中在长尾 token 或者标点属于正常量化噪声如果出现语义级偏差比如数字算错、逻辑反转就要回到逐层对比去定位。5. 常见报错排查401、local proxy failed、reading choices、OAuth这一节按真实报错来组织每个报错给出触发条件和排查路径。401 Unauthorized这个报错在本地 vLLM 上通常不会出现因为 vLLM 默认不校验 API Key。如果你在客户端看到了 401大概率是客户端把请求发到了远端通道而 Key 没填对。检查客户端的 Base URL 是不是http://localhost:8000/v1以及 Authorization header 是否带了正确的 Key。如果你用的是 TaoToken 通道确认 Key 是从 API Keys 页面获取的并且没有多余空格。local proxy failed这个报错通常出现在客户端配置了代理但代理不可达的情况下。排查时先确认客户端是否设置了HTTP_PROXY或HTTPS_PROXY环境变量如果有临时 unset 掉再试。另外检查 Base URL 里的端口是否和 vLLM 启动端口一致localhost和127.0.0.1在某些环境下行为不同建议统一用127.0.0.1。Error reading choices这个报错说明请求发出去了但返回的 JSON 结构不符合客户端预期。常见原因是 vLLM 返回的是/v1/completions格式而客户端期望/v1/chat/completions格式。检查客户端的 endpoint 配置如果是聊天类工具确保请求的是 chat 接口。另外如果--served-model-name和客户端填的 Model ID 不一致vLLM 会返回错误信息而不是 choices也会触发这个报错。OAuth 相关报错如果你用的是 Claude Code 或类似工具可能会遇到 OAuth token 过期或无效的提示。这类工具通常有自己的认证流程和 vLLM 的 API Key 是两套机制。排查时先确认工具的认证配置是否指向了正确的通道。如果是接入本地 vLLM通常不需要 OAuth直接用 API Key 模式即可。如果工具强制要求 OAuth检查它的配置文件里 Base URL 是否被覆盖成了远端地址。Unknown quantization method这个报错在加载 AWQ 权重时出现说明 vLLM 没有识别出量化方式。检查模型目录下是否有quant_config.json以及quantization字段的值是否为awq。如果文件存在但报错依旧可能是 vLLM 版本不支持该量化格式升级到 0.9.0 以上再试。KeyError: qweight这个报错说明权重文件的结构和 vLLM 期望的不一致。常见原因是量化时用的 AutoAWQ 版本和 vLLM 内置的 AWQ 加载器版本不匹配。解决方法是统一版本或者用 vLLM 官方推荐的量化脚本重新生成权重。CUDA out of memoryAWQ 本身是为了省显存但如果gpu_memory_utilization设得太高或者max_model_len设得太大依然会 OOM。先把gpu_memory_utilization降到 0.8max_model_len降到 4096确认能跑起来之后再逐步往上调。另外注意如果同时跑了多个 vLLM 实例显存会叠加检查是否有残留进程。排查时的一个通用原则先确认是加载问题还是推理问题。加载问题的报错通常发生在服务启动阶段推理问题的报错发生在请求阶段。前者看 vLLM 启动日志后者看客户端返回。把这两类分开排查效率会高很多。6. 语义一致 CTA从验证到长期编码的通道选择AWQ 在 vLLM 里的部署核心不是“跑起来”而是“跑对”。从权重加载到精度对齐每一步都有可验证的动作quant_config.json确认量化配置benchmark_serving.py确认吞吐lm_eval确认标准任务精度逐层余弦相似度确认量化误差分布输出对齐确认语义一致性。这套流程走下来你对模型的实际表现会有清晰的判断而不是靠感觉。如果你在验证过程中需要一个稳定的 FP16 基线来做对照TaoToken 的模型对话通道可以直接用API 地址是https://taotoken.net/api接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content。文档里有完整的请求示例和参数说明照着改一下就能跑通。对于需要长期做编码任务或 Agent 开发的场景本地 vLLM 适合做实验和批量推理但日常的编码辅助可以考虑 Coding Plan地址是https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content。它的定位是给编码类工具提供稳定的模型接入和本地部署形成互补。最后给一个实用建议每次重新量化或者升级 vLLM 版本之后把逐层对比脚本再跑一遍。量化误差会随着 kernel 实现的变化而波动上一次相似度 0.98 的层下一次可能掉到 0.95。把这个脚本存成check_awq_alignment.py当成回归测试的一部分比事后排查省事得多。