Haystack 2.21 KreuzbergConverter 完整指南：本地化多格式文档转换组件的 API 与实战

Haystack 2.21 KreuzbergConverter 完整指南：本地化多格式文档转换组件的 API 与实战

【免费下载链接】haystackOpen-source AI orchestration framework for building context-engineered, production-ready LLM applications. Design modular pipelines and agent workflows with explicit control over retrieval, routing, memory, and generation. Built for scalable agents, RAG, multimodal applications, semantic search, and conversational systems.项目地址: https://gitcode.com/GitHub_Trending/ha/haystack

本文基于 Haystack 官方文档站 2.21 版本的集成 API 参考页（kreuzberg.md），完整解读KreuzbergConverter这一文档转换组件：它如何将 PDF、Office 文档、图片等 75+ 种格式的文件在本地提取为 HaystackDocument对象。读完后，你可以掌握该组件的全部构造参数（config、config_path、store_full_path、batch、easyocr_kwargs）、ExtractionConfig的 OCR 与 Token 缩减定制方式，以及run方法在sources/meta上的输入输出契约，并将其正确接入自己的索引 Pipeline。

1. 组件定位：Kreuzberg 是什么，它属于哪一层

KreuzbergConverter的完整导入路径为：

haystack_integrations.components.converters.kreuzberg.converter

根据 API 参考文档，Kreuzberg 是一个文档智能（document intelligence）框架，能从 PDF、Office 文档、图片以及 75 种以上其他格式中提取文本；所有处理均在本地完成，不发起任何外部 API 调用——这使得它适合对数据隐私有要求、或无法依赖云端 OCR 服务的部署场景。

需要注意其在 Haystack 生态中的层次关系。本文档所属仓库的核心组件目录haystack/components/converters/下内置了 CSV、DOCX、HTML、JSON、Markdown、PPTX、PDFMiner、PyPDF、TXT、XLSX 等转换器（见 converters 目录），而 Kreuzberg 属于外部第三方集成，通过独立的 PyPI 包kreuzberg-haystack安装，代码位于独立的 haystack-core-integrations 集成仓库中。在 2.21 版本文档站的转换器导航页（converters.mdx）中，Kreuzberg 也归入 “External Integrations” 一类。换言之，本文描述的是官方 API 参考对第三方集成的收录快照；该集成的实现源码不在本仓库内，但其输入输出契约完全遵循本仓库定义的Document（document.py）与ByteStream（byte_stream.py）数据类，因此可以无缝嵌入任何标准 Haystack Pipeline。

2. 安装与最简用法

按集成包的包名安装：

pip install kreuzberg-haystack

最简用法——两个文件转成Document列表：

from haystack_integrations.components.converters.kreuzberg import ( KreuzbergConverter, ) converter = KreuzbergConverter() result = converter.run(sources=["document.pdf", "report.docx"]) documents = result["documents"]

run返回一个字典，唯一的键是documents，值为生成的Document列表。默认情况下每个源文件对应一个 Document；若启用了按页提取或分块（见第 4 节），则会变为每页/每块一个 Document。

3.__init__构造参数逐项解析

KreuzbergConverter的构造函数签名为：

__init__( *, config: ExtractionConfig | None = None, config_path: str | Path | None = None, store_full_path: bool = False, batch: bool = True, easyocr_kwargs: dict[str, Any] | None = None ) -> None

注意第一个*表示所有参数均为关键字参数（keyword-only），调用时不能按位置传参。各参数含义如下：

几个实践要点：

• batch=True是默认行为，批量场景下可借助 rayon 线程池获得并行加速；在需要严格控制单文件处理顺序或排查单个文件错误时，可显式设为False顺序执行。
• config与config_path互斥，设计意图是两种配置风格并存：程序化定制直接传ExtractionConfig对象；把配置沉淀为 TOML/YAML/JSON 文件、由部署环境管理时则用config_path。
• easyocr_kwargs仅在 easyocr 后端下有意义，例如需要占用 GPU 时，可在这里传入 EasyOCR 的对应参数；使用 tesseract 后端时该参数不起作用。

4. 用ExtractionConfig定制提取行为

