开源发布｜ZhDocParser：不是 OCR，而是面向 RAG 与 Agent 的中文复杂文档结构化解析工具

开源发布｜ZhDocParser：不是 OCR，而是面向 RAG 与 Agent 的中文复杂文档结构化解析工具

如果你也做过 RAG、知识库、Agent，应该都踩过一个坑：

文档不是"读不出来"，而是"读出来之后根本不能用"。

---

摘要

今天正式分享我最近持续打磨的一个开源项目：ZhDocParser 。

它的目标不是做"又一个 OCR 工具"，而是把 中文 PDF / DOCX 稳定转换成适合 RAG、知识库、Agent 使用的结构化内容。

目前项目已经支持：

• PDF / DOCX 解析
• Markdown / JSON / chunks.json 输出
• 标题层级恢复
• 页眉页脚过滤
• 简单多栏阅读顺序恢复
• 表格抽取与表格上下文绑定
• 多页连续表格合并
• 弱边框文本表格识别
• CLI / HTTP API / Python SDK
• 可运行 benchmark 与 reference eval

项目地址：

• GitHub: https://github.com/melonelish/ZhDocParser

---

一、为什么我要做这个项目？

这几年做 RAG、文档问答、知识库、Agent 项目时，我反复遇到同一个问题：

真正难的不是"把文字抽出来"，而是"把文档结构保留下来"。

很多现成工具在简单文本上没有问题，但一旦遇到下面这些材料，效果就会明显下降：

• 中文公文
• 报告型 PDF
• 教辅 / 题库 / 讲义
• 多栏版式文档
• 带复杂表格的资料
• 页眉页脚很多的材料

常见问题也很典型：

• 标题层级丢了，整篇文档变成一坨纯文本
• 表格抽出来了，但上下文没了
• 左右双栏被按行交错拼接
• 页眉页脚混进正文，检索噪声很高
• chunk 没有来源信息，命中后难以追溯

所以我想做一个更偏"文档理解"的工具，而不是停留在"文本提取"。

---

二、ZhDocParser 不是 OCR，它解决的到底是什么问题？

一句话定义它：

ZhDocParser 是一个面向中文复杂文档的结构化解析工具，用来把 PDF / DOCX 转成适合 RAG 与 Agent 使用的 Markdown、JSON 与 Chunks。

它关心的重点不是"识别出字"，而是下面这几件事：

• 文档结构有没有保住
• 标题层级有没有恢复
• 表格语义有没有保住
• chunk 是否可以直接喂给检索系统
• 结果是否可追踪、可引用、可解释

也就是说，它更像一个 文档结构恢复引擎。

---

三、这个项目目前已经能做什么？

当前版本已经支持这些核心能力：

1. 文档输入

• PDF
• DOCX

2. 输出格式

• document.md
• document.json
• chunks.json

3. 文档结构能力

• 标题层级恢复
• 章节路径保留
• section_id_path / parent_id 结构关系输出
• 页眉页脚过滤
• 简单双栏 PDF 阅读顺序恢复

4. 表格能力

• PDF 网格表格抽取
• DOCX 表格抽取
• 表格标题识别
• 表格上下文绑定
• 多页连续表格合并
• 弱边框 / 文本对齐表格的第一版识别

5. 面向 RAG 的输出

• chunk 自动生成
• 支持独立 chunks.json
• chunk 附带 page_range / source_pages / section_id_path / heading_path_text
• 表格 chunk 支持 continued / context_before / context_after

6. 接入方式

• CLI
• HTTP API
• Python SDK

---

四、它最适合哪些场景？

我目前最看重的，是它在下面几类场景里的落地性：

1. RAG / 知识库构建

如果你要把 PDF、DOCX 喂给向量库，纯文本通常不够。

你更需要的是：

• 正确的标题层级
• 高质量 chunk
• 可追踪的来源元数据
• 不被页眉页脚污染的正文

2. Agent 文档理解

Agent 在处理文档时，最怕的是结构错乱。

如果标题、表格、上下文都乱了，后面的推理链很容易偏掉。

3. 中文公文 / 报告 / 教辅材料处理

这类文档往往更复杂，也更能体现一个解析器有没有真正"可用"。

---

五、一个最关键的定位：它不是 OCR，而是结构化理解

这句话我想单独拎出来说：

不是把文档读成字，而是把文档读成结构。

OCR 只是底层能力之一。

如果最终输出还是一坨没有结构的文本，那对 RAG 和 Agent 来说，价值是很有限的。

ZhDocParser 关注的是：

• 结构恢复
• 语义保留
• 检索友好
• 可追踪输出

---

六、当前版本的一些亮点

这次我重点打磨了几个我自己很在意的点。

1. 双栏 PDF 不再按行交错读取

很多工具会把这种内容读成：

左栏第一行
右栏第一行
左栏第二行
右栏第二行

而更合理的结果应该是：

左栏第一行
左栏第二行
右栏第一行
右栏第二行

ZhDocParser 现在对这类简单报告型双栏版式已经做了第一版恢复。

2. 表格不再只是"几行几列"

我比较在意的一点是：

