liteparse

LiteParse — 本地文档解析

概述

LiteParse 是一款快速的开源文档解析器（Rust 核心，提供 Python/Node 绑定），专注于本地、感知版面的文本提取，并提供边界框。它不会生成 Markdown，也不会调用云端大模型。输出为纯文本（保留版面）或包含每页 text_items 的结构化 JSON（含位置、字体元数据和可选的置信度）。

**版本说明：**示例适用于 liteparse 2.0.0（PyPI，2026 年 5 月）。上游 V1 分支已过时；本文档仅介绍 V2 / main。

有关如何选择解析器，以及与 MarkItDown、pdf 技能或 LlamaParse 的比较，请参阅 references/choosing_a_parser.md。

适用场景

在以下情况下使用 LiteParse：

• 快速本地解析 PDF 或转换后的 Office/图像文件，无需依赖云服务
• 提取带边界框的空间文本，用于感知版面的 RAG、引用依据或图形/表格区域逻辑
• 对扫描版 PDF 或图像执行 OCR（使用内置的 Tesseract，或由用户运行的 HTTP OCR 服务）
• 为必须查看图表、图形或手写内容的多模态 Agent 生成页面截图（PNG）
• 批量导入文献文件夹、补充 PDF 或协议库
• 解析 指定页面或受密码保护的 PDF

不适用场景

任务	改用
用于大模型导入的 Markdown（EPUB、音频、YouTube、HTML）	markitdown 技能
合并/拆分 PDF、处理表单、水印、旋转	pdf 技能
密集表格、手写内容、生产级云端流水线	LlamaParse（云端服务；需单独注册）

安装

uv pip install "liteparse==2.0.0"

这将安装 Python 绑定和 lit CLI。验证安装：

lit --help
python -c "import liteparse; print(liteparse.__version__)"

可选系统工具（用于非 PDF 输入）：

• LibreOffice — Word、Excel、PowerPoint、OpenDocument、CSV/TSV
• ImageMagick — PNG、JPEG、TIFF、WebP、SVG 等

安装命令见 references/ocr_and_formats.md。

Node.js / TypeScript（可选）：npm i @llamaindex/liteparse — 参阅 references/api_reference.md。

---

快速开始

Python

from liteparse import LiteParse

parser = LiteParse(quiet=True)
result = parser.parse("paper.pdf")
print(result.text)

for page in result.pages:
    print(f"Page {page.page_num}: {len(page.text_items)} items")

CLI

# Layout-preserved text (default)
lit parse paper.pdf

# Structured JSON with bounding boxes
lit parse paper.pdf --format json -o paper.json

# Disable OCR on text-native PDFs (faster)
lit parse paper.pdf --no-ocr

---

核心工作流

1. 解析为保留版面的文本

适用于快速提取整份文档的文本，或将文本交给不需要坐标的分块器。

parser = LiteParse(ocr_enabled=True, quiet=True)
result = parser.parse("document.pdf")
full_text = result.text

lit parse document.pdf -o output.txt

2. 解析为结构化 JSON（边界框）

用于构建感知版面的 RAG、高亮源文档区域，或将文本与截图关联。

import json
from liteparse import LiteParse

parser = LiteParse(output_format="json", quiet=True)
result = parser.parse("document.pdf")

# Programmatic access
for page in result.pages:
    for item in page.text_items:
        bbox = (item.x, item.y, item.width, item.height)
        # item.text, item.confidence, item.font_name, item.font_size

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

JSON 字段布局：references/output_formats.md。

3. 解析指定页面

parser = LiteParse(target_pages="1-5,10,15-20", quiet=True)
result = parser.parse("long_paper.pdf")

lit parse long_paper.pdf --target-pages "1-5,10"

4. 从字节数据或标准输入解析

适用于上传、S3 下载，或通过管道传入远程 PDF。

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

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

5. 为多模态 Agent 生成页面截图

截图可捕捉仅靠文本提取无法获取的视觉内容（图形、复杂表格、手写内容）。

from pathlib import Path

parser = LiteParse(dpi=150, quiet=True)
shots = parser.screenshot("document.pdf", page_numbers=[1, 2, 3])
out = Path("screenshots")
out.mkdir(exist_ok=True)
for s in shots:
    (out / f"page_{s.page_num}.png").write_bytes(s.image_bytes)

lit screenshot document.pdf --target-pages "1,3,5" -o ./screenshots
lit screenshot document.pdf --dpi 300 -o ./screenshots

当 Agent 需要获取同一页面的坐标和像素数据时，可结合使用JSON 解析 + 截图。

6. 批量解析目录

处理大型语料库时，建议使用 CLI（并行 OCR 工作线程）或内置脚本。

lit batch-parse ./papers ./parsed --format json --recursive
lit batch-parse ./papers ./parsed --extension .pdf --no-ocr

python scripts/batch_parse_dir.py ./papers ./parsed --format json --recursive

无需网络调用的 Python 批处理封装，请参阅 scripts/batch_parse_dir.py。

7. OCR 配置

OCR 默认开启。内置了 Tesseract，基本的英文 OCR 无需额外安装。