这是本组件最灵活的扩展面：所有高级能力都通过传入 kreuzberg 的ExtractionConfig打开。

4.1 指定输出格式与 OCR 后端

API 参考给出的标准示例——输出 Markdown 并用 Tesseract 做 OCR：

from kreuzberg import ExtractionConfig, OcrConfig converter = KreuzbergConverter( config=ExtractionConfig( output_format="markdown", ocr=OcrConfig(backend="tesseract", language="eng"), ), )

• output_format="markdown"让提取结果以 Markdown 结构输出，保留了标题、列表等结构信息，对下游 LLM 消费更友好；
• OcrConfig(backend="tesseract", language="eng")指定 OCR 后端与识别语言；切换到backend="easyocr"时，即可通过构造参数easyocr_kwargs进一步透传 EasyOCR 选项。

4.2 Token 缩减：为 LLM 消费裁剪文本体积

ExtractionConfig支持token_reduction配置，用于缩减输出体积、降低 LLM 上下文开销：

from kreuzberg import ExtractionConfig, TokenReductionConfig converter = KreuzbergConverter( config=ExtractionConfig( token_reduction=TokenReductionConfig(mode="moderate"), ), )

共有五个档位："off"、"light"、"moderate"、"aggressive"、"maximum"。API 参考页指出缩减后的文本会直接出现在Document.content中——也就是说它影响的是最终产出的文档内容本身，而非仅影响某个中间表示。根据当前版本文档站的组件说明（kreuzbergconverter.mdx），其原理是基于 TF-IDF 的抽取式摘要，识别并保留最重要的词与短语，逐步去掉额外空白、填充词、冗余表述；各档位的参考压缩幅度大致为："light"约 15%、"moderate"约 30%、"aggressive"约 50%、"maximum"超过 50%（"off"表示不缩减）。这一机制对长文档入库做 RAG 时控制嵌入/生成阶段的 token 成本非常实用。

4.3 OCR 前的图像预处理

对扫描件质量不佳的场景，可调整 OCR 前的图像预处理：

from kreuzberg import ( ExtractionConfig, ImagePreprocessingConfig, OcrConfig, TesseractConfig, ) converter = KreuzbergConverter( config=ExtractionConfig( ocr=OcrConfig( backend="tesseract", tesseract_config=TesseractConfig( preprocessing=ImagePreprocessingConfig(...) ), ), ), )

ImagePreprocessingConfig可调节的选项包括：目标 DPI、自动旋转（auto-rotate）、纠偏（deskew）、去噪（denoise）、对比度增强，以及二值化方法（binarization method）。这些参数决定了 Tesseract 拿到的是否是“干净”的输入图，对扫描件 OCR 准确率影响直接。

4.4 按页提取与其他常用子配置

API 参考中列出了config可定制的全部维度：“输出格式、OCR 后端与语言、强制 OCR 模式、按页提取、分块、关键词提取，以及其他 kreuzberg 选项”。其中按页提取（PageConfig）在组件文档中有明确示例：

from kreuzberg import ExtractionConfig, PageConfig converter = KreuzbergConverter( config=ExtractionConfig( page=PageConfig(extract_pages=True), ), ) result = converter.run(sources=["multipage.pdf"]) # 每页一个 Document，且元数据中含 page_number

另外，config_path方式等价于把上述配置写进文件后加载：

converter = KreuzbergConverter(config_path="extraction_config.toml")

4.5 产出的 Document 携带丰富元数据

组件文档指出，除默认的整文件 Document 外，Kreuzberg 产出的 Document 会附带丰富的元数据，例如质量分数、检测到的语言、提取的关键词、表格数据以及 PDF 注解（annotations）等。这与本仓库Document数据类开放的自由meta字典设计一致（见 document.py），下游过滤器和检索器都可以直接基于这些元字段做二次加工。

5.run方法的输入输出契约

run( sources: list[str | Path | ByteStream], meta: dict[str, Any] | list[dict[str, Any]] | None = None, ) -> dict[str, list[Document]]

sources（必填）：文件路径、目录路径或ByteStream对象的列表。当传入的是目录路径时，会展开为该目录的直接文件子项——注意是非递归展开，且按字母序排序。这也意味着在 Pipeline 中该组件可对接任何能产出ByteStream的上游（如文件抓取类组件），与 byte_stream.py 定义的数据结构直接互通。

