【免费下载链接】gemma-4-12B-it_rai_1.9.0_npu
想做 Gemma4 12B 图像理解？这篇文章带你从零跑通。gemma-4-12B-it_rai_1.9.0_npu 是由 Google Gemma 4 12B IT 导出、面向 AMD Ryzen AI NPU 深度优化的多模态大模型：ONNX 格式 + AWQ/UINT4 量化，模型被拆分为 decoder、vision_encoder、audio_encoder、embedding 四个组件。本文详解视觉编码器如何工作、Gemma4ImageTransform 的每个预处理参数，并手把手教你完成第一次"图片问答"。
🗂️ 一分钟认识这个模型：4 个 ONNX 组件
项目采用"组合模型"（compositemodel）结构，完整定义见 model_config.json。模型被拆成 4 个独立 ONNX 模块，各司其职：
| 组件 | 文件 | 职责 |
|---|---|---|
| vision_encoder | vision_encoder/model.onnx | 把图片编码成视觉特征向量 |
| embedding | embedding/model.onnx | 把文本与视觉特征融合成统一输入 |
| decoder | decoder/model.onnx | 语言模型本体，逐词生成回答 |
| audio_encoder | audio_encoder/model.onnx | 音频编码（本文不展开） |
💡 每个
model.onnx旁边的model.onnx.data是 ONNX 外部权重文件，两者必须放在同一目录。decoder 目录还多一个 decoder/model.pb.bin，供 RyzenAI NPU 混合推理后端加载（见 genai_config.json）。
该模型通过 Quark 量化（AWQ / Group 128 / UINT4 权重）和 OGA Model Builder 导出，专为 AMD Ryzen AI 硬件部署优化，背景信息可参考 README.md。
🖼️ 图像理解流水线：一张图片如何变成答案
把一张图片交给模型后，它会依次经历 4 个阶段：
- 解码：
DecodeImage操作把图片文件解码为 RGB 彩色图像； - 预处理：
Gemma4ImageTransform将图片切分为规整的 patch 网格，产出pixel_values（像素值）与pixel_position_ids（像素位置）——正好是 genai_config.json 中声明的两个网络输入； - 编码：vision_encoder 网络输出
image_features（视觉特征），并通过 2×2 空间合并（spatial_merge_size: 2）把特征压缩为固定 280 个"软 token"； - 融合与生成：embedding 模块把文本 embedding 中图片占位位置替换为
image_features（输入输出定义见 genai_config.json），decoder 随即照常生成回答。
这就是 gemma4_unified 架构的精髓——"encoder-free"统一设计：视觉特征直接注入 embedding 层，流水线在 NPU 上更加高效。
📝 Gemma4ImageTransform 预处理参数详解
预处理流水线定义在 image_processor.json，Gemma4ImageTransform 有 3 个关键参数：
| 参数 | 取值 | 作用 |
|---|---|---|
patch_size | 48 | 图片按 48×48 像素切块，等于网络侧"16 像素原生 patch × 3×3 池化" |
max_soft_tokens | 280 | 图片 token 数上限，保证任意尺寸图片都压缩到相同长度，兼顾精度与速度 |
pooling_kernel_size | 1 | 预处理阶段池化操作的核大小 |
网络侧的对应参数在 model_config.json 的 vision_config 中，可以一一对照：
patch_size: 16+pooling_kernel_size: 3→ 16×3=48，与预处理阶段的patch_size精确对齐；num_soft_tokens: 280→ 与预处理的max_soft_tokens一致；mm_embed_dim: 3840→ 与文本塔隐藏层维度 3840 相同，视觉特征因此能无缝"拼进"文本流。
图片的起止标记定义在 tokenizer_config.json 中：<|image>（id 255999）表示图片开始，<|image|>（id 258880）是图片占位 token，<image|>（id 258882）表示图片结束。280 个软 token 就填充在这段占位区间里。
⚡ 三步上手：跑通第一次图像理解
第 1 步：安装依赖
模型要求 Python 3.10 与 onnxruntime-genai >= 0.15.0，直接用项目自带的 requirements.txt 一键安装：
pip install -r requirements.txt
第 2 步：运行图片理解命令
项目内置了端到端测试脚本 test_model.py，直接用 image 模式运行图像理解：
python test_model.py . image dog.jpg "请用一句话描述这张图片。"
参数依次为：模型目录（. 表示当前目录）、模式 image、图片路径、想问的问题。不提供问题时，默认执行"用一句话描述这张图片"。完整参数说明见 test_model.py 顶部文档。
第 3 步：读取流式输出
脚本内部通过 create_multimodal_processor 自动完成"解码 → 预处理 → 编码 → 生成"全流程（见 test_model.py），运行时会流式打印模型回答，结束时显示生成的 token 数与耗时，方便评估 NPU 上的推理速度。
🧠 提示词格式小细节：图片占位符怎么写
在这个模型的对话模板 chat_template.jinja 中，提到图片必须在用户轮次写入 <|image|> 占位符，再在同一位置挂载图片数据：
<|turn>user
<|image|>请用一句话描述这张图片。
<turn|>
<|turn>model
test_model.py 会替你自动拼装这个格式（见 test_model.py）；如果你要自己写脚本，照这个模式即可。
💡 新手避坑清单
- 权重与图要成对：
model.onnx是图结构、model.onnx.data是权重数据，复制部署时必须把同目录的两个文件一起搬走； - NPU 建议 1.6.0 以上：视觉编码器本身默认跑在 CPU（未配置 NPU provider，见 genai_config.json），decoder 通过
hybrid_opt_token_backend: npu跑 NPU 混合后端；各 Ryzen AI 版本的最大提示长度限制记录在 rai_config.json（如 1.7.x 系列为 4096）； - decoder 使用了"剪枝 LM head"：它只为最后一个 token 输出 logits，这是部署层面的优化，ORT GenAI 会透明处理，你无需关心。
📚 相关文件资料
| 文件 | 说明 |
|---|---|
| image_processor.json | 图像预处理流水线定义（DecodeImage + Gemma4ImageTransform） |
| vision_encoder/ | 视觉编码器 ONNX 模型与外部权重 |
| genai_config.json | ORT GenAI 主配置：各组件输入/输出映射、NPU 推理选项 |
| model_config.json | 组合模型结构及 vision_config / text_config / audio_config |
| tokenizer_config.json | 图片、音频占位 token 与处理器配置 |
| chat_template.jinja | Gemma 4 官方对话模板 |
| test_model.py | 支持 text / image / audio 三模式的端到端测试脚本 |
| requirements.txt | 运行环境依赖（onnxruntime-genai、numpy） |
【免费下载链接】gemma-4-12B-it_rai_1.9.0_npu
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
