Llama-3.2-1B_rai_1.8.0_npu_4K 是 AMD 官方为 Ryzen AI NPU 深度优化的 Llama-3.2-1B 文本生成模型，采用 AWQ 4-bit 量化与 Full Fusion 算子融合技术，在端侧 NPU 上实现 4096 token 长上下文推理。本文带你拆解它的部署实现原理。

这是什么模型？一句话看懂定位

这个项目是 AMD 基于 Meta 开源的 Llama-3.2-1B 的描述，它的制作流程分三步：

1. Quark Quantization：使用 Quark 量化框架完成权重压缩；
2. OGA Model Builder：构建 ONNX GenAI 格式模型（即model.onnx）；
3. NPU 部署后处理：执行 Full Fusion 算子融合，并扩展上下文到 4096。

产物就是一套可直接被 ONNX Runtime GenAI + Ryzen AI EP 加载的文件：model.onnx（计算图）+ model.onnx.data（权重外置数据）+ 一组dd_metastate_*NPU 运行时元数据。

🔑 简单理解：4K = 4096 token 上下文窗口，Full Fusion = 把注意力等关键算子整体融合成 NPU 原生算子。

核心配置速览：1B 小模型的"骨架"

打开 config.json 可以看到模型的核心结构参数：

其中rope_scaling配置了llama3类型的 YaRN 缩放（factor: 32.0），说明底层具备长上下文位置编码能力——NPU 部署版则将其实际运行窗口锁定在 4096，以平衡内存占用与推理速度。

另外 params.json 用 llama.cpp 风格记录了相同参数（n_layers: 16、n_kv_heads: 8、rope_theta: 500000.0），方便做交叉验证。

量化策略：AWQ + UINT4，端侧友好的关键

README 明确给出了量化方案：AWQ / Group 128 / Asymmetric / BFP16 激活 / UINT4 权重。在 config.json 的quantization_config中可以逐条印证：

• quant_method: "quark"：Quark 量化框架；
• weight.dtype: "uint4"：4-bit 无符号整数权重；
• group_size: 128：每 128 个权重共享一组缩放因子；
• symmetric: false：非对称量化；
• scaling_layers中还列出了 AWQ 的缩放层映射（q_proj/k_proj/v_proj由input_layernorm前驱缩放，gate_proj/up_proj由post_attention_layernorm缩放）。

1B 模型用 4-bit 权重后体积大幅缩水，正好塞进 NPU 可寻址的内存空间，这是"4K 长上下文还能跑在端侧"的物质基础。

Full Fusion 原理：算子融合到 NPU 原生指令

"Full Fusion" 的含义在于：不再让 ONNX 逐算子在 CPU 上解释执行，而是把每一层的算子整体融合成 NPU 可识别的扁平（flat）算子。

仓库中 cache/Token_modellayers.0input_layernormMLADFRMSNORM_meta.json 和 cache/modellayers.0input_layernormMLADFRMSNORM_meta.json 就是融合后的"算子蓝图"，逐层记录了 16 层解码层被重写后的算子序列。统计一下可以看到典型的融合形态：

• MLADFRMSNORM（1 次）：首层 RMSNorm，直接接嵌入层输出；
• MladfMatMul（81 个）：所有量化 GEMM（Q/K/V/O 投影、MLP 投影）统一为 NPU 原生 4-bit 矩阵乘；
• FLATMHA（16 个）：整个 GroupQueryAttention（Q/K/V + RoPE + 注意力 + KV Cache 读写）融合为一个算子；
• FlatRMSAdd（32 个）：残差相加 + RMSNorm 二合一；
• FlatMLP（16 个）：gate/up 投影 + SiLU + 逐元素乘合并在一个算子里。

以FLATMHA为例，它内部封装了num_heads: 32、kv_num_heads: 8、scale: 0.125（即 1/√64）、do_rotary: 1（内置 RoPE 旋转位置编码），并把past_key_values.%d.key/value作为输入、present.%d.key/value作为输出——KV Cache 的管理也一并进了算子。这正是"Full Fusion"的精髓：一次调度跑完整个注意力块，NPU 几乎不需要来回搬运中间张量。