parser = LiteParse(
    ocr_enabled=True,
    ocr_language="eng",       # Tesseract codes: fra, deu, etc.
    num_workers=4,            # parallel OCR (default: CPU cores - 1)
    dpi=150,                  # higher DPI → better OCR, slower
)

lit parse scan.pdf --ocr-language fra
lit parse scan.pdf --no-ocr
lit parse scan.pdf --ocr-server-url http://localhost:8080/ocr

**离线 / 隔离网络环境：**将 TESSDATA_PREFIX 设为包含 .traineddata 文件的目录，或传入 --tessdata-path。详情见：references/ocr_and_formats.md。

8. 加密 PDF

parser = LiteParse(password="secret", quiet=True)
result = parser.parse("protected.pdf")

lit parse protected.pdf --password secret

9. 按短语搜索文本项

合并相邻文本项，并返回短语（例如章节标题）的组合边界框。

from liteparse import search_items

page = result.get_page(1)
matches = search_items(page.text_items, "Materials and Methods", case_sensitive=False)

---

多格式输入

类别	扩展名（示例）	要求
PDF	.pdf	原生支持
Office	.docx、.xlsx、.pptx、.doc、.odt、…	LibreOffice
图像	.png、.jpg、.tiff、.webp、.svg、…	ImageMagick

文件会在内部转换为 PDF，然后进行解析。如果缺少转换工具，解析会失败并给出可操作的错误提示——安装依赖后重试。

---

性能提示

• 对原生数字 PDF 使用 --no-ocr — 可获得最大幅度的提速
• target_pages — 仅解析方法/补充材料部分
• num_workers — 利用多个 CPU 核心扩展 OCR
• max_pages — 限制超大文件的页数（默认值为 1000）
• lit batch-parse — 使用 --recursive 和 --extension 处理目录级任务
• OCR 质量已足够时，可降低 dpi（例如设为 100）

---

参考文件

文件	何时阅读
references/choosing_a_parser.md	不确定应使用 LiteParse、MarkItDown、pdf 还是 LlamaParse 时
references/api_reference.md	Python/TypeScript API、类型、search_items
references/cli_reference.md	完整的 lit 命令标志
references/output_formats.md	JSON 架构、bboxes、置信度分数
references/ocr_and_formats.md	Tesseract、HTTP OCR、LibreOffice、ImageMagick

---

故障排除

问题	解决方法
Office 文件解析失败	安装 LibreOffice；确保 soffice 位于 PATH 中（Windows：将 LibreOffice 的 program 目录添加到 PATH）
图像解析失败	安装 ImageMagick；验证 convert 或 magick 是否可用
OCR 质量较差	提高 --dpi；尝试 --ocr-language；或使用 HTTP OCR 服务
OCR 速度慢	如不需要则使用 --no-ocr；减少页数；增加 num_workers
隔离网络环境中的 OCR	使用 export TESSDATA_PREFIX=/path/to/tessdata 或 --tessdata-path
字节数据触发 ParseError	确保输入是有效的 PDF 字节数据（Office 字节数据需要文件路径并进行转换）

---

资源

• GitHub：https://github.com/run-llama/liteparse
• 文档：https://developers.llamaindex.ai/liteparse/
• PyPI：https://pypi.org/project/liteparse/2.0.0/
• npm：https://www.npmjs.com/package/@llamaindex/liteparse
• OCR API 规范：https://github.com/run-llama/liteparse/blob/main/OCR_API_SPEC.md

Agent 操作流程

1. 检查环境。 确认研究问题、数据库、日期范围和纳入标准。
2. 明确输入。 根据数据或用户提供的信息确认格式、标识符和参数。任何会影响结果的值都应先询问，不要猜测。
3. 先运行小规模任务。 在一个数据库中使用范围较窄的查询进行搜索，并检查结果是否相关。
4. 按照上述说明和参考资料 执行完整任务。
5. 验证结果。 每条参考文献都应来自真实记录，且其标识符可解析；记录结果数量和搜索字符串。
6. 报告。 说明运行了什么（版本、命令、参数）、检查了什么，以及仍有哪些不确定之处。

如果发生这种情况	请执行以下操作
API 限流或返回错误	等待后重试、减少批次大小或切换数据库，并报告缺失之处。
已安装版本中缺少这些说明里的函数、标志或端点	查阅该已安装版本自己的文档（help()、--help、官方文档），调整操作，并告知用户。切勿虚构 API。
所需输入、标识符或参数含义不明确	询问用户，或在运行前明确说明所作假设。

诚信规则

• 切勿捏造结果、参数、标识符、引文或统计数据。如果无法运行或验证某项内容，请如实说明。
• 切勿总结未检索到的论文；切勿凭记忆引用。
• 此处与版本相关的细节可能已经过时：请根据已安装版本的官方文档进行确认。
• 对于需要付费、占用共享 GPU 或云配额、涉及个人或患者数据，或无法撤销的操作，请先征求同意。

相关技能

• markitdown：使用 Microsoft MarkItDown 将文档转换为 Markdown（Python API、markitdown CLI、markitdown-ocr 插件、markitdown-mcp 服务），涵盖……
• llamaindex：用于构建带有 RAG 的 LLM 应用的数据框架。
• open-notebook：Google NotebookLM 的可自托管、开源替代方案，可用于 AI 研究和文档分析。