用途
当文档是基于图像的——扫描版 PDF、拍摄的页面、截图、含文字的 JPEG/PNG/TIFF——可使用本技能。Xberg 会自动对光栅图像执行 OCR，并自动检测缺少文本层的 PDF。当某个「看起来是文本」的 PDF 提取结果为空或乱码时，可强制启用 OCR。
何时强制启用 OCR：
- 提取返回空的 content 字段，但文件在视觉上能正常打开。
- PDF 文本层是垃圾数据（从查看器复制粘贴产生乱码）。
- 希望在混合的扫描版与数字版 PDF 上获得一致的输出。
示例命令：
xberg extract scan.pdf --force-ocr=true
xberg extract scan.pdf --ocr=true --ocr-language eng
如果某页的文本层不可靠，--force-ocr=true 会重新栅格化并对每一页运行 OCR。
后端
Tesseract 是默认后端，随 CLI 一同提供，无需额外安装。其他后端为选择性启用：
| 后端 | 参数 | 安装 | 说明 |
|---|---|---|---|
| Tesseract | --ocr-backend tesseract（默认） | 内置 | 最佳通用选择，通过 tessdata 支持 100 多种语言。 |
| PaddleOCR | --ocr-backend paddle-ocr | 内置（ONNX Runtime） | 擅长亚洲文字。在 WASM 或 Windows 上不可用。 |
| Candle VLM | --ocr-backend candle-trocr（及其他 candle-*） | 内置（Candle） | 本地视觉 OCR 模型（candle-trocr、candle-paddleocr-vl、candle-glm-ocr、candle-deepseek-ocr）。 |
| VLM（托管） | --ocr-backend vlm + --vlm-model | liter-llm 提供方（--vlm-api-key） | 通过 liter-llm 使用多模态 LLM。当 OCR 在密集或手写版式上失败时使用。 |
先选 Tesseract，仅在准确率不可接受时才切换。
语言包
Tesseract 使用 ISO 639-2 代码，默认是 eng。可用 + 组合：
xberg extract menu.jpg --ocr=true --ocr-language "eng+deu"
xberg extract bilingual.pdf --ocr-language "eng+jpn"
xberg extract any.pdf --ocr-language all # 所有已安装语言包
在操作系统层面安装缺失的语言包：
# macOS
brew install tesseract-lang
# Debian/Ubuntu
sudo apt install tesseract-ocr-deu tesseract-ocr-jpn tesseract-ocr-fra
# 仅安装特定语言
sudo apt install tesseract-ocr-<iso639-2>
若请求的语言包未安装，Xberg 会快速失败并给出有用错误，错误中会指出缺失的文件名。
常用参数
- --ocr=true — 启用 OCR（对图像和扫描版 PDF 自动启用）。
- --force-ocr=true — 即使存在文本层也对每一页执行 OCR。
- --disable-ocr=true — 从不执行 OCR（仅提取内嵌文本，否则失败）。
- --ocr-language <lang> — 单个代码、用 + 连接的列表，或 all。
- --ocr-backend <tesseract|paddle-ocr|vlm|candle-trocr|candle-paddleocr-vl|candle-glm-ocr|candle-deepseek-ocr> — 选择后端。
- --ocr-auto-rotate=true — 通过自动旋转模型进行预旋转。
- --acceleration <cpu|coreml|cuda|tensorrt|auto> — 用于 paddle-ocr / auto-rotate / 版式模型的 ONNX 加速器。
性能建议
- 缓存默认开启。对同一文件与配置重复提取是即时的。除非有理由，不要传 --no-cache=true。
- 批量 OCR 使用 xberg batch *.pdf --ocr=true——内部工作池会跨 CPU 核心并行。内存紧张时用 --max-concurrent N 限制并发。
- 仅在低分辨率扫描件时提高 --target-dpi（默认 300）。更高 DPI 更慢；印刷文本通常 200 足够。
- 仅在页面可能旋转时启用 --ocr-auto-rotate=true；分类器会增加延迟。
- 在 Apple Silicon 上，对于 paddle-ocr 和版式检测，--acceleration coreml 通常优于 CPU。
配置文件替代方案
较长的参数链应放入 xberg.toml——会从当前工作目录向上自动发现。
force_ocr = true
output_format = "markdown"
[ocr]
backend = "tesseract"
language = "eng+deu"
auto_rotate = true
随后直接运行：
xberg extract document.pdf
常见失败模式
- 「missing tessdata」——在操作系统层面安装语言包（见上文）。
- 扫描版 PDF 未加 --force-ocr 时内容为空——文件带有虚假的零宽文本层。用 --force-ocr=true 重新运行。
- 旋转页面上的 OCR——加上 --ocr-auto-rotate=true 或预先旋转。
- CJK 输出乱码——确保安装了正确的语言包并通过 --ocr-language 传入；中文/日文可考虑 paddle-ocr。
完整的参数与配置 schema 见同项目 xberg 技能的 references/cli-reference.md 和 references/configuration.md。