进阶教程:复刻 Qwen3-4B_rai_1.8.0_npu_16K 的构建流水线,把你的 4B 模型部署到 NPU
进阶教程:复刻 Qwen3-4B_rai_1.8.0_npu_16K 的构建流水线,把你的 4B 模型部署到 NPU
本文是一份面向初学者的进阶教程,带你完整拆解 Qwen3-4B_rai_1.8.0_npu_16K 这套 AMD Ryzen AI NPU 部署模型的构建流水线:从基础模型 Qwen3-4B 出发,经历 Quark 量化、OGA Model Builder 导出 ONNX、NPU 后处理(Token Fusion 16K 上下文) 三个阶段,最终得到一个可被 Ryzen AI 1.8.0 直接加载的 NPU 推理包。读懂这套流水线后,你可以把自己的任意 4B 级模型按同样步骤部署到 NPU 上。
📦 先看仓库:Qwen3-4B NPU 模型包里都藏了什么
这个仓库本质上不是一个"训练好的模型",而是一份已经跑完整条部署流水线的成品包。打开仓库,文件大致可以分成四类:
| 类别 | 代表文件 | 作用 |
|---|---|---|
| 模型权重(量化后) | model.onnx、model.onnx.data | ONNX 计算图 + 分离的大权重文件(约 2.3 GB,UINT4 量化权重) |
| NPU 编译产物 | model.pb.bin、dd_metastate_* 系列文件 |
NPU 端融合算子与 KV Cache 的元状态,供 Ryzen AI 引擎直接加载 |
| 推理配置 | genai_config.json、rai_config.json、generation_config.json | 告诉运行时如何用 NPU 执行、采样参数如何设置 |
| 词表与对话模板 | tokenizer.json、vocab.json、chat_template.jinja | 文本切词与 ChatML 对话格式 |
💡 一个小细节:
model.onnx本体只有几百 KB,真正的权重被分离到了 model.onnx.data 中——这是 ONNX 外部权重(external data)的常见做法,方便 Git 管理。
🏭 构建流水线总览:三步把 4B 模型送上 NPU
根据 README.md 的说明,这套模型的生产链路非常清晰:
Qwen3-4B (BFloat16)
│ ① Quark 量化(AWQ)
▼
量化版 PyTorch 权重(UINT4)
│ ② OGA Model Builder 导出
▼
model.onnx + model.onnx.data
│ ③ NPU 后处理 + Token Fusion
▼
model.pb.bin + dd_metastate_*(NPU 可直接执行)
第一步:Quark 量化——AWQ 算法把权重压到 4 比特
量化参数完整记录在 config.json 的 quantization_config 字段中,这是整条流水线的"配方":
- 量化算法:
awq(Activation-aware Weight Quantization),通过scaling_layers配置了q_proj / k_proj / v_proj、o_proj、gate_proj / up_proj、down_proj四组缩放层,每组都指明了对应的prev_op输入归一化层; - 权重格式:
dtype: uint4、group_size: 128、symmetric: false(非对称分组量化)、round_method: half_even; - 激活格式:BFP16(按 README 说明)。
把 2.5 GB 的 BFloat16 权重压到约 1.3 GB 的 UINT4,是让 4B 模型塞进笔记本 NPU 统一内存的关键一步。如果你要复刻,核心工作就是准备一份同样结构的 quantization_config 喂给 Quark。
第二步:OGA Model Builder 导出 ONNX
量化后的权重交给 AMD 官方的 OGA Model Builder 工具,导出为 ONNX 格式。产物就是仓库里的:
- model.onnx:约 757 KB 的计算图结构文件;
- model.onnx.data:约 2.27 GB 的外部权重数据。
导出完成后,模型结构在 config.json 中可以验证:36 层 qwen3 架构、hidden_size: 2560、32 个注意力头、8 个 KV 头(GQA 结构)、head_dim: 128。
第三步:NPU 后处理——Token Fusion 与 16K 上下文
这是仓库名 npu_16K 的由来,也是"别人有、你没有"的一步。AMD 对 ONNX 做了 NPU 部署后处理(Token Fusion 16K context):
- model.pb.bin:NPU 引擎编译后的执行数据文件,在 genai_config.json 中通过
"external_data_file": "model.pb.bin"被引用; dd_metastate_*系列文件(共 23 个):每个 Transformer 层(如modellayers.0input_layernormMLADFRMSNORM)都生成一组.state/.meta/.ctrlpkt/.super元状态文件,并按 256、512、1024、2048、3072、4096、16384 七种序列长度预置了attention_mask_padded_*的缓存状态。这样运行时切换不同上下文长度无需重新编译——例如 dd_metastate_...attention_mask_padded_16384_.meta 就对应 16K 档位。
⚙️ 关键配置逐项解读:NPU 是怎么被点亮的
genai_config.json:运行时"点火开关"
genai_config.json 是整个部署包的运行说明书,其中最值得关注的 RyzenAI Provider 选项:
"RyzenAI": {
"hybrid_opt_max_seq_length": "4096",
"hybrid_opt_chunk_context": "1",
"hybrid_opt_chunk_context_threshold": "1",
"external_data_file": "model.pb.bin",
"hybrid_opt_token_backend": "npu",
"fusion_opt_io_bind_kv_cache": "1"
}
hybrid_opt_token_backend: npu:明确 Token 级推理走 NPU 后端,CPU 与 NPU 混合调度(hybrid);hybrid_opt_max_seq_length: 4096配合chunk_size: 4096(genai_config.json):长 Prompt 按 4096 分块预填充;max_length: 16384:解码最长 16K,与 16K 预置档位呼应。
采样参数则同时写在了 genai_config.json 和 generation_config.json:temperature 0.6、top_k 20、top_p 0.95、do_sample: true。
rai_config.json:各版本 Ryzen AI 的 Prompt 上限
rai_config.json 按 Ryzen AI 软件版本给出了 max_prompt_length 上限(1.3.1~1.5.1 为 2048,1.6.0 起提升到 4096)。你部署自己的模型时,这份文件决定了 Prompt 窗口策略,可按硬件版本增删键值。
词表与对话模板:别漏掉的"最后一公里"
- 词表共 151936 个 token,其中 special_tokens_map.json 定义了 `