LiteParse 是选择性地使用 OCR —— 只对内嵌图片，或原生文本抽取没找到文字的页面才做 OCR。这样既保持解析速度，又能拿到扫描页与内嵌图片里的文字。

内置 Tesseract（默认）

Tesseract 已随 LiteParse 打包，开箱即用，直接运行即可：

终端窗口

lit parse document.pdf

语言支持

为非英文文档指定 OCR 语言，可以获得更好的准确度：

终端窗口

lit parse document.pdf --ocr-language fra    # French
lit parse document.pdf --ocr-language deu    # German
lit parse document.pdf --ocr-language jpn    # Japanese

Tesseract 使用 ISO 639-3 语言代码（eng、fra、deu 等）。

离线 / 隔离网络环境

在没有外网的环境里，把 Tesseract 指向一个存放好 .traineddata 文件的本地目录：

终端窗口

# Via environment variable
export TESSDATA_PREFIX=/path/to/tessdata
lit parse document.pdf --ocr-language eng

# Or via CLI flag
lit parse document.pdf --tessdata-path /path/to/tessdata

tessdata_path / tessdataPath 选项在库 API 里同样可用。

故障排查：缺少语言数据

如果 Tesseract 找不到它的语言数据，你会看到类似这样的错误：

Error opening data file tessdata/eng.traineddata
Please make sure the TESSDATA_PREFIX environment variable is set to your "tessdata" directory.
Failed loading language 'eng'

打包的 Tesseract 仍然需要对应语言的 .traineddata 文件。它通常在首次使用时自动下载并缓存（Linux 上是 ~/.tesseract-rs/tessdata，macOS 上是 ~/Library/Application Support/tesseract-rs/tessdata）；如果没有发生这次下载 —— 比如离线、网络受限或沙箱安装 —— OCR 就无法运行。

要解决这个问题，任选下面一种做法：

• 下载对应语言文件（例如 eng.traineddata），然后用 TESSDATA_PREFIX 或 --tessdata-path 指向它（见上文）。
• 改用 HTTP OCR 服务，而不是内置引擎。
• 如果不需要 OCR，用 --no-ocr 关掉它。

当每一页都缺少语言数据时，LiteParse 现在会带着明确的 OCR failed for all N page(s) 错误失败，而不是返回一份 OCR 文本静默为空的文档 —— 这样没配好的环境问题会立刻暴露，而不是产出看起来完整的残缺结果。

关闭 OCR

如果你不需要 OCR（纯原生文本的 PDF，或者不在乎图片里的内容），关掉它能解析得更快：

终端窗口

lit parse document.pdf --no-ocr

HTTP OCR 服务

需要更高准确度或 GPU 加速的 OCR 时，可以把 LiteParse 指向一个 HTTP OCR 服务。LiteParse 为常见的 OCR 引擎内置了可直接使用的示例。

EasyOCR

终端窗口

# Start the EasyOCR server (requires Python)
git clone https://github.com/run-llama/liteparse.git
cd liteparse/ocr/easyocr
pip install -r requirements.txt
python server.py

# Parse with EasyOCR in another terminal
lit parse document.pdf --ocr-server-url http://localhost:8828/ocr

PaddleOCR

终端窗口

# Start the PaddleOCR server (requires Python)
git clone https://github.com/run-llama/liteparse.git
cd liteparse/ocr/paddleocr
pip install -r requirements.txt
python server.py

# Parse with PaddleOCR in another terminal
lit parse document.pdf --ocr-server-url http://localhost:8828/ocr

需要鉴权的服务

用 --ocr-server-header 为每个 OCR 请求附加 HTTP 头，每个头重复一次该参数：

终端窗口

lit parse document.pdf \
  --ocr-server-url https://ocr.internal/ocr \
  --ocr-server-header "Authorization: Bearer $TOKEN" \
  --ocr-server-header "X-Tenant: acme"

在库里对应 ocr_server_headers / ocrServerHeaders，接受一个「头名 → 值」的映射。没有设置 OCR 服务 URL 时它不生效。

并行 OCR 工作线程

LiteParse 会并行地对多个页面做 OCR。默认使用比 CPU 核数少一个的工作线程。可以用下面方式覆盖：

终端窗口

lit parse document.pdf --num-workers 8

当你需要降低对外部 OCR 服务的请求速率，或者你的 OCR 引擎是 GPU 加速、能承受更高并发时，这一点很有用。

自定义 OCR 服务

只要实现 LiteParse 的 OCR API，就能接入任何 OCR 引擎。你的服务端只需要提供一个端点：

POST /ocr
Content-Type: multipart/form-data

请求字段：

字段	类型	必填	说明
file	binary	是	图片文件（PNG、JPG 等）
language	string	否	ISO 639-1 语言代码（默认：en）

留意语言代码。 LiteParse 会把 --ocr-language 的值原样转发，而它默认是 Tesseract 风格的 ISO 639-3 代码 eng —— 不是 en。你的服务端应当两种都接受。自带的 EasyOCR 与 PaddleOCR 服务端是在派发前把 eng → en 做一次映射来做到的；自定义服务端也要照做，或者显式传 --ocr-language en。

响应格式：

{
  "results": [
    {
      "text": "recognized text",
      "bbox": [12, 40, 220, 62],
      "confidence": 0.95
    }
  ]
}

每条结果包含：

字段	类型	说明
text	string	识别出的文字
bbox	[x1, y1, x2, y2]	以像素计的边界框。原点在左上角，x 向右、y 向下
confidence	number	0.0 到 1.0 之间的得分

测试你的服务端

终端窗口

# Quick test with curl
curl -X POST http://localhost:8828/ocr \
  -F "file=@test.png" \
  -F "language=en" | jq .

# Use with LiteParse
lit parse document.pdf --ocr-server-url http://localhost:8828/ocr

常见坑

• 没有检测到文字时返回 {"results": []}
• 边界框必须是轴对齐的（[x1, y1, x2, y2]，从左上到右下）
• 如果你的引擎返回旋转框，请取最小/最大坐标把它们转换成轴对齐框
• 如果你的引擎不提供置信度得分，就返回 1.0
• 结果应按阅读顺序排列（从上到下、从左到右）
• 把 OCR 模型缓存在内存里，而不是每次请求都重新加载

浏览器（WASM）里的 OCR

内置 Tesseract 与 HTTP OCR 后端在 WASM 构建中都不可用。作为替代，你可以传入一个带 recognize 方法的自定义 ocrEngine 对象。细节见浏览器用法指南。

关于 OCR 技术路线的一点说明

如今，把“OCR”这个词同时用于传统方法和较新的基于 LLM 的文档理解模型，是很常见的。

LiteParse 的 OCR API 是专门为「返回带边界框的文字」这类方法设计的。

如果你想接入的方法不返回边界框，那就只能自己生成一些占位边界框。