extracting-with-ocr
Use when extracting text from scanned PDFs, photographed pages, or images that have no embedded text layer. Covers OCR backends, language packs, force-OCR, and performance tuning.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-14
- Stars
- ★ 1.6k
- Forks
- 491
01 前言 Front Matter
- name
- extracting-with-ocr
- description
- Use when extracting text from scanned PDFs, photographed pages, or images that have no embedded text layer. Covers OCR backends, language packs, force-OCR, and performance tuning.
03 SKILL.md 正文
Extracting with OCR
Use this when a document is image-based: scanned PDFs, photographed pages, screenshots, JPEG/PNG/TIFF with text. Kreuzberg auto-OCRs raster images and auto-detects PDFs that lack a text layer. Force it on when extraction returned empty/garbled text from a PDF that "looks" textual.
When to force OCR
- Extraction returned an empty
contentfield, but the file opens visually. - The PDF text layer is junk (copy-paste from a viewer produces gibberish).
- You want consistent output across mixed scanned + digital PDFs.
kreuzberg extract scan.pdf --force-ocr=true
kreuzberg extract scan.pdf --ocr=true --ocr-language eng
If a page has an unreliable text layer, --force-ocr=true re-rasterizes
and runs OCR on every page.
Backends
Tesseract is the default and ships with the CLI — no extra install. Other backends are opt-in:
| Backend | Flag | Install | Notes |
|---|---|---|---|
| Tesseract | --ocr-backend tesseract (default) |
bundled | Best general-purpose, 100+ languages via tessdata. |
| PaddleOCR | --ocr-backend paddle-ocr |
bundled (ONNX Runtime) | Strong on Asian scripts. Not available on WASM or Windows. |
| EasyOCR | --ocr-backend easyocr |
Python binding (pip install kreuzberg[easyocr]) |
Heavier model. CUDA accel via easyocr_kwargs={"gpu": True}. |
| VLM (vision) | layout + a multimodal LLM via config | configured per backend | Use when OCR fails on dense or handwritten layouts. |
Pick Tesseract first. Switch only when accuracy is unacceptable.
Language packs
Tesseract uses ISO 639-2 codes. Default is eng. Combine with +:
kreuzberg extract menu.jpg --ocr=true --ocr-language "eng+deu"
kreuzberg extract bilingual.pdf --ocr-language "eng+jpn"
kreuzberg extract any.pdf --ocr-language all # all installed packs
Install missing packs at the OS level:
# macOS
brew install tesseract-lang
# Debian/Ubuntu
sudo apt install tesseract-ocr-deu tesseract-ocr-jpn tesseract-ocr-fra
# Specific lang only
sudo apt install tesseract-ocr-<iso639-2>
Kreuzberg fails fast with a helpful error if you request a language pack that is not installed. Read the error — it names the missing file.
Useful flags
--ocr=true— enable OCR (auto-enabled for images and scanned PDFs).--force-ocr=true— OCR every page even if a text layer exists.--disable-ocr=true— never OCR (extract embedded text only or fail).--ocr-language <lang>— single code or+-joined list, orall.--ocr-backend <tesseract|paddle-ocr|easyocr>— pick backend.--ocr-auto-rotate=true— pre-rotate via the auto-rotate model.--acceleration <cpu|coreml|cuda|tensorrt|auto>— ONNX accelerator for paddle-ocr / auto-rotate / layout models.
Performance tips
- Cache is on by default. Repeated extraction of the same file + config is
instant. Do not pass
--no-cache=trueunless you have a reason. - For batch OCR, use
kreuzberg batch *.pdf --ocr=true— internal worker pool parallelizes across CPU cores. Cap with--max-concurrent Nif memory is tight. - Raise
--target-dpi(default 300) only for low-resolution scans. Higher DPI is slower; 200 is usually enough for printed text. - Enable
--ocr-auto-rotate=trueonly when pages may be rotated; the classifier adds latency. - On Apple Silicon,
--acceleration coremltypically beats CPU for paddle-ocr and layout detection.
Config file alternative
Long flag chains belong in kreuzberg.toml — auto-discovered from cwd
upward.
force_ocr = true
output_format = "markdown"
[ocr]
backend = "tesseract"
language = "eng+deu"
auto_rotate = true
Then just run:
kreuzberg extract document.pdf
Common failure modes
- "missing tessdata" — install the language pack at OS level (see above).
- Empty content on a scanned PDF without
--force-ocr— the file has a bogus zero-width text layer. Re-run with--force-ocr=true. - OCR on a rotated page — add
--ocr-auto-rotate=trueor pre-rotate. - Garbled CJK output — ensure the right language pack is installed and
passed via
--ocr-language; considerpaddle-ocrfor Chinese/Japanese.
See references/cli-reference.md and references/configuration.md in the
sibling kreuzberg skill for the full flag and config schema.
04 同仓库更多 Skills
worktable-review-with-annotations
Create, inspect, reply to, update, or resolve situated Worktable annotations. Use when feedback belongs to a Doc section, block, text range, or HTML Doc, or when the user asks to address existing review feedback and coordinate a requested artifact edit.
worktable-find-and-synthesize-context
Find, assess, and synthesize context from Worktable Docs and Records. Use when the user asks what a workspace contains, wants workspace-backed research, needs current facts reconciled across artifacts, or requests a cited synthesis without changing workspace state.
worktable-create-or-update-docs
Create, edit, rename, or maintain narrative Worktable Docs. Use for plans, decisions, briefs, notes, research syntheses, and other durable prose when the user requests a new artifact or a safe update to an existing one.
worktable-create-or-manage-records
Organize repeated structured information as durable Worktable Records. Use for research datasets, inventories, directories, pipelines, trackers, and other collections whose items need identity, fields, filtering, links, validation, or individual updates.
worktable-create-or-manage-interactive-html
Create or improve durable visual and interactive artifacts in Worktable. Use for dashboards, trackers, calculators, mini apps, slide presentations, and other requests that benefit from a polished HTML Doc.
worktable-collaborate-threads
Read, answer, and hand off messages through durable Worktable threads with users or other authenticated participants. Use when the user asks to check addressed messages, reply to a participant, continue a thread, request another agent's help, wait briefly for a response, or watch for comments and messages sent to the agent.