Llama-3.2-3B-Instruct_rai_1.8.0_npu_4K 模型目录全解：model.onnx、tokenizer 与 dd_metastate 文件逐一揭秘
Llama-3.2-3B-Instruct_rai_1.8.0_npu_4K 模型目录全解：model.onnx、tokenizer 与 dd_metastate 文件逐一揭秘
📦 Llama-3.2-3B-Instruct_rai_1.8.0_npu_4K 是 AMD 官方针对 Ryzen AI NPU 优化部署的 Llama 3.2 3B 指令模型，包含 model.onnx 推理图、tokenizer 分词器与大量 dd_metastate NPU 融合缓存文件。本文带你逐个文件拆解这个目录，搞懂每个文件的真实作用，让你拿到模型包后不再一脸懵。
一、先搞清楚：这个模型是怎么来的？
根据 README.md 的说明，该模型经历了三步加工：
- Quark 量化：采用 AWQ 算法，权重压缩为 UINT4，分组大小 Group 128，非对称量化，激活值使用 BFP16；
- OGA Model Builder：构建 ONNX 图（即
model.onnx）； - NPU 后处理：做"Full Fusion 4K"全融合，支持 4096 token 上下文。
📌 一句话总结：这是一个"量化 + ONNX 化 + NPU 预编译"三合一的部署包，专为 AMD Ryzen AI（ryzenai 1.8.0）芯片设计。
核心规格速览（来自 config.json 与 params.json）
| 参数 | 数值 | 含义 |
|---|---|---|
隐藏层维度 hidden_size |
3072 | 每个 token 的向量宽度 |
层数 num_hidden_layers |
28 | Transformer 堆叠层数 |
注意力头 num_attention_heads |
24 | 多头注意力 |
KV 头 num_key_value_heads |
8 | GQA 分组，省显存的关键 |
词表大小 vocab_size |
128256 | 可识别的 token 总数 |
| RoPE 缩放 | llama3 / factor 32 | 将上下文从 8192 扩展到 131072 |
💡 KV 头只有注意力头的 1/3，这是 Llama 3.2 系列的 GQA（分组查询注意力） 设计，是它能在端侧跑起来的关键之一。
二、目录文件全景：谁大谁小、谁是谁的"附属品"
打开目录，文件其实只分四大类，先建立整体认知：
| 类别 | 文件 | 作用 |
|---|---|---|
| 模型权重 | model.onnx、model.onnx.data | ONNX 计算图 + 约 984MB 量化权重 |
| 分词器 | tokenizer.model、tokenizer.json、tokenizer_config.json、special_tokens_map.json | 文字 ↔ token 数字的翻译官 |
| NPU 缓存 | 30 个 dd_metastate_* 文件 |
NPU 预编译融合图缓存（重点！） |
| 配置与许可 | config.json、genai_config.json、rai_config.json 等 | 运行参数、许可协议 |
三、model.onnx 与 model.onnx.data：推理的"大脑 + 记忆"
model.onnx 是什么？
model.onnx 是 ONNX 计算图，描述整个模型从输入到输出每一步运算的连接关系。它本身很小，真正的"肉"在旁边的数据文件里——这是 ONNX 的**外部数据（external data）**机制：
- model.onnx：计算图结构 + 元数据；
- model.onnx.data：约 984MB 的实际权重数据（UINT4 量化后的结果）。
谁来"驾驶"这张图？
genai_config.json 是 ONNX Runtime GenAI 的启动配置，几个关键字段值得注意：
provider_options中配置了 RyzenAI 执行提供方，并开启hybrid_opt_token_backend: npu——即 token 生成环节交给 NPU 加速；- 输入/输出被精确映射：
input_ids、attention_mask、position_ids、past_key_values.%d.key等（KV Cache 逐层读写）； search段给出默认采样参数：temperature: 0.6、top_p: 0.9、max_length: 4096，与 generation_config.json 中的设置保持一致。
⚠️ 新手避坑提示：本仓库的大文件通过 Git LFS 存储。克隆仓库后如果看到 model.onnx.data 只有几百字节，说明 LFS 指针还没拉取，需要执行：
git lfs install
git lfs pull
如需克隆本仓库：git clone https://gitcode.com/hf_mirrors/amd/Llama-3.2-3B-Instruct_rai_1.8.0_npu_4K
四、tokenizer 家族：文字如何变成模型看得懂的数字
模型本身只认识数字，tokenizer（分词器） 负责完成"文字 → token id"的翻译。本目录中有 4 个相关文件：
| 文件 | 作用 |
|---|---|
| tokenizer.model | SentencePiece 模型本体（约 2.1MB），记录词表与 BPE 合并规则 |
| tokenizer.json | 词表与规则的 JSON 等价形式，供不同库快速加载 |
| tokenizer_config.json | 128000 起的一批特殊 token 定义（added_tokens_decoder） |
| special_tokens_map.json | 指定 bos_token 与 eos_token |
特殊 token 小抄
- 开始符
bos_token：<|begin_of_text|>（id 128000） - 结束符
eos_token：<|eot_id|>（id 128009） - config.json 中
eos_token_id实际配置了 3 个结束信号：128001（<|end_of_text|>）、128008（<|eom_id|>）、128009（<|eot_id|>），任一出现在生成结果中即停止。
chat_template.jinja：对话格式的"剧本"
chat_template.jinja 是一个 Jinja2 模板，规定了多轮对话拼接到 prompt 中的精确格式：
- 系统消息以
<|start_header_id|>system<|end_header_id|>开头，并自动注入Cutting Knowledge Date与Today Date； - 每轮 user / assistant 消息同样包裹在 header 标签之间，以
<|eot_id|>收尾； - 末尾自动追加
assistant头，等待模型续写。
💡 如果你自己调用推理 API，务必让客户端应用这个模板，否则对话效果会大打折扣。
五、dd_metastate 文件：NPU 预融合缓存到底是什么？🔍
目录里最"吓人"的一堆文件，名字长这样：
dd_metastate_Llm_Prefill_modellayers.0input_layernormMLADFRMSNORM_sequence_length_padded_1024_.ctrlpkt
别慌，它的命名完全可以拆解：
dd_metastate_ + 阶段(Prefill/Token) + 融合节点名 + 填充长度 + 扩展名
| 片段 | 含义 |
|---|---|
Prefill |
预填充阶段：一次性处理整段 prompt，文件名带 sequence_length_padded_XXX，覆盖 128/256/512/…/4096 |
Token |
逐 token 生成阶段：文件名带 attention_mask_padded_XXX，覆盖 256/512/1024/…/4096 |
modellayers.0input_layernormMLADFRMSNORM |
第 0 层被 NPU 融合成一个大算子的节点（输入 LayerNorm + RMSNorm 等） |
| 扩展名 | 见下表 |
5 种扩展名各管什么？
| 扩展名 | 职责（通俗理解） |
|---|---|
.super |
该填充长度下 NPU 超级图（super graph）缓存 |
.state |
节点运行状态（如 .state 文件 仅 128 字节） |
.fconst |
融合节点的固定常量参数 |
.ctrlpkt |
控制包（control packet），NPU 调度用 |
.meta |
描述上述缓存的元数据 |
为什么需要它们？
NPU 上跑动态形状的图很昂贵。AMD 在构建阶段就把 每种上下文长度 的图预先编译、融合好（README 所称 "Full Fusion 4K context"）。运行时按你的 prompt 长度选最接近的预编译版本，省去了现场编译时间，这也是目录名中 npu_4K 的由来——预置缓存覆盖到 4096。
⚠️ 注意：这些文件是相互配套的 NPU 运行时产物，请勿单独移动、重命名或删除其中任何一个，保持整个目录完整即可。
六、其余配置文件：各就各位
| 文件 | 说明 |
|---|---|
| rai_config.json | 按 Ryzen AI 运行时版本（1.3.1 ~ 1.7.1）限制最大 prompt 长度：1.5.1 及以前 2048，1.6.0 起 4096 |
| params.json / orig_params.json | 原始 Llama 结构参数（dim、n_layers、rope_theta 等），内容一致，属导出时留下的原始记录 |
| LICENSE.txt | 修改版 MIT 许可（AMD 2025） |
| USE_POLICY.md | Meta 的 Llama 3.2 可接受使用政策，商用前请阅读 |
七、新手上手三步走 ✅
- 完整克隆：确认
git lfs pull拉下了约 1GB 的model.onnx.data，而不是几个百字节的 LFS 指针； - 核对配套：
model.onnx、model.onnx.data、tokenizer.*、全部dd_metastate_*缺一不可，目录整体拷贝； - 对接运行时：该包面向 Ryzen AI（ryzenai 1.8.0）+ ONNX Runtime GenAI，按 README.md 指引的 Ryzen AI 官方文档接入即可，默认采样参数已写在 genai_config.json 中，开箱即用。
掌握这份"文件说明书"后，你可以自信地管理这个模型目录——model.onnx 是引擎、tokenizer 是翻译官、dd_metastate 是 NPU 的预编译缓存，三者各司其职，共同让 3B 模型在 Ryzen AI NPU 上跑满 4K 上下文。