痛点：做 RAG 的同学常常卡在一类文档——扫描件 PDF、截图 PDF 或者图片嵌入的 PDF。怎么说呢，即使把文件上传到向量库，检索时却总是搜不到任何内容。因为文字根本不在 PDF 的文本层。

我在建立公司级 RAG 知识库 PaiSmart 时也深受其扰。经过多次尝试，终于找到了一个“轻量、本地、快速”的方法：使用 LlamaIndex 开源的 LiteParse一条命令就可以完成 OCR。无需 API Key，解析速度相当给力。

下面把整个方案拆解为四个关键环节。并穿插实际踩坑经验，方便你复现。

LiteParse 是 LlamaIndex 团队于 2024 年 5 月 12 日 开源的文档解析工具，遵循 Apache 许可证。项目仓库地址见图中链接，

LlamaIndex 已经很有名。他们的明星产品 LlamaParse 能够精准解析各种复杂文档，但它是基于云服务，需要上传文件、付费并保持网络连接。

LiteParse 将 LlamaParse 的主要能力抽离出来以本地可执行文件的形式提供。实现了以下特性：

• 本地运行：完全离线，不依赖网络或外部 API。
• 轻量快：主要用 Rust 重写。底层依赖 PDFium 渲染 PDF，使用 Tesseract 完成 OCR。
• No API Key：无需任何云端凭证，即可直接在机器上执行。按理说，

它适用于结构相对简单、追求低延迟的场景。特别是 AI Agent “快速读一遍、需要时再细看”的迭代模式。

LlamaParse 仍然负责更艰深的文档，而 LiteParse 则专注于“轻量级”需求。

支持的文件类型

• PDF：直接走 PDFium 做空间文本解析，对扫描页和内嵌图片自动触发 OCR。
• Office 文档：Word、PPT、Excel、CSV 等先通过 LibreOffice 转成 PDF，再统一解析。
• 图片：PNG、JPG、TIFF、WebP 等先用 ImageMagick 转为 PDF，接下来 OCR。不过，

lit 命令行使用教程

L​iteParse 提供 npm、pip 与 cargo 三种安装方式。安装后统一使用名为 lit 的 CLI 工具。

npm i -g @llamaindex/liteparse # 或者
pip install liteparse # 或者
cargo install liteparse

基础解析

lit parse docs/paismart.pdf

默认把文本直接输出到标准输出，可配合 Unix 管道使用，例如快速定位包含 “table” 的行：

lit parse docs/paismart.pdf | grep "table"

If PDF lives remotely。you can pipe it straight from curl:

curl -sL https://example.com/report.pdf | lit parse -

结构化 JSON 输出

lit parse document.pdf --format json -o output.json

The generated JSON not only contains plain text,but also bounding‑box coordinates of each text segment and its page number.

常用可选参数概览

• : 只解析指定页码，调试大文件时省时省资源。
• : 关闭 OCR，对纯文本 PDF 加速显著。
• : 指定语言包，中文需使用 chi_sim.
• : 接入外部 OCR 服务。不过，不填则使用内置 Tesseract。
• : 渲染分辨率；DPI 越高 OCR 越准，但耗时与内存也随之增长。
• : 并行 worker 数，多核机器可加速处理。
• : 限制最大解析页数，防止超大文件拖垮进程。说起来，
• : 解密受密码保护的 PDF。

批量与截图功能

# 批量解析整个目录
lit batch-parse ./input-directory ./output-directory
# 为每一页生成截图
lit screenshot document.pdf -o ./screenshots

把 LiteParse 接进 PaiSmart

整体流程回顾

• User uploads a file → Kafka receives a processing task.
• The consumer pulls task → invokes a parsing service → splits document into chunks.
• The chunks are embedded → vectors are stored in Elasticsearch for semantic search.
• The parsing step is where LiteParse 替换了原来的 Apache Tika，实现对扫描件的完整识别。

子进程调用示例

