LensVLM-9B 是 Apple 发布的一款 9B 参数规模的视觉语言模型（VLM），其核心思路是先"浏览"文本的压缩页图像，再借助习得的工具（learned tools）只把与问题相关的页面选择性扩展回未压缩形式，从而在极低视觉 token 开销下完成长文档问答。本篇指南以本仓库（HuggingFace 模型镜像）中的 README.md 为骨架，结合 config.json、processor_config.json、chat_template.jinja 等模型配置文件，带你完整理解其架构设计与压缩-扩展推理范式，并给出可复现的安装、推理命令与压缩比参数说明。读完本文，你将掌握 LensVLM-9B 的模型结构、预处理管线、对话模板机制，以及如何对其输入自定义文档并调节5x / 10x / 15x压缩比完成长文本视觉问答。

一、模型概述：从"压缩浏览"到"选择性扩展"

LensVLM is a 9B Vision Language Model (VLM) that scans compressed images of text, then selectively expands only the relevant pages to their uncompressed form via learned tools.

这是 README.md 对 LensVLM 的一句话定义，也是理解整个模型的钥匙：

1. 压缩浏览（Compressed Scan）：输入不是整篇长文，而是把文本渲染、压缩成页面图像（page images），模型以图像方式"扫一遍"全文，视觉 token 开销被大幅压低；
2. 选择性扩展（Selective Expansion）：模型在浏览过程中通过习得的工具调用判断"哪些页面与当前问题相关"，仅将这些页面解压回未压缩文本并纳入上下文；
3. 按需扩容（Context Expansion）：最终送入解码器的上下文是由"压缩全景 + 少量被选中的全文页"组成，兼顾信息完整性与上下文长度控制。

该模型配套论文为LensVLM: Selective Context Expansion for Compressed Visual Representation of Text（arXiv:2605.07019），配套推理代码单独发布在官方 ml-lensvlm 仓库（链接见 README 的 Code 一节）。

本仓库是模型权重卡仓库，即模型权重的托管镜像，包含 README.md、config.json、generation_config.json、processor_config.json、tokenizer.json、tokenizer_config.json、chat_template.jinja、model.safetensors 以及 LICENSE、NOTICE、ACKNOWLEDGEMENTS 等法律与致谢文件。注意：推理脚本并不在本仓库内，而是位于官方 ml-lensvlm 代码仓库，使用时需按下文"安装与推理"一节操作。

二、仓库文件速览与定位

从文件大小可以推断，本镜像中的model.safetensors（136 字节）与tokenizer.json（133 字节）均为 git-lfs 指针占位文件，实际权重与词表由 Transformers 在加载模型时按需从托管仓库下载，因此推理环境需要具备网络访问能力。

三、模型架构与关键配置解析（config.json）

config.json 声明了model_type: "qwen3_5"、架构类Qwen3_5ForConditionalGeneration，权重精度bfloat16，由 Transformers 5.2.0 序列化。根据 NOTICE 的声明，模型架构、hidden size、层数、层类型与词表大小均与上游 Qwen3.5-9B 保持一致，Apple 的修改集中在权重微调与推理相关配置上。

3.1 文本端（text_config）：32 层混合注意力

文本端关键参数如下：

layer_types数组给出了 32 层的具体排布：共24 个linear_attention层 + 8 个full_attention层，全注意力层位于第 4、8、12、16、20、24、28、32 层（即每隔 4 层一个，索引从 3 开始）。这种"线性注意力为主、稀疏全注意力兜底"的混合结构正是 Qwen3.5 系列面向超长上下文的设计：线性注意力层具备linear_conv_kernel_dim: 4、linear_num_key_heads: 16、linear_num_value_heads: 32、linear_key_head_dim: 128、linear_value_head_dim: 128等参数，并以mamba_ssm_dtype: "float32"计算 SSM 部分。

位置编码方面，rope_parameters采用mRoPE（多模态旋转位置编码）：mrope_interleaved: true、mrope_section: [11, 11, 10]（文本/图像高度/图像宽度三段各 11/11/10 维）、rope_theta: 10000000、partial_rotary_factor: 0.25。这与视觉输入的空间坐标编码直接相关——图像 token 拥有独立的行、列位置分量，使模型能感知"页面上文字的空间布局"，这正是"扫描压缩页图像"的底层基础。

