mlx_vlm.generate参数参考：Unlimited-OCR-2-bf16 API完整清单与调用示例

Unlimited-OCR-2-bf16 是把百度 Unlimited-OCR-2 文档解析模型转换为 MLX bfloat16 权重的 OCR 视觉语言模型，本文整理 mlx_vlm.generate 命令的完整参数清单与调用示例，覆盖单页/多页文档解析和 Python 推理 API，帮你快速上手。

📦 模型简介：Unlimited-OCR-2-bf16 是什么

Unlimited-OCR-2-bf16 面向文档级 OCR 场景：输入扫描页图片，输出带版面结构（文本块、坐标、公式、表格）的结构化标记。它的核心特点包括：

• bfloat16 未量化权重：SAM 与 CLIP 双视觉塔、逐层 DASH 稀疏注意力路由全部保持 bfloat16 精度，总权重约 6.7GB，见 model.safetensors.index.json
• MoE 语言塔：12 层、64 个路由专家的 DeepSeek-V2 结构，支持 128K 上下文，配置见 config.json
• DASH 块稀疏注意力 + page2d RoPE：专为长文档多页解析设计，实现见 dash_attention.py

⚠️ 环境提示：Unlimited-OCR-2 的支持（page2d RoPE 与 DASH 块稀疏注意力）正在合并进 mlx-vlm 主干。正式发布前，需要安装包含该支持的 mlx-vlm 分支版本，具体安装说明见 README.md。

⚙️ mlx_vlm.generate 参数完整清单

mlx_vlm.generate 是这个模型的标准推理入口，核心参数一览：

参数	说明	推荐值 / 示例
--model	MLX 模型名称或本地路径	mlx-community/Unlimited-OCR-2-bf16
--image	输入图片路径，支持多张（每页一张）	page.png、p1.png p2.png
--prompt	解析指令；不写 <image> 占位符时会自动按页拼装	"Multi page parsing."
--max-tokens	最大生成 token 数，多页需放大	单页 8192，多页 16384
--temperature	采样温度；0 为贪心解码，OCR 场景推荐	0
--seed	随机种子，固定可复现结果	42
--hf-upstream	指定上游 Hugging Face 原始模型，可选	默认自动识别
--cache-dir	模型下载缓存目录，可选	—
--max-image-size	限制输入图片最大尺寸（像素），可选	—

💡 想看当前安装版本的完整参数列表，随时运行 mlx_vlm.generate --help。

图像预处理由 processor_config.json 控制：候选分辨率 1024×1024、patch_size 为 16、downsample_ratio 为 4、最多 16 个局部裁剪（max_crops）。

🚀 快速上手：调用示例

单页解析（gundam 模式：1024 全局视图 + 最多 16 个局部裁剪）

mlx_vlm.generate --model mlx-community/Unlimited-OCR-2-bf16 --image page.png \
    --prompt "Multi page parsing." --max-tokens 8192 --temperature 0

多页解析（一次请求多张图，每页一个 1024 基础视图）

mlx_vlm.generate --model mlx-community/Unlimited-OCR-2-bf16 --image p1.png p2.png \
    --prompt "Multi page parsing." --max-tokens 16384 --temperature 0

多页输出中，跨页延续的内容块会用 cross_* / append_* 标签衔接，上游仓库提供了转 Markdown 的转换器。

🐍 Python 推理 API：model.infer 参数说明

仓库内还内置了与 vLLM 部署行为对齐的 Python 推理入口 modeling_unlimitedocr.py，方便你直接嵌入自己的脚本：

model.infer(
    tokenizer,
    prompt="Multi page parsing.",
    image_file="page.png",   # 单页传字符串；多页传路径列表
    temperature=0.0,
    max_length=131072,
    max_page_tokens=20000,
    save_results=True,
    output_path="./out",
)

主要参数含义：

参数	说明
prompt	指令文本；无 <image> 占位符时自动按页构造布局
image_file	图片路径 / PIL 图像，多页传列表（按页序）
crop_mode	None 自动选择（单页 gundam 裁剪 / 多页基础视图）；True/False 强制指定
temperature	0 贪心解码，非零时按 softmax(logits/T) 采样，见 modeling_unlimitedocr.py
max_length	全局长度上限，默认 131072
max_new_tokens	新生成 token 上限，不传则取 max_length - 提示长度
page_count_guard	页码守卫：输出页数与输入页数一致，默认开启
max_page_tokens	单页输出 token 上限，默认 20000
no_repeat_ngram_size / ngram_window	可选的重复 n-gram 抑制
dash_topm	解码期 DASH 路由保留的块数，默认 16
save_results / output_path	生成标注框图与 Markdown 结果文件
return_dict	返回含 token_ids、finish_reason、耗时等信息的字典

对话模板（<|User|> / <|Assistant|> 角色）定义在 conversation.py，Jinja 版本见 chat_template.jinja。

📄 输出格式解析：如何看懂生成结果

生成结果使用结构化标记，常见标签：

• <PAGE>：页分隔，多页解析时按页输出
• <BLOCK>label[x0, y0, x1, y1]<FORK>text：文本块标签 + 坐标 + 内容
• cross_* / append_*：跨页延续的块，表示内容从上一页接续

设置 save_results=True 后，脚本会把每页的标注框图、result.md 与原始输出 result_raw.md 写入 output_path，逻辑见 modeling_unlimitedocr.py。

❓ 常见问题（FAQ）

Q1：运行 mlx_vlm.generate 报错或不识别模型？ Unlimited-OCR-2 需要带 page2d RoPE 与 DASH 支持的 mlx-vlm 分支版本，请确认已按 README.md 说明升级安装。

Q2：为什么示例都设置 --temperature 0？ OCR 解析追求确定性与可复现性，贪心解码（temperature=0）能避免随机采样引入的解析波动；如需复现实验结果，再配合 --seed 固定种子。

Q3：--max-tokens 怎么设置？ 单页建议 8192，多页按页数放大（示例为 2 页 16384），避免截断导致后续页缺失。

Q4：想检查模型结构参数？ 查看 config.json 与 generation_config.json，MoE 专家数、稀疏注意力配置（sparse_topk_blocks、dash_topk_blocks 等）都在其中。

小结

• 命令行入口 mlx_vlm.generate：用 --model、--image、--prompt、--max-tokens、--temperature 五个参数即可完成单页/多页文档解析
• Python 侧用 model.infer()，支持裁剪模式、页码守卫、结果落盘等更细粒度控制
• 输出为 <PAGE>/<BLOCK> 结构化标记，可直接交给上游 Markdown 转换器
• 关键配置：config.json、processor_config.json、README.md

按以上参数清单调整你的解析任务，即可在 MLX 后端上稳定运行 Unlimited-OCR-2-bf16。