CheinTian / notes
Clipping · 6 分钟

PaddleOCR-VL 服务问题排查与部署汇总

#clippings#OCR#PaddleOCR#computer-vision#document-parsing#VLM#vLLM#deployment#troubleshooting#architecture#docker#python

📝 摘要

本文汇总了 PaddleOCR-VL 服务在 vLLM 部署下的效果问题排查结论及完整部署方案。客户反馈 PaddleOCR-VL 丢失版面分析能力，根本原因是直接用 OpenAI SDK 裸调 vLLM 的 /v1/chat/completions 接口，只调用了 VLM 识别模型而绕过了版面分析模型 PP-DocLayoutV3。PaddleOCR-VL 的正确用法是两阶段 pipeline：版面分析 + VLM 识别。文章提供了两种解决方案——客户端 SDK 集成（方案A）和完整服务化部署（方案B，推荐），并对比了 Paddle 家族四款产品（PP-OCRv6 / PP-StructureV3 / PP-ChatOCRv4 / PaddleOCR-VL）的定位差异和选型决策速查。

核心概念： PaddleOCR-VL 是两阶段 pipeline 系统，不能仅调用 VLM 识别模型，必须让版面分析和 VLM 识别都在 pipeline 内完成才能获得完整文档解析能力。

关键技术栈 / 关键要点：

  1. PaddleOCR-VL 两阶段架构 — 版面分析（PP-DocLayoutV3）检测区域与阅读顺序 + VLM 识别（PaddleOCR-VL-1.6-0.9B）对裁剪子图逐一识别
  2. vLLM 部署陷阱 — 裸调 /v1/chat/completions 只触发 VLM 识别，绕过版面分析，导致复杂版面结构错乱、表格/公式识别差、幻觉文本
  3. 方案 B 完整服务化 — Docker Compose 部署完整 pipeline，对外暴露 /layout-parsing REST API，客户端一次 HTTP 调用即获结构化结果
  4. Paddle 四产品选型 — PP-OCRv6（纯文字识别）/ PP-StructureV3（传统版面解析，轻量快速）/ PaddleOCR-VL（VLM 端到端，精度最高）/ PP-ChatOCRv4（KIE 关键信息抽取）
  5. PP-StructureV3 作为降级备选 — 精度低一档但资源消耗小，同样支持 Markdown 输出和 Docker Compose 部署

关键结论 / 实践建议： 对接后端系统优先采用方案 B（完整服务化），客户端零配置，服务端一次部署；若 GPU 资源紧张可降级到 PP-StructureV3；若需求变为字段抽取而非全文档结构化，应切换到 PP-ChatOCRv4。

PaddleOCR-VL 服务问题排查与部署方案 — 结论汇总

问题现象

客户反馈:vLLM 部署的 PaddleOCR-VL 服务,实测效果不理想,丢失版面分析能力(复杂版面下结构错乱、表格/公式识别质量差、出现幻觉文本)。

根本原因

客户是直接用 OpenAI SDK/协议裸调 vLLM 起的 /v1/chat/completions 接口,把整页图片当 image_url 传给 VLM。

这种用法只调用了 PaddleOCR-VL 系统里的一半——VLM 识别模型(PaddleOCR-VL-1.6-0.9B),完全绕过了另一半——版面分析模型(PP-DocLayoutV3)。

PaddleOCR-VL 官方设计是两阶段 pipeline:

  1. 版面分析:检测文档中的文本/表格/公式/图表/印章等区域,确定阅读顺序,裁剪出子图
  2. VLM 识别:对每个裁剪出的子图分别识别,再按阅读顺序合并成完整结果

官方文档明确警告过这个坑:"直接向 vLLM/SGLang/FastDeploy 等服务发请求,不等价于执行完整的 PaddleOCR-VL pipeline",并把这列为排障第一步要检查的问题。

两种解决方案

方案 A:客户端集成模式(client 装 PaddleOCR SDK)

架构:

plaintext
客户端(装 paddleocr[doc-parser] + PaddlePaddle)
   ├─ 版面分析:本地跑(PP-DocLayoutV3,模型轻量,CPU 即可)
   └─ VLM 识别:转发给远程 vLLM 服务

客户端要做的事:

  • 安装 paddlepaddle(CPU 版即可)+ paddleocr[doc-parser]
  • 首次运行自动下载版面分析模型(轻量,几十~100MB 级别,CPU 推理无压力)
  • 代码里指定 vl_rec_backend="vllm-server" + vl_rec_server_url 指向已部署好的 vLLM 服务
  • 纯 CPU 机器无需任何额外配置,SDK 会自动检测无 GPU 则 fallback 到 CPU

适用场景: 客户希望用 Python 直接集成到自己的应用代码里

方案 B:完整服务化部署(推荐,更适合对接 CSGHub 这类后端系统)

架构:

plaintext
客户端 → POST /layout-parsing (完整 PaddleOCR-VL 服务)
              ├─ 版面分析(服务内部本地跑)
              └─ VLM 识别(服务内部转发给 vLLM,配置在 pipeline 配置文件中)

用官方 Docker Compose(或手动部署)起一个完整 pipeline 的 web 服务,对外暴露标准 REST API,内部自动编排"版面分析 + VLM 识别 + 结果合并"全流程,客户端只需一次 HTTP 调用即可拿到最终结构化结果。

