# 文档解析

文档解析找出页面的版面区块（文本、标题、表格、公式、图片等），识别每个区块，并按阅读顺序返回各区块，同时返回整页的 Markdown。表格以 HTML 表格表示，公式以 LaTeX 表示。典型用途是把发票、论文、报告和书页转换为结构化文本。每次请求为一页图片。多页 PDF 输入暂不可用。如需读取截图或裁剪区域中的纯文字行，请参阅[文字识别（OCR）](https://stack.foldbun.com/zh/docs/use-cases/text-recognition/)。

## 版面区块与阅读顺序

页面的每个区域作为 `blocks` 的一项返回，包含 `type`、`order`、`bbox`，以及识别出的 `text` 和 `markdown`。`type` 为 `text`、`title`、`table`、`formula`、`figure`、`caption`、`header`、`footer`、`list`、`other` 之一。`order` 为阅读顺序，从 0 开始，由模型判定；下图中的页面按栏依次阅读。响应的 `markdown` 字段按该顺序拼接各区块。

![一页双栏论文，25 个版面区块上标有编号框；右侧为区块列表，列出类型和文字。](../../../../../assets/docs/paddleocr-vl-layout.webp)

*Playground 对一页双栏论文的实录结果。编号为 `order`；右侧列表显示 `type` 和 `text` 的开头，25 个区块中包括标题、文本、公式、表格和页脚。*

`options.blocks` 为 `false` 时不返回 `blocks`，只返回 `markdown`。

## HTML 表格

`table` 类型的区块把表格作为 HTML `<table>` 放在 `text` 和 `markdown` 中，行、列和表头单元格得以保留，可直接渲染或解析。

![一页发票，两个表格被青色框标出；右侧为第 7 个区块（明细大表）的 HTML 渲染结果。](../../../../../assets/docs/paddleocr-vl-tables.webp)

*Playground 对一张发票的实录结果。青色框是 `table` 类型的区块；右侧是 `order` 为 7 的区块的 HTML 渲染结果。*

## LaTeX 公式

`formula` 类型的区块把独立成行的公式作为 LaTeX 返回，以 `$$` 包围。夹在正文行内的公式留在该区块的 `text` 和 `markdown` 中，以 `$` 包围。

![一页中文物理教材，位移公式被框出；下方为识别出的 LaTeX，以及前一文本区块中的行内公式。](../../../../../assets/docs/paddleocr-vl-formulas.webp)

*Playground 对一页教材的实录结果。框出的独立公式是 `formula` 类型的区块；识别出的 LaTeX 显示在页面下方，并附有相邻 `text` 区块中的一个行内公式。*

## 支持的模型

`paddleocr-vl` 是 `POST /v1/documents/parse` 的默认模型，也是唯一的模型。

- [`paddleocr-vl`](https://stack.foldbun.com/zh/docs/models/paddleocr-vl/#文档解析) 是面向文档的模型：带框的有类型区块、阅读顺序、HTML 表格、LaTeX 公式，以及整页的 Markdown。按页计费，仅在付费池中可用。
- [`ppocr-v6`](https://stack.foldbun.com/zh/docs/models/ppocr-v6/#文档解析) 返回纯文字行和字级框，不返回版面、阅读顺序、表格和公式，是截图、裁剪区域和复制文字类 OCR 的低成本选择。两者的对比表见[文字识别（OCR）](https://stack.foldbun.com/zh/docs/use-cases/text-recognition/#支持的模型)。

## 调用示例

将一页发票图片发送到 `POST /v1/documents/parse`，同时返回版面区块：

```bash
curl https://api.stack.foldbun.com/v1/documents/parse \
  -H "Authorization: Bearer $FOLDBUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "paddleocr-vl",
    "image": { "id": "img_e0100380a624332f4161c651ea355c84914159eaa064df2db226519dadb944e7" },
    "options": { "blocks": true }
  }'
```

以下响应有删减：该页有更多区块，Markdown 字符串也更长。

```json
{
  "id": "call_01a1913d-e9ef-767e-8ca1-f490b0af5533",
  "model": "paddleocr-vl",
  "image": {
    "id": "img_e0100380a624332f4161c651ea355c84914159eaa064df2db226519dadb944e7",
    "width": 1008,
    "height": 1426,
    "bytes": 143151,
    "contentType": "image/jpeg"
  },
  "pages": 1,
  "markdown": "INVOICE\n\n<table>...</table>\n\n## BILL TO\n\nAlder & Finch Trading Ltd.\n...",
  "blocks": [
    { "type": "header", "order": 1, "bbox": [710, 76, 933, 124], "text": "INVOICE", "markdown": "INVOICE" },
    {
      "type": "table",
      "order": 2,
      "bbox": [81, 164, 928, 223],
      "text": "<table><tr><td>INVOICE NO.</td><td>ISSUE DATE</td></tr><tr><td>INV-2026-04817</td><td>14 Oct 2026</td></tr></table>",
      "markdown": "<table><tr><td>INVOICE NO.</td><td>ISSUE DATE</td></tr><tr><td>INV-2026-04817</td><td>14 Oct 2026</td></tr></table>"
    }
  ],
  "cost": 2,
  "balance": 996,
  "timing": { "queueMs": 0, "processingMs": 1294 },
  "billing": {
    "lines": [
      { "unit": "page", "quantity": 1, "unitPrice": 2, "amount": 2, "waived": false }
    ],
    "total": 2,
    "charged": true,
    "pool": null
  }
}
```

### 响应解读

- `pages` 为 1：一次请求是一页图片。
- `markdown` 为按阅读顺序排列的整页内容，表格为 HTML。
- `blocks` 为每个版面区域一项，JSON 中显示其中两项。此处 `type` 为 `header` 和 `table`，`order` 为阅读顺序，`bbox` 为 `[x1, y1, x2, y2]`，单位为摆正后的原图的像素，此处为 1008 × 1426（`image.width`、`image.height`）。
- `text` 为区块识别出的文字。`table` 区块的 `text` 和 `markdown` 均为 HTML `<table>`。
- `billing.charged` 为 `true`，`pool` 为 `null`：本次调用从余额中扣费，因此 `cost` 为 2。

全部字段：[API 参考](https://stack.foldbun.com/zh/docs/api/operations/parsedocument/)。

**本次调用的费用。** 每次调用 2（`page`）额度，与区块数量无关，与本响应的实际扣费一致。单价见[计费](https://stack.foldbun.com/zh/docs/billing/#价目表)。

## 接口与参考

| 接口 | 在本用例中 | 参考 |
|---|---|---|
| `POST /v1/documents/parse` | 一页图片得到有序区块、HTML 表格、LaTeX 公式和整页 Markdown | [API 参考](https://stack.foldbun.com/zh/docs/api/operations/parsedocument/) |
| `POST /v1/ocr` | 返回纯文字行和字级框，而不是结构 | [API 参考](https://stack.foldbun.com/zh/docs/api/operations/ocr/) |

- [`paddleocr-vl`](https://stack.foldbun.com/zh/docs/models/paddleocr-vl/)：模型的工作原理、限制和实测延迟。
- [计费](https://stack.foldbun.com/zh/docs/billing/#价目表)：`paddleocr-vl` 每次调用计一个 `page`。
- [文字识别（OCR）](https://stack.foldbun.com/zh/docs/use-cases/text-recognition/)：`ppocr-v6` 的纯文字行和字级框，以及两个模型的对比。