PaddleOCR-VL 在 Apple Silicon 上的部署与使用完全指南M1–M4【免费下载链接】PaddleOCRTurn any PDF or image document into structured data for your AI. A powerful, lightweight OCR toolkit that bridges the gap between images/PDFs and LLMs. Supports 100 languages.项目地址: https://gitcode.com/GitHub_Trending/pa/PaddleOCRPaddleOCR 为 Apple SiliconApple M1/M2/M3/M4 等用户提供了 PaddleOCR-VL 文档解析模型的专属硬件使用教程覆盖从本地推理环境搭建、MLX-VLM 加速推理服务接入到完整 API 服务手动部署与模型微调的全流程。读完本文你将能够在 Mac 上以 PaddlePaddle CPU 推理引擎完成 PaddleOCR-VL 的本地直接推理通过 MLX-VLM 把 VLM 阶段托管给专有推理服务以提升性能并掌握面向生产环境的服务部署与配置调整方法。说明除非特别注明本文中的 PaddleOCR-VL 指 PaddleOCR-VL 模型系列如 PaddleOCR-VL-1.6涉及 PaddleOCR-VL v1 版本的内容会单独标注。PaddleOCR-VL 是什么两阶段文档解析流水线PaddleOCR-VL 是为文档元素识别设计的高效文档解析模型系列。在开始 Apple Silicon 部署之前需要先理解其流水线结构PaddleOCR-VL 由**版面分析layout analysis与基于 VLM 的识别VLM-based recognition**两个核心阶段组成。第一阶段 · 版面分析模型以整张图像为输入检测并定位各类版面元素如表格、公式确定阅读顺序并根据检测结果裁剪出对应的元素级子图第二阶段 · VLM 识别每个子图被独立送入 VLM产出该元素的识别结果如 Markdown 文本随后所有元素级输出按照版面分析阶段确定的阅读顺序合并形成整张图像的完整解析结果。因此要充分释放 PaddleOCR-VL 的能力必须使用版面分析 VLM 识别的完整流水线而不是单独使用 VLM 组件。例如仅用 Transformers 直接运行 PaddleOCR-VL 模型或向 vLLM、SGLang、FastDeploy 等服务发送请求都不等同于执行完整的 PaddleOCR-VL 流水线。若遇到复现不了指标或幻觉文本过多等问题首先应检查是否使用了完整流水线。关于模型结构与算法细节可参考 PaddleOCR-VL 算法文档。硬件适配范围与本教程适用场景Apple Silicon 包括但不限于Apple M1、M2、M3、M4。官方已在 Apple M4 上验证过 PaddleOCR-VL 的准确性与速度但由于硬件多样性其余 Apple Silicon 机型的兼容性尚未完全确认欢迎社区在不同硬件上测试并反馈结果。Apple Silicon 上支持的推理方法与整体支持矩阵可参考 PaddleOCR-VL 使用教程 中的推理方法与硬件支持矩阵。在 Apple Silicon 上本地推理当前仅支持 PaddlePaddle 推理引擎与其他硬件不同vLLM、SGLang、FastDeploy 等推理加速框架不适用于此硬件。工作流导航按目标选择阅读章节目标本硬件支持情况阅读章节本地直接推理支持第 1 节本地运行环境准备 第 2 节快速开始客户端 VLM 推理服务支持先完成本地直接推理再阅读第 3 节使用 VLM 推理服务完整 API 服务仅支持手动部署先完成第 1 节再阅读第 4.1 节手动部署随后继续第 4.2 节客户端调用方式与第 4.3 节流水线配置调整说明模型微调支持第 5 节模型微调1. 本地运行环境准备1.1 支持的环境搭建方式本地运行环境搭建方式状态备注官方 Docker 镜像暂不支持本硬件当前不支持该路径手动安装推理引擎与 PaddleOCR支持按本指南步骤进行继续阅读本节Apple Silicon 上的本地推理目前只支持 PaddlePaddle 推理引擎因此官方 Docker 镜像NVIDIA GPU 专用在本硬件上不可用需要走手动安装路径。1.2 创建虚拟环境强烈建议在虚拟环境中安装 PaddleOCR-VL以避免依赖冲突。例如使用 Python 标准库 venv 创建虚拟环境# 创建虚拟环境 python -m venv .venv_paddleocr # 激活环境 source .venv_paddleocr/bin/activate1.3 安装 PaddlePaddle 与 PaddleOCR在虚拟环境中依次执行以下命令完成安装python -m pip install paddlepaddle3.2.1 -i https://www.paddlepaddle.org.cn/packages/stable/cpu/ python -m pip install -U paddleocr[doc-parser]请安装 PaddlePaddle 框架 3.2.1 或以上版本。Apple Silicon 使用 CPU 版 PaddlePaddlepaddlepaddle注意不要与其他版本的 PaddlePaddle 同时安装。第二条命令通过paddleocr[doc-parser]附加依赖安装 PaddleOCR-VL 所需的文档解析基础包。主教程PaddleOCR-VL 使用教程中将 Python 3.9–3.13 记录为已验证范围可作为 Apple Silicon 环境选型的参考。2. 快速开始Apple Silicon 上的快速开始流程与主教程一致请参考 PaddleOCR-VL 使用教程 - 2. Quick Start注意需指定--device cpu。2.1 命令行使用CLI首次运行 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-i/--input待预测数据支持本地图片/PDF 文件路径、网络 URL 或包含图片的本地目录目录中暂不支持 PDF需用具体文件路径指定--device cpuApple Silicon 上必须显式指定 CPU 设备--save_path ./output将结构化结果保存到当前目录下的output目录便于检查与调试不设置则结果仅打印到终端。执行成功后终端会打印结构化结果设置了--save_path时结果文件会保存到output目录。2.2 常用功能开关参数含义默认值--use_doc_orientation_classify是否启用文档方向分类模块False--use_doc_unwarping是否启用文本图像矫正模块False--use_layout_detection是否启用版面分析模块True--use_chart_recognition是否启用图表解析功能False--use_seal_recognition是否启用印章识别功能False--use_ocr_for_image_block是否对图像块内文字执行 OCRFalse--format_block_content是否将block_content内容格式化为 MarkdownFalse--merge_layout_blocks是否合并跨栏或上下交错的版面检测框True--use_queues是否启用内部队列异步处理对多页 PDF 或大量图片场景尤其高效True--pipeline_version流水线版本可选v1、v1.5、v1.6v1.6--layout_threshold版面模型分数阈值0–1 之间0.5--layout_shape_mode版面结果几何表示模式可选rect/quad/poly/autoauto--vl_rec_backend多模态识别模型推理后端不设置则使用默认本地推理--vl_rec_server_url使用推理服务时指定服务地址无--vl_rec_max_concurrency使用推理服务时指定最大并发请求数无--vl_rec_api_model_name使用推理服务时指定服务端模型名无--vl_rec_api_key使用推理服务时指定 API Key无--repetition_penalty/--temperature/--top_pVLM 采样参数无--min_pixels/--max_pixelsVLM 图像预处理允许的最小/最大像素数无--max_new_tokensVLM 生成的最大 token 数无注意由于 PaddleOCR-VL 默认模型相对较大本地推理可能较慢。实际生产使用建议采用第 3 节的 VLM 推理服务方案以提升速度。2.3 Python 脚本集成在真实项目中通常通过代码集成模型只需几行代码即可快速运行 PaddleOCR-VL 推理Apple Silicon 上需指定devicecpufrom 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) # 保存 Word 格式结果对于 PDF 文件每一页会被单独处理并生成独立的 Markdown 文件如需跨页表格合并、重建多级标题或合并多页结果可使用restructure_pages()方法。该方法的参数包括merge_tables是否跨页合并表格默认True、relevel_titles是否解析多级标题默认True、concatenate_pages是否将多页结果拼接为一页默认False。处理多个文件时推荐将目录路径或文件路径列表传给predict方法以最大化处理效率output pipeline.predict(imgs) # 传入目录路径 output pipeline.predict([imgs/file1.png, imgs/file2.png, imgs/file3.png]) # 或传入文件路径列表PaddleOCRVL流水线对象的实现在 paddleocr/_pipelines/paddleocr_vl.py 中它基于 PaddleX 流水线封装__init__中定义了layout_detection_model_name、layout_threshold、vl_rec_backend、vl_rec_server_url等与文档参数一一对应的构造参数并通过_get_paddlex_config_overrides()将它们映射到 PaddleX 流水线配置例如SubModules.VLRecognition.genai_config.backend、genai_config.server_url等字段从源码层面印证了 CLI 与 Python API 参数的一致性。3. 使用 VLM 推理服务MLX-VLM本节介绍如何将 PaddleOCR-VL 接入专用的 VLM 推理服务后端。在 Apple Silicon 上这通常用于在生产环境中提升默认配置之外的推理性能。本硬件指南的示例以MLX-VLM作为 VLM 推理服务后端。重要提示按本节启动的服务只负责 PaddleOCR-VL 工作流中的 VLM 推理阶段不提供完整的端到端文档解析 API。强烈不建议直接用 HTTP 请求或 OpenAI 客户端调用该服务处理文档图片。如需部署具备完整 PaddleOCR-VL 能力的服务请参考本文第 4 节的服务部署部分。3.1 启动方式与本硬件支持情况启动方式状态备注官方 Docker 镜像暂不支持本硬件当前不支持该路径通过 PaddleOCR CLI 安装依赖并启动服务暂不支持本硬件当前不支持该路径直接用加速框架启动服务支持按本指南步骤进行本节提供 MLX-VLM 启动步骤在 Apple Silicon 上MLX-VLM 是唯一受支持的 VLM 推理服务后端推理方法与硬件支持矩阵中的PaddlePaddle MLX-VLM组合即对应此路径。3.2 安装并启动 MLX-VLM 推理服务安装 MLX-VLM 推理框架v0.3.11 或更高版本python -m pip install mlx-vlm0.3.11启动 MLX-VLM 推理服务mlx_vlm.server --port 81113.3 客户端调用方式以下调用方式适用于已启动的 MLX-VLM 推理服务。3.3.1 命令行调用通过--vl_rec_backend指定后端类型此处为mlx-vlm-server通过--vl_rec_server_url指定服务地址通过--vl_rec_api_model_name指定 huggingface repo id 或服务端模型权重路径。示例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.63.3.2 Python 脚本集成创建PaddleOCRVL对象时通过vl_rec_backend指定后端类型、vl_rec_server_url参数指定服务地址、vl_rec_api_model_name指定 huggingface repo id 或服务端模型权重路径。示例pipeline PaddleOCRVL( vl_rec_backendmlx-vlm-server, vl_rec_server_urlhttp://localhost:8111/, vl_rec_api_model_namePaddlePaddle/PaddleOCR-VL-1.6, )从源码看paddleocr/_pipelines/paddleocr_vl.py 中定义了受支持的后端列表_SUPPORTED_VL_BACKENDS [native, vllm-server, sglang-server, fastdeploy-server, mlx-vlm-server, llama-cpp-server]并会在__init__中对非法的vl_rec_backend抛出ValueError传入的mlx-vlm-server最终被映射到 PaddleX 配置中的SubModules.VLRecognition.genai_config.backend字段见同文件_get_paddlex_config_overrides()第 267-281 行vl_rec_server_url、vl_rec_api_model_name分别对应genai_config.server_url与genai_config.client_kwargs.model_name。3.4 性能调优请参考 PaddleOCR-VL 使用教程 - 3.3 Performance Tuning 中的客户端参数调整建议PaddleOCR 会将单张或多张输入图像裁剪出的子图分组后向服务端并发请求因此并发请求数对性能影响显著。CLI 与 Python API 可通过vl_rec_max_concurrency参数调整最大并发请求数当客户端与 VLM 推理服务为 1:1 且服务端资源充足时提高并发可提升性能若服务端需支撑多个客户端或计算资源有限则应降低并发以避免资源过载和服务异常。4. 服务部署4.1 本硬件支持的部署方式部署方式状态备注Docker Compose 部署暂不支持本硬件当前仅支持手动部署路径手动部署支持先完成第 1 节本地运行环境准备再继续第 4.2 节由于 Apple Silicon 上不支持 NVIDIA GPU 专用的 Docker Compose 方案该方案以 vLLM 或 FastDeploy 作为底层 VLM 后端且要求 CUDA 12.6因此完整 API 服务只能走手动部署路径。4.2 手动部署说明本节中的 PaddleOCR-VL 服务与上一节的 VLM 推理服务不同后者只负责完整流程中的一部分即 VLM 推理作为底层服务被前者调用。首先完成第 1 节的本地运行环境准备然后通过 PaddleX CLI 安装服务部署插件paddlex命令随paddleocr一起安装通常无需单独安装 PaddleXpaddlex --install serving随后使用 PaddleX CLI 启动服务paddlex --serve --pipeline PaddleOCR-VL启动成功后服务默认监听8080端口终端输出类似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)与 serving 相关的命令行选项名称说明--pipelinePaddleX 流水线注册名或流水线配置文件路径--device流水线部署设备默认优先使用 GPU否则使用 CPU--host服务绑定的主机名或 IP默认0.0.0.0--port服务监听端口默认8080--use_hpip指定后使用高性能推理--hpi_config高性能推理配置注意默认配置下该服务一次只能处理一个请求。如需并发请求处理请参考deploy/paddleocr_vl_docker/hps/下的高性能服务部署方案说明。4.3 客户端调用方式请参考 PaddleOCR-VL 使用教程 - 4.3 Client Invocation Methods。服务提供的主要操作包括infer执行版面解析POST /layout-parsing请求体中file字段必填为服务器可访问的图片含 TIFF多页 TIFF 逐页处理或 PDF 文件的 URL或上述文件内容的 Base64 编码结果fileType为文件类型0表示 PDF1表示图片缺省时从 URL 推断。可选字段包括useDocOrientationClassify、useDocUnwarping、useLayoutDetection、useChartRecognition、useSealRecognition、useOcrForImageBlock、layoutThreshold、layoutShapeMode、temperature、topP、minPixels、maxPixels、maxNewTokens、restructurePages是否跨页重组结果默认false、mergeTables、relevelTitles、prettifyMarkdown默认true、showFormulaNumber默认false、returnMarkdownImages默认true、outputFormats额外导出格式目前仅支持docx、visualize等。restructurePages跨页重组结果POST /restructure-pages请求体中pages必填为infer返回的每页prunedResult与markdownImages组成的数组可选mergeTables、relevelTitles、concatenatePages、prettifyMarkdown、showFormulaNumber、returnMarkdownImages、outputFormats。请求成功时响应状态码为200响应体包含logId请求 UUID、errorCode固定为0、errorMsg固定为Success与resultlayoutParsingResults数组与dataInfo失败时errorCode与状态码一致。layoutParsingResults中每个元素包含prunedResult去除input_path、page_index字段的简化结果、markdowntext与images、outputImages、inputImage、exports设置outputFormats时存在等字段。主教程中提供了 Python、C、Java、Go、C#、Node.js、PHP 等语言的服务调用示例代码可直接参考。4.4 流水线配置调整说明注意如果不需要调整流水线配置可以忽略本节。调整服务部署的 PaddleOCR-VL 配置只需三步获取配置文件 → 修改配置文件 → 应用配置文件。4.4.1 获取配置文件手动安装依赖部署时执行以下命令生成流水线配置文件paddlex --get_pipeline_config PaddleOCR-VL仓库中也提供了现成的配置样例对应不同 VLM 后端例如 pipeline_config_vllm.yaml 与 pipeline_config_fastdeploy.yaml。4.4.2 修改配置文件增强 VLM 推理性能如需使用加速框架如 vLLM启动方式见主教程第 3 节修改配置文件中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为顶层字段Serving: visualize: False也可以在请求体中将visualize字段设为false来针对单次请求关闭可视化。限制 PDF 与多页 TIFF 的解析页数默认情况下服务会处理整个 PDF 文件多页 TIFFfileType1会逐页展开。生产环境中页数过多可能影响系统稳定性。可在配置文件中设置Serving: extra: max_num_input_imgs: 页数上限例如 100max_num_input_imgs同时限制 PDF 与多页 TIFF 的最大处理页数设为null表示不限制。4.4.3 应用配置文件手动安装依赖部署时启动服务时将--pipeline参数指定为自定义配置文件路径即可paddlex --serve --pipeline /path/to/your_pipeline_config.yaml5. 模型微调如果 PaddleOCR-VL 在特定业务场景下未达到精度预期官方建议使用 ERNIEKit 套件对 VLM如 PaddleOCR-VL-0.9B进行监督微调SFT详细步骤参考 ERNIEKit 官方文档中的 PaddleOCR-VL SFT 章节。目前不支持对版面分析与排序模型进行微调。总结Apple SiliconM1–M4上使用 PaddleOCR-VL 的关键要点可归纳为本地直接推理以 venv 虚拟环境 CPU 版 PaddlePaddle 3.2.1 paddleocr[doc-parser]为唯一受支持路径官方 Docker 镜像不适用于本硬件性能提升通过mlx_vlm.server启动 MLX-VLM 推理服务再以--vl_rec_backend mlx-vlm-server--vl_rec_server_url--vl_rec_api_model_name接入客户端CLI 与 Python API 均支持并用vl_rec_max_concurrency调节并发完整 API 服务仅支持手动部署流程为paddlex --install serving→paddlex --serve --pipeline PaddleOCR-VL随后通过POST /layout-parsing与POST /restructure-pages两个 HTTP 接口调用微调使用 ERNIEKit 对 VLM 组件做 SFT注意版面分析模型暂不支持微调。建议在部署前对照 PaddleOCR-VL 使用教程 中的推理方法与硬件支持矩阵确认所选路径的可用性并在实际硬件上充分验证后再进入生产环境。【免费下载链接】PaddleOCRTurn any PDF or image document into structured data for your AI. A powerful, lightweight OCR toolkit that bridges the gap between images/PDFs and LLMs. Supports 100 languages.项目地址: https://gitcode.com/GitHub_Trending/pa/PaddleOCR创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考