用SGLang服务量化后的AWQ模型时量化配置项缺失导致加载失败的修复

使用 SGLang 加载 AWQ 量化模型时，如果只给定模型目录，SGLang 需要从模型配置里读取量化方式，再决定调用哪个 kernel 和预处理逻辑。很多 AWQ 模型发布时 config.json 里没有完整写入 quantization_config，或者只写了 quant_method 却没有把 weights 对应的量化参数带全，SGLang 就会在构建模型阶段的早期抛错，而不是等到正式跑推理才暴露。常见现象是报错里出现 AWQ、quantization、quant_method 或 qweight 等关键词，但模型权重文件本身并没有损坏。

这是模型元数据和推理框架之间的配置对接问题，不是权重文件损坏。按顺序做三件事：查看模型目录下 config.json 里是否包含 quantization_config；没有则从原始权重仓库或量化生成日志里找回准确的量化参数；最后在 SGLang 启动命令或 API 调用里显式指定 quantization=awq，并确认加载日志里不再出现配置缺失错误。如果无法找回参数，只能重新量化，不能靠猜参数硬加载。

先确认报错属于配置缺失，而不是模型文件不完整

拿到报错后，先看堆栈指向哪个阶段。SGLang 在加载模型时会先读取配置，然后构建模型实例，最后加载权重。如果报错发生在 ModelConfig 构造阶段，说明配置解析失败，与权重文件无关。如果发生在加载权重阶段，才需要检查模型分片是否完整、文件是否下载完全。你可能看到的信息类似 quantization_config missing required key 或 error while loading quantized weight，前者直接指向配置缺失，后者可能由多个原因引起，需要先查 torch 版本和 SGLang 量化 kernel 是否匹配。

最简单的验证方式是单独用 transformers 尝试加载同样的模型目录。如果 transformers 能正常加载并输出模型信息，SGLang 仍报错，说明是 SGLang 侧对量化配置的解析要求更严格。如果 transformers 也报类似错误，那就是模型目录本身缺少关键量化元数据。

检查 config.json 中的 quantization_config 是否完整

进入模型目录，打开 config.json，找到 quantization_config 字段。AWQ 模型通常需要包含以下信息：

"quantization_config": {
  "quant_method": "awq",
  "zero_point": true,
  "group_size": 128,
  "bits": 4,
  "version": "gemm"
}

有些模型仓库会把 quantized_model 或 weight_quant 等字段单独放在顶层，没有套进 quantization_config，SGLang 在读取时找不到就直接丢弃。你要确认的是：SGLang 读取到的 quant_method 是否为 awq，以及模型源本身使用的 AWQ 版本。旧版 AWQ 是 version="gemm"，部分新模型使用 gemv 或 marlin 变体，SGLang 对旧版的兼容性更稳定，对 Marlin 内核需要对应的 CUDA 算力支持。

如果 config.json 里完全没有 quantization_config，不要手动猜测参数值填进去。AWQ 的 group_size、zero_point 和 bit 配置依赖量化时的输入数据分布，填错不会报配置错误，但会直接产出乱码推理结果，更难排查。正确做法是回到这个 AWQ 模型的来源页面，看它对应的原始 FP16 模型仓库和量化脚本，从那里找回真实参数。

在 SGLang 启动命令里显式指定量化方式

SGLang 支持通过 `--quantization` 参数或 API 请求中的 quantization 字段指定量化类型，不依赖模型 config.json 里是否存在该字段。这是一个临时但有效的规避动作，适用于确认模型本身来自正规 AWQ 量化流程、只是元数据不完整的情况。

启动服务时，在命令行末尾加上：

python -m sglang.launch_server \
  `--model-path` /path/to/awq-model \
  `--quantization` awq \
  `--port` 30000

如果使用 OpenAI 兼容接口 startup，就在模型加载配置里写 "quantization": "awq"。加上这个参数后，SGLang 会跳过对 config.json 中 quantization_config 的解析，直接按 AWQ 方式构建推理图。此时如果模型文件本身是真 AWQ 量化，通常能正常启动。

需要注意，这个参数只解决“SGLang 不识别配置”的问题，不能解决“权重本身不是 AWQ”的问题。如果你用 `--quantization` awq 强行加载一个原本为 GPTQ 或全精度模型创建的文件，加载阶段可能不报错，但推理结果完全不可用。因此，显式指定量化方式之前，需要确认模型目录里是否存在 AWQ 量化痕迹，例如权重文件名中包含 awq，或 HuggingFace 仓库页面明确标注 AWQ。

补充完整配置后重新加载并验证

如果你的模型确实缺少 quantization_config，且你已经从原始量化脚本里拿到了准确参数，可以手动补全到 config.json 中，再启动 SGLang。修改配置前先备份原文件，避免改动后无法回退。补全后重启 SGLang 服务，观察启动日志中是否出现类似 Loading AWQ quantized model、Using AWQ kernel 的提示。此时再用一个小的测试提示词请求一次推理，检查输出是否为有意义的英文或中文句子。AWQ 配置错误最常见的表现是输出乱码、大量重复 token 或只返回同一个字符，这种问题不会出现在启动阶段，只能通过推理结果判断，所以每次修改配置后都要做一次真实推理验证。

如果补全配置后 SGLang 仍报错，查看 CUDA 依赖和 torch 版本是否与 SGLang 当前版本匹配。AWQ 推理依赖的 kernel 对 CUDA 算力有最低要求，较老的 GPU 可能无法运行 Marlin 内核，此时需要回退到 gemm 内核版本。这个步骤与配置缺失无关，但经常和上述问题同时出现，容易混淆排查方向。

确认是否需要回归到原始权重重做量化

以上所有操作都假设模型确实是按 AWQ 方法量化生成的。如果模型来源不明，或者量化方式被重新封装过，无法找到原始量化参数，那么任何配置修补都是在猜测。SGLang 不会验证权重是否正确，只会按你给的配置执行计算。一旦 group_size、zero_point 或版本搭配错误，服务可以启动，但交付的推理结果不可信。面对这种场景，最直接的方法是放弃这个 AWQ 模型目录，改用原始 FP16 模型重新跑一次 AWQ 量化。

重新量化需要做两件事：确认原始模型结构完整；确认量化工具与 SGLang 支持的 AWQ 版本兼容。定量化时的 group_size 建议保持模型发布者常用的 128，bit 数用 4，zero_point 按工具默认开启即可。量化完成后生成的 config.json 会自动带上 quantization_config，不会再有缺失问题。

还有一个更轻量的替代方案：如果原模型是 GPTQ 格式，可以先把 SGLang 加载方式切到 GPTQ 对应的环境，不需要强行使用 AWQ。AWQ 和 GPTQ 虽然都是 4-bit 量化，但权重排布和反量化逻辑完全不同，不要混用。