LiteParse 输出空白或乱码？5 步排查法让解析结果快速恢复正常

LiteParse 输出空白或乱码？5 步排查法让解析结果快速恢复正常

【免费下载链接】liteparseA fast, helpful, and open-source document parser项目地址: https://gitcode.com/GitHub_Trending/li/liteparse

LiteParse 是本地运行的开源文档解析器，把 PDF、Office、图片转成 Markdown、JSON、纯文本。你的输出一旦缺字、乱码或整页空白，LiteParse 排查可以按症状走。本文按你看到的症状分节，每节给可执行的命令，照着跑一遍，几分钟内定位问题根源。

先花 30 秒分流：一条命令判定页面类型

拿到问题文档，先跑复杂度检测，别急着改配置：

lit is-complex document.pdf

它逐页输出needs_ocr判定和原因列表（scanned、no-text、garbled），任一页需要 OCR 时退出码非零。读原因列表：标scanned的页是扫描件，文本本来就躺在图片里；标no-text的是空白页；标garbled的是字体编码坏了。后面三节按症状分流，这一步决定你该往哪走。

输出空白怎么查：扫描件没跑 OCR、语言包缺失

🔍最常见原因：页面是扫描图，但解析没走 OCR。整页是图、没有文本层，不开 OCR 时输出必然是空。验证：跑lit is-complex document.pdf，看该页reasons是否含scanned。解法：重跑解析并去掉--no-ocr，中文扫描件把语言改成对应代码：

lit parse document.pdf --ocr-language chi_sim

下面是这类文档的典型样子，解析它只得到空文本时，基本可以锁定 OCR 环节：

次常见原因：Tesseract 语言包缺失。离线机器首次运行时语言包静默下载失败，所有页 OCR 都挂，报错OCR failed for all N page(s)——这是它拒绝静默返回空白结果的设计。验证：用--tessdata-path或TESSDATA_PREFIX指向已下载.traineddata的目录重跑，或换 HTTP OCR 服务（见 ocr/paddleocr/server.py）。解法：

lit parse document.pdf --tessdata-path /path/to/tessdata

乱码错字怎么查：语言代码、字体映射、OCR 服务不通

按概率排第一：语言代码错配。内置 Tesseract 用 ISO 639-3 代码（eng、deu），而 HTTP OCR 服务常只认en。验证：对照你传的参数看用的是哪条链路。解法：换 ISO 639-3 代码，或显式传短代码给 HTTP 服务：

lit parse document.pdf --ocr-server-url http://localhost:8828/ocr --ocr-language en

排第二：字体编码映射失败。原生文本层里字符映射不到正确字形，提取出一串乱码，跟 OCR 无关。验证：加--extract-text-metadata看每个文本项的字体信息，乱码项的字体名往往就是元凶，实现逻辑可查 font_cmap.rs 与 glyph_resolver.rs。解法：对该页单独跑lit parse document.pdf --target-pages "3" --no-ocr确认是原生文本问题后，走 OCR 兜底。

排第三：HTTP OCR 服务不通。服务没起、端口错、/ocr端点没实现规范都会挂。验证：单独 curl 测端点：

curl -X POST http://localhost:8828/ocr -F "file=@test.png" -F "language=en"

解法：端点通了再谈解析，接口字段要求见 OCR_API_SPEC.md。

内容齐全但结构乱：查块分类和开关

最常见原因：块被分错。Markdown 由块分类器生成，段落被当成表格、列表被折进段落都会让结构崩掉。验证：

lit parse document.pdf --format json --extract-blocks

JSON 里每个块带kind和 bbox，对照页面截图找分错的那块，分类器实现集中在 crates/liteparse/src/markdown_layout/。

次常见：页眉页脚被默认剥离。你觉得"内容丢了"，其实是运行页眉被过滤。验证：加--keep-headers-footers重跑对比输出。

第三：图片占位与链接语法干扰阅读。占位符![](img_pN_K.png)和链接语法看着乱，但内容没丢。验证：跑--image-mode off --no-links做对比实验，排除误判。

📌 拿不准"是提取坏了还是原文就这样"时，截图人工裁决最快：

lit screenshot document.pdf -o ./screenshots --dpi 150

逐区域比对截图和解析输出，哪块对不上就把页码记下来，用--target-pages只重解析那几页。

报错前缀速查表

错误定义集中在 crates/liteparse/src/error.rs，看前缀就能归类：

收尾：4 步自检顺序

1. lit is-complex分流：扫描、空白还是乱码
2. 核 OCR 配置：语言代码、语言包、服务 URL
3. --target-pages缩小范围，--extract-blocks看分类
4. lit screenshot截图比对原文

按这个顺序走完，90% 的解析异常都能当场定位。现在你已经能独立排查 LiteParse 了。

【免费下载链接】liteparseA fast, helpful, and open-source document parser项目地址: https://gitcode.com/GitHub_Trending/li/liteparse