LiteParse 完整中文操作手册¶

基于 LiteParse 主分支（2025年5月），GitHub: https://github.com/run-llama/liteparse

一、项目简介：它是什么，解决什么问题？¶

LiteParse 是由 LlamaIndex（run-llama）团队开发的开源、本地化、高性能文档解析工具，核心使用 Rust 编写，底层依赖 Google PDFium 进行 PDF 文本提取与渲染。

它解决了什么问题？¶

痛点	LiteParse 的解法
现有解析库速度慢、资源占用高	Rust 核心 + PDFium，极速解析
需要云端 API 才能解析文档	完全本地运行，无云依赖
解析结果缺乏空间位置信息	提供精确 Bounding Box（边界框）坐标
OCR 配置繁琐	内置 Tesseract，零配置开箱即用
只支持 Python 或 JS 单一语言	支持 Rust、Python、Node.js、浏览器 WASM
无法批量处理目录文档	内置 `batch-parse` 命令

二、何时适合使用？（使用场景判断）¶

✅ 适合使用 LiteParse 的场景¶

构建 RAG（检索增强生成）系统：需要从 PDF 中快速抽取文本喂给 LLM
本地离线文档处理：不希望文档内容上传到云端（隐私敏感场景）
批量文档预处理：对整个目录的 PDF/Office 文件进行批量解析
需要空间布局信息：需要知道每段文字在页面上的坐标位置
LLM Agent 视觉辅助：为 Agent 生成文档页面截图以理解图表、图片
多语言技术栈：在 Python、Node.js、Rust 或浏览器环境中使用同一工具

⚠️ 不适合使用 LiteParse，应改用 LlamaParse（云端版）的场景¶

文档包含密集表格
多栏复杂布局（报纸、学术论文）
含有图表、流程图的文档
手写文字识别
扫描版 PDF（图片型 PDF，文字层缺失）

三、安装方法¶

Python¶

pip install liteparse

Node.js / TypeScript¶

npm install @llamaindex/liteparse
# 全局安装（获得全局 lit 命令）
npm install -g @llamaindex/liteparse

Rust（CLI 工具或库）¶

# 安装 CLI 命令行工具
cargo install liteparse

# 作为库加入项目
cargo add liteparse

浏览器 WASM¶

npm install @llamaindex/liteparse-wasm

安装可选依赖¶

LibreOffice（用于 Office 文档转换）：

# macOS
brew install --cask libreoffice

# Ubuntu/Debian
apt-get install libreoffice

# Windows
choco install libreoffice-fresh

ImageMagick（用于图片转 PDF）：

# macOS
brew install imagemagick

# Ubuntu/Debian
apt-get install imagemagick

四、核心功能与 API 使用说明¶

4.1 Python API¶

基本解析¶

from liteparse import LiteParse

parser = LiteParse()

# 解析本地文件
result = parser.parse("document.pdf")
print(result.text)  # 输出纯文本

# 遍历每页结构化数据
for page in result.pages:
    print(f"第 {page.page_num} 页：共 {len(page.text_items)} 个文本块")

从字节流解析（适合 Web 上传场景）¶

with open("document.pdf", "rb") as f:
    result = parser.parse(f.read())
print(result.text)

配置完整参数¶

parser = LiteParse(
    ocr_enabled=True,               # 是否启用 OCR（默认 True）
    ocr_language="eng",             # OCR 语言（Tesseract 语言代码）
    ocr_server_url=None,            # 外部 HTTP OCR 服务 URL（可选）
    tessdata_path=None,             # tessdata 目录路径（离线环境用）
    max_pages=1000,                 # 最大解析页数
    target_pages="1-5,10",          # 指定解析特定页（可选）
    dpi=150,                        # 渲染 DPI
    preserve_very_small_text=False, # 是否保留极小字体文本
    password=None,                  # 加密文档密码
    quiet=False,                    # 是否抑制进度输出
    num_workers=4,                  # OCR 并发工作线程数
)

生成页面截图¶

