大家好，我是六哥，相信很多朋友肯定都有过从各种文档里提取文本的经历，那过程可太让人头疼了！今天就给大家分享一款超实用的现代Python库——Kreuzberg，帮你轻松解决文本提取的难题。

一、Kreuzberg解决了什么问题

现在很多文本提取工具，要么依赖外部API调用，要么配置特别复杂，使用起来很不方便。而Kreuzberg专为解决RAG（检索增强生成）应用里的文本提取需求而生，不过它可不止这点用处，任何文本提取场景都能完美适配。它专注于本地处理，依赖少，简单又高效。

二、Kreuzberg的强大功能

1. 通用文本提取：不管是可搜索的PDF、扫描版PDF，还是图片、办公文档，Kreuzberg都能从中精准提取文本。比如你要从合同PDF里提取关键条款，或者从产品宣传图里抓取文字信息，它都能轻松搞定。
2. 智能处理：扫描文档能自动OCR识别，文本文件能检测编码。像处理不同来源的文本资料，它能自动识别编码，让乱码问题不再出现。
3. 现代Python设计：采用异步优先的API，基于anyio构建，支持全面的类型提示，方便在IDE中开发，还具备详细的错误处理，包含上下文信息，开发过程更省心。

三、Kreuzberg的显著特点

1. 简单便捷：提供简洁的API，不用复杂配置就能运行，哪怕是新手小白也能轻松上手。
2. 本地处理：无需调用外部API，不依赖云服务，数据安全有保障，没网也能正常工作。
3. 资源高效：轻量级处理，不依赖GPU，普通电脑也能流畅运行，节省硬件成本。
4. 格式支持全面：支持的格式超丰富，涵盖文档、图像、文本等各类格式，基本能满足日常所有需求。

四、使用方法超简单

1. 安装
   • 安装Python包：pip install kreuzberg
   • 安装系统依赖项：需要Pandoc（用于文档格式转换）和Tesseract OCR（用于图像和PDF光学字符识别），按照各自的安装指南安装就行。
2. 基本使用
   Kreuzberg提供了简单的异步文本提取API，主要有两个功能：
   • extract_file()：从文件中提取文本，可以接受字符串路径或pathlib.Path 。

from pathlib import Path
from kreuzberg import extract_file, extract_bytes

# 基本文件提取
async def extract_document():
    # 从PDF文件提取
    pdf_result = await extract_file("document.pdf")
    print(f"PDF文本: {pdf_result.content}")

    # 从图像提取
    img_result = await extract_file("scan.png")
    print(f"图像文本: {img_result.content}")

    # 从Word文档提取
    docx_result = await extract_file(Path("document.docx"))
    print(f"Word文本: {docx_result.content}")

- `extract_bytes()`：从字节中提取文本，接受字节字符串。比如处理上传的文件：

from kreuzberg import extract_bytes

async def process_upload(file_content: bytes, mime_type: str):
    """处理已知MIME类型的上传文件内容。"""
    result = await extract_bytes(file_content, mime_type=mime_type)
    return result.content

# 不同文件类型的示例用法
async def handle_uploads():
    # 处理PDF上传
    pdf_result = await extract_bytes(pdf_bytes, mime_type="application/pdf")

    # 处理图像上传
    img_result = await extract_bytes(image_bytes, mime_type="image/jpeg")

    # 处理Word文档上传
    docx_result = await extract_bytes(docx_bytes,
        mime_type="application/vnd.openxmlformats-officedocument.wordprocessingml.document")

3. 高级功能
   • PDF处理选项：可以强制对包含嵌入图像或扫描内容的PDF进行OCR处理。

from kreuzberg import extract_file

async def process_pdf():
    # 对包含图像或扫描内容的PDF强制OCR
    result = await extract_file("document.pdf", force_ocr=True)

    # 处理扫描版PDF（自动使用OCR）
    scanned = await extract_file("scanned.pdf")

- **提取结果对象**：所有提取函数返回的对象包含提取的文本（`content`）和输出格式（`mime_type`）。

from kreuzberg import ExtractionResult

async def process_document(path: str) -> tuple[str, str]:
    # 作为具名元组访问
    result: ExtractionResult = await extract_file(path)
    print(f"内容: {result.content}")
    print(f"格式: {result.mime_type}")

    # 或解包为元组
    content, mime_type = await extract_file(path)
    return content, mime_type