在 Token 阶段算子属性中还能看到total_seq_len: 4096——4K 上下文窗口在算子层面被硬编码进 NPU 内核。

Prefill 与 Token：双流水线的 4K 设计

大文件名的前缀藏着推理的两阶段设计：

• Llm_Prefill_*：预填充阶段，一次性处理整段提示词，按sequence_length_padded生成 128/256/512/…/4096 共 10 档填充规格；
• Llm_Token_*：解码阶段，逐 token 生成，按attention_mask_padded生成 256/512/…/4096 共 7 档规格。

对应的元数据文件采用三件套结构，例如：

• dd_metastate_Llm_Prefill_modellayers.0input_layernormMLADFRMSNORM_sequence_length_padded_4096_.meta
• dd_metastate_Llm_Token_Token_modellayers.0input_layernormMLADFRMSNORM_attention_mask_padded_4096_.ctrlpkt
• 同名.super文件：NPU 执行上下文

其中.meta为算子/状态元数据、.ctrlpkt为控制包、.state为运行时状态表（如 dd_metastate_Llm_Prefill_modellayers.0input_layernormMLADFRMSNORM.state），.fconst则是常量表。这些大文件在 .gitattributes 中被配置为 Git LFS 存储——下载前请确保 LFS 已启用，否则拿到的是指针文件。

💡为什么分档？NPU 偏好定长张量。把输入填充（padding）到预设档位，可以命中预编译的 NPU 内核，避免每次动态 shape 重新编译，从而大幅降低首 token 延迟。

部署配置解析：genai_config.json 与 rai_config.json

运行时的"总开关"在 genai_config.json：

• session_options.provider_options中指定了"RyzenAI": { "hybrid_opt_token_backend": "npu" }，即解码阶段优先把 token 计算下放到 NPU 后端；
• inputs/outputs声明了input_ids、attention_mask、past_key_values.%d.key等标准 ONNX GenAI 张量接口；
• search段给出默认采样策略：temperature: 0.6、top_k: 50、top_p: 0.9，与 generation_config.json 保持一致；
• max_length: 4096再次呼应 4K 上下文上限。

而 rai_config.json 描述了Ryzen AI 驱动版本与最大提示长度的兼容矩阵：

也就是说，想要完整发挥 4096 长上下文，需要 Ryzen AI 1.6.0 或更高版本；在旧版驱动下会自动回落到 2048。项目名中的ra_1.8.0正表明本包面向 1.8.0 时代的 NPU 运行时。

上手部署与使用建议

1. 环境要求：AMD Ryzen AI 300 系列 APU 设备，安装 1.8.0 左右的 Ryzen AI 驱动与运行时（hybrid OGA 部署路径可参考 AMD Ryzen AI 官方文档，README 已给出指引）；
2. 加载模型：使用 ONNX Runtime GenAI 创建 session，指定本目录的 model.onnx 与genai_config.json，权重会自动从 model.onnx.data 读取；
3. 喂入长文本：提示词控制在 4096 以内可获得最佳性能；超过档位（如 2304）会自动向上填充到 256 的倍数；
4. 调优采样：改写search段即可，无需重新导出模型。

总结：4K Full Fusion 的设计哲学

这个模型包展示了端侧长上下文推理的完整思路：AWQ 4-bit 量化压低体积 → ONNX GenAI 标准化接口 → 双阶段（Prefill/Token）算子全融合 → padding 分档命中预编译内核 → KV Cache 并入 MHA 算子。最终让一台 APU 上的 NPU 能从容处理 4096 token 的提示词。

如果你想深入细节，建议按以下顺序阅读仓库文件：config.json（量化与结构）→ genai_config.json（运行时会话）→ rai_config.json（版本兼容）→ cache/ 目录 下的两份_meta.json（融合算子蓝图）→ 根目录dd_metastate_*（NPU 运行时元数据）。

提示：模型受 Llama 3.2 许可与 USE_POLICY.md 使用政策约束，商用前请确认授权范围。