List command = new ArrayList<>;command.add，// lit
command.add;command.add);// 临时 PDF 方法
command.add;command.add，command.add;command.add);command.add，command.add);command.add，command.add);按理说，command.add;command.add，// chi_sim+eng
command.add;说起来，...
ProcessBuilder pb = new ProcessBuilder;pb.redirectOutput;pb.redirectError;Process proc = pb.start;boolean finished = proc.waitFor;
if {
proc.destroyForcibly;// log timeout …}
...
// finally 删除所有临时文件

关键坑点说明：

1. 超时控制：L​iteParse 在大文件或开启 OCR 时可能耗时较长。需要在子进程层面设置硬性超时并强制 kill，以防止任务阻塞线程池。

S​TDOUT / STDERR 缓冲区：If not redirected,buffers can fill up and cause child process to hang. Redirect m to temporary files for later debugging.

T​emporary file lifecycle：A single parse creates four temporary artifacts . Ensure y are cleaned up in a finally block regardless of success or failure.

P​age‑level切分 + 页码保留：L​iteParse’s JSON includes page numbers. By splitting text per page we:

• Avoid mixing sentence fragments across pages.
• Easily surface “第 N 页” in retrieval results for traceability.

The code snippet below shows how we preserve page numbers while chunking:

for { String pageText = page.text;if ) continue;List childChunks = splitTextIntoChunksWithSemantics;saveChildChunks(fileMd5,childChunks,userId。orgTag,isPublic,savedChunkCount,page.pageNumber);}

Chunk 切分策略与配置示例

至于file，parsing:
chunk-size: 1000 # 最大字符数
overlap-size: 200 # 前后块语义重叠字符数
min-chunk-size: 200 # 小于此长度会合并到相邻块
从pdf来看，engine: liteparse
liteparse:
command: lit
ocr-enabled: true
ocr-language: chi_sim+eng
说到dpi。300
max-pages: 0 # 0 表示不限制页面数量
timeout-seconds: 120 # 子进程最大运行时间
num-workers: 4 # 并行度，可根据机器核数调节
说到quiet，true # 静默模式，只输出必要信息
password: "" # 如有加密PDF请填入密码
# 环境变量可覆盖上述任意字段，例如 LIT_COMMAND_PATH、LIT_OCR_LANGUAGE 等。

图片 PDF 实测 —— 本地 Tesseract vs 阿里云高精版 OCR

本地 Tesseract 基础测试

TESSDATA_PREFIX="$HOME/Library/Application Support/tesseract-rs/tessdata"\
lit parse docs/paismart.pdf \
--target-pages "-" \
--dpi 300 \
--ocr-language chi_sim+eng \
--quiet

The raw scan looks like this。虽然识别结果不是完美，但已经可以检索到关键词汇。：LiteParse 并不会对每一页盲目进行 OCR，它会先用 PDFium 抽取文本；只有当页面文字稀疏或检测到乱码时才触发 OCR，从而显著降低不必要的计算开销。

DPI 与识别精度关系说明

• DPI 越高 → 渲染出的位图越清晰 → OCR 准确率提高；但同时 CPU/内存消耗呈线性增长。
  • A typical trade‑off for enterprise documents is DPI=300 which balances速度与准确率.
• If memory or latency is critical。consider DPI=150 and enable caching of already processed pages.

CJK语言包准备

Tesseract 默认只自带英文，需要额外下载简体中文训练数据 )。以下为跨网站安装脚本：

mkdir -p "$HOME/Library/Application Support/tesseract-rs/tessdata" curl -L -o "$HOME/Library/Application Support/tesseract-rs/tessdata/eng.traineddata" \ https这方面，//github.com/tesseract‑ocr/tessdatafast/raw/main/eng.traineddata curl -L -o "$HOME/Library/Application Support/tesseract-rs/tessdata/chisim.traineddata" \ 至于https，//github.com/tesseract‑ocr/tessdatafast/raw/main/chisim.traineddata

