vision_artifact.py 机制深度解读:Ternary-Bonsai-2-2B-mlx-2bit 如何为 FP16 视觉塔与三值语言模型搭建桥梁
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 里有两处刻意的设计:
- 不用
AutoProcessor自动探测:因为包的model_type是自定义的prism_hadamard_qwen35,自动解析认不出来;而且默认路径会拉进 torch 依赖。这里显式指定 PIL 后端的Qwen2VLImageProcessorPil,让整条视觉输入路径只依赖 numpy 和 Pillow(见 vision_artifact.py 的注释与实现)。 - 终止符"双保险":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 混合权重包的加载逻辑。