从 Wan2.2 到 MLX：AnimeGen-I2V-A14B-Lightning-bf16 的 bf16 转换流程与键名映射实战复盘

AnimeGen-I2V-A14B-Lightning-bf16是一套面向Apple Silicon（MLX）的**动漫图生视频（Image-to-Video）**模型权重，基于Wan2.2-I2V-A14B双专家 MoE 结构，已完成bf16精度转换、**键名映射（key mapping）**与Lightning 少步合并，可直接跑4 步、CFG-free的快速生成。本文带你复盘这套权重"从原始 Wan2.2 到 MLX 可运行"的完整转换链路。

这套权重到底能做什么？

简单说：给一张动漫风格首帧图，它能在 Apple 芯片（M 系列 Mac）上用 MLX 框架把它变成一段短视频。

它的三个卖点正好对应三个工程决策：

• 🎬动漫专精：在 Wan2.2-I2V-A14B 基础上做过动漫图生视频微调，出片更贴近日系动漫质感；
• ⚡少步加速：权重已离线合并Lightning LoRA，只需4 步采样、无需 CFG，出片速度大幅提升；
• 🍎原生 MLX：把原始 HuggingFace 权重转成 MLX 可直接加载的bf16格式，键名也对齐了 A14B 的契约，即插即用。

这套权重是为 Swift-MLX 的wan-core/ Bernini-R 运行时构建的。如果你希望占用内存更小，项目还提供了int4 量化版（见文末）。

仓库里有什么：5 个文件一览

打开仓库，你会看到 4 个.safetensors权重文件 + 1 个 config.json。下表是各文件的作用与实测体积（bf16 下每参数 2 字节）：

按 bf16 每参数 2 字节反推，单个 DiT 专家约143 亿（≈14.3B）参数，文本编码器约57 亿参数。全部载入内存约69 GB，因此建议选用高统一内存（≥64 GB）的 Apple Silicon 机型运行。

核心配置解读：读懂 config.json

config.json 描述了模型结构与默认采样参数，理解它有助于你正确调用模型。关键项如下：

其中dual_model: true+boundary: 0.875是 Wan2.2 "A14B" 的双专家设计核心：高噪阶段与低噪阶段由两个专家分别负责，boundary决定何时切换。

图生视频的"通道拼接"原理（in_dim=36）

这是新手最容易困惑的地方：它没有单独的 CLIP 图像编码器，而是把图像信息直接"拼"进潜变量里。

具体地，DiT 的输入是36 通道（见 README.md）：

[ 噪声潜变量(16) + 时间掩码 mask(4) + 图像潜变量(16) ] = 36 通道

工作流程：

1. 构造一段视频，第一帧是条件图像，其余帧全零；
2. 通过 16 通道的 WanVAE 编码得到z_video(16)；
3. 构造首帧时间掩码mask(4)，合成y = [mask, z_video] = 20通道；
4. 每个去噪步都把y拼到 16 通道噪声潜变量上，y在所有步保持不变。

这也是为什么 config.json 里in_dim是36而不是普通视频模型的 16。

实战复盘一：bf16 转换流程

从原始模型到可运行的 MLX 权重，核心是四步：

1. 取原始权重：以aidealab/AnimeGen-I2V（动漫微调版）为蓝本，其基座是Wan-AI/Wan2.2-I2V-A14B；
2. 键名映射（sanitize）：把原始 Wan 的键名规范化，使键集合严格等于 A14B 的 1095-key 契约（见下一节）；
3. 精度统一为 bf16：将所有专家/编码器/VAE 权重以 bfloat16 存储，兼顾精度与 Apple Silicon 的内存效率；
4. 分专家落地：高噪、低噪两个专家各自独立转换，保持dual_model结构不变。

整个过程追求1:1 还原——不改结构、不丢键，只做"键名规范化 + 精度对齐 + 框架适配"，确保 MLX 侧加载后行为与原始模型一致。

实战复盘二：键名映射（key mapping）为什么关键？

不同框架（PyTorch / diffusers / MLX）对同名张量的键名命名习惯经常不一致：前缀、下划线、模块层级都可能不同。如果键名对不上，加载时就会出现"张量缺失 / 权重没生效"这类隐蔽错误。

本项目的做法（见 README.md）：

• 原始 Wan 键名 → sanitize：对每个键做统一清理，去掉框架差异前缀、规范层级；
• 契约校验：以A14B 的 1095 个键作为"标准答案"，转换后逐一对齐，保证键集合完全一致；
• 逐专家处理：高噪、低噪专家分别独立校验，避免跨专家串键。

💡 复盘要点：做跨框架权重转换时，"键集合 == 目标契约"是比"文件能打开"更重要的正确性指标。建议转换后做键名 diff，确认无缺失、无多余键。

实战复盘三：Lightning LoRA 离线合并

"少步 + CFG-free" 的能力来自Lightning 蒸馏 LoRA的离线合并（见 README.md）：

• 采用lightx2v的Wan2.2-I2V-A14B-4steps-lora-rank64蒸馏 LoRA；
• 在转换阶段逐专家离线合并进主干权重：set_adapters([high, low], [1.0, 1.0])，权重系数均取 1.0；
• 合并后无需运行时再挂 LoRA，直接把"少步能力"烤进 bf16 权重里。

这就是文件名里的Lightning含义——出厂即可快速出片，省去推理时的额外 LoRA 加载开销。

推荐推理配方（few-step + CFG-free）

配合上述权重，官方模型卡推荐的推理参数（见 README.md）：

帧数公式16·seconds + 1例如 5 秒 → 81 帧，正好与 config.json 的frame_num: 81对应；且 81 = 4×20+1，符合 4n+1 约束。

如何获取这套权重？

权重体积较大（约 69 GB），通过 Git LFS 分发。在可联网环境下，可用下面的仓库地址拉取完整文件：

git lfs install git clone https://gitcode.com/hf_mirrors/mlx-community/AnimeGen-I2V-A14B-Lightning-bf16

拉取后确认 4 个.safetensors均为真实文件（而非 LFS 指针文本），再交给 Swift-MLX 的wan-core/ Bernini-R 运行时加载即可。

常见问题（FAQ）

Q1：为什么有 high / low 两个模型文件？因为 Wan2.2-A14B 采用双专家 MoE，高噪与低噪阶段各用一个专家，boundary: 0.875控制切换。两者都不可或缺。

Q2：bf16 和 int4 版怎么选？内存充足、追求最高画质用bf16（本文这套）；统一内存紧张、想降低显存占用则选int4 量化版，代价是会有轻微精度损失。

Q3：需要单独的图像编码器吗？不需要。本项目用通道拼接（in_dim=36）把图像潜变量直接并入 DiT 输入，没有独立的 CLIP 图像编码器。

Q4：能在非 Mac 设备上跑吗？这套权重是MLX（Apple Silicon）专用格式，主要面向 M 系列芯片；其他平台请使用原始的 diffusers 权重。

小结

AnimeGen-I2V-A14B-Lightning-bf16把一个复杂的"原始 Wan2.2 → 可用 MLX 权重"转换过程，浓缩成了 4 个可复用的经验：

1. 键名映射以目标契约（1095-key）为准做 1:1 校验，保证正确性；
2. 精度统一到 bf16，兼顾精度与 Apple Silicon 内存效率；
3. Lightning LoRA 离线合并，出厂即 4 步、CFG-free；
4. **通道拼接（in_dim=36）**实现无 CLIP 的图像条件化。

掌握这条链路后，你就能把它作为模板，复用到其他"Wan2.2 → MLX"的图生视频模型转换中。