meta（可选）：要附加到产出 Document 上的元数据，支持两种形态：

• 单个字典：其内容会加到所有产出 Document 的元数据上；
• 字典列表：列表长度必须与 sources 数量一致，两份列表将按位置一一 zip 配对。

若sources中含ByteStream对象，它们自身的meta也会被合并进对应输出 Document。

目录 + meta 的组合限制（容易踩坑）：当sources中存在目录时，meta必须是单个字典而不能是列表——因为目录里到底有多少文件事先无法确定，无法与列表 zip 对齐。批量入库时如果按目录整批投喂，记住这一条约束即可避免运行期报错。

返回值：dict[str, list[Document]]，其中documents键为创建的 Document 列表。

6. 序列化：to_dict/from_dict

to_dict() -> dict[str, Any] from_dict(data: dict[str, Any]) -> KreuzbergConverter

这一对方法遵循 Haystack 组件的通用序列化协议：to_dict返回组件的可序列化字典，from_dict从字典还原组件实例。其工程价值在于 Pipeline 的 YAML/JSON 持久化——把整个索引 Pipeline 序列化部署时，转换器及其配置会随 Pipeline 一起落盘，反序列化后恢复相同的运行行为。从本仓库的序列化实现（serialization.py）可以看到，Haystack 核心对组件的to_dict/from_dict做了统一的注册与校验机制，第三方集成组件正是通过实现这一对方法接入该体系的。

7. 在 Pipeline 中的落位

KreuzbergConverter最典型的位点是索引 Pipeline 的入口处，位于 Preprocessor / DocumentWriter 之前：文件进来 → Kreuzberg 提取为 Document → 切分 → 写入文档库。以本仓库自带的组件为例，一个最小可用的接入形态是：

from haystack import Pipeline from haystack.components.preprocessors import DocumentSplitter from haystack.components.writers import DocumentWriter from haystack.document_stores.in_memory import InMemoryDocumentStore from haystack_integrations.components.converters.kreuzberg import KreuzbergConverter document_store = InMemoryDocumentStore() pipeline = Pipeline() pipeline.add_component("converter", KreuzbergConverter()) pipeline.add_component( "splitter", DocumentSplitter(split_by="sentence", split_length=5), ) pipeline.add_component("writer", DocumentWriter(document_store=document_store)) pipeline.connect("converter", "splitter") pipeline.connect("splitter", "writer") pipeline.run({"converter": {"sources": ["report.pdf", "presentation.pptx"]}})

其中DocumentSplitter、DocumentWriter、InMemoryDocumentStore均来自本仓库核心（切分器见haystack/components/preprocessors/，写入器见haystack/components/writers/，内存文档库见 in_memory 目录），替换成其他文档库与切分策略即可得到生产形态的索引流水线。

8. 小结与适用边界

• 适用场景：需要本地、离线、免 API 地批量解析 PDF/Office/图片/邮件/压缩包等多种格式，并直接产出带丰富元数据Document的索引前置环节；
• 关键调优点：ExtractionConfig的输出格式与 OCR 配置、TokenReductionConfig的五个档位、OCR 图像预处理参数、batch并行开关；
• 注意边界：config与config_path互斥；sources含目录时meta只能传单字典；目录展开为非递归的直接子文件；该组件为外部集成包kreuzberg-haystack提供，实现不在本仓库haystack/核心代码中，但其接口契约与本仓库的Document/ByteStream数据类完全兼容；
• 版本提示：本文以 2.21 版 API 参考（kreuzberg.md）为基准；当前文档站（converters.mdx 中的 kreuzbergconverter.mdx）已将支持格式数更新为 91+，并补充了按页提取、Token 缩减比例等更细的说明，升级使用时建议以对应版本文档为准。

【免费下载链接】haystackOpen-source AI orchestration framework for building context-engineered, production-ready LLM applications. Design modular pipelines and agent workflows with explicit control over retrieval, routing, memory, and generation. Built for scalable agents, RAG, multimodal applications, semantic search, and conversational systems.项目地址: https://gitcode.com/GitHub_Trending/ha/haystack