表格本身不是孤立的，表格标题和表格前后说明同样重要。

所以现在表格除了 rows，还会带：

• title
• context_before
• context_after
• source_pages
• continued

这对后续做检索和引用很有帮助。

3. 多页表格可以连续合并

很多报告里的表格不是一页能放下的。

如果每一页都被当成独立表格，下游几乎一定要再做二次处理。

现在项目已经支持一版 多页连续表格合并。

4. 提供 SDK / API / CLI 三种接入方式

这点我专门补上了，因为我不希望它只是一个"演示型项目"。

---

七、快速上手

1. 安装

git clone https://github.com/melonelish/ZhDocParser.git
cd ZhDocParser
pip install -e .[dev]

2. 单文件解析

zhdocparser parse ./samples/example.pdf -o ./outputs

输出会生成一个 bundle：

outputs/example_pdf/
  document.md
  document.json
  chunks.json

3. 目录批量解析

zhdocparser parse-dir ./samples -o ./batch_outputs

4. HTTP API

zhdocparser serve --host 127.0.0.1 --port 8000

本地路径解析：

curl -X POST http://127.0.0.1:8000/parse ^
  -H "Content-Type: application/json" ^
  -d "{\"source_path\":\"D:/fabuxiangmu2/samples/example.docx\",\"max_chunk_chars\":500}"

上传文件解析：

curl -X POST http://127.0.0.1:8000/parse-upload ^
  -F "file=@D:/fabuxiangmu2/samples/example.docx" ^
  -F "response_format=metadata"

5. Python SDK

from zhdocparser import parse_file
from zhdocparser.config import ParserConfig

document = parse_file(
    "samples/example.docx",
    ParserConfig(doc_type_override="general", max_chunk_chars=500),
)

print(document.metadata.title)
print(len(document.chunks))

---

八、这个版本重点做了哪些升级？

如果按版本看，这个项目已经从最初的"基础可跑"，逐步迭代到了现在更像"可集成组件"的形态。

当前版本重点包括：

• 统一 ParserConfig
• Python SDK 高层接口
• 上传式 API
• 结构化错误响应
• 章节层级关系字段
• 多页连续表格合并
• 弱边框文本表格识别
• 可运行 eval/ 评测体系

---

九、我为什么补了一套 eval？

这是我这次比较坚持要做的一件事。

很多开源项目会写：

• "支持某某能力"
• "效果更强"
• "适合某某场景"

但如果没有一套最基本的 reference 和 benchmark，很难持续验证自己到底有没有进步。

所以我专门补了：

• eval/README.md
• eval/run_benchmarks.py
• reference expectations
• report fixture
• weak-border table fixture
• continued-table fixture

现在可以直接跑：

python ./eval/run_benchmarks.py

它会验证这些 case：

• 示例 PDF
• 示例 DOCX
• 双栏阅读顺序
• 弱边框文本表格
• 多页连续表格

这一步对开源项目很重要，因为它决定了你后面迭代时是不是"有标准可对照"。

---

十、当前状态怎么样？

我自己对它的评价是：

已经不是 demo 了，但还不是最终形态。

我比较满意的是：

• 方向是对的
• 结构已经清晰
• 输出已经能接 RAG / Agent
• 工程入口已经比较完整
• 有 benchmark 和 regression 了

但它也还有明显边界：

• 还没做 OCR fallback
• 扫描件能力还没补
• 超复杂多栏仍然是启发式
• PDF 表格对显式网格仍更友好
• 合并单元格重建还不够强

所以它现在是一个 "已经可用、但还值得持续打磨" 的状态。

---

十一、后续 roadmap

接下来我比较想继续推进这些方向：

1. OCR / 扫描件支持

把扫描版 PDF 也纳入可用范围。

2. 更强的多栏恢复

不仅支持简单报告型双栏，还能覆盖更复杂布局。

3. 更强的 PDF 表格能力

特别是无边框表格、复杂表格和合并单元格。

4. 更完整的 API / MCP / 工程接入能力

让它更容易接到真实业务系统里。

---

十二、适合谁来看看这个项目？

如果你是下面这些人，我觉得这个项目大概率会对你有帮助：

• 正在做 RAG / 知识库
• 正在做 Agent 文档理解
• 经常处理中文 PDF / DOCX
• 需要把文档转成 Markdown / JSON
• 对文档结构恢复、表格抽取感兴趣

---

十三、项目地址

• GitHub: https://github.com/melonelish/ZhDocParser

如果你觉得这个方向有价值，欢迎：

• Star
• 提 Issue
• 提 PR
• 给我一些真实中文复杂文档样例反馈

---

十四、最后想说一句

我做这个项目时越来越强烈的一个感受是：

中文世界并不缺"能识别文字"的工具，缺的是"能把复杂文档真正还原成可用结构"的工具。

如果你也在做文档理解、知识库、RAG 或 Agent，希望 ZhDocParser 能给你一点帮助。

这也是我把它开源出来的原因。

如果这篇文章你觉得有帮助，也欢迎点个收藏，我会继续更新这个项目的后续迭代记录。

---