# PaddleOCR-VL (paddleocr-vl)

`paddleocr-vl` 解析一页文档。它找出版面区块（文本、标题、表格、公式、图片等），识别每个区块，并按阅读顺序返回各区块，同时返回整页的 Markdown。表格以 HTML 表格表示，公式以 LaTeX 表示。

| | |
|---|---|
| 模型 ID | `paddleocr-vl`（接口的默认模型） |
| 模型 | PaddleOCR-VL 1.6（0.9B），配合 PP-DocLayoutV3 版面分析（PaddlePaddle） |
| 权重 | PaddleOCR 官方 PaddleOCR-VL 1.6（0.9B）与 PP-DocLayoutV3 |
| 用例 | [文档解析](https://stack.foldbun.com/zh/docs/use-cases/document-parsing/)、[文字识别（OCR）](https://stack.foldbun.com/zh/docs/use-cases/text-recognition/) |
| 接口 | `POST /v1/documents/parse` |
| 模型池 | 付费池：从余额中扣费 |
| 计费单位 | `page`。单位与价格：[计费](https://stack.foldbun.com/zh/docs/billing/#价目表) |
| 许可证 | Apache-2.0 |

## 工作原理

一次调用是对一页图片的两步流水线：先做版面分析，再识别每个区块。因此模型一次读取一个区域，而不是整页。计费对应的是页。

**版面分析。** PP-DocLayoutV3 把页面切分为区块，为每个区块给出类型（`text`、`title`、`table`、`formula`、`figure`、`caption`、`header`、`footer`、`list` 或 `other`）和框。同一步骤还确定区块的阅读顺序：双栏页面按栏依次阅读。

**区块识别。** 每个区块交给 PaddleOCR-VL 1.6（0.9B）。这是一个视觉语言模型，读取区块图像并写出其内容：普通文字、HTML 表格，或公式的 LaTeX。没有文字的区块（例如图片）不返回 `text`。

**拼装。** 各区块按阅读顺序拼接为整页的 Markdown。图片不会作为图像文件返回。

识别对每个区块各运行一次，但一次调用只计为一个 `page`，与页面有多少区块无关。

## 各用例下的特性

### 文档解析

`paddleocr-vl` 是 `POST /v1/documents/parse` 的默认模型，适用于发票、论文、报告和书页。

- 页面的每个区域作为一个区块返回，包含 `type`、`order`（阅读顺序，从 0 开始，由模型判定）、`bbox`，以及识别出的 `text` 和 `markdown`。
- 表格是 HTML `<table>` 元素，同时出现在 `text` 和 `markdown` 中。独立成行的公式是以 `$$` 包围的 LaTeX；夹在正文行内的公式留在该区块的 `text` 和 `markdown` 中，以 `$` 包围。
- 响应还包含整页的 `markdown`。`options.blocks` 为 `false` 时不返回 `blocks`，只返回 `markdown`。
- 每次请求为一页图片，`pages` 始终为 1。多页 PDF 输入暂不可用。

用例说明与调用示例：[文档解析](https://stack.foldbun.com/zh/docs/use-cases/document-parsing/)。

### 文字识别（OCR）

`paddleocr-vl` 可以读取任何页面图片中的文字，但返回区块而不是纯文字行。截图、裁剪区域和复制文字类 OCR 的低成本选择是 [`ppocr-v6`](https://stack.foldbun.com/zh/docs/models/ppocr-v6/#文字识别ocr)。

与 [`ppocr-v6`](https://stack.foldbun.com/zh/docs/models/ppocr-v6/) 的对比：[文字识别（OCR）](https://stack.foldbun.com/zh/docs/use-cases/text-recognition/#支持的模型)。

## 限制与说明

- 每次调用一张页面图片。暂不接受多页 PDF。
- 图片限制：详见[图片](https://stack.foldbun.com/zh/docs/images/)。Stack 在识别前会为模型缩放页面。所有坐标均为摆正后的原图的像素，其尺寸由 `image.width` 和 `image.height` 返回。
- 延迟：录制的调用（用例页面中的调用示例）中 `timing.processingMs` 为 1294 ms。该数值取决于页面、排队情况和节点负载，不构成保证。