# 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（云端版）](https://cloud.llamaindex.ai) 的场景

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

---

## 三、安装方法

### Python
```bash
pip install liteparse
```

### Node.js / TypeScript
```bash
npm install @llamaindex/liteparse
# 全局安装（获得全局 lit 命令）
npm install -g @llamaindex/liteparse
```

### Rust（CLI 工具或库）
```bash
# 安装 CLI 命令行工具
cargo install liteparse

# 作为库加入项目
cargo add liteparse
```

### 浏览器 WASM
```bash
npm install @llamaindex/liteparse-wasm
```

### 安装可选依赖

**LibreOffice**（用于 Office 文档转换）：
```bash
# macOS
brew install --cask libreoffice

# Ubuntu/Debian
apt-get install libreoffice

# Windows
choco install libreoffice-fresh
```

**ImageMagick**（用于图片转 PDF）：
```bash
# macOS
brew install imagemagick

# Ubuntu/Debian
apt-get install imagemagick
```

---

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

### 4.1 Python API

#### 基本解析
```python
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 上传场景）
```python
with open("document.pdf", "rb") as f:
    result = parser.parse(f.read())
print(result.text)
```

#### 配置完整参数
```python
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 并发工作线程数
)
```

#### 生成页面截图
```python
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

#### 基本解析
```typescript
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} 个文本块`);
}
```

#### 配置完整参数
```typescript
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,
});
```

#### 生成页面截图
```typescript
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 命令行使用

#### 解析文档
```bash
# 基本解析（输出纯文本）
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
```

#### 批量解析整个目录
```bash
lit batch-parse ./input-directory ./output-directory

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

#### 生成页面截图
```bash
# 所有页面截图
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 训练数据目录（适用于离线/气隙环境） |

---

## 七、限制与注意事项

### 功能限制

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

### 性能注意事项

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

### 安全注意事项

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

### 版本说明

11. 项目已升级至 **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
```