vision_artifact.py 机制深度解读:Ternary-Bonsai-2-2B-mlx-2bit 如何为 FP16 视觉塔与三值语言模型搭建桥梁

原创2026-11-12 21:51:281,707 阅读
文章标签:人工智能大模型多模态模型量化本地部署计算机视觉

vision_artifact.py 机制深度解读:Ternary-Bonsai-2-2B-mlx-2bit 如何为 FP16 视觉塔与三值语言模型搭建桥梁

vision_artifact.py 是 Ternary-Bonsai-2-2B-mlx-2bit 这个 1.20 GB 视觉语言模型包里的"桥接器":它负责把 2-bit 三值量化的语言模型与 FP16 原精度视觉塔装配进同一个 mlx-vlm 模型实例。本文面向新手,拆解它的四步加载流水线、旋转激活变换,以及 FP16 视觉特征如何无缝喂给三值语言模型。

🧩 为什么需要这座"桥":一个模型,两种权重格式

先看这个模型包的特殊之处:

部分 权重格式 精度 是否需要特殊处理
语言模型(~1.88B,24 层,hidden 2048) 三值 {−1, 0, +1},MLX 2-bit 分组存储(group 128) FP16 激活 ✅ 需要 Hadamard 旋转激活 + 量化矩阵乘
视觉塔(~0.33B,24 层 ViT,hidden 1024) 标准 Qwen 塔,未旋转 FP16 ❌ 原样直通即可

整个模型仅占 1.20 GB(同权重 FP16 语言模型约 3.8 GB)。省空间的代价是:语言模型的投影层权重预先做了 Hadamard 旋转、折叠进存储基(见 hadamard.json 中的 prism.hadamard.block_size: 512)。这意味着标准 MLX 加载器拿到它只能得到错误结果——运行时必须对激活值做匹配的旋转变换。

而视觉塔恰恰相反:它是官方原版、未旋转、未量化的 FP16 结构。于是加载器要同时伺候两种截然不同的权重——这正是 vision_artifact.py 存在的意义,它的思路只有一句话:

构建 mlx-vlm 标准的 qwen3_5 视觉语言模型,只把量化层装进语言模型,视觉塔保持直通。

🔄 加载流水线:load_vl_model 的四步

入口函数 load_vl_model 按顺序完成四步装配:

第 1 步:读配置、验身份 — 读取 config.json,确认三件事:model_type 必须是 prism_hadamard_qwen35、components.vision 为 true(这个包自带视觉塔;纯文本包应改用 artifact.py 的加载器)、base_model_type 是 qwen3_5(见 config.json 与 config.json)。任何一条不满足就直接报错拒绝加载。

第 2 步:搭好官方骨架 — 用配置构建完整的 mlx-vlm qwen3_5 视觉语言模型(vision_artifact.py),此时所有层(含视觉塔)都还是标准全精度层。

第 3 步:逐个换装 Packed 层 — 遍历 config.json 里 modules 清单中的 152 条记录。每条记录给出模块路径(如 model.layers.23.mlp.up_proj)和 Hadamard 块大小;加载器从 model.safetensors 取出对应的 weight(2-bit 编码)、scales、biases 三件套,加上可选的 signs 符号向量(见 vision_artifact.py),组装成 Packed 层,替换到语言模型的对应位置。

第 4 步:strict 加载兜底 — 最后以 strict=True 加载剩余全部权重(vision_artifact.py)。视觉塔的 FP16 权重就是在这一步原样填入的——vision_artifact 全程没有碰过它们,这就是"直通"的由来。

⚙️ Packed 层内部:先旋转激活,再做 2-bit 量化矩阵乘

Packed 层是整个机制的心脏,调用时分两条路径:

  • 投影层(150 个)前向路径:先对输入激活做前向 Hadamard 变换(fwht:升精度到 float32 → 乘以符号向量 signs → 按 512 大小的块做归一化 Hadamard 变换 → 转回 FP16),再执行 2-bit 分组量化矩阵乘 mx.quantized_matmul(Packed._linear),权重解码后严格等于三值 {−1, 0, +1}。
  • 嵌入层(1 个)逆向路径:查表取出词表行后做逆 Hadamard 变换(Packed.call),因为词表嵌入的存储形式也是旋转过的。

