PaddleOCR-VL Apple Silicon 使用教程¶

Info

除非另有说明，本教程中提到的 “PaddleOCR-VL” 均指 PaddleOCR-VL 系列模型（如 PaddleOCR-VL-1.5 等）；若特指 PaddleOCR-VL v1 版本，将另行明确标注。

本教程是 PaddleOCR-VL 在 Apple Silicon 上的使用指南，涵盖了从环境准备到服务化部署的完整流程。

Apple Silicon 包括但不限于以下几种：

Apple M1
Apple M2
Apple M3
Apple M4

目前 PaddleOCR-VL 已在 Apple M4 上完成精度验证；鉴于硬件环境的多样性，其他 Apple Silicon 的兼容性尚未验证。我们诚挚欢迎社区用户在不同硬件上进行测试并反馈您的运行结果。

Tip

建议先阅读 PaddleOCR-VL 使用教程中的流程导览，根据您的使用目标确认应阅读哪些章节；再回到当前硬件教程阅读对应章节。

1. 环境准备¶

我们强烈推荐您在虚拟环境中安装 PaddleOCR-VL，以避免发生依赖冲突。 例如，使用 Python venv 标准库创建虚拟环境：

# 创建虚拟环境
python -m venv .venv_paddleocr
# 激活环境
source .venv_paddleocr/bin/activate

执行如下命令完成安装：

python -m pip install paddlepaddle==3.2.1 -i https://www.paddlepaddle.org.cn/packages/stable/cpu/
python -m pip install -U "paddleocr[doc-parser]"

请注意安装 3.2.1 及以上版本的飞桨框架。

2. 快速开始¶

请参考PaddleOCR-VL 使用教程 - 2. 快速开始。

3. 使用 VLM 推理服务提升推理性能¶

默认配置下的推理性能未经过充分优化，可能无法满足实际生产需求。此步骤主要介绍如何通过 VLM 推理服务提升 PaddleOCR-VL 的推理性能。在当前硬件文档中，示例使用 MLX-VLM 作为 VLM 推理服务后端。

3.1 启动 VLM 推理服务¶

安装 MLX-VLM 推理框架（v0.3.11以上版本）：

python -m pip install "mlx-vlm>=0.3.11"

启动 MLX-VLM 推理服务：

mlx_vlm.server --port 8111

3.2 客户端使用方法¶

以下调用方式适用于已启动的 MLX-VLM 推理服务。

3.2.1 CLI 调用¶

可通过 --vl_rec_backend 指定后端类型（mlx-vlm-server），通过 --vl_rec_server_url 指定服务地址，通过 --vl_rec_api_model_name 指定 huggingface repo id 或服务端模型权重路径，例如：

paddleocr doc_parser \
  --input 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.5

3.2.2 Python API 调用¶

创建 PaddleOCRVL 对象时传入 vl_rec_backend 指定后端类型， vl_rec_server_url 参数指定服务地址，vl_rec_api_model_name 指定 huggingface repo id 或服务端模型权重路径，例如：

pipeline = PaddleOCRVL(
    vl_rec_backend="mlx-vlm-server", 
    vl_rec_server_url="http://localhost:8111/",
    vl_rec_api_model_name="PaddlePaddle/PaddleOCR-VL-1.5",
)

3.3 性能调优¶

请参考PaddleOCR-VL 使用教程 - 3.3 性能调优。

4. 服务化部署¶

目前仅支持手动部署方式。

4.1 手动部署¶

请参考PaddleOCR-VL 使用教程 4.2 方法二：手动部署。

4.2 客户端调用方式¶

请参考PaddleOCR-VL 使用教程 - 4.3 客户端调用方式。

4.3 产线配置调整说明¶

请参考PaddleOCR-VL 使用教程 - 4.4 产线配置调整说明。

5. 模型微调¶

请参考PaddleOCR-VL 使用教程 - 5. 模型微调。