config.json、recipe.yaml、processor_config.json都在干嘛?gemma-4-26B-A4B-it-w4a16-llmcompressor仓库文件逐个拆解
config.json、recipe.yaml、processor_config.json都在干嘛?gemma-4-26B-A4B-it-w4a16-llmcompressor仓库文件逐个拆解
第一次打开 gemma-4-26B-A4B-it-w4a16-llmcompressor 这个模型仓库时,满屏的 JSON 和 YAML 难免让人懵:config.json、recipe.yaml、processor_config.json 到底各管什么?这篇文章带你逐个拆解这个 AMD 出品的 4-bit 量化(W4A16)Gemma 4 MoE 模型 仓库,搞懂每个文件的职责、它们之间如何协作,以及新手最容易踩的几个坑。
📦 仓库文件总览:一张表看懂全家福
这个仓库本质上是一个量化后的多模态大模型检查点(Checkpoint):源模型是 RedHatAI/gemma-4-26B-A4B-it(26B 参数、每 token 激活约 4B 的 MoE 架构),AMD 用 LLM Compressor 的 GPTQ 算法做了 4-bit 权重量化,把磁盘占用从 48.1 GiB 压到约 14.6 GiB(缩小约 70%),专门面向 AMD EPYC CPU + ZenDNN 推理场景。
全部文件一览:
| 文件 | 一句话职责 | 谁在读它 |
|---|---|---|
| config.json | 模型"身份证":架构、词表、量化配置 | transformers / vLLM |
| recipe.yaml | 量化"配方":当初是怎么压缩的 | LLM Compressor |
| processor_config.json | 图像/音频/视频预处理参数 | AutoProcessor |
| tokenizer.json | 词表本体(约 26 万 token) | GemmaTokenizer |
| tokenizer_config.json | 特殊 token、工具调用解析规则 | 分词器 |
| chat_template.jinja | 对话轮次、思考、工具调用格式模板 | 推理框架 |
| model.safetensors | 量化后的模型权重本体 | 推理引擎 |
| generation_config.json | 默认采样参数(top_p 等) | 生成接口 |
| review_status.json | 模型发布审核状态 | 发布流程 |
| README.md | 使用文档与快速上手 | 人 |
| LICENSE | Gemma 许可协议 | 法律层面 |
下面按"核心三件套 → 词表三件套 → 其余文件"的顺序拆解。
🪪 config.json:模型的"身份证",还藏着量化配置
config.json 是 Hugging Face 生态的标准入口文件——transformers 和 vLLM 加载模型时,第一个读的就是它。你可以把它理解为模型的"身份证 + 体检报告"。
1. 架构信息:告诉框架"我是谁"
关键字段:
"architectures": ["Gemma4ForConditionalGeneration"]、"model_type": "gemma4":声明这是一个 Gemma 4 多模态条件生成模型;- 顶层同时包含
text_config和vision_config两段:文本塔 30 层、每层 128 个专家(experts)、每次只激活 8 个(top_k_experts: 8),hidden_size2816、词表 262144、支持 262144 的长上下文,且大量使用滑窗注意力(sliding_window: 1024); "dtype": "bfloat16":激活仍用 BF16 计算(这正是 W4A16 中"A16"的含义——权重 4-bit、激活 16-bit)。
2. quantization_config:整个文件最核心的部分
这段(位于 config.json)声明了"这个模型是被量化过的,请按以下规则解码权重":
"quant_method": "compressed-tensors",
"format": "pack-quantized",
"num_bits": 4, "type": "int", "symmetric": true,
"group_size": 64, "strategy": "group"
用人话说就是:
- 4-bit INT 对称分组量化:每 64 个权重共享一组缩放因子,权重以"打包"形式(
pack-quantized)存储在 safetensors 里,所以文件小了三倍多; ignore名单(config.json 中那份超长的列表):明确列出哪些层没有量化、保持 BF16——整个视觉塔(vision_tower全部 27 层)、视觉投影层、每层 MoE 的 router 和lm_head。这些"精度敏感区"故意保留全精度,是量化模型不掉智商的关键。
⚠️ 新手注意:
group_size是 64 而不是常见的 128。因为 Gemma 4 的down_proj输入维度是 2112 和 704,都不能被 128 整除,而 64 能整除所有量化层。如果你的工具链默认按 128 读分组,会直接读错——README.md 在 Limitations 里专门强调了这一点。
3. 一个容易忽略的细节
architectures 必须是 Gemma4ForConditionalGeneration(完整多模态类)而不是纯文本类。README.md 提到:量化时如果误用 AutoModelForCausalLM,会把 config.json 降级成纯文本配置,产出的检查点会被 vLLM 拒绝加载。
🍲 recipe.yaml:量化"配方",记录当初怎么压缩的
recipe.yaml 是 LLM Compressor 在量化时写下的"食谱"。它不是推理时必需的,但极其有参考价值——它完整记录了"这个 4-bit 模型是怎么炼成的"。
核心内容就一份 GPTQModifier 配置:
| 参数 | 值 | 含义 |
|---|---|---|
num_bits / type |
4 / int | 4-bit 整数量化 |
group_size |
64 | 每 64 个权重一组共享缩放因子 |
symmetric |
true | 对称量化(零点在 0,省一个零点参数) |
actorder |
static | 静态列重排,降低舍入误差 |
observer |
memoryless_minmax | 用最值法统计缩放范围 |
targets |
[Linear] | 只量化线性层 |
ignore |
lm_head、router.proj、experts.down_proj、vision_tower 等 | 精度敏感层跳过 |
dampening_frac |
0.01 | GPTQ 的阻尼系数 |
结合 README.md 可以还原完整故事:AMD 用 128 条 ultrachat_200k 校准数据(最长 2048 token)跑 GPTQ 一次性量化(oneshot),产出即上面 config.json 里的 quantization_config。
💡 一句话理解两者关系:recipe.yaml 是"做法",config.json 里的 quantization_config 是"成品标签"。前者给人类和复现者看,后者给推理框架看。
🖼️ processor_config.json:多模态输入的"预处理说明书"
Gemma 4 不只懂文字,还能看图、听音频、看视频。processor_config.json 就规定了这些原始数据如何被切分、缩放成模型能吃的 token,对应处理器类是 Gemma4Processor,内含三个子模块:
image_processor(Gemma4ImageProcessor):图片切 16×16 的 patch、像素值除以 255 归一化(rescale_factor: 0.00392...就是 1/255),每张图最终编码为 280 个视觉 token(image_seq_length: 280);feature_extractor(Gemma4AudioFeatureExtractor):16 kHz 采样率的音频转成 128 维 Mel 频谱特征,hop_length: 160即每 10ms 一帧;video_processor(Gemma4VideoProcessor):视频抽 32 帧、每帧同样切 patch,最多 70 个软 token。
对使用者的实际意义:你用 AutoProcessor 加载这个仓库时,图像/音频的预处理行为完全由此文件决定,不需要自己写任何预处理代码;多模态检查点缺少它也会导致 vLLM 加载失败(README.md 特意说明量化流程末尾要补存 processor)。
🔤 词表三件套:tokenizer.json、tokenizer_config.json、chat_template.jinja
这三个文件共同决定了"文字 ↔ token"的转换方式和对话格式。
tokenizer.json:词表本体,约 26 万个 token 的完整映射表,由 GemmaTokenizer 使用,一般无需手动查看。
tokenizer_config.json:特殊 token 与输出解析规则,几个亮点:
- 多模态占位符:
<|image|>、<|audio|>、<|video|>以及各自的开头/结束标记; - 工具调用相关 token:
<|tool>、<|tool_call>、<|tool_response>; think_token(<|think|>):思考模式开关;response_schema里还带了正则,用于从模型输出中解析出 thinking、tool_calls、content 三个部分——这是框架做函数调用解析的依据。
chat_template.jinja:Google Gemma 4 官方对话模板(Jinja2 语法),负责把 messages 列表渲染成模型输入,处理了四件新手最容易写错的事:
- 轮次(turn)结构:用
<|turn>system / user / model和<turn|>精确包裹每轮对话; - 思考通道:
enable_thinking开启时,在 system 轮注入<|think|>,推理内容写入<|channel>thought通道; - 工具声明与调用:
<|tool>块声明函数,<|tool_call>call:函数名{参数}发起调用,<|tool_response>块回传结果; - 多模态内容块:图片/音频/视频统一替换为对应占位 token。
📄 其余文件快速过一遍
- model.safetensors:权重本体,14.6 GiB 的量化权重都在里面(本镜像中该文件由 Git LFS 管理,
git lfs install后拉取才是完整权重); - generation_config.json:默认生成参数——
top_k: 64、top_p: 0.95、temperature: 1.0、do_sample: true,以及结束符eos_token_id(1、106、50)。调用 API 时不传参就用它,建议按官方推荐值微调; - README.md:完整使用文档,包含 vLLM 快速上手、依赖版本清单(torch 2.11.0 / zentorch 2.11.0.3 / vLLM 0.26.0 / llmcompressor 0.12.0)、GSM8K 评测(4-bit 模型保住了 BF16 基线 98.48% 的分数)和 OpenMP 环境变量设置;
- review_status.json:AMD 内部发布审核记录(PR 号、审核人、状态),与使用模型无关,看到它说明这个检查点走完了官方审核流程;
- LICENSE:沿用 Gemma 社区许可,商用前记得看一眼条款。
🚨 新手避坑清单:加载前必看的 4 件事
- 版本锁死:该模型只验证过 ZenDNN 6.1.0 / ZenTorch 2.11.0.3 / PyTorch 2.11.0 / vLLM 0.26.0 这套组合,其他版本可能加载失败(README.md);
- 只能 CPU 推理:这是为 AMD EPYC + ZenDNN 优化的 CPU 模型,别拿去跑 GPU 集群;
- group_size=64 是非标值:假设 128 分组的工具会读错权重(README.md);
- 视觉通路未量化:视觉塔保持 BF16,且评测是在
language_model_only=True下做的,纯文本场景结论最可靠(README.md)。
总结
| 文件 | 核心职责 | 使用时机 |
|---|---|---|
| config.json | 架构 + 量化配置(4-bit、group 64、BF16 白名单) | 每次加载都读 |
| recipe.yaml | 量化过程"配方"(GPTQ + 校准 + 豁免层) | 复现/审计量化时看 |
| processor_config.json | 图/音/视预处理参数 | 多模态输入时生效 |
一句话收尾:config.json 说明模型是什么,recipe.yaml 说明模型怎么来的,processor_config.json 说明输入怎么喂——三者各司其职,配合 model.safetensors 里的权重,就构成了一个可以在 AMD CPU 上跑起来的 4-bit Gemma 4 多模态模型。