在 Mac 上用 MLX-VLM 运行 PaddleOCR-VL文档 OCR、表格、公式与图表识别实战指南【免费下载链接】mlx-vlmMLX-VLM is a package for inference and fine-tuning of Vision Language Models (VLMs) on your Mac using MLX.项目地址: https://gitcode.com/GitHub_Trending/ml/mlx-vlm本指南以 MLX-VLM 仓库中 PaddleOCR-VL 集成文档 为核心系统讲解如何在 Apple Silicon Mac 上通过 MLX 框架本地推理 PaddlePaddle 出品的视觉语言模型 PaddleOCR-VL。读完本文你将掌握四类文档理解任务的 CLI 命令与 Python 调用方式理解 MLX-VLM 为其定制的处理器、动态分辨率切分与多模态位置编码原理并能在自己的文档处理流程中直接落地使用。PaddleOCR-VL 与 MLX-VLM 集成概览PaddleOCR-VL 是 PaddlePaddle 发布的面向文档理解的视觉语言 OCR 模型覆盖普通 OCR、表格识别、公式识别与图表理解等典型文档任务。MLX-VLM 为它在 MLX 运行时上提供了完整的推理支持集成工作由 mlx_vlm/models/paddleocr_vl/ 目录下的六个模块共同完成模块文件职责paddleocr_vl.py顶层Model组装视觉塔 语言模型图像特征与文本嵌入的合并processing_paddleocr_vl.py自定义PaddleOCRVLProcessor与ImageProcessor注册进 AutoProcessorvision.py视觉编码器Patch Embedding、2D RoPE、空间合并投影器language.py语言解码器MRoPE 旋转位置编码、图像/视频 token 的 3D 位置索引config.pyModelConfig/VisionConfig/TextConfig三份配置 dataclass其中处理器注册通过 paddleocr_vl.py 中的install_auto_processor_patch(paddleocr_vl, PaddleOCRVLProcessor)完成使得load(PaddlePaddle/PaddleOCR-VL)时能自动匹配到正确的预处理管线同时 prompt_utils.py 将paddleocr_vl映射为LIST_WITH_IMAGE_FIRST消息格式apply_chat_template会自动把图片放在对话首条消息并格式化提示词。环境安装与模型获取安装最新版 MLX-VLM 包pip install -U mlx-vlm首次运行时无需手动下载权重--model PaddlePaddle/PaddleOCR-VL会从 Hugging Face 拉取模型权重、tokenizer 与preprocessor_config.json。处理器加载图像几何参数的方式正是从该 JSON 文件中读取——详见 processing_paddleocr_vl.py 中from_pretrained的实现它逐个提取min_pixels、max_pixels、patch_size、temporal_patch_size、merge_size、image_mean、image_std等键缺失时回退到ImageProcessor的默认值。命令行推理四类文档任务基础 OCR纯文本提取uv run mlx_vlm.generate \ --model PaddlePaddle/PaddleOCR-VL \ --image /path/to/document.png \ --prompt OCR: \ --max-tokens 512 \ --temperature 0表格识别uv run mlx_vlm.generate \ --model PaddlePaddle/PaddleOCR-VL \ --image /path/to/table.png \ --prompt Table Recognition: \ --max-tokens 1024 \ --temperature 0公式识别uv run mlx_vlm.generate \ --model PaddlePaddle/PaddleOCR-VL \ --image /path/to/formula.png \ --prompt Formula Recognition: \ --max-tokens 512 \ --temperature 0图表理解uv run mlx_vlm.generate \ --model PaddlePaddle/PaddleOCR-VL \ --image /path/to/chart.png \ --prompt Chart Recognition: \ --max-tokens 1024 \ --temperature 0四个任务共用同一个模型与处理器仅通过提示词前缀区分任务类型。--temperature 0保证确定性输出适合表格、公式等对格式准确性要求高的场景表格与图表任务建议将--max-tokens放宽到 1024避免长结构化输出被截断。Python API在代码中集成CLI 底层对应的是mlx_vlm提供的load/generate/apply_chat_template三件套from mlx_vlm import load, generate from mlx_vlm.prompt_utils import apply_chat_template model, processor load(PaddlePaddle/PaddleOCR-VL) image [/path/to/document.png] prompt OCR: formatted_prompt apply_chat_template( processor, model.config, prompt, num_imageslen(image), ) result generate( modelmodel, processorprocessor, promptformatted_prompt, imageimage, max_tokens512, temperature0.0, ) print(result.text)关键点说明apply_chat_template基于MessageFormat.LIST_WITH_IMAGE_FIRST格式构造多模态消息图片 token 由处理器内部处理不要手动拼接|IMAGE_PLACEHOLDER|占位符详见下文“提示词注意事项”image参数接收路径列表本地路径与远程图片 URL 均可直接使用generate的max_tokens与temperature与 CLI 参数一一对应result.text即为解码后的最终输出文本。处理器与图像预处理原理MLX-VLM 为 PaddleOCR-VL 实现了 MLX 原生的 ImageProcessor其核心机制是动态分辨率切分smart resize避免把高分辨率文档图暴力压缩导致文字模糊。smart_resize 动态缩放smart_resize 保证缩放后图像的宽高均为patch_size * merge_size默认 14×228的整数倍同时把总像素数约束在[min_pixels, max_pixels]区间内并拒绝宽高比超过 200 的极端图像。默认参数参数默认值含义min_pixels147384缩放后最少像素数对应 384×384 左右max_pixels2822400缩放后最大像素数约 1680×1680patch_size14视觉 Patch 边长merge_size2空间合并粒度2×2 块合并image_mean/image_std0.5 / 0.5归一化均值与标准差rescale_factor1/255像素值缩放系数预处理流水线依次执行转 RGB → smart_resize 缩放 → 除以 255 → 按均值/标准差归一化 → 切成 14×14 Patch 并展平 → 输出pixel_values与image_grid_thw记录每张图t×h×w网格尺寸供视觉塔与位置索引使用。处理器与 tokenizer 的协作PaddleOCRVLProcessor 组合了图像处理器与AutoTokenizer其__call__会自动将文本中的|IMAGE_PLACEHOLDER|占位符替换为与图像 Patch 数量对应的|placeholder|序列数量为grid_t * grid_h * grid_w / merge_size²再替换回图像 token 后完成分词。这就是 README 强调“不要手动加占位符”的原因——重复或数量错误的占位符会破坏input_ids与视觉特征的一一对应。模型前向视觉特征如何注入语言模型顶层 Model 由VisionModel与LanguageModel组成get_input_embeddings定义了图像注入逻辑视觉塔对pixel_values编码得到视觉特征hidden_statesmerge_input_ids_with_image_features 定位input_ids中所有等于image_token_id配置值为 100295见 config.py的位置用视觉特征逐位替换文本嵌入计算 MRoPE 位置索引与 rope delta 并写入语言模型。视觉塔细节VisionModel 包含 27 层编码器隐藏维度 1152、16 头注意力见 VisionConfig。两个值得注意的实现点位置编码插值interpolate_pos_encoding用双线性插值把预训练的方形位置嵌入拉伸到任意h×w网格配合 2D 高度/宽度 RoPErot_pos_emb使模型可处理训练分辨率之外的文档图空间合并投影器PaddleOCRProjector先将 2×2 邻域 Patch 的特征拼接spatial_merge_size² × dim再经 LayerNorm → Linear → GELU → Linear 投影到语言模型维度 1024显著压缩视觉 token 数量多图场景通过cu_seqlens打包成单序列批量前向。语言模型与 MRoPELanguageModel 是 18 层、隐藏维度 1024、2 个 KV 头的 Qwen 风格解码器TextConfig。它使用 MRoPERotaryEmbedding 的sectioned_half_split风格mrope_section[16, 24, 24]将位置维度分成时间/高度/宽度三段分别编码多模态 token 的空间信息get_rope_index逐图像扫描vision_start_token_id101305之后的 token为图像区域生成 3D 位置 ID与视觉塔的网格坐标严格对齐。rope_theta500000与 131072 的max_position_embeddings为长文档提供了充足的位置容量。提示词注意事项Prompt NotesOCR:是纯文本提取的默认提示词适用于扫描件、截图中的文字识别其他内置任务提示词为Table Recognition:、Formula Recognition:、Chart Recognition:分别触发表格结构化输出、公式通常输出 LaTeX 形式与图表语义理解如需结构化提取可直接在提示词中给出任务指令或目标 schema模型会按指令约束输出格式使用apply_chat_template时通常不应手动添加图像占位符避免 token 计数错位输入既支持本地图片路径也支持图片 URL二者用法一致。小结与延伸阅读至此你已掌握 PaddleOCR-VL 在 MLX-VLM 上的完整推理路径CLI 一行命令跑通四类文档任务Python API 实现程序化集成并理解了从动态分辨率切分、空间合并投影到 MRoPE 位置编码的端到端实现原理。如需进一步深入处理器与注册机制的完整实现见 processing_paddleocr_vl.py模型配置项与默认值见 config.py视觉编码器与语言解码器源码见 vision.py 与 language.py集成说明的权威出处见 PaddleOCR-VL 官方文档若需了解提示词格式化如何作用于paddleocr_vl可查阅 prompt_utils.py。注意本指南基于当前仓库的集成实现模型行为以 Hugging Face 上PaddlePaddle/PaddleOCR-VL官方权重为准推理需 Apple Silicon Mac 且已正确安装 MLX 环境。【免费下载链接】mlx-vlmMLX-VLM is a package for inference and fine-tuning of Vision Language Models (VLMs) on your Mac using MLX.项目地址: https://gitcode.com/GitHub_Trending/ml/mlx-vlm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
在 Mac 上用 MLX-VLM 运行 PaddleOCR-VL：文档 OCR、表格、公式与图表识别实战指南
在 Mac 上用 MLX-VLM 运行 PaddleOCR-VL文档 OCR、表格、公式与图表识别实战指南【免费下载链接】mlx-vlmMLX-VLM is a package for inference and fine-tuning of Vision Language Models (VLMs) on your Mac using MLX.项目地址: https://gitcode.com/GitHub_Trending/ml/mlx-vlm本指南以 MLX-VLM 仓库中 PaddleOCR-VL 集成文档 为核心系统讲解如何在 Apple Silicon Mac 上通过 MLX 框架本地推理 PaddlePaddle 出品的视觉语言模型 PaddleOCR-VL。读完本文你将掌握四类文档理解任务的 CLI 命令与 Python 调用方式理解 MLX-VLM 为其定制的处理器、动态分辨率切分与多模态位置编码原理并能在自己的文档处理流程中直接落地使用。PaddleOCR-VL 与 MLX-VLM 集成概览PaddleOCR-VL 是 PaddlePaddle 发布的面向文档理解的视觉语言 OCR 模型覆盖普通 OCR、表格识别、公式识别与图表理解等典型文档任务。MLX-VLM 为它在 MLX 运行时上提供了完整的推理支持集成工作由 mlx_vlm/models/paddleocr_vl/ 目录下的六个模块共同完成模块文件职责paddleocr_vl.py顶层Model组装视觉塔 语言模型图像特征与文本嵌入的合并processing_paddleocr_vl.py自定义PaddleOCRVLProcessor与ImageProcessor注册进 AutoProcessorvision.py视觉编码器Patch Embedding、2D RoPE、空间合并投影器language.py语言解码器MRoPE 旋转位置编码、图像/视频 token 的 3D 位置索引config.pyModelConfig/VisionConfig/TextConfig三份配置 dataclass其中处理器注册通过 paddleocr_vl.py 中的install_auto_processor_patch(paddleocr_vl, PaddleOCRVLProcessor)完成使得load(PaddlePaddle/PaddleOCR-VL)时能自动匹配到正确的预处理管线同时 prompt_utils.py 将paddleocr_vl映射为LIST_WITH_IMAGE_FIRST消息格式apply_chat_template会自动把图片放在对话首条消息并格式化提示词。环境安装与模型获取安装最新版 MLX-VLM 包pip install -U mlx-vlm首次运行时无需手动下载权重--model PaddlePaddle/PaddleOCR-VL会从 Hugging Face 拉取模型权重、tokenizer 与preprocessor_config.json。处理器加载图像几何参数的方式正是从该 JSON 文件中读取——详见 processing_paddleocr_vl.py 中from_pretrained的实现它逐个提取min_pixels、max_pixels、patch_size、temporal_patch_size、merge_size、image_mean、image_std等键缺失时回退到ImageProcessor的默认值。命令行推理四类文档任务基础 OCR纯文本提取uv run mlx_vlm.generate \ --model PaddlePaddle/PaddleOCR-VL \ --image /path/to/document.png \ --prompt OCR: \ --max-tokens 512 \ --temperature 0表格识别uv run mlx_vlm.generate \ --model PaddlePaddle/PaddleOCR-VL \ --image /path/to/table.png \ --prompt Table Recognition: \ --max-tokens 1024 \ --temperature 0公式识别uv run mlx_vlm.generate \ --model PaddlePaddle/PaddleOCR-VL \ --image /path/to/formula.png \ --prompt Formula Recognition: \ --max-tokens 512 \ --temperature 0图表理解uv run mlx_vlm.generate \ --model PaddlePaddle/PaddleOCR-VL \ --image /path/to/chart.png \ --prompt Chart Recognition: \ --max-tokens 1024 \ --temperature 0四个任务共用同一个模型与处理器仅通过提示词前缀区分任务类型。--temperature 0保证确定性输出适合表格、公式等对格式准确性要求高的场景表格与图表任务建议将--max-tokens放宽到 1024避免长结构化输出被截断。Python API在代码中集成CLI 底层对应的是mlx_vlm提供的load/generate/apply_chat_template三件套from mlx_vlm import load, generate from mlx_vlm.prompt_utils import apply_chat_template model, processor load(PaddlePaddle/PaddleOCR-VL) image [/path/to/document.png] prompt OCR: formatted_prompt apply_chat_template( processor, model.config, prompt, num_imageslen(image), ) result generate( modelmodel, processorprocessor, promptformatted_prompt, imageimage, max_tokens512, temperature0.0, ) print(result.text)关键点说明apply_chat_template基于MessageFormat.LIST_WITH_IMAGE_FIRST格式构造多模态消息图片 token 由处理器内部处理不要手动拼接|IMAGE_PLACEHOLDER|占位符详见下文“提示词注意事项”image参数接收路径列表本地路径与远程图片 URL 均可直接使用generate的max_tokens与temperature与 CLI 参数一一对应result.text即为解码后的最终输出文本。处理器与图像预处理原理MLX-VLM 为 PaddleOCR-VL 实现了 MLX 原生的 ImageProcessor其核心机制是动态分辨率切分smart resize避免把高分辨率文档图暴力压缩导致文字模糊。smart_resize 动态缩放smart_resize 保证缩放后图像的宽高均为patch_size * merge_size默认 14×228的整数倍同时把总像素数约束在[min_pixels, max_pixels]区间内并拒绝宽高比超过 200 的极端图像。默认参数参数默认值含义min_pixels147384缩放后最少像素数对应 384×384 左右max_pixels2822400缩放后最大像素数约 1680×1680patch_size14视觉 Patch 边长merge_size2空间合并粒度2×2 块合并image_mean/image_std0.5 / 0.5归一化均值与标准差rescale_factor1/255像素值缩放系数预处理流水线依次执行转 RGB → smart_resize 缩放 → 除以 255 → 按均值/标准差归一化 → 切成 14×14 Patch 并展平 → 输出pixel_values与image_grid_thw记录每张图t×h×w网格尺寸供视觉塔与位置索引使用。处理器与 tokenizer 的协作PaddleOCRVLProcessor 组合了图像处理器与AutoTokenizer其__call__会自动将文本中的|IMAGE_PLACEHOLDER|占位符替换为与图像 Patch 数量对应的|placeholder|序列数量为grid_t * grid_h * grid_w / merge_size²再替换回图像 token 后完成分词。这就是 README 强调“不要手动加占位符”的原因——重复或数量错误的占位符会破坏input_ids与视觉特征的一一对应。模型前向视觉特征如何注入语言模型顶层 Model 由VisionModel与LanguageModel组成get_input_embeddings定义了图像注入逻辑视觉塔对pixel_values编码得到视觉特征hidden_statesmerge_input_ids_with_image_features 定位input_ids中所有等于image_token_id配置值为 100295见 config.py的位置用视觉特征逐位替换文本嵌入计算 MRoPE 位置索引与 rope delta 并写入语言模型。视觉塔细节VisionModel 包含 27 层编码器隐藏维度 1152、16 头注意力见 VisionConfig。两个值得注意的实现点位置编码插值interpolate_pos_encoding用双线性插值把预训练的方形位置嵌入拉伸到任意h×w网格配合 2D 高度/宽度 RoPErot_pos_emb使模型可处理训练分辨率之外的文档图空间合并投影器PaddleOCRProjector先将 2×2 邻域 Patch 的特征拼接spatial_merge_size² × dim再经 LayerNorm → Linear → GELU → Linear 投影到语言模型维度 1024显著压缩视觉 token 数量多图场景通过cu_seqlens打包成单序列批量前向。语言模型与 MRoPELanguageModel 是 18 层、隐藏维度 1024、2 个 KV 头的 Qwen 风格解码器TextConfig。它使用 MRoPERotaryEmbedding 的sectioned_half_split风格mrope_section[16, 24, 24]将位置维度分成时间/高度/宽度三段分别编码多模态 token 的空间信息get_rope_index逐图像扫描vision_start_token_id101305之后的 token为图像区域生成 3D 位置 ID与视觉塔的网格坐标严格对齐。rope_theta500000与 131072 的max_position_embeddings为长文档提供了充足的位置容量。提示词注意事项Prompt NotesOCR:是纯文本提取的默认提示词适用于扫描件、截图中的文字识别其他内置任务提示词为Table Recognition:、Formula Recognition:、Chart Recognition:分别触发表格结构化输出、公式通常输出 LaTeX 形式与图表语义理解如需结构化提取可直接在提示词中给出任务指令或目标 schema模型会按指令约束输出格式使用apply_chat_template时通常不应手动添加图像占位符避免 token 计数错位输入既支持本地图片路径也支持图片 URL二者用法一致。小结与延伸阅读至此你已掌握 PaddleOCR-VL 在 MLX-VLM 上的完整推理路径CLI 一行命令跑通四类文档任务Python API 实现程序化集成并理解了从动态分辨率切分、空间合并投影到 MRoPE 位置编码的端到端实现原理。如需进一步深入处理器与注册机制的完整实现见 processing_paddleocr_vl.py模型配置项与默认值见 config.py视觉编码器与语言解码器源码见 vision.py 与 language.py集成说明的权威出处见 PaddleOCR-VL 官方文档若需了解提示词格式化如何作用于paddleocr_vl可查阅 prompt_utils.py。注意本指南基于当前仓库的集成实现模型行为以 Hugging Face 上PaddlePaddle/PaddleOCR-VL官方权重为准推理需 Apple Silicon Mac 且已正确安装 MLX 环境。【免费下载链接】mlx-vlmMLX-VLM is a package for inference and fine-tuning of Vision Language Models (VLMs) on your Mac using MLX.项目地址: https://gitcode.com/GitHub_Trending/ml/mlx-vlm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考