sudo mkdir -p /usr/local/share/tessdata sudo curl -L -o /usr/local/share/tessdata/eng.traineddata \ 至于https。//github.com/tesseract‑ocr/tessdatafast/raw/main/eng.traineddata sudo curl -L -o /usr/local/share/tessdata/chisim.traineddata \ 从https来看，//github.com/tesseract‑ocr/tessdatafast/raw/main/chisim.traineddata

The environment variable `TESSDATA_PREFIX` must point to folder containing se `.traineddata` files so that LiteParse’s embedded Tesseract can locate m.

T​esseract 在一些低分辨率或复杂布局的扫描件上仍然会出现漏字或错字。话说回来，为了解决这个痛点，我们利用 LiteParse 提供的 --ocr-server-url` 参数。把识别工作交给阿里云“通用文字识别高精版”。这一步只需要实现一个符合 LiteParse 协议的 HTTP 接口即可。

L​iteParse 所需返回格式

{
"results":,"confidence": 0.98 }。...
]
}

• `SubImages → BlockInfo → BlockDetails`：每个 BlockDetail 包含 `BlockContent`、`BlockPoints`和 `BlockConfidence`。
  该结构与 LiteParse 要求不匹配，需要一次转换层来适配。

实现适配层步骤

• **InternalOcrController**：暴露 `/api/v1/internal/ocr/liteparse` 接口；话说回来，接收来自 LitePar se 的 base64 图片流；返回符合上面 JSON 格式的数据。按理说，
• **AliyunOcrService**：封装阿里云 SDK 调用 `RecognizeAllText`；返回原始响应对象，
• **LitePare xOcrAdapterService**：将 Aliyun 响应中的 `BlockDetails` 翻译成 `results` 格式；坐标从四角点转为左上右下矩形 ``；置信度保持两位小数，

You can toggle 娱乐ween local Tesse r act and Aliyun 高精版 simply by setting an environment variable:

 aliyun:
说到ocr。enabled: true # true → 使用阿里云，高精版；false → 回退至本地 Tesse r act
endpoint: ocr-api.cn-hangzhou.aliyuncs .com
access-key-id: ${ALIYUNOCRACCESSKEYID}
access-key-secret: ${ALIYUNOCRACCESSKEYSECRET}
type这方面，Advanced # 通用文字识别高精版
output-coordinate: points # 返回四角坐标。便于后续转换
callback-token: ${ALIYUNOCRCALLBACK_TOKEN} # 若需要鉴权，请配置 token

PaaS Deployment Tip:只要在容器启动脚本里导出 ALIYUN_OCR_ENABLED=true 并填好 AccessKey，即可无缝切换，无需重新建立镜像或修改代码逻辑。

验证效果

 lit parse docs/paismart.pdf \
--target-pages "-" \
--dpi 300 \
--ocr-language chisim+eng \
--ocr-server-url http://localhost:${INTERNALPORT}/api/v1/internal/ocr/liteparse \
--quiet

The resulting text exhibits明显提高——几乎没有漏字。中文标点也能正确保留，使得后续向量化检索命中率提高约 30% 左右。使用者现在可以在对话中直接引用原始页码，例如：“请参见第 12 页”。这正是我们最初想要解决的痛点——让扫描件一样拥有可追溯的检索能力。

项目亮点摘录
项目名称 ： PaiSmart – 公司级开源 RAG 知识库	时间 ： 2024 Q1 – 至今
职责概述 ：
- 基于 LitePar se 重构了全部 PDF 与图片型文档的解析流水线。实现了离线 O C R，无需第三方 APIKey，大幅减少成本；说起来，<\/b> - 搭建了「OCR 可插拔」适配层。将本地 T esser act 与阿里云高精版 O C R 无缝切换，使得中文扫描件检索准确率提高约30%；<\/b> - 引入页码保留 + 按页切块策略。为每条向量记录来源页码，实现「检索结果溯源」功能，提高业务可信度；<\/b> - 实现父文档 + 子切片 + 汉语分词 + 重叠字符机制的语义切块方案，提高召回率并降低碎片化风险；<\/b> - 将所有关键参数抽象为环境变量，同一套代码即可在开发、预生产和生产环境平滑部署。<\/b> <\/ul>

---