Kreuzberg项目基础使用指南：文档与图像文本提取

Kreuzberg项目基础使用指南：文档与图像文本提取

项目概述

Kreuzberg是一个专注于文档和图像文本提取的Python工具库，提供了简洁高效的API接口。该工具支持多种文件格式，能够帮助开发者快速实现文本内容提取功能，适用于文档处理、数据分析等多种应用场景。

核心功能解析

Kreuzberg提供了两大类功能接口：单文件处理和批量处理，每种类型又分为异步和同步两种调用方式。

单文件处理函数

1. 异步函数

   • extract_file(): 从文件路径异步提取文本
   • extract_bytes(): 从内存中的字节数据异步提取文本

2. 同步函数

   • extract_file_sync(): 同步版本的文件提取
   • extract_bytes_sync(): 同步版本的字节数据提取

批量处理函数

1. 异步批量处理

   • batch_extract_file(): 异步批量处理多个文件
   • batch_extract_bytes(): 异步批量处理多个字节数据

2. 同步批量处理

   • batch_extract_file_sync(): 同步批量处理多个文件
   • batch_extract_bytes_sync(): 同步批量处理多个字节数据

实际应用示例

异步模式使用

单文件提取

import asyncio
from kreuzberg import extract_file

async def process_single_file():
    # 提取PDF文档内容
    result = await extract_file("document.pdf")
    
    # 输出提取结果
    print("文档内容:", result.content)
    print("文件类型:", result.mime_type)
    print("元数据:", result.metadata)

asyncio.run(process_single_file())

批量文件处理

import asyncio
from pathlib import Path
from kreuzberg import batch_extract_file

async def process_multiple_files():
    # 准备文件路径列表
    documents = [
        Path("report.pdf"),
        Path("contract.docx"),
        Path("receipt.jpg")
    ]
    
    # 并发处理所有文件
    extraction_results = await batch_extract_file(documents)
    
    # 处理结果
    for doc, result in zip(documents, extraction_results):
        print(f"文件: {doc.name}")
        print(f"内容摘要: {result.content[:200]}...")
        print(f"文件类型: {result.mime_type}")
        print("-" * 40)

asyncio.run(process_multiple_files())

同步模式使用

单文件提取

from kreuzberg import extract_file_sync

# 同步提取文件内容
result = extract_file_sync("presentation.pptx")
print(result.content)

批量文件处理

from kreuzberg import batch_extract_file_sync

# 定义文件列表
documents = ["notes.pdf", "memo.docx", "diagram.png"]

# 批量处理
results = batch_extract_file_sync(documents)

for file_path, extraction in zip(documents, results):
    print(f"{file_path} 提取完成，内容长度: {len(extraction.content)}")

处理内存中的文件数据

当文件已经加载到内存时，可以直接使用字节处理函数：

import asyncio
from kreuzberg import extract_bytes

async def process_in_memory():
    # 读取文件到内存
    with open("specification.pdf", "rb") as f:
        file_data = f.read()
    
    # 处理内存数据
    result = await extract_bytes(file_data, mime_type="application/pdf")
    print("提取结果:", result.content)

asyncio.run(process_in_memory())

结果对象详解

所有提取函数都返回ExtractionResult对象，包含三个重要属性：

1. content: 提取的文本内容
2. mime_type: 文件的MIME类型
3. metadata: 文件元数据(如标题、作者、创建时间等)

from kreuzberg import extract_file, ExtractionResult

async def analyze_document():
    # 类型注解有助于IDE智能提示
    result: ExtractionResult = await extract_file("thesis.pdf")
    
    # 基础内容
    print("文档正文:", result.content[:500] + "...")
    
    # 元数据处理
    meta = result.metadata
    if "title" in meta:
        print("标题:", meta["title"])
    
    if "authors" in meta:
        print("作者:", ", ".join(meta["authors"]))
    
    if "created" in meta:
        print("创建日期:", meta["created"])

asyncio.run(analyze_document())

最佳实践建议

1. 性能考虑：对于大量文件处理，优先使用异步批量处理函数以获得最佳性能
2. 内存管理：处理超大文件时，考虑使用文件路径方式而非字节方式，避免内存占用过高
3. 错误处理：在实际应用中应该添加适当的异常处理逻辑
4. 类型提示：使用类型注解(如ExtractionResult)可以获得更好的IDE支持

通过以上介绍，开发者可以快速掌握Kreuzberg的基本使用方法，实现高效的文档内容提取功能。该库设计简洁但功能强大，适合集成到各种文档处理流程中。