3.2 视觉端（vision_config）：27 层视觉编码器

视觉端（model_type: "qwen3_5"）关键参数：

也就是说：16×16 patch 切分 → 2×2 空间合并 → 经 27 层编码器 → 投影到 4096 维与文本隐层对齐。这套视觉子网与 Qwen2.5-VL/Qwen3 系列同源，保证了处理超高分辨率页面图像时的效率（结合 processor 的max_pixels限制，见下文）。

3.3 多模态特殊 token

config.json与 tokenizer_config.json 共同定义了以下多模态标记（token id 见 config）：

对话中图像被渲染为<|vision_start|><|image_pad|><|vision_end|>的 token 序列，由 chat 模板自动插入（见第六节）。

四、长上下文设计与压缩页渲染

LensVLM-9B 的文本端max_position_embeddings为262144（256K）tokens，tokenizer_config.json 中的model_max_length同样为 262144，这说明模型原生支持超长输入。但"能支持长上下文"不等于"每个 token 都值得付账"——这正是 LensVLM 压缩浏览范式的动机：

• 不把整篇文档的全文逐字送入，而是先把文档按页渲染为图像并压缩，让模型以极少的视觉 token 获得全文"版面级"概览；
• 解码过程中，模型通过工具调用挑选与问题相关的页面，将选中的页面扩展为未压缩文本，进入上下文；
• 于是长文档问答的 token 成本 ≈ 压缩页图像 token + 少数相关页的全文 token，远低于全量长上下文。

NOTICE 明确写道，model.safetensors是 Apple "为压缩页面图像上的选择性上下文扩展（selective context expansion over compressed page images）而微调"的权重，而 processor_config.json 则是 "为压缩页渲染（compressed-page rendering）设定的图像/视频预处理默认值"——配置文件与模型卡互为印证。

五、安装与推理：从默认 Demo 到自定义文档

以下命令全部继承自 README.md 的 Usage 一节，可直接复现。

5.1 环境准备

LensVLM 的推理代码不在本权重仓库内，需先获取官方 ml-lensvlm 代码仓库（README 的 Code 一节给出了仓库地址）：

git clone https://github.com/apple-aiml-research/ml-lensvlm cd ml-lensvlm pip install -r requirements.txt

随后通过 Transformers 从模型仓库加载apple/LensVLM-9B权重（首次运行会自动下载权重与词表，请确保网络可用）。注意：模型权重受 LICENSE 约束，仅限非商业研究用途，使用前请阅读许可条款（见第八节）。

5.2 运行默认 Demo

python scripts/run_demo.py --model apple/LensVLM-9B

该命令会加载模型并运行内置演示，用于快速验证环境与推理链路是否打通。

5.3 对自定义文档提问

python demo.py \ --model apple/LensVLM-9B \ --text_file document.txt \ --question "What is the main finding?" \ --compression 10x

各参数含义：

5.4 压缩比选项：5x / 10x / 15x

README 明确给出三档压缩选项：5x、10x、15x。可以推断：

• 压缩比越高（如 15x），单页图像占用的视觉 token 越少，浏览全文的 token 成本越低，但页面细节损失越大，对"压缩图像中可读信息"的依赖越强；
• 压缩比越低（如 5x），页面细节保留更完整，视觉 token 开销相应上升；
• 实际使用时建议针对文档类型与问题粒度做小规模对比实验：版面复杂、数字密集的文档可先用低压缩比，纯文本长文可尝试高压缩比。

数据准备与评测的详细流程（包括页面渲染脚本、评测集组织方式等）在官方 ml-lensvlm 仓库 README 中有完整说明，可结合使用。

六、图像与视频预处理配置（processor_config.json）

processor_config.json 定义了输入侧预处理，processor_class为Qwen3VLProcessor，图像处理器为Qwen2VLImageProcessorFast。关键图像参数：

