开源发布｜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. 文档输入PDFDOCX2. 输出格式document.mddocument.jsonchunks.json3. 文档结构能力标题层级恢复章节路径保留section_id_path / parent_id结构关系输出页眉页脚过滤简单双栏 PDF 阅读顺序恢复4. 表格能力PDF 网格表格抽取DOCX 表格抽取表格标题识别表格上下文绑定多页连续表格合并弱边框 / 文本对齐表格的第一版识别5. 面向 RAG 的输出chunk 自动生成支持独立chunks.jsonchunk 附带page_range / source_pages / section_id_path / heading_path_text表格 chunk 支持continued / context_before / context_after6. 接入方式CLIHTTP APIPython SDK四、它最适合哪些场景我目前最看重的是它在下面几类场景里的落地性1. RAG / 知识库构建如果你要把 PDF、DOCX 喂给向量库纯文本通常不够。你更需要的是正确的标题层级高质量 chunk可追踪的来源元数据不被页眉页脚污染的正文2. Agent 文档理解Agent 在处理文档时最怕的是结构错乱。如果标题、表格、上下文都乱了后面的推理链很容易偏掉。3. 中文公文 / 报告 / 教辅材料处理这类文档往往更复杂也更能体现一个解析器有没有真正“可用”。五、一个最关键的定位它不是 OCR而是结构化理解这句话我想单独拎出来说不是把文档读成字而是把文档读成结构。OCR 只是底层能力之一。如果最终输出还是一坨没有结构的文本那对 RAG 和 Agent 来说价值是很有限的。ZhDocParser 关注的是结构恢复语义保留检索友好可追踪输出六、当前版本的一些亮点这次我重点打磨了几个我自己很在意的点。1. 双栏 PDF 不再按行交错读取很多工具会把这种内容读成左栏第一行 右栏第一行 左栏第二行 右栏第二行而更合理的结果应该是左栏第一行 左栏第二行 右栏第一行 右栏第二行ZhDocParser 现在对这类简单报告型双栏版式已经做了第一版恢复。2. 表格不再只是“几行几列”我比较在意的一点是表格本身不是孤立的表格标题和表格前后说明同样重要。所以现在表格除了rows还会带titlecontext_beforecontext_aftersource_pagescontinued这对后续做检索和引用很有帮助。3. 多页表格可以连续合并很多报告里的表格不是一页能放下的。如果每一页都被当成独立表格下游几乎一定要再做二次处理。现在项目已经支持一版多页连续表格合并。4. 提供 SDK / API / CLI 三种接入方式这点我专门补上了因为我不希望它只是一个“演示型项目”。七、快速上手1. 安装gitclone https://github.com/melonelish/ZhDocParser.gitcdZhDocParser pipinstall-e.[dev]2. 单文件解析zhdocparser parse ./samples/example.pdf-o./outputs输出会生成一个 bundleoutputs/example_pdf/ document.md document.json chunks.json3. 目录批量解析zhdocparser parse-dir ./samples-o./batch_outputs4. HTTP APIzhdocparser serve--host127.0.0.1--port8000本地路径解析curl-XPOST http://127.0.0.1:8000/parse ^-HContent-Type: application/json^-d{\source_path\:\D:/fabuxiangmu2/samples/example.docx\,\max_chunk_chars\:500}上传文件解析curl-XPOST http://127.0.0.1:8000/parse-upload ^-FfileD:/fabuxiangmu2/samples/example.docx^-Fresponse_formatmetadata5. Python SDKfromzhdocparserimportparse_filefromzhdocparser.configimportParserConfig documentparse_file(samples/example.docx,ParserConfig(doc_type_overridegeneral,max_chunk_chars500),)print(document.metadata.title)print(len(document.chunks))八、这个版本重点做了哪些升级如果按版本看这个项目已经从最初的“基础可跑”逐步迭代到了现在更像“可集成组件”的形态。当前版本重点包括统一ParserConfigPython SDK 高层接口上传式 API结构化错误响应章节层级关系字段多页连续表格合并弱边框文本表格识别可运行eval/评测体系九、我为什么补了一套 eval这是我这次比较坚持要做的一件事。很多开源项目会写“支持某某能力”“效果更强”“适合某某场景”但如果没有一套最基本的 reference 和 benchmark很难持续验证自己到底有没有进步。所以我专门补了eval/README.mdeval/run_benchmarks.pyreference expectationsreport fixtureweak-border table fixturecontinued-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能给你一点帮助。这也是我把它开源出来的原因。如果这篇文章你觉得有帮助也欢迎点个收藏我会继续更新这个项目的后续迭代记录。