接口调用方式:

plaintext
POST http://<server>:8080/layout-parsing
Content-Type: application/json

{
  "file": "<base64编码的图片或PDF>",
  "fileType": 1   // 0=PDF, 1=图片
}

返回结果核心字段(result.layoutParsingResults 数组,每页/每图一个元素):

  • prunedResult:结构化解析结果(区域、内容、阅读顺序)
  • markdown:Markdown 格式结果
  • outputImages:可视化标注图(base64 或预签名 URL)

两种方案对比

方案 A(客户端集成) 方案 B(完整服务化)
客户端需要装什么 Python + PaddlePaddle(CPU 版足够) 无需装任何 OCR 相关依赖
调用协议 Python SDK 调用 标准 REST API(POST + JSON)
适合场景 Python 应用直接集成 微服务架构、多语言客户端对接(PHP/Go/TS 均有官方示例)
版面分析在哪跑 客户端本地 服务端本地
部署复杂度 客户端要装环境 服务端一次部署,客户端零配置

建议: 对接 CSGHub 这类后端系统,优先用方案 B,后端只管发文件收结果,不用关心内部两阶段模型编排逻辑。

关键结论(一句话版)

不能直接用 OpenAI 协议裸调 vLLM 服务处理文档图片,那只是调了 VLM 识别模型,丢失了版面分析能力。正确做法是让"版面分析+VLM识别"两阶段都在 PaddleOCR-VL 官方定义的 pipeline 里跑完,要么在客户端本地跑版面分析(方案A),要么直接部署官方完整服务、调用 /layout-parsing 接口(方案B,推荐)。

Paddle 家族这几个东西定位不一样,不是升级换代关系,而是针对不同任务的独立产品线。

四款产品定位

1. PP-OCRv6 — 纯文字检测识别

不含版面理解,只做"图里有哪些文字、文字是什么"。是通用场景文字识别模型,一个模型能处理多种文字类型及复杂手写体,轻量(1.5M~34.5M 参数),CPU 就能跑得很快。

适用: 只要文字内容、不关心版面结构的场景——证件识别、单据关键字段抓取、验证码/水印文字提取、大批量图片文字检索索引等。

2. PP-StructureV3 — 传统版面解析 pipeline

采用"版面优先"策略:先检测和分类文档区域,再用针对每种内容类型(文本、表格、公式、印章、图表)优化的专用识别模块分别处理。相比 v1 pipeline,增强了版面检测、表格识别、公式识别能力,并新增了多栏阅读顺序还原、图表理解、结果转 Markdown 的能力。

和 PaddleOCR-VL 的本质区别是:PP-StructureV3 走的是传统检测识别路线(每种元素用专门的小模型,如表格结构识别模型、公式识别模型各自独立),而不是统一用 VLM 做识别。

适用: 需要高精度文档结构化解析(转 Markdown/HTML/表格),但希望模型更轻量、部署成本更低、速度更快,不想背 VLM 的推理开销。官方目前强推这个版本作为文档解析主力方案。

3. PP-ChatOCRv4 — 智能关键信息抽取(KIE)

是结合 LLM、多模态大模型(MLLM)与 OCR 技术的智能分析方案,原生集成 ERNIE 4.5 做精准关键信息抽取,能通过向量检索和对话式问答处理生僻字、多页 PDF、复杂表格等复杂抽取场景。相比上一代准确率提升 15 个百分点。

适用: 不是"把整页转成结构化文档",而是**"从文档里问答式地抽取特定字段"**——比如从合同里抽"甲方名称、签约日期、金额",从发票里抽"税号、开票单位",本质是 KIE(关键信息提取)场景,用自然语言 prompt 问答的方式拿到指定字段,而不是拿到全文档结构。

4. PaddleOCR-VL — VLM 端到端文档解析

前面已经聊过的,版面分析(PP-DocLayoutV3)+ VLM 识别(PaddleOCR-VL-0.9B)两阶段,靠 VLM 统一处理各种元素类型,精度目前是几款里最高的(OmniDocBench SOTA),尤其在复杂版面、古籍、生僻字、印章、图表理解上表现突出,但推理成本比传统 pipeline 高。

怎么选(决策速查)

需求 选择
只要识别文字内容,不关心版面结构 PP-OCRv6
要把整页/整份文档转成结构化 Markdown/表格,追求速度和轻量部署 PP-StructureV3
要把整页/整份文档转成结构化 Markdown,追求最高精度,能接受更高算力成本 PaddleOCR-VL
不要整页结构,只要从文档里问答式抽取几个指定字段(甲方、金额、日期等 KIE 场景) PP-ChatOCRv4

落到你的场景

CSGHub 目前接的是 PaddleOCR-VL,如果客户后续反馈"GPU 资源紧张、想要更轻量的方案",PP-StructureV3 是一个可以作为备选降级方案介绍的对象——精度低一档但资源消耗小很多,同样支持转 Markdown、同样有 Docker Compose 一键部署的服务化方案(架构上和 PaddleOCR-VL 的方向二类似)。而如果客户后续需求变成"从文档里抽取特定字段"而不是"要完整文档结构",那应该引导他们换用 PP-ChatOCRv4,而不是继续在 PaddleOCR-VL 上折腾 prompt。

返回 Clippings