进阶教程:复刻 Qwen3-4B_rai_1.8.0_npu_16K 的构建流水线,把你的 4B 模型部署到 NPU

原创2026-10-21 18:55:461,905 阅读

进阶教程:复刻 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 格式。产物就是仓库里的:

导出完成后,模型结构在 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 窗口策略,可按硬件版本增删键值。

词表与对话模板:别漏掉的"最后一公里"

登录后查看全文
Qwen3-4B_rai_1.8.0_npu_16K