kreuzberg

用途

Kreuzberg 是一个文档智能提取库，用于从多种文件格式中提取文本、表格、元数据和图像。它采用 Rust 核心，并提供 Python、Node.js/TypeScript、Ruby、Go、Java、C#、PHP、Elixir 等语言的原生绑定。该技能适合在编写文档提取相关代码时使用，例如提取文本或元数据、对扫描件或图片执行 OCR、批量处理文件、配置提取选项，以及实现自定义插件。

主要能力

• 支持 91 种以上文件格式，包括 PDF、Word、电子表格、演示文稿、电子书、图片、标记语言、数据文件、纯文本、电子邮件、压缩包和学术格式。
• 提取文本内容、MIME 类型、元数据、表格（含单元格与 Markdown）、检测到的语言、文本分块、图像、语义元素、逐页内容和关键词。
• OCR 对图片和扫描 PDF 自动运行，默认后端为 Tesseract（内置原生绑定，无需外部安装）。其他后端包括 EasyOCR（仅 Python）、PaddleOCR（仅 Python，4.8.5 起内置）、Guten（仅 Node.js）。
• 支持批量处理多个文件。
• 支持配置输出格式、分块、OCR、语言检测、PDF 密码等选项。
• 支持自定义插件，如后处理器、校验器、OCR 后端。

使用方式

安装：

Python：pip install kreuzberg，可选 OCR 后端 pip install kreuzberg[easyocr]。

Node.js：npm install @kreuzberg/node。

Rust：在 Cargo.toml 中添加 kreuzberg = { version = "4", features = ["tokio-runtime"] }，可选特性包括 pdf、ocr、chunking、embeddings、language-detection、keywords-yake、keywords-rake。

CLI：从 GitHub releases 下载，或 cargo install kreuzberg-cli。

快速开始示例（Python 异步）：

from kreuzberg import extract_file

result = await extract_file("document.pdf")
print(result.content)       # extracted text
print(result.metadata)      # document metadata
print(result.tables)        # extracted tables

Python 同步使用 extract_file_sync。Node.js 使用 extractFile 或 extractFileSync。Rust 使用 extract_file（异步）或 extract_file_sync（需 tokio-runtime 特性）。CLI 命令如 kreuzberg extract document.pdf、kreuzberg extract document.pdf --format json、kreuzberg extract document.pdf --output-format markdown。

配置可通过各语言的配置结构体或 TOML 配置文件完成，CLI 会自动发现当前或父目录中的 kreuzberg.toml。

批量处理：Python 使用 batch_extract_files 或 batch_extract_files_sync，Node.js 使用 batchExtractFiles，Rust 使用 batch_extract_file（需 tokio-runtime 特性），CLI 使用 kreuzberg batch *.pdf --format json。

OCR 语言代码支持单语言（如 "eng"）、多语言（如 "eng+deu"）或全部已安装语言（"all"）。可通过 force_ocr=True 强制 OCR。

错误处理提供 KreuzbergError、ParsingError、OCRError、ValidationError、MissingDependencyError 等异常类型。

适用场景

• 从 PDF、Office 文档、图片、HTML、电子邮件、压缩包、学术文件中提取文本和元数据。
• 对扫描文档或图片执行 OCR。
• 批量处理多个文件。
• 需要配置输出格式、分块、OCR、语言检测等提取选项的场景。
• 需要实现自定义插件（后处理器、校验器、OCR 后端）的场景。

限制与注意事项

• 部分 OCR 后端有语言限制：EasyOCR 和 PaddleOCR 仅 Python 可用，Guten 仅 Node.js 可用。
• Rust 的 extract_file_sync、batch_extract_file、batch_extract_file_sync 需要 Cargo.toml 中启用 tokio-runtime 特性。
• Rust 的 extract_file 是异步函数，需在异步上下文中调用。
• Python 的 ChunkingConfig 字段应使用 max_chars 和 max_overlap，而非 max_characters 或 overlap。
• Rust 的 extract_file 第三个参数是 &ExtractionConfig 引用，而非 Option。
• CLI 中 --format 控制 CLI 输出（text/json），--output-format 控制内容格式（plain/markdown/djot/html）。
• Node.js 的 extractFile(path, mimeType?, config?) 中 mimeType 是第二个参数，可传 null 跳过。
• 配置文件字段名使用 snake_case。
• 完整文档见 https://docs.kreuzberg.dev，GitHub 见 https://github.com/kreuzberg-dev/kreuzberg。