PaddleOCR-VL 在 Apple Silicon 上的使用教程本地推理、MLX-VLM 加速与服务化部署实战【免费下载链接】PaddleOCR飞桨多语言OCR工具包实用超轻量OCR系统支持80种语言识别提供数据标注与合成工具支持服务器、移动端、嵌入式及IoT设备端的训练与部署 Awesome multilingual OCR toolkits based on PaddlePaddle (practical ultra lightweight OCR system, support 80 languages recognition, provide data annotation and synthesis tools, support training and deployment among server, mobile, embedded and IoT devices)项目地址: https://gitcode.com/paddlepaddle/PaddleOCRPaddleOCR-VL 是 PaddleOCR 推出的文档解析模型系列采用版面分析 VLM 识别两阶段架构可对文本、表格、公式、图表、印章等复杂元素进行页级文档解析。本文围绕 Apple SiliconApple M1 / M2 / M3 / M4 等硬件完整讲解本地运行环境准备、快速推理、基于 MLX-VLM 的 VLM 推理服务接入、手动服务化部署以及模型微调路径帮助开发者在 Mac 上完成从环境搭建到生产级文档解析服务的全流程落地。1. 硬件支持概况Apple Silicon 上的 PaddleOCR-VLApple Silicon 包括但不限于 Apple M1、M2、M3、M4 等芯片。根据 PaddleOCR-VL Apple Silicon 使用教程 的说明已在 Apple M4 上完成精度验证由于硬件环境多样其他 Apple Silicon 机型的兼容性尚未由官方验证欢迎社区用户在不同硬件上测试并反馈运行结果。当前硬件本地推理仅支持 PaddlePaddle 推理引擎官方 Docker 镜像路径在 Apple Silicon 上不可用。完整 API 服务仅支持手动部署不支持 Docker Compose 部署。模型微调支持。从主教程 PaddleOCR-VL 推理方式与硬件支持矩阵 可以确认 Apple Silicon 在推理方式支持上的边界推理方式Apple Silicon 支持情况PaddlePaddle版面分析 VLM 均在本地飞桨推理✅ 支持Transformers 适配中PaddlePaddle vLLM / SGLang / FastDeploy❌ 不支持PaddlePaddle MLX-VLM✅ 支持Apple Silicon 专属路径PaddlePaddle llama.cpp 适配中Transformers MLX-VLM✅ 支持其中PaddlePaddle MLX-VLM的含义是客户端本地使用飞桨框架完成版面分析等流程环节仅将 VLM 推理交给 MLX-VLM 服务处理。这是 Apple Silicon 上提升推理性能、满足生产需求的主要路径也是本教程第 3 节的核心内容。需要特别说明的是PaddleOCR-VL 的完整能力必须依赖版面分析与 VLM 识别协同的完整流程单独使用 VLM 组件例如直接请求 MLX-VLM 服务处理整张文档图无法复现论文或官方精度并可能产生大量幻觉文本。详细原理请参见 PaddleOCR-VL 使用教程。2. 本地运行环境准备Apple Silicon 上仅支持手动安装推理引擎和 PaddleOCR这一种环境准备方式官方 Docker 镜像路径不可用。强烈推荐在虚拟环境中安装 PaddleOCR-VL以避免依赖冲突。例如使用 Python venv 标准库# 创建虚拟环境 python -m venv .venv_paddleocr # 激活环境 source .venv_paddleocr/bin/activate然后执行如下命令完成安装python -m pip install paddlepaddle3.2.1 -i https://www.paddlepaddle.org.cn/packages/stable/cpu/ python -m pip install -U paddleocr[doc-parser]注意请安装 3.2.1 及以上版本的飞桨框架。与 NVIDIA GPU 路径安装paddlepaddle-gpu不同Apple Silicon 安装的是 CPU 版飞桨。主教程验证过的 Python 版本范围为 3.9–3.13。安装完成后可通过paddleocr doc_parserCLI或from paddleocr import PaddleOCRVLPython API使用 PaddleOCR-VL。从源码 paddleocr/_pipelines/paddleocr_vl.py 可以看到PaddleOCRVL类支持pipeline_version取值v1/v1.5/v1.6默认v1.6并通过_paddlex_pipeline_name映射到对应的 PaddleX 产线PaddleOCR-VL/PaddleOCR-VL-1.5/PaddleOCR-VL-1.6。3. 快速开始本地直接推理Apple Silicon 上本地直接推理即纯 PaddlePaddle 路径的快速开始方式与主教程 PaddleOCR-VL 使用教程 - 2. 快速开始 一致区别在于设备需指定为 CPU。3.1 命令行方式体验首次运行时PaddleOCR-VL 会自动下载官方模型请确保环境可以联网并预留一定的下载和初始化时间。Apple Silicon 上的示例命令paddleocr doc_parser -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/paddleocr_vl_demo.png --device cpu --save_path ./output可选功能开关示例同样适用于 Apple Silicon# 通过 --use_doc_orientation_classify 指定是否使用文档方向分类模型 paddleocr doc_parser -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/paddleocr_vl_demo.png --use_doc_orientation_classify True --save_path ./output # 通过 --use_doc_unwarping 指定是否使用文本图像矫正模块 paddleocr doc_parser -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/paddleocr_vl_demo.png --use_doc_unwarping True --save_path ./output # 通过 --use_layout_detection 指定是否使用版面分析模块默认 True paddleocr doc_parser -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/paddleocr_vl_demo.png --use_layout_detection False --save_path ./output执行成功后终端会打印结构化结果若设置了--save_path ./output结果文件会保存到当前目录的output中。3.2 Python API 方式集成from pathlib import Path from paddleocr import PaddleOCRVL output_dir Path(./output) output_dir.mkdir(parentsTrue, exist_okTrue) # Apple Silicon pipeline PaddleOCRVL(devicecpu) output pipeline.predict(https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/paddleocr_vl_demo.png) for res in output: res.print() # 打印预测的结构化输出 res.save_to_json(save_pathoutput_dir) # 保存结构化 json 结果 res.save_to_markdown(save_pathoutput_dir) # 保存 markdown 结果 res.save_to_word(save_pathoutput_dir) # 保存 Word 结果对于 PDF 多页结果PaddleOCRVL还提供了restructure_pages()方法支持跨页表格合并、重建多级标题、合并多页结果为一页output pipeline.predict(input./your_pdf_file.pdf) pages_res list(output) output pipeline.restructure_pages(pages_res, merge_tablesTrue, relevel_titlesTrue, concatenate_pagesTrue)提示由于 PaddleOCR-VL 的默认模型较大纯本地 CPU 推理速度可能较慢建议实际推理使用第 4 节的 MLX-VLM 服务化方式。4. 使用 VLM 推理服务接入 MLX-VLM对于 Apple Silicon 硬件接入 VLM 推理服务通常用于提升默认配置下的推理性能以更好满足生产需求。核心思路是客户端继续负责版面分析等完整流程中的其他环节仅将 VLM 推理交给专用服务处理。IMPORTANT按本节说明启动的服务仅负责 PaddleOCR-VL 流程中的 VLM 推理环节不提供完整的端到端文档解析 API。强烈不建议直接通过 HTTP 请求或使用 OpenAI 客户端调用该服务处理文档图像。如需部署具备 PaddleOCR-VL 完整能力的服务请参考第 5 节。4.1 启动 MLX-VLM 推理服务Apple Silicon 上 VLM 推理服务的启动方式为直接使用推理加速框架启动官方 Docker 镜像路径、PaddleOCR CLI 安装依赖路径均不支持。安装 MLX-VLM 推理框架v0.3.11 以上版本python -m pip install mlx-vlm0.3.11启动 MLX-VLM 推理服务mlx_vlm.server --port 8111MLXApple 的机器学习框架针对 Apple Silicon 的统一内存架构做了深度优化因此PaddlePaddle MLX-VLM是 Apple Silicon 上唯一被官方标记为支持的混合推理组合见第 1 节矩阵。从源码 paddleocr/_pipelines/paddleocr_vl.py 可以看到_SUPPORTED_VL_BACKENDS中包含了mlx-vlm-server后端与vllm-server、sglang-server、fastdeploy-server、llama-cpp-server并列。4.2 客户端调用方式以下调用方式适用于已启动的 MLX-VLM 推理服务。三个关键参数vl_rec_backend指定后端类型此处为mlx-vlm-servervl_rec_server_url指定服务地址vl_rec_api_model_name指定 huggingface repo id 或服务端模型权重路径。4.2.1 CLI 调用paddleocr doc_parser \ --input https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/paddleocr_vl_demo.png \ --vl_rec_backend mlx-vlm-server \ --vl_rec_server_url http://localhost:8111/ \ --vl_rec_api_model_name PaddlePaddle/PaddleOCR-VL-1.64.2.2 Python API 调用pipeline PaddleOCRVL( vl_rec_backendmlx-vlm-server, vl_rec_server_urlhttp://localhost:8111/, vl_rec_api_model_namePaddlePaddle/PaddleOCR-VL-1.6, )从源码实现看vl_rec_backend、vl_rec_server_url、vl_rec_api_model_name、vl_rec_api_key、vl_rec_max_concurrency等参数最终通过_get_paddlex_config_overrides()映射到产线配置的SubModules.VLRecognition.genai_config结构包括backend、server_url、max_concurrency、client_kwargs.model_name、client_kwargs.api_key字段这也与第 5.3 节产线配置文件中的VLRecognition.genai_config字段一一对应。4.3 性能调优PaddleOCR 会将来自单张或多张输入图像中的子图分组并对服务器发起并发请求因此并发请求数对性能影响显著对 CLI 和 Python API可通过vl_rec_max_concurrency参数调整最大并发请求数对服务化部署可修改配置文件中VLRecognition.genai_config.max_concurrency字段。当客户端与 VLM 推理服务为 1 对 1 且服务端资源充足时可适当增加并发数以提升性能若服务端需支持多个客户端或计算资源有限则应降低并发数以避免资源过载导致服务异常。更多参数如temperature、top_p、repetition_penalty、min_pixels、max_pixels、max_new_tokens等的完整说明可参考 PaddleOCR-VL 使用教程 - 3.3 性能调优 及 推理引擎与配置说明。5. 服务化部署手动部署路径Apple Silicon 上完整 API 服务仅支持手动部署Docker Compose 部署路径不可用。该服务与第 4 节的 VLM 推理服务不同服务化部署提供完整的端到端文档解析 API并将 VLM 推理服务作为其底层服务被调用。5.1 手动部署先完成第 2 节本地运行环境准备然后执行以下命令# 通过 PaddleX CLI 安装服务化部署插件paddlex 命令会随 paddleocr 一并安装 paddlex --install serving # 启动服务器默认监听 8080 端口 paddlex --serve --pipeline PaddleOCR-VL启动后将看到类似输出INFO: Started server process [63108] INFO: Waiting for application startup. INFO: Application startup complete. INFO: Uvicorn running on http://0.0.0.0:8080 (Press CTRLC to quit)服务化部署相关命令行参数参数说明--pipelinePaddleX 产线注册名或产线配置文件路径--device产线部署设备。默认情况下若 GPU 可用则使用 GPU否则使用 CPU--host服务器绑定的主机名或 IP 地址默认为0.0.0.0--port服务器监听的端口号默认为8080--use_hpip启用高性能推理模式--hpi_config高性能推理配置5.2 客户端调用方式手动部署后可通过 HTTP API 调用。服务提供两个主要操作POST /layout-parsing进行版面解析。请求体中file为服务器可访问的图像/PDF 文件 URL 或 Base64 编码内容必填fileType为文件类型0表示 PDF1表示图像含 TIFF另支持useDocOrientationClassify、useLayoutDetection、useChartRecognition、useSealRecognition、layoutThreshold、temperature、topP、restructurePages、outputFormats当前支持docx、visualize等可选字段。响应中result.layoutParsingResults为逐页解析结果每个元素包含prunedResult、markdowntextimages、outputImages、inputImage、exports等字段。POST /restructure-pages重构多页结果。请求体包含pages数组必填以及mergeTables、relevelTitles、concatenatePages等参数。服务请求/响应格式约定请求处理成功时响应状态码为200响应体含logIdUUID、errorCode固定为0、errorMsg固定为Success与result失败时errorCode与响应状态码相同。图像等二进制内容默认以 Base64 内联返回可通过配置切换为预签名 URL 返回见 5.3 节。完整的 Python / C / Java / Go / C# / Node.js / PHP 多语言调用示例可参考 PaddleOCR-VL 使用教程 - 4.3 客户端调用方式。5.3 产线配置调整说明调整服务化部署配置只需三步获取配置文件 → 修改配置文件 → 应用配置文件。获取配置文件手动部署时执行paddlex --get_pipeline_config PaddleOCR-VL生成产线配置文件Docker Compose 场景下对应仓库中的 pipeline_config_vllm.yaml 与 pipeline_config_fastdeploy.yaml。常用修改项使用加速框架提升 VLM 推理性能在产线配置文件中修改VLRecognition.genai_config.backend和VLRecognition.genai_config.server_url字段例如VLRecognition: ... genai_config: backend: vllm-server server_url: http://localhost:8118/v1启用文档图像预处理功能默认配置启动的服务不支持文档预处理功能客户端调用将返回错误。如需启用将use_doc_preprocessor设置为True并使用修改后的配置重启服务。禁用结果可视化功能服务默认返回可视化结果存在额外开销可添加顶层字段禁用Serving: visualize: False也可在请求体中设置visualize为false仅对单次请求生效。配置以 URL 形式返回二进制内容服务默认以 Base64 内联返回图像等二进制内容如需改为 URL 形式目前支持存储至百度智能云对象存储 BOSServing: return_urls: True extra: file_storage: type: bos endpoint: https://bj.bcebos.com bucket_name: some-bucket ak: xxx sk: xxx key_prefix: deploy url_expires_in: 3600限制 PDF 与多页 TIFF 解析页数为保障服务稳定运行可限制最大处理页数Serving: extra: max_num_input_imgs: 100max_num_input_imgs同时限制 PDF 与多页 TIFF设置为null时不限制。应用配置文件手动部署时在启动命令中通过--pipeline指定自定义配置文件路径即可Docker Compose 场景下需挂载到/home/paddleocr目录Apple Silicon 不适用。6. 模型微调若 PaddleOCR-VL 在特定业务场景中的精度表现未达预期官方推荐使用ERNIEKit 套件对视觉语言模型例如 PaddleOCR-VL-0.9B进行有监督微调SFT。具体操作步骤参考 PaddleOCR-VL 使用教程 - 5. 模型微调。目前暂不支持对版面分析排序模型进行微调。7. 使用建议与注意事项务必使用完整流程只有版面分析 VLM 识别协同的完整 PaddleOCR-VL 流程才能复现官方精度单独调用 MLX-VLM 服务或直接请求 VLM 组件无法获得完整的文档解析能力且可能出现幻觉文本。环境隔离PaddleOCR-VL 依赖较多务必在 venv 等虚拟环境中安装Apple Silicon 上安装的是 CPU 版paddlepaddle3.2.1及以上切勿与 GPU 版混装。精度验证范围官方已在 Apple M4 上完成精度验证其他 Apple Silicon 机型建议先小批量测试再投入生产。推理加速默认配置下纯 CPU 本地推理较慢如需更好性能优先采用第 4 节的PaddlePaddle MLX-VLM组合并通过vl_rec_max_concurrency/genai_config.max_concurrency调优并发。服务边界第 4 节的 MLX-VLM 服务仅承担 VLM 推理环节不提供端到端文档解析 API需要完整服务能力时请使用第 5 节的手动服务化部署。持续反馈Apple Silicon 硬件环境多样欢迎在不同 M 系列芯片上测试并将运行结果反馈给社区帮助完善兼容性验证。【免费下载链接】PaddleOCR飞桨多语言OCR工具包实用超轻量OCR系统支持80种语言识别提供数据标注与合成工具支持服务器、移动端、嵌入式及IoT设备端的训练与部署 Awesome multilingual OCR toolkits based on PaddlePaddle (practical ultra lightweight OCR system, support 80 languages recognition, provide data annotation and synthesis tools, support training and deployment among server, mobile, embedded and IoT devices)项目地址: https://gitcode.com/paddlepaddle/PaddleOCR创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
PaddleOCR-VL 在 Apple Silicon 上的使用教程：本地推理、MLX-VLM 加速与服务化部署实战
PaddleOCR-VL 在 Apple Silicon 上的使用教程本地推理、MLX-VLM 加速与服务化部署实战【免费下载链接】PaddleOCR飞桨多语言OCR工具包实用超轻量OCR系统支持80种语言识别提供数据标注与合成工具支持服务器、移动端、嵌入式及IoT设备端的训练与部署 Awesome multilingual OCR toolkits based on PaddlePaddle (practical ultra lightweight OCR system, support 80 languages recognition, provide data annotation and synthesis tools, support training and deployment among server, mobile, embedded and IoT devices)项目地址: https://gitcode.com/paddlepaddle/PaddleOCRPaddleOCR-VL 是 PaddleOCR 推出的文档解析模型系列采用版面分析 VLM 识别两阶段架构可对文本、表格、公式、图表、印章等复杂元素进行页级文档解析。本文围绕 Apple SiliconApple M1 / M2 / M3 / M4 等硬件完整讲解本地运行环境准备、快速推理、基于 MLX-VLM 的 VLM 推理服务接入、手动服务化部署以及模型微调路径帮助开发者在 Mac 上完成从环境搭建到生产级文档解析服务的全流程落地。1. 硬件支持概况Apple Silicon 上的 PaddleOCR-VLApple Silicon 包括但不限于 Apple M1、M2、M3、M4 等芯片。根据 PaddleOCR-VL Apple Silicon 使用教程 的说明已在 Apple M4 上完成精度验证由于硬件环境多样其他 Apple Silicon 机型的兼容性尚未由官方验证欢迎社区用户在不同硬件上测试并反馈运行结果。当前硬件本地推理仅支持 PaddlePaddle 推理引擎官方 Docker 镜像路径在 Apple Silicon 上不可用。完整 API 服务仅支持手动部署不支持 Docker Compose 部署。模型微调支持。从主教程 PaddleOCR-VL 推理方式与硬件支持矩阵 可以确认 Apple Silicon 在推理方式支持上的边界推理方式Apple Silicon 支持情况PaddlePaddle版面分析 VLM 均在本地飞桨推理✅ 支持Transformers 适配中PaddlePaddle vLLM / SGLang / FastDeploy❌ 不支持PaddlePaddle MLX-VLM✅ 支持Apple Silicon 专属路径PaddlePaddle llama.cpp 适配中Transformers MLX-VLM✅ 支持其中PaddlePaddle MLX-VLM的含义是客户端本地使用飞桨框架完成版面分析等流程环节仅将 VLM 推理交给 MLX-VLM 服务处理。这是 Apple Silicon 上提升推理性能、满足生产需求的主要路径也是本教程第 3 节的核心内容。需要特别说明的是PaddleOCR-VL 的完整能力必须依赖版面分析与 VLM 识别协同的完整流程单独使用 VLM 组件例如直接请求 MLX-VLM 服务处理整张文档图无法复现论文或官方精度并可能产生大量幻觉文本。详细原理请参见 PaddleOCR-VL 使用教程。2. 本地运行环境准备Apple Silicon 上仅支持手动安装推理引擎和 PaddleOCR这一种环境准备方式官方 Docker 镜像路径不可用。强烈推荐在虚拟环境中安装 PaddleOCR-VL以避免依赖冲突。例如使用 Python venv 标准库# 创建虚拟环境 python -m venv .venv_paddleocr # 激活环境 source .venv_paddleocr/bin/activate然后执行如下命令完成安装python -m pip install paddlepaddle3.2.1 -i https://www.paddlepaddle.org.cn/packages/stable/cpu/ python -m pip install -U paddleocr[doc-parser]注意请安装 3.2.1 及以上版本的飞桨框架。与 NVIDIA GPU 路径安装paddlepaddle-gpu不同Apple Silicon 安装的是 CPU 版飞桨。主教程验证过的 Python 版本范围为 3.9–3.13。安装完成后可通过paddleocr doc_parserCLI或from paddleocr import PaddleOCRVLPython API使用 PaddleOCR-VL。从源码 paddleocr/_pipelines/paddleocr_vl.py 可以看到PaddleOCRVL类支持pipeline_version取值v1/v1.5/v1.6默认v1.6并通过_paddlex_pipeline_name映射到对应的 PaddleX 产线PaddleOCR-VL/PaddleOCR-VL-1.5/PaddleOCR-VL-1.6。3. 快速开始本地直接推理Apple Silicon 上本地直接推理即纯 PaddlePaddle 路径的快速开始方式与主教程 PaddleOCR-VL 使用教程 - 2. 快速开始 一致区别在于设备需指定为 CPU。3.1 命令行方式体验首次运行时PaddleOCR-VL 会自动下载官方模型请确保环境可以联网并预留一定的下载和初始化时间。Apple Silicon 上的示例命令paddleocr doc_parser -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/paddleocr_vl_demo.png --device cpu --save_path ./output可选功能开关示例同样适用于 Apple Silicon# 通过 --use_doc_orientation_classify 指定是否使用文档方向分类模型 paddleocr doc_parser -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/paddleocr_vl_demo.png --use_doc_orientation_classify True --save_path ./output # 通过 --use_doc_unwarping 指定是否使用文本图像矫正模块 paddleocr doc_parser -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/paddleocr_vl_demo.png --use_doc_unwarping True --save_path ./output # 通过 --use_layout_detection 指定是否使用版面分析模块默认 True paddleocr doc_parser -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/paddleocr_vl_demo.png --use_layout_detection False --save_path ./output执行成功后终端会打印结构化结果若设置了--save_path ./output结果文件会保存到当前目录的output中。3.2 Python API 方式集成from pathlib import Path from paddleocr import PaddleOCRVL output_dir Path(./output) output_dir.mkdir(parentsTrue, exist_okTrue) # Apple Silicon pipeline PaddleOCRVL(devicecpu) output pipeline.predict(https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/paddleocr_vl_demo.png) for res in output: res.print() # 打印预测的结构化输出 res.save_to_json(save_pathoutput_dir) # 保存结构化 json 结果 res.save_to_markdown(save_pathoutput_dir) # 保存 markdown 结果 res.save_to_word(save_pathoutput_dir) # 保存 Word 结果对于 PDF 多页结果PaddleOCRVL还提供了restructure_pages()方法支持跨页表格合并、重建多级标题、合并多页结果为一页output pipeline.predict(input./your_pdf_file.pdf) pages_res list(output) output pipeline.restructure_pages(pages_res, merge_tablesTrue, relevel_titlesTrue, concatenate_pagesTrue)提示由于 PaddleOCR-VL 的默认模型较大纯本地 CPU 推理速度可能较慢建议实际推理使用第 4 节的 MLX-VLM 服务化方式。4. 使用 VLM 推理服务接入 MLX-VLM对于 Apple Silicon 硬件接入 VLM 推理服务通常用于提升默认配置下的推理性能以更好满足生产需求。核心思路是客户端继续负责版面分析等完整流程中的其他环节仅将 VLM 推理交给专用服务处理。IMPORTANT按本节说明启动的服务仅负责 PaddleOCR-VL 流程中的 VLM 推理环节不提供完整的端到端文档解析 API。强烈不建议直接通过 HTTP 请求或使用 OpenAI 客户端调用该服务处理文档图像。如需部署具备 PaddleOCR-VL 完整能力的服务请参考第 5 节。4.1 启动 MLX-VLM 推理服务Apple Silicon 上 VLM 推理服务的启动方式为直接使用推理加速框架启动官方 Docker 镜像路径、PaddleOCR CLI 安装依赖路径均不支持。安装 MLX-VLM 推理框架v0.3.11 以上版本python -m pip install mlx-vlm0.3.11启动 MLX-VLM 推理服务mlx_vlm.server --port 8111MLXApple 的机器学习框架针对 Apple Silicon 的统一内存架构做了深度优化因此PaddlePaddle MLX-VLM是 Apple Silicon 上唯一被官方标记为支持的混合推理组合见第 1 节矩阵。从源码 paddleocr/_pipelines/paddleocr_vl.py 可以看到_SUPPORTED_VL_BACKENDS中包含了mlx-vlm-server后端与vllm-server、sglang-server、fastdeploy-server、llama-cpp-server并列。4.2 客户端调用方式以下调用方式适用于已启动的 MLX-VLM 推理服务。三个关键参数vl_rec_backend指定后端类型此处为mlx-vlm-servervl_rec_server_url指定服务地址vl_rec_api_model_name指定 huggingface repo id 或服务端模型权重路径。4.2.1 CLI 调用paddleocr doc_parser \ --input https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/paddleocr_vl_demo.png \ --vl_rec_backend mlx-vlm-server \ --vl_rec_server_url http://localhost:8111/ \ --vl_rec_api_model_name PaddlePaddle/PaddleOCR-VL-1.64.2.2 Python API 调用pipeline PaddleOCRVL( vl_rec_backendmlx-vlm-server, vl_rec_server_urlhttp://localhost:8111/, vl_rec_api_model_namePaddlePaddle/PaddleOCR-VL-1.6, )从源码实现看vl_rec_backend、vl_rec_server_url、vl_rec_api_model_name、vl_rec_api_key、vl_rec_max_concurrency等参数最终通过_get_paddlex_config_overrides()映射到产线配置的SubModules.VLRecognition.genai_config结构包括backend、server_url、max_concurrency、client_kwargs.model_name、client_kwargs.api_key字段这也与第 5.3 节产线配置文件中的VLRecognition.genai_config字段一一对应。4.3 性能调优PaddleOCR 会将来自单张或多张输入图像中的子图分组并对服务器发起并发请求因此并发请求数对性能影响显著对 CLI 和 Python API可通过vl_rec_max_concurrency参数调整最大并发请求数对服务化部署可修改配置文件中VLRecognition.genai_config.max_concurrency字段。当客户端与 VLM 推理服务为 1 对 1 且服务端资源充足时可适当增加并发数以提升性能若服务端需支持多个客户端或计算资源有限则应降低并发数以避免资源过载导致服务异常。更多参数如temperature、top_p、repetition_penalty、min_pixels、max_pixels、max_new_tokens等的完整说明可参考 PaddleOCR-VL 使用教程 - 3.3 性能调优 及 推理引擎与配置说明。5. 服务化部署手动部署路径Apple Silicon 上完整 API 服务仅支持手动部署Docker Compose 部署路径不可用。该服务与第 4 节的 VLM 推理服务不同服务化部署提供完整的端到端文档解析 API并将 VLM 推理服务作为其底层服务被调用。5.1 手动部署先完成第 2 节本地运行环境准备然后执行以下命令# 通过 PaddleX CLI 安装服务化部署插件paddlex 命令会随 paddleocr 一并安装 paddlex --install serving # 启动服务器默认监听 8080 端口 paddlex --serve --pipeline PaddleOCR-VL启动后将看到类似输出INFO: Started server process [63108] INFO: Waiting for application startup. INFO: Application startup complete. INFO: Uvicorn running on http://0.0.0.0:8080 (Press CTRLC to quit)服务化部署相关命令行参数参数说明--pipelinePaddleX 产线注册名或产线配置文件路径--device产线部署设备。默认情况下若 GPU 可用则使用 GPU否则使用 CPU--host服务器绑定的主机名或 IP 地址默认为0.0.0.0--port服务器监听的端口号默认为8080--use_hpip启用高性能推理模式--hpi_config高性能推理配置5.2 客户端调用方式手动部署后可通过 HTTP API 调用。服务提供两个主要操作POST /layout-parsing进行版面解析。请求体中file为服务器可访问的图像/PDF 文件 URL 或 Base64 编码内容必填fileType为文件类型0表示 PDF1表示图像含 TIFF另支持useDocOrientationClassify、useLayoutDetection、useChartRecognition、useSealRecognition、layoutThreshold、temperature、topP、restructurePages、outputFormats当前支持docx、visualize等可选字段。响应中result.layoutParsingResults为逐页解析结果每个元素包含prunedResult、markdowntextimages、outputImages、inputImage、exports等字段。POST /restructure-pages重构多页结果。请求体包含pages数组必填以及mergeTables、relevelTitles、concatenatePages等参数。服务请求/响应格式约定请求处理成功时响应状态码为200响应体含logIdUUID、errorCode固定为0、errorMsg固定为Success与result失败时errorCode与响应状态码相同。图像等二进制内容默认以 Base64 内联返回可通过配置切换为预签名 URL 返回见 5.3 节。完整的 Python / C / Java / Go / C# / Node.js / PHP 多语言调用示例可参考 PaddleOCR-VL 使用教程 - 4.3 客户端调用方式。5.3 产线配置调整说明调整服务化部署配置只需三步获取配置文件 → 修改配置文件 → 应用配置文件。获取配置文件手动部署时执行paddlex --get_pipeline_config PaddleOCR-VL生成产线配置文件Docker Compose 场景下对应仓库中的 pipeline_config_vllm.yaml 与 pipeline_config_fastdeploy.yaml。常用修改项使用加速框架提升 VLM 推理性能在产线配置文件中修改VLRecognition.genai_config.backend和VLRecognition.genai_config.server_url字段例如VLRecognition: ... genai_config: backend: vllm-server server_url: http://localhost:8118/v1启用文档图像预处理功能默认配置启动的服务不支持文档预处理功能客户端调用将返回错误。如需启用将use_doc_preprocessor设置为True并使用修改后的配置重启服务。禁用结果可视化功能服务默认返回可视化结果存在额外开销可添加顶层字段禁用Serving: visualize: False也可在请求体中设置visualize为false仅对单次请求生效。配置以 URL 形式返回二进制内容服务默认以 Base64 内联返回图像等二进制内容如需改为 URL 形式目前支持存储至百度智能云对象存储 BOSServing: return_urls: True extra: file_storage: type: bos endpoint: https://bj.bcebos.com bucket_name: some-bucket ak: xxx sk: xxx key_prefix: deploy url_expires_in: 3600限制 PDF 与多页 TIFF 解析页数为保障服务稳定运行可限制最大处理页数Serving: extra: max_num_input_imgs: 100max_num_input_imgs同时限制 PDF 与多页 TIFF设置为null时不限制。应用配置文件手动部署时在启动命令中通过--pipeline指定自定义配置文件路径即可Docker Compose 场景下需挂载到/home/paddleocr目录Apple Silicon 不适用。6. 模型微调若 PaddleOCR-VL 在特定业务场景中的精度表现未达预期官方推荐使用ERNIEKit 套件对视觉语言模型例如 PaddleOCR-VL-0.9B进行有监督微调SFT。具体操作步骤参考 PaddleOCR-VL 使用教程 - 5. 模型微调。目前暂不支持对版面分析排序模型进行微调。7. 使用建议与注意事项务必使用完整流程只有版面分析 VLM 识别协同的完整 PaddleOCR-VL 流程才能复现官方精度单独调用 MLX-VLM 服务或直接请求 VLM 组件无法获得完整的文档解析能力且可能出现幻觉文本。环境隔离PaddleOCR-VL 依赖较多务必在 venv 等虚拟环境中安装Apple Silicon 上安装的是 CPU 版paddlepaddle3.2.1及以上切勿与 GPU 版混装。精度验证范围官方已在 Apple M4 上完成精度验证其他 Apple Silicon 机型建议先小批量测试再投入生产。推理加速默认配置下纯 CPU 本地推理较慢如需更好性能优先采用第 4 节的PaddlePaddle MLX-VLM组合并通过vl_rec_max_concurrency/genai_config.max_concurrency调优并发。服务边界第 4 节的 MLX-VLM 服务仅承担 VLM 推理环节不提供端到端文档解析 API需要完整服务能力时请使用第 5 节的手动服务化部署。持续反馈Apple Silicon 硬件环境多样欢迎在不同 M 系列芯片上测试并将运行结果反馈给社区帮助完善兼容性验证。【免费下载链接】PaddleOCR飞桨多语言OCR工具包实用超轻量OCR系统支持80种语言识别提供数据标注与合成工具支持服务器、移动端、嵌入式及IoT设备端的训练与部署 Awesome multilingual OCR toolkits based on PaddlePaddle (practical ultra lightweight OCR system, support 80 languages recognition, provide data annotation and synthesis tools, support training and deployment among server, mobile, embedded and IoT devices)项目地址: https://gitcode.com/paddlepaddle/PaddleOCR创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