screenshots = parser.screenshot("document.pdf", page_numbers=[1, 2, 3])
for s in screenshots:
    print(f"第 {s.page_num} 页：{s.width}x{s.height} 像素")
    with open(f"page_{s.page_num}.png", "wb") as f:
        f.write(s.image_bytes)

4.2 Node.js / TypeScript API¶

基本解析¶

import { LiteParse } from '@llamaindex/liteparse';

const parser = new LiteParse();
const result = await parser.parse('document.pdf');
console.log(result.text);

// 遍历每页结构化数据
for (const page of result.pages) {
  console.log(`第 ${page.pageNum} 页：${page.textItems.length} 个文本块`);
}

配置完整参数¶

const parser = new LiteParse({
  ocrEnabled: true,
  ocrLanguage: 'eng',
  ocrServerUrl: undefined,
  tessdataPath: undefined,
  maxPages: 1000,
  targetPages: '1-5,10',
  dpi: 150,
  preserveVerySmallText: false,
  password: undefined,
  quiet: false,
  numWorkers: 4,
});

生成页面截图¶

const screenshots = parser.screenshot('document.pdf', [1, 2, 3]);
for (const s of screenshots) {
  console.log(`第 ${s.pageNum} 页：${s.width}x${s.height} 像素`);
  // s.imageBuffer 包含 PNG 字节数据
}

4.3 CLI 命令行使用¶

解析文档¶

# 基本解析（输出纯文本）
lit parse document.pdf

# 输出为 JSON 格式并保存文件
lit parse document.pdf --format json -o output.json

# 解析指定页范围（第 1-5 页、第 10 页）
lit parse document.pdf --target-pages "1-5,10"

# 禁用 OCR（更快，纯文本层）
lit parse document.pdf --no-ocr

# 解析远程 PDF（通过管道）
curl -sL https://example.com/report.pdf | lit parse -

# 指定中文 OCR
lit parse document.pdf --ocr-language chi_sim

# 使用外部 OCR 服务
lit parse document.pdf --ocr-server-url http://localhost:8000

批量解析整个目录¶

lit batch-parse ./input-directory ./output-directory

# 递归处理子目录，只处理 PDF 文件
lit batch-parse ./input ./output --recursive --extension .pdf

生成页面截图¶

# 所有页面截图
lit screenshot document.pdf -o ./screenshots

# 指定页面截图
lit screenshot document.pdf --target-pages "1,3,5" -o ./screenshots

# 高清截图（300 DPI）
lit screenshot document.pdf --dpi 300 -o ./screenshots

4.4 HTTP OCR 服务集成¶

LiteParse 支持自定义外部 OCR 服务，接口规范：

POST /ocr
参数：file（文件）、language（语言代码）
返回 JSON：
{
  "results": [
    {
      "text": "识别的文字",
      "bbox": [x1, y1, x2, y2],
      "confidence": 0.98
    }
  ]
}

官方提供 EasyOCR 和 PaddleOCR 的现成封装可直接使用。

五、支持的文件格式¶

原生支持（无需额外依赖）¶

格式	扩展名
PDF	`.pdf`

需要 LibreOffice（Office 文档转换）¶

类别	支持格式
Word 文档	`.doc` `.docx` `.docm` `.odt` `.rtf` `.pages`
PowerPoint	`.ppt` `.pptx` `.pptm` `.odp` `.key`
电子表格	`.xls` `.xlsx` `.xlsm` `.ods` `.csv` `.tsv` `.numbers`

需要 ImageMagick（图片格式）¶

类别	支持格式
图片	`.jpg` `.jpeg` `.png` `.gif` `.bmp` `.tiff` `.webp` `.svg`

六、配置选项汇总¶

