企业官网建设流程全解析

Gemma3-4B-it_gpuep_1.0_gpu_128 是 AMD 基于 Gemma 3 4B 指令微调模型（google/gemma-3-4b-it）转换而成的ONNX 模型包，专为 AMD Ryzen AI 硬件优化部署。整个 ONNX 模型目录只包含 14 个文件，每个文件各司其职：3 个 ONNX 计算图、3 个权重数据文件、5 个分词器文件，以及 3 个配置文件。本文带你逐一拆解这 14 个文件的作用，让你一文看懂 ONNX 模型目录的组织逻辑。📦

30秒快速了解：这是一个什么样的ONNX模型？

在拆文件之前，先用几句话交代背景（详见 README.md）：

• 来源模型：google/gemma-3-4b-it，4B 参数、支持文本 + 图像的多模态模型
• 转换工具：AMD 的 OGA Model Builder
• 量化策略：RTN / Group 128 / FP16 激活 /INT4 权重——权重压到 4 位整数，体积更小、端侧推理更快
• 推理引擎：配套 ONNX Runtime GenAI 使用（从配置中的onnxruntime-genai日志 ID 可以看出）
• 许可协议：MIT License

💡 目录名中的gpuep_1.0_gpu_128正是"GPU Execution Provider + Group 128 量化"的缩写，与 README 中的量化策略一一对应。

ONNX模型目录14个文件一览表

所有文件位于 Upload gemma3-4b-it ONNX files/ 目录下，先看全景：

全部文件加起来约4.2 GB，其中 97% 的体积来自 3 个.onnx.data权重文件——这也是模型体积"大头"所在。

模型核心：三大ONNX计算图与权重数据文件

text.onnx：文本解码器的"主体"

text.onnx 是整个模型的核心，承载 Gemma 3 的34 层 Transformer 解码器（num_hidden_layers: 34，隐藏维度 2560，8 个注意力头 + 4 个 KV 头，即 GQA 架构）。

它的输入输出在 genai_config.json 中有明确定义：

• 输入：inputs_embeds（词向量）、attention_mask、position_ids，以及past_key_values（历史 KV 缓存）
• 输出：logits（下一个 Token 的预测分数）和新的 KV 缓存

而 text.onnx.data 则是它"拆开存放"的约 2.1 GB INT4 量化权重。ONNX 模型超过一定大小时，惯例就是把权重拆到.data文件中，text.onnx只保留计算图结构，加载时按名配对读取。

embedding.onnx：Token 走向量的一站

embedding.onnx 是一张很小的图（仅 4 KB），负责把 Token ID 转换成向量，并处理视觉特征的对齐。它的输入是input_ids和image_features，输出inputs_embeds——正好是text.onnx的输入，两者首尾相连：

Token ID / 图像特征 → embedding.onnx → inputs_embeds → text.onnx → logits → 下一个Token

embedding.onnx.data 约 1.25 GB，存的是词嵌入矩阵——词表大小高达 262,208，所以这块权重并不小。

vision.onnx：多模态的"眼睛"

vision.onnx 是视觉编码器，输入pixel_values（预处理后的图像张量），输出image_features（图像特征向量），再交给 embedding 阶段拼进文本序列。vision.onnx.data 约 800 MB，存着视觉塔的权重。

这正是 Gemma 3 4B "能看图"能力的来源：图像先走 vision.onnx，特征向量再汇入文本解码流程。🧩

配置中枢：genai_config.json 是模型的"总调度台"

genai_config.json 是 ONNX Runtime GenAI 的入口配置，作用相当于"目录的说明书"：

• model.type: "gemma3"：声明模型架构类型
• 三大子模块注册：decoder → text.onnx、embedding → embedding.onnx、vision → vision.onnx，每个子模块都写明了文件名、输入输出张量名
• 关键参数：上下文长度context_length: 131072（128K 超长上下文）、词表大小 262,208、BOS Token ID 为 2、EOS 为 1 和 106
• search默认采样参数：top_k: 64、top_p: 0.95、do_sample: true等，推理时生成温度、截断策略都从这里起步

可以说，引擎启动时先读它，才能知道去加载哪几个.onnx文件、各输入输出叫什么名字。

分词器四件套：把文字变成数字的流水线

ONNX 模型不认识文字，只认 ID。把文字切成 Token 并映射为 ID 的任务，由 4 个文件协同完成：

1. tokenizer.json（≈ 32 MB）主分词器文件，包含完整的词表与 BPE 编码规则，体积最大的"非权重"文件。

2. tokenizer.model（≈ 4.5 MB）SentencePiece 格式的词表模型，是 tokenizer.json 的"姊妹文件"，两者词表一致，兼容不同推理框架的加载习惯。

3. tokenizer_config.json（≈ 1.15 MB）分词行为的"开关面板"：add_bos_token: true（自动补句首符）、add_eos_token: false，并完整列出了 26 万余个附加 Token 的解码器定义（文件多达 5 万余行，所以体积不小）。

4. added_tokens.json + special_tokens_map.json两张轻量"速查表"。前者只有一行：<image_soft_token>对应 ID 262144——这是图像占位符 Token；后者登记了<bos>、<eos>、<pad>、<start_of_image>/<end_of_image>（boi/eoi）等特殊 Token，供快速查询，不必翻大词表。

图像预处理规则：processor_config.json

processor_config.json 定义了图片送入 vision.onnx 之前的 5 步处理流水线：

1. DecodeImage：解码为 RGB
2. Resize：缩放到896 × 896（双三次插值）
3. Rescale：像素值归一化
4. Normalize：以 mean=0.5、std=0.5 标准化
5. Permute3D：转为 Channel First 排布

理解这份配置，就能知道"喂给模型的图像"到底经过了哪些变形——图像输入效果异常时，这里往往是第一检查点。

对话怎么组织：chat_template.jinja 聊天模板

chat_template.jinja 是一个 Jinja2 模板，负责把"你/模型"的多轮对话渲染成模型认识的文本格式：

• 每段对话包裹在<start_of_turn>user/<start_of_turn>model和<end_of_turn>之间
• 强制校验角色必须user / assistant 交替，否则抛异常
• 遇到图片内容时插入<start_of_image>标记，与special_tokens_map.json中的 boi/eoi Token 呼应
• 系统提示（system）会被拼接到首轮 user 前缀中

简单说：tokenizer 决定"怎么切"，chat_template 决定"怎么排"。

常见疑问：为什么仓库里文件看起来只有几百字节？

如果你 clone 后打开text.onnx发现只有 130 多个字节，别慌——👀 这是Git LFS（Large File Storage）的标准现象。

像text.onnx、tokenizer.json这类大文件，仓库里存放的是 LFS 指针文件，内容形如：

version https://git-lfs.github.com/spec/v1 oid sha256:5e71d480ca... size 557551

指针中的size字段才是真实文件大小（上表中的"实际大小"均取自这里）。执行git lfs pull拉取二进制大文件后，才会得到真正可加载的模型文件。

总结：一文记住ONNX模型目录结构

把 14 个文件按"职能"归类，ONNX 模型目录结构一目了然：

• 🧠 计算图 × 3：text.onnx（解码主体）+embedding.onnx（嵌入）+vision.onnx（视觉）
• 💾 权重 × 3：对应的.onnx.data文件，INT4 量化，共约 4.1 GB
• ⚙️ 配置 × 3：genai_config.json（总调度）+processor_config.json（图像预处理）+chat_template.jinja（对话模板）
• 🔤 分词 × 5：tokenizer.json、tokenizer.model、tokenizer_config.json、added_tokens.json、special_tokens_map.json

一句话概括这套 ONNX 模型目录的精髓：图小权重拆、配置管调度、分词保翻译——图文件定义"怎么算"，data 文件存"算什么"，配置与分词文件则负责把文字和图片翻译成模型能理解的张量。读懂了这 14 个文件，你再看到任何 ONNX 模型目录，都能迅速定位每个文件的作用。