为什么激活要旋转?因为权重已经"预先旋转"存好了——数学上要求激活做匹配变换,两者相乘才等价于原始全精度模型。旋转元数据由 hadamard.json 统一描述:150 个投影权重走前向折叠(hadamard.json),嵌入层走逆向逆变换(hadamard.json),两组清单互不重叠。

👁️ 视觉塔直通:FP16 特征如何进入三值语言模型

视觉侧完全不需要任何变换:图像被切成 16×16 的 patch 逐块编码(config.json:24 层编码器、hidden 1024、2×2 空间合并),特征再映射到 2048 维,落在语言模型的嵌入空间里。

随后这些视觉 token 以 <vision_start> / <vision_end> 标记包裹着插入文本序列(对应 ID 在 config.json 中明确列出,image_token_id: 248056)。语言模型读到图像 token 位置时,走的就是它日常处理文本 token 的同一套三值权重 + 旋转激活路径——图文在 2048 维嵌入空间里彻底融为一体,桥也就搭通了。

🛠️ 处理器组装:为什么绕开 AutoProcessor

build_processor 里有两处刻意的设计:

  1. 不用 AutoProcessor 自动探测:因为包的 model_type 是自定义的 prism_hadamard_qwen35,自动解析认不出来;而且默认路径会拉进 torch 依赖。这里显式指定 PIL 后端的 Qwen2VLImageProcessorPil,让整条视觉输入路径只依赖 numpy 和 Pillow(见 vision_artifact.py 的注释与实现)。
  2. 终止符"双保险":generation_config.json 里列了两个结束 token(248046 和 248044),而 HF tokenizer 自己只认识其中一个。加载器优先采用文件里的完整清单构造 StoppingCriteria,让运行时在两个标记处都停,行为与 llama.cpp 跑同权重保持一致(vision_artifact.py)。

另外,chat_config 会把 model_type 临时换回 qwen3_5——因为 apply_chat_template 按 model_type 分支决定如何插入图像占位 token,用回基础类型图像占位才能正确落地。

🚀 快速上手:两条加载路线

路线 A:新版 mlx-vlm 原生加载(0.7.8+ 已原生支持该包):

from mlx_vlm import load, generate
from mlx_vlm.prompt_utils import apply_chat_template

model, processor = load("bonsai2-2b-mlx")
prompt = apply_chat_template(processor, model.config, "What is in this image?", num_images=1)
print(generate(model, processor, prompt, ["photo.jpg"], max_tokens=4096,
               temperature=1.0, top_p=0.95, top_k=20))

路线 B:内置加载器(旧版 mlx-vlm):

pip install -r runtime/requirements.txt
python quickstart.py "你的问题"

quickstart.py 内部检测 config.json 的 components.vision 字段,自动调用 load_vl_model 走视觉管线。注意:务必显式传采样参数(generation_config.json 推荐 temperature=1.0, top_p=0.95, top_k=20),否则 generate() 会退化成贪心解码。开思考模式时建议给输出预留至少 8192 个 token;quickstart.py 本身关闭思考、256 token 截断,只是冒烟测试。

📁 关键文件地图

文件 作用
config.json 模型类型、152 个量化模块清单(modules)、视觉配置与图像 token ID
hadamard.json Hadamard 旋转块大小(512)、符号向量与折叠权重清单
model.safetensors 2-bit 三值语言权重 + FP16 视觉塔,共 1.20 GB
generation_config.json 双终止符 ID 与采样参数
reload-validation.json 打包后重载验证日志:152 个模块、logits 精确一致
runtime/vision_artifact.py 本文主角:视觉版加载器
runtime/runtime.py Packed 层与 Hadamard 变换实现
runtime/artifact.py 纯文本包的加载/保存/校验
quickstart.py 一行命令冒烟测试
PACK-RUNTIME.md 内置加载器的使用契约与限制

总结

vision_artifact.py 用一条四步流水线——校验配置、搭标准 qwen3_5 视觉模型、换装 152 个三值 Packed 层、strict 加载 FP16 视觉塔——完成了"旋转基 2-bit 语言模型"与"原精度视觉塔"的合流。桥接的关键在于只改造语言模型侧:视觉塔保持 FP16 直通,图像特征以标准 vision token 形式进入嵌入空间,后续由三值权重 + Hadamard 旋转激活照常处理。理解了这个机制,你就掌握了 Ternary-Bonsai-2-2B-mlx-2bit 整套 1.20 GB 混合权重包的加载逻辑。

登录后查看全文
Ternary-Bonsai-2-2B-mlx-2bit