- **错误处理**：Kreuzberg通过多种异常类型提供全面的错误处理，所有异常都继承自`KreuzbergError` ，每个异常都包含有助于调试的上下文信息。

from kreuzberg import extract_file
from kreuzberg.exceptions import (
    ValidationError,
    ParsingError,
    OCRError,
    MissingDependencyError
)

async def safe_extract(path: str) -> str:
    try:
        result = await extract_file(path)
        return result.content

    except ValidationError as e:
        # 输入验证问题
        # - 不支持或无法检测的MIME类型
        # - 文件缺失
        # - 无效输入参数
        print(f"验证失败: {e}")

    except OCRError as e:
        # OCR特定问题
        # - Tesseract处理失败
        # - 图像转换问题
        print(f"OCR失败: {e}")

    except MissingDependencyError as e:
        # 系统依赖问题
        # - 缺少Tesseract OCR
        # - 缺少Pandoc
        # - 版本不兼容
        print(f"依赖缺失: {e}")

    except ParsingError as e:
        # 一般处理错误
        # - PDF解析失败
        # - 格式转换问题
        # - 编码问题
        print(f"处理失败: {e}")

    return ""

# 示例错误上下文
try:
    result = await extract_file("document.xyz")
except ValidationError as e:
    # 错误将包含上下文：
    # ValidationError: 不支持的mime类型
    # 上下文: {
    #    "file_path": "document.xyz",
    #    "supported_mimetypes": ["application/pdf",...]
    # }
    print(e)

try:
    result = await extract_file("scan.jpg")
except OCRError as e:
    # 错误将包含上下文：
    # OCRError: OCR返回非0代码失败
    # 上下文: {
    #    "file_path": "scan.jpg",
    #    "tesseract_version": "5.3.0"
    # }
    print(e)

五、支持格式超丰富

1. 文档格式：PDF（可搜索和扫描的文档）、Microsoft Word（.docx ，.doc ）、PowerPoint 演示文稿（.pptx ）、OpenDocument 文本（.odt ）、富文本格式（.rtf ）、EPUB (.epub)、DocBook XML（.dbk ，.xml ）、FictionBook (.fb2)、LaTeX (.tex,.latex)、Typst (.typ)。
2. 标记和文本格式：HTML（.html ，.htm ）、纯文本（.txt ）和Markdown（.md ，.markdown ）、reStructuredText (.rst) 、Org-mode (.org)、DokuWiki (.txt) 、Pod (.pod)、手册页（.1 ，.2 等）。
3. 数据和研究成果格式：Excel 电子表格（.xlsx ）、CSV（.csv ）和TSV（.tsv ）文件、Jupyter Notebooks (.ipynb)、BibTeX（.bib ）和BibLaTeX（.bib ）、CSL-JSON (.json) 、EndNote XML (.xml)、RIS (.ris)、JATS XML（.xml ）。
4. 图片格式：JPEG (.jpg,.jpeg,.pjpeg)、PNG (.png) 、TIFF (.tiff,.tif)、BMP (.bmp) 、GIF (.gif) 、WebP（.webp ）、JPEG 2000（.jp2 ，.jpx ，.jpm ，.mj2 ）、便携式Anymap（.pnm ）、便携式位图（.pbm ）、便携式灰度图（.pgm ）、便携式像素图（.ppm ）。

六、架构设计很巧妙

Kreuzberg设计为在现有开源工具之上的高级异步抽象，集成了多个工具来实现强大功能：

1. PDF处理：使用pdfium2处理可搜索的PDF文件，Tesseract OCR处理扫描内容。
2. 文档转换：利用Pandoc支持多种文档和标记格式，python-pptx处理PowerPoint文件，html-to-markdown处理HTML内容，还有专门处理Excel电子表格的工具。
3. 文本处理：实现智能编码检测，以及Markdown和纯文本处理。

如果你对Kreuzberg感兴趣，想深入了解或者参与开发，可以访问项目链接：https://github.com/Goldziher/kreuzberg 。

优秀不够，你是否无可替代

软件测试交流QQ群：721256703，期待你的加入！！

欢迎关注我的微信公众号：软件测试君