config.json、recipe.yaml、processor_config.json都在干嘛?gemma-4-26B-A4B-it-w4a16-llmcompressor仓库文件逐个拆解

原创2026-10-18 15:16:461,420 阅读

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_size 2816、词表 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 列表渲染成模型输入,处理了四件新手最容易写错的事:

  1. 轮次(turn)结构:用 <|turn>system / user / model 和 <turn|> 精确包裹每轮对话;
  2. 思考通道:enable_thinking 开启时,在 system 轮注入 <|think|>,推理内容写入 <|channel>thought 通道;
  3. 工具声明与调用:<|tool> 块声明函数,<|tool_call>call:函数名{参数} 发起调用,<|tool_response> 块回传结果;
  4. 多模态内容块:图片/音频/视频统一替换为对应占位 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 件事

  1. 版本锁死:该模型只验证过 ZenDNN 6.1.0 / ZenTorch 2.11.0.3 / PyTorch 2.11.0 / vLLM 0.26.0 这套组合,其他版本可能加载失败(README.md);
  2. 只能 CPU 推理:这是为 AMD EPYC + ZenDNN 优化的 CPU 模型,别拿去跑 GPU 集群;
  3. group_size=64 是非标值:假设 128 分组的工具会读错权重(README.md);
  4. 视觉通路未量化:视觉塔保持 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 多模态模型。

登录后查看全文
gemma-4-26B-A4B-it-w4a16-llmcompressor