拆解LightOnOCR-3-1B-mlx-8bit架构:Pixtral视觉塔与Qwen3语言模型如何融合
拆解LightOnOCR-3-1B-mlx-8bit架构:Pixtral视觉塔与Qwen3语言模型如何融合
LightOnOCR-3-1B-mlx-8bit 是一款 10 亿参数级多模态 OCR 模型的 MLX 8bit 量化版本:它由 Pixtral 视觉塔负责"看图"、Qwen3 语言模型负责"写字",再通过一个 MLP 投影器完成两者之间的"翻译",让 Apple Silicon 也能高效跑通表格、表单等文档的文字识别任务。
下面带你快速拆解它的完整架构,看懂视觉编码器与语言模型到底是怎么"合体"的。
📊 整体架构一览:三大组件如何协作
整个模型是典型的 视觉编码器 + 投影器 + 语言模型 三段式多模态架构,推理数据流如下:
输入图片 → Pixtral视觉编码器(24层) → Pixel Shuffle下采样(4:1)
→ MLP投影器 → 替换为3025个图像token → Qwen3语言模型(28层) → 输出识别文本
| 组件 | 角色 | 规模 |
|---|---|---|
| Pixtral 视觉塔 | 图像特征提取 | 24 层 Transformer,hidden=1024 |
| MLP 投影器(mlp1) | 对齐图像特征与词元空间 | 4 层网络(含 Pixel Shuffle) |
| Qwen3 语言模型 | 自回归生成文本 | 28 层,hidden=1024,GQA 注意力 |
一个很巧妙的设计是:视觉塔和语言模型的 hidden_size 都是 1024,维度天然对齐,大幅降低了融合难度。
🔍 Pixtral 视觉塔:24 层图像编码器详解
视觉塔参数定义在 config.json 的 vision_config 字段中,model_type 明确标注为 pixtral:
| 参数 | 值 | 作用 |
|---|---|---|
num_hidden_layers |
24 | 视觉 Transformer 层数 |
patch_size |
14 | 图像切成 14×14 像素的块 |
image_size |
1540 | 长边最大 1540 像素,支持高分辨率文档 |
num_attention_heads |
16 | 注意力头数(head_dim=64) |
hidden_size |
1024 | 输出特征维度 |
rope_theta |
10000 | 旋转位置编码频率 |
以一张满尺寸 1540×1540 的图片为例:先被切成 110×110 = 12100 个 patch,经过 24 层编码器后,再由下采样压缩为 3025 个图像 token(vision_feature_layer 取 -1,即最后一层输出)。
⚙️ Qwen3 语言模型:28 层轻量 LLM
语言侧配置在 config.json 的 text_config 中,采用标准 Qwen3 结构(Qwen3ForCausalLM):
| 参数 | 值 | 说明 |
|---|---|---|
num_hidden_layers |
28 | 全部为 full_attention 层 |
hidden_size / intermediate_size |
1024 / 3072 | 主干与 FFN 宽度 |
num_attention_heads / num_key_value_heads |
16 / 8 | GQA 分组查询注意力,省 KV 显存 |
head_dim |
128 | 每头维度 |
vocab_size |
151936 | 与词表文件 tokenizer.json 对应 |
tie_word_embeddings |
true | 嵌入层与输出层权重共享,进一步瘦身 |
rope_theta |
1000000 | 支持 16384 上下文窗口 |
权重索引 model.safetensors.index.json 中可以看到 language_model.model.layers.0.* 下的 q_norm/k_norm(QK-Norm)与 SwiGLU MLP(gate_proj/up_proj/down_proj),都是 Qwen3 的标志性结构。
🔗 融合核心:Pixel Shuffle 下采样 + MLP 投影器
视觉特征和文本词元如何"无缝拼接"?答案在 modeling_llmjpvl.py 中:
- Pixel Shuffle 下采样:pixel_shuffle() 把相邻 2×2 的 patch 特征在空间上"洗牌"合并——token 数量降为 1/4,通道数升为 4 倍(1024 → 4096),在压缩序列长度的同时保留细节。
- MLP 投影器:mlp1 是一个
LayerNorm(4096) → Linear(4096→1024) → GELU → Linear(1024→1024)的四层网络,把图像特征投影到语言模型的词元空间。 - 特殊 token 替换:处理器在文本中插入特殊图像 token(定义见 constants.py),前向时 forward() 用投影后的视觉特征直接覆盖这些 token 的嵌入,再整串送入 Qwen3 自回归生成。
图像预处理由 processing_llmjpvl.py 的动态切块逻辑完成:按图片宽高比把大图切为若干 512×512 子块(参数见 preprocessor_config.json),每张图可产出 1~12 块,块数越多细节越足。
📦 8bit 量化:1.45GB 的轻量权重布局
该仓库是 config.json 中声明的 MLX 8bit 仿射量化版本(group_size: 64, mode: affine):每个 64 个权重共享一组缩放参数(这就是索引文件中成对出现的 .weight 与 .scales)。
- 总权重约 1.45GB(
total_size: 1452560384),8GB 内存的 Mac 即可流畅运行 - 权重分片存放在 model-00001-of-00002.safetensors 与 model-00002-of-00002.safetensors,MLX 运行时加载单文件 model.safetensors
🚀 快速上手:mlx-vlm 一条命令推理
安装依赖后,一条命令即可体验"图片进、文字出":
pip install -U mlx-vlm
python -m mlx_vlm.generate --model mlx-community/LightOnOCR-3-1B-mlx-8bit --max-tokens 100 --temperature 0.0 --prompt "Describe this image." --image <path_to_image>
采样参数参考 generation_config.json:推荐 temperature 0.2、top_p 0.9;做 OCR 场景建议像上面示例那样用 temperature 0.0 贪心解码,保证输出稳定。对话格式遵循 chat_template.jinja 模板,图像在文本流中以特殊 token 占位。
📁 关键文件导航
| 文件 | 说明 |
|---|---|
| config.json | 总配置:视觉塔 + Qwen3 + 8bit 量化参数 |
| configuration_llmjpvl.py | 组合式多模态配置类(视觉 + LLM 双子配置) |
| modeling_llmjpvl.py | 核心模型:特征提取、Pixel Shuffle、嵌入融合 |
| processing_llmjpvl.py | 动态切块处理器与 chat template 逻辑 |
| preprocessor_config.json | 图像预处理参数(512×512 切块规格) |
| processor_config.json | 多模态处理器:Pixtral 图像处理器 + spatial_merge_size: 2 |
| tokenizer.json | 词表与分词规则(151936 词表) |
| special_tokens_map.json | 特殊 token:图像占位符、对话角色标签 |
| constants.py | 图像占位符与对话通道的常量定义 |
| model.safetensors.index.json | 权重分片索引,可查每个参数所在文件 |
✅ 架构设计总结
- Pixtral 视觉塔(24 层、1540px 长边)专为高分辨率文档而生,表格细纹、小字号都不在话下
- Qwen3 语言模型(28 层、GQA、共享词嵌入)轻量且上下文达 16K,足以容纳整页文档
- Pixel Shuffle + MLP 投影器用 4:1 空间压缩换取短序列,是 1B 小模型也能处理大图的关键
- MLX 8bit 量化把体积压到 1.45GB,本地 Mac 即可离线部署 OCR 流水线
理解了这套"视觉塔 → 下采样 → 投影 → 语言模型"的融合范式,你就能读懂绝大多数 Pixtral / InternVL 风格的多模态 OCR 架构了。