这些默认值直接服务于压缩页渲染：max_pixels限制单页图像规模，保证超高分辨率页面被缩放到模型可接受的范围；patch_size与merge_size则决定了每页图像最终产生的视觉 token 数量。视频处理器（Qwen3VLVideoProcessor）还提供fps: 2、max_frames: 768、min_frames: 4等帧采样默认值。

七、生成配置与解码默认值（generation_config.json）

generation_config.json 由 Apple 设定，作为解码默认值：

• eos_token_id: [248046, 248044]：<|im_end|>与<|endoftext|>均作为结束符；
• pad_token_id: 248044；
• use_cache: true：推理时启用 KV cache（与 config.json 中训练用的use_cache: false形成对比，同一模型在训练与推理阶段采用不同 cache 策略）。

八、对话模板与提示格式（chat_template.jinja）

chat_template.jinja 与上游 Qwen3.5 逐字节一致（NOTICE 声明其未修改），承担多模态消息的组装工作，值得关注的行为包括：

• 图像/视频占位：消息中的图像被渲染为<|vision_start|><|image_pad|><|vision_end|>；当开启add_vision_id时，会自动追加Picture N:前缀用于编号定位；
• 系统消息约束：系统消息中不允许包含图像或视频（会直接抛异常），且必须位于消息序列开头；
• 思考模式（thinking）：add_generation_prompt开启后，模板会以<|im_start|>assistant\n<think>\n结尾引导模型先推理；enable_thinking=false时则输出空的<think>\n\n</think>块，实现"关闭思考"；
• 工具调用格式：若消息携带tools，模板会注入# Tools系统指令，并规定<tool_call><function=...>...</function></tool_call>的 XML 调用格式。这一机制与 LensVLM"选择性扩展页面"的习得工具直接相关——模型正是通过工具调用请求解压相关页面。

九、许可、致谢与合规要点

LensVLM-9B 的许可结构分为两层（详见 LICENSE 与 NOTICE）：

1. 模型权重：受Apple Machine Learning Research Model License约束。该许可授予个人、非独占、不可转让、可撤销的非商业研究用途许可（"Research Purposes" 指以推进科学知识为目的的实验、分析、测试，明确排除商业产品开发与商业服务）；再分发时须附带协议副本并保留归属声明。
2. 源代码：官方 ml-lensvlm 推理代码另行发布，遵循Apple Sample Code License。

同时，NOTICE 与 ACKNOWLEDGEMENTS 声明：

• LensVLM-9B 权重是Qwen3.5-9B（Apache License 2.0，Copyright 2026 Alibaba Cloud）的衍生作品，Apple 的修改被明确标记为 "NOT A CONTRIBUTION"；
• 修改涉及：model.safetensors（为压缩页选择性扩展微调）、config.json（以新版 Transformers 重序列化并更新训练/推理设置，但架构、hidden size、层数、层类型、词表大小不变）、tokenizer.json/tokenizer_config.json（重序列化，词表逐字节一致）、generation_config.json/processor_config.json（Apple 设定的解码与预处理默认值）；
• chat_template.jinja未修改；页面渲染使用的 DejaVu 字体等第三方材料在 ACKNOWLEDGEMENTS 中致谢。

因此在研究引用与合规使用前，请完整阅读上述三个文件，确认你的使用场景符合 Apple 研究许可的限制。

十、引用与延伸阅读

若在你的研究或论文中使用了 LensVLM-9B，请按 README.md 提供的方式引用：

@article{xie2026lensvlm, title={LensVLM: Selective Context Expansion for Compressed Visual Representation of Text}, author={Xie, Roy and Friedman, Dan and Yu, Donghan and Pan, Bowen and Fifty, Christopher and Kim, Jang-Hyun and Du, Xianzhi and Gan, Zhe and Rathod, Vivek and Dhingra, Bhuwan}, journal={arXiv preprint arXiv:2605.07019}, year={2026} }

进一步深入可依次阅读本仓库中的 config.json（架构细节）、processor_config.json（压缩页预处理）、chat_template.jinja（工具调用与思考格式）以及 NOTICE（修改声明），再结合官方 ml-lensvlm 代码仓库的demo.py、scripts/run_demo.py与requirements.txt复现完整推理流程。