企业官网建设流程全解析

在 Qwen-2.5_1.5B_Instruct_rai_1.8.0_npu_4K 中，model.onnx.data（约 572 MB）存着 AWQ uint4 量化权重，而目录里那 52 个陌生的dd_metastate_文件，正是 AMD Ryzen AI NPU 推理加速的"动态形状编译缓存"。它们记录了模型在不同序列长度分桶下的 NPU 编译产物与调度信息，是首次推理免编译、毫秒级启动的关键。本文带你彻底看懂这套命名与文件结构。

📁 dd_metastate 文件全景：52 个文件都存了什么

本模型共含52 个dd_metastate_文件，按扩展名分为 5 类，按推理路径分为 Prefill（预填充）与 Token（解码）两组：

这些文件在 Git 仓库中均以 Git-LFS 指针形式存放（例如 model.onnx 本身也只是指向约 33 MB 数据的一个指针），clone 后需执行git lfs pull才能拿到真实内容。

🔎 命名规则逐段拆解：文件名就是缓存的索引键

以最典型的文件为例：

dd_metastate_Llm_Prefill_modellayers.0input_layernormMLADFRMSNORM_sequence_length_padded_1024_.meta

Prefill 路径覆盖128、256、512、768、1024、1536、2048、2304、3072、4096共 10 个长度桶；Token 路径覆盖256、512、1024、2048、3072、4096共 6 个桶——两者在 4096 处汇合，呼应了模型名中的 "4K" 上限（rai_config.json 中 RAI 1.6.0 及以上版本的max_prompt_length即为 4096）。

⚡ Prefill 与 Token 两阶段的缓存差异

两类缓存的体积特征截然不同，背后是两种阶段计算特点的差异：

• Prefill（长序列，计算密集）：.meta随桶变大单调增长——128 桶约 23 MB，1024 桶约 47 MB，4096 桶达102 MB。Attention 的计算量随序列长度近似平方增长，编译产物自然更大；.ctrlpkt全部为空，因为整图编译已把调度固化在.meta中。
• Token（单 token 解码，访存密集）：所有桶的.meta都稳定在约 2.17 MB（2167335 ~ 2167338 字节），形状变化几乎不影响体积；但每个桶额外携带8.7 ~ 8.9 MB 的.ctrlpkt控制包，供运行时在解码循环中重新组织内核调度。

两组还各配一个共享的大文件：.fconst存预格式化权重（Prefill 约 706 MB、Token 约 828 MB），.state则只是几百字节的状态表条目（如state_table_updates）。

🛠️ 运行时发生了什么：分桶匹配，免编译启动

动态形状编译缓存的工作流程可以概括为三步：

1. 构建期：OGA Model Builder 对 ONNX 图做 Full Fusion，针对上述每个长度桶预先编译 NPU 内核，产物落盘为.meta/.ctrlpkt/.fconst/.state；
2. 运行期：Ryzen AI 运行时（genai_config.json 中provider_options指定RyzenAI且hybrid_opt_token_backend: "npu"）收到输入后，把实际长度匹配到最近的 padding 桶；
3. 命中缓存：直接加载对应桶的编译产物执行，跳过耗时数秒甚至更久的即时编译（JIT）过程。

这也是为什么缓存文件与 NPU 硬件和 SDK 版本强绑定——换一个 NPU 或 Ryzen AI 版本，桶内二进制就不再通用。

📂 配套缓存文件：可读的算子图在 cache/ 目录

根目录之外，cache/ 目录还保留了构建阶段的完整算子图描述：

• cache/modellayers.0input_layernormMLADFRMSNORM_meta.json（约 1.1 MB）：Prefill 路径的算子列表，含MLADFRMSNORM、MladfMatMul（4-bit 量化矩阵乘，bits: 4、block_size: 128）、FLATMHA等 NPU 融合算子；
• cache/Token_modellayers.0input_layernormMLADFRMSNORM_meta.json（约 1 MB）：Token 路径对应的算子图；
• cache/txn_bins.zip（约 888 KB）：编译事务二进制包（LFS 指针）。

对照 config.json 可验证：28 层full_attention、12 个 attention head、2 个 KV head（GQA），与算子图中的GroupQueryAttention一一对应。

📌 使用建议清单

• 不要删除任何dd_metastate_*文件，它们是 NPU 快速启动的核心资产；
• 磁盘紧张时注意.fconst两个文件合计约1.5 GB，加上model.onnx.data约 572 MB，完整模型占用需预留 2 GB 以上；
• 若克隆后文件只有 133 字节左右，说明 LFS 未拉取，执行git lfs pull即可；
• 输入超过 4096 时，运行时会自动回落到 4096 桶或触发分块 Prefill，超长上下文（max_position_embeddings: 32768）依赖运行时策略而非额外的缓存桶；
• 修改部署上下文上限时，参考 rai_config.json 与 genai_config.json 中context_length、max_length的联动关系。

小结

dd_metastate文件并非"垃圾缓存"，而是NPU 动态形状编译缓存的完整索引：入口算子 + 形状桶 + 文件类型三要素唯一确定一份编译产物。理解它，你就能看懂 Ryzen AI 模型从 ONNX 到 NPU 落地的最后一块拼图，也能为自研 NPU 部署方案设计形状分桶策略提供参考。