拆解LightOnOCR-3-1B-mlx-8bit架构:Pixtral视觉塔与Qwen3语言模型如何融合

原创2026-10-18 15:28:181,626 阅读
文章标签:人工智能大模型本地部署计算机视觉多模态OCR

拆解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 中:

  1. Pixel Shuffle 下采样:pixel_shuffle() 把相邻 2×2 的 patch 特征在空间上"洗牌"合并——token 数量降为 1/4,通道数升为 4 倍(1024 → 4096),在压缩序列长度的同时保留细节。
  2. MLP 投影器:mlp1 是一个 LayerNorm(4096) → Linear(4096→1024) → GELU → Linear(1024→1024) 的四层网络,把图像特征投影到语言模型的词元空间。
  3. 特殊 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)。

🚀 快速上手: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 架构了。

登录后查看全文
LightOnOCR-3-1B-mlx-8bit