选项	Python	Node.js	CLI 参数	默认值	说明
OCR 开关	`ocr_enabled`	`ocrEnabled`	`--no-ocr`	`True`	是否启用 OCR
OCR 语言	`ocr_language`	`ocrLanguage`	`--ocr-language`	`eng`	Tesseract 语言代码
OCR 服务器	`ocr_server_url`	`ocrServerUrl`	`--ocr-server-url`	`None`	HTTP OCR 服务地址
tessdata 路径	`tessdata_path`	`tessdataPath`	`--tessdata-path`	`None`	离线训练数据路径
最大页数	`max_pages`	`maxPages`	`--max-pages`	`1000`	最多解析页数
目标页面	`target_pages`	`targetPages`	`--target-pages`	`None`	如 `"1-5,10"`
DPI	`dpi`	`dpi`	`--dpi`	`150`	渲染/截图分辨率
保留小字体	`preserve_very_small_text`	`preserveVerySmallText`	`--preserve-small-text`	`False`	保留极小文字
文档密码	`password`	`password`	`--password`	`None`	加密文档解密密码
静默模式	`quiet`	`quiet`	`-q` / `--quiet`	`False`	不输出进度信息
并发线程	`num_workers`	`numWorkers`	`--num-workers`	CPU核数-1	OCR 并发数

环境变量¶

变量名	说明
`TESSDATA_PREFIX`	指定 Tesseract 训练数据目录（适用于离线/气隙环境）

七、限制与注意事项¶

功能限制¶

复杂文档解析能力有限：密集表格、复杂多栏布局效果不佳，建议改用云端 LlamaParse
手写文字和图表无法有效提取
纯扫描版 PDF 需依赖 OCR，准确率受图片质量影响
Office 文档需预先安装 LibreOffice；图片格式需预先安装 ImageMagick
WASM 版本不包含 CLI 工具，且受浏览器沙箱限制

性能注意事项¶

OCR 会显著增加处理时间：对已有文字层的 PDF，用 --no-ocr 可大幅提速
高 DPI 截图更清晰，但内存和时间开销增加
合理设置 --num-workers 并发数，避免资源争抢

安全注意事项¶

完全本地处理，数据不出本机，适合敏感文档
若使用外部 HTTP OCR 服务，图像数据会发送至该服务地址，需注意

版本说明¶

项目已升级至 V2（当前主分支）；V1 代码保留在 logan/liteparse-v1 分支

附：项目架构概览¶

Input（输入）
  PDF ──────────────────────────────────────────► PDFium 文本提取
  DOCX / XLSX / PPTX / 图片 ──► LibreOffice/ImageMagick 转换 ──► PDFium

Core（Rust 核心）
  文本提取 → 选择性 OCR → OCR 合并 → 空间网格投影

Output（输出）
  JSON（含坐标）/ 纯文本（保留布局）/ PNG 截图

Bindings（语言绑定）
  Python (PyO3) / Node.js (napi-rs) / WASM (wasm-bindgen) / CLI

LiteParse 完整中文操作手册¶

一、项目简介：它是什么，解决什么问题？¶

它解决了什么问题？¶

二、何时适合使用？（使用场景判断）¶

✅ 适合使用 LiteParse 的场景¶

⚠️ 不适合使用 LiteParse，应改用 LlamaParse（云端版） 的场景¶

三、安装方法¶

Python¶

Node.js / TypeScript¶

Rust（CLI 工具或库）¶

浏览器 WASM¶

安装可选依赖¶

四、核心功能与 API 使用说明¶

4.1 Python API¶

基本解析¶

从字节流解析（适合 Web 上传场景）¶

配置完整参数¶

生成页面截图¶

4.2 Node.js / TypeScript API¶

基本解析¶

配置完整参数¶

生成页面截图¶

4.3 CLI 命令行使用¶

解析文档¶

批量解析整个目录¶

生成页面截图¶

4.4 HTTP OCR 服务集成¶

五、支持的文件格式¶

原生支持（无需额外依赖）¶

需要 LibreOffice（Office 文档转换）¶

需要 ImageMagick（图片格式）¶

六、配置选项汇总¶

环境变量¶

七、限制与注意事项¶

功能限制¶

性能注意事项¶

安全注意事项¶

版本说明¶

附：项目架构概览¶

⚠️ 不适合使用 LiteParse，应改用 LlamaParse（云端版）的场景¶