Qwen2.5_3B_Instruct_rai_1.8.0_npu_4K文件结构逐层解析：10分钟看懂model.onnx、tokenizer与dd_metastate

本文为新手逐层解析 Qwen2.5_3B_Instruct_rai_1.8.0_npu_4K 的文件结构：这是一个由 AMD 基于 Qwen2.5 3B Instruct 量化并导出为 ONNX 格式的开源模型，专为 AMD Ryzen AI（NPU） 本地部署优化，支持 4K 上下文。搞懂 model.onnx、tokenizer 文件族和 dd_metastate_* 缓存后，你就能独立完成模型的下载、校验与推理配置。

📦 先看全景：这个仓库里到底有什么？

仓库由 AMD 通过 Quark 量化 + OGA Model Builder + NPU 后处理（Full Fusion，4K 上下文） 流水线生成（见 README.md）。按职责划分，全部文件可归为 5 类：

分类	文件	作用
🧠 模型本体	model.onnx、model.onnx.data	ONNX 计算图 + 外置权重（约 760 MB）
⚙️ 模型配置	config.json	网络结构与 AWQ 量化参数
⚙️ 推理配置	genai_config.json、generation_config.json、rai_config.json	推理会话、采样参数、NPU 运行时限制
🗣️ 分词器	tokenizer.json、vocab.json、merges.txt、tokenizer_config.json、special_tokens_map.json、added_tokens.json、chat_template.jinja	文本 ↔ token id 互转与对话格式
🚀 NPU 缓存	dd_metastate_* 系列	NPU 预编译元数据，加速首次加载

💡 一句话记忆：onnx 是“大脑”，tokenizer 是“嘴和耳朵”，json 是“说明书”，dd_metastate 是“暖机缓存”。

🧠 重点一：model.onnx 与 model.onnx.data 是什么关系？

这是新手最常被问到的问题：为什么一个模型要拆成两个文件？

• model.onnx：ONNX 计算图本身，只有约 33 MB，描述"数据如何在 36 层 Transformer 中流动"。
• model.onnx.data：外置权重文件，约 760 MB，存放真正的量化权重。

这种"图/权分离"是 ONNX 的标准做法，方便只改图不动权重。

从 config.json 可以看到它的"身份证"：

参数	数值
架构	Qwen2ForCausalLM（qwen2）
隐藏层 / 隐藏维度	36 层 / 2048
注意力头	16 个 query 头 + 2 个 KV 头（GQA）
词表大小	151,936
最大位置编码	32,768（推理按 4K 上下文发布）
量化方案	AWQ / Group 128 / 非对称 / uint4 权重 + BFP16 激活

第 10~22 行的量化策略（AWQ / Group 128 / Asymmetric / BFP16 activations / UINT4 Weights，见 README.md）正是体积能从 bf16 原版的 ~6 GB 压到 ~760 MB 的原因——uint4 权重是它能在笔记本 NPU 上跑起来的关键。

🗣️ 重点二：tokenizer 文件族逐个认识

分词器负责把"你好"变成 [151643, 104106, 8788, 151645] 这样的 id 序列。7 个文件各司其职：

文件	通俗理解
vocab.json（约 2.6 MB）	词表"字典"：token ↔ id 的完整映射
merges.txt（15 万余条）	BPE 合并规则，决定子词如何拼合
tokenizer.json	分词器"总开关"，整合词表+规则
tokenizer_config.json	行为配置（不自动加 BOS 等）
special_tokens_map.json	特殊 token 映射，如 <|im_end|> = 151645
added_tokens.json	新增 token，如 `