企业官网建设流程全解析

Haystack 集成 KreuzbergConverter：本地化多格式文档转 Document 的完整实战指南

【免费下载链接】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

KreuzbergConverter是 Haystack 生态中一个以 Rust 为核心的文档智能转换组件，它通过kreuzberg-haystack集成包将 PDF、Office 文档、图片及 91+ 种文件格式在本地转换为 HaystackDocument，全程不发起任何外部 API 调用。本文将基于版本化 API 参考（docs-website/reference_versioned_docs/version-2.20/integrations-api/kreuzberg.md）与官方组件指南（docs-website/docs/pipeline-components/converters/kreuzbergconverter.mdx），系统讲解其安装、独立使用、Pipeline 集成、ExtractionConfig深度定制与序列化接口，并对照 Haystack 核心转换器源码揭示其与生态其余 Converter 的设计异同。

为什么选择 Kreuzberg：本地化、高覆盖的文档智能抽取

KreuzbergConverter的定位非常清晰：把「任意常见文档」变成「可供检索与喂给 LLM 的干净文本」。它的底层是 Kreuzberg——一个文档智能框架，核心处理逻辑由 Rust 实现，支持从 PDF、Office 文档、图片以及 75+ 其他格式中提取文本。所有处理均在本地完成，不依赖任何外部 API，这意味着数据不出域、无网络依赖、成本可控，非常适合对数据隐私和延迟敏感的企业级索引管线。

需要特别说明的是，官方组件指南中描述其格式覆盖为 91+ 种，而版本 2.20 的 API 参考写作 75+ 种，两者都是同一组件的不同版本措辞。从当前仓库可见，docs-website/docs/pipeline-components/converters/kreuzbergconverter.mdx 与各版本化文档（如 version-3.1 版本）均采用 91+ 的描述，读者应以官方最新指南为准，并将其理解为「随版本持续增长的格式矩阵」。

从组件目录结构看，该集成属于 Haystack 生态的外置集成包（kreuzberg-haystack），与 Haystack 核心内置的 pypdf.py、docx.py、pdfminer.py 等单格式转换器形成互补：核心包提供「一种格式一个组件」的精细控制，而 Kreuzberg 集成以单个组件覆盖海量格式，显著降低索引管线的组件数量与维护成本。

支持的格式类别总览

官方指南将 Kreuzberg 的格式覆盖划分为六类：

• 文档类：PDF、DOCX、DOC、PPTX、PPT、XLSX、XLS、ODT、ODS、ODP、RTF、Pages、Keynote、Numbers 等；
• 图片类（经 OCR）：PNG、JPEG、TIFF、GIF、BMP、WebP、JPEG 2000、SVG；
• 文本/标记类：Markdown、HTML、XML、LaTeX、Typst、JSON、YAML、reStructuredText、Jupyter Notebook；
• 邮件类：EML、MSG（支持附件提取）；
• 压缩包类：ZIP、TAR、GZIP、7Z（递归解压并处理内部内容）；
• 电子书与学术类：EPUB、BibTeX、DocBook、JATS。

默认情况下每个源文件生成一个 HaystackDocument；当开启按页提取（per-page extraction）或分块（chunking）后，会改为每页/每块一个Document。生成结果携带丰富的元数据，包括质量评分（quality scores）、检测到的语言、抽取的关键词、表格数据以及 PDF 注解等。

快速上手：安装与独立使用

安装

集成包通过 PyPI 分发，包名为kreuzberg-haystack：

pip install kreuzberg-haystack

安装完成后，即可从haystack_integrations.components.converters.kreuzberg导入组件。

独立使用

最简单的调用方式与 Haystack 核心转换器保持一致——构造组件后直接调用run()：

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

API 参考给出的run签名如下：

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

几个关键行为：

• sources支持三种类型：文件路径字符串、Path对象，以及 Haystack 的ByteStream二进制对象（定义见 byte_stream.py，包含data、meta、mime_type三个字段）。这一点与核心转换器一致：以 txt.py 为代表的run同样接收sources: list[str | Path | ByteStream]，并通过get_bytestream_from_source（utils.py）将路径统一包装成带file_path元数据的ByteStream。
• 目录路径会自动展开：当sources中出现目录时，会展开为其直接文件子项（非递归、按字母序排序）。
• meta的两种形态：传单个字典时，该字典内容会合并进所有产出Document的元数据；传字典列表时，其长度必须与sources数量一致（两者按位置 zip）。若sources中包含ByteStream对象，则其自身携带的meta也会被合并进输出Document。
• 目录与列表型meta的冲突：当sources中存在目录时，由于目录内文件数量在运行前不可知，meta必须是单个字典而不能是列表。

这一meta归一化机制在核心代码中有完整对应实现：utils.py 的normalize_metadata会将None、单字典、字典列表统一为与源数量等长的独立字典列表，并对单字典逐源deepcopy，避免下游对元数据的原地修改污染其他文档。理解这一点有助于排查「为什么所有文档共享同一份元数据引用」之类的隐性坑。

在 Pipeline 中使用

KreuzbergConverter最常见的管道位置是索引管线的开头、PreProcessors 之前，官方指南给出的完整索引管线示例如下：

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"]}})

该链路完整呈现了 RAG 索引的标准三步：转换 → 切分 → 写入文档库。KreuzbergConverter输出documents: list[Document]，其下游可直接对接 DocumentSplitter（按句子切分、每 5 句一块），再经 DocumentWriter 写入InMemoryDocumentStore。得益于 Haystack 统一的documents输出约定，Kreuzberg 可以无缝替换/并存于任何内置 Converter 所在的索引管线位置。

构造参数详解

KreuzbergConverter的__init__签名如下：

__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

几个值得展开的细节：

1. config与config_path二选一：两者都用于注入提取配置，API 参考明确标注二者不可同时使用。config_path的适用场景是把提取策略沉淀为团队共享的配置文件（TOML/YAML/JSON），便于版本管理与跨环境复用，详见下文「配置文件驱动」小节。
2. store_full_path的语义与核心组件一致：Haystack 内置转换器（如 txt.py）在store_full_path=False时会通过os.path.basename(file_path)将元数据中的file_path降级为纯文件名；Kreuzberg 集成遵循同一约定。建议在需要追溯文档来源绝对位置（如审计、去重、重新抓取）时开启。
3. batch是性能关键开关：默认True意味着多文件场景下由 Kreuzberg 的 Rust 侧 rayon 线程池并行抽取，吞吐远高于逐文件串行；仅在内存受限或需要严格顺序输出的场景才关闭。
4. easyocr_kwargs仅影响easyocr后端：当config中 OCR 后端选择 EasyOCR 时，此参数可将 GPU 设备、beam width、模型缓存目录等选项透传，参考 EasyOCR 官方文档的参数清单。

深度定制：ExtractionConfig 的三大实用场景

ExtractionConfig是 Kreuzberg 提取行为的统一入口。API 参考与组件指南共同展示了三种最常用的定制模式。

场景一：Markdown 输出 + Tesseract OCR（扫描件处理）

from haystack_integrations.components.converters.kreuzberg import KreuzbergConverter from kreuzberg import ExtractionConfig, OcrConfig converter = KreuzbergConverter( config=ExtractionConfig( output_format="markdown", ocr=OcrConfig(backend="tesseract", language="eng"), ), ) result = converter.run(sources=["scanned_document.pdf"]) documents = result["documents"]

该配置把输出格式设为markdown（保留标题层级、列表等结构信息，对下游分块与 LLM 上下文构建更友好），并让 OCR 走 Tesseract 后端、语言限定为英语。对于扫描件 PDF（无文本层），ExtractionConfig还支持强制 OCR 模式，确保纯图片型文档也能抽取文本。

场景二：按页提取（每页一个 Document）

from haystack_integrations.components.converters.kreuzberg import KreuzbergConverter from kreuzberg import ExtractionConfig, PageConfig converter = KreuzbergConverter( config=ExtractionConfig( page=PageConfig(extract_pages=True), ), ) result = converter.run(sources=["multipage.pdf"]) # One Document per page, each with page_number in metadata

开启PageConfig(extract_pages=True)后，多页 PDF 会拆成每页一个Document，且每个文档的元数据中带有page_number。这一粒度对「引用页码的 RAG」与「按页审核」场景极有价值，配合 Haystack 的Document元数据字段（见 document.py）可直接作为后续 Ranker 或生成器的引用依据。

场景三：Token Reduction 压缩输出

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

Token 缩减面向 LLM 消费场景，采用基于 TF-IDF 的抽取式摘要：识别并保留最重要的术语与短语，逐步剔除多余空白、填充词与冗余表述。共分五档，官方指南给出了每档的近似压缩比例：

缩减后的文本直接体现在Document.content中，无需额外后处理即可喂给下游，可有效控制长文档索引时的 token 成本与上下文占用。

场景四：OCR 图像预处理调优

对于 OCR 质量敏感的场景，API 参考还给出了图像预处理的调优入口：

OcrConfig( tesseract_config=TesseractConfig( preprocessing=ImagePreprocessingConfig(...) ) )

ImagePreprocessingConfig支持目标 DPI、自动旋转（auto-rotate）、纠偏（deskew）、去噪（denoise）、对比度增强与二值化方法等选项。低质量扫描件（歪斜、噪点多、光照不均）可借此显著提升 OCR 准确率——这是把「能抽」变成「抽得准」的关键旋钮。

配置文件驱动：config_path

当提取策略需要团队级复用或按环境切换时，把配置写入独立文件更合适：

from haystack_integrations.components.converters.kreuzberg import KreuzbergConverter converter = KreuzbergConverter(config_path="extraction_config.toml")

config_path支持.toml、.yaml、.json三种格式。一个典型的extraction_config.toml可同时表达输出格式、OCR 与 token 缩减策略：

output_format = "markdown" [ocr] backend = "tesseract" language = "eng" [token_reduction] mode = "moderate"

注意config与config_path互斥，二者只能择一。完整配置项清单与格式支持矩阵可查阅 Kreuzberg 官方文档（docs.kreuzberg.dev）。

序列化支持：to_dict / from_dict

作为 Haystack 组件，KreuzbergConverter实现了标准的组件序列化协议，这对 Pipeline 的 YAML 持久化与反序列化至关重要（Haystack 的Pipeline.dumps()/loads()依赖各组件此协议）。

to_dict() -> dict[str, Any]

to_dict将组件序列化为字典，其中包含组件类型与构造参数。反序列化方法：

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

from_dict接收一个字典（通常来自Pipeline.loads()的 YAML/JSON 内容），返回一个等价的KreuzbergConverter实例。序列化往返保证了索引管线可以「定义即配置」——例如将包含config_path的组件定义写入 YAML，在不同环境中重建完全一致的提取行为。

与 Haystack 核心转换器家族的关系

把KreuzbergConverter放在 Haystack 转换器生态中看，它的定位与核心内置转换器互为补充：

• 核心单格式转换器：haystack/components/converters/目录下按格式拆分，如 txt.py（文本）、docx.py（Word）、pypdf.py（PDF）、pptx.py（PPT）、xlsx.py（Excel）、html.py、markdown.py、json.py 等。它们各自小而专，依赖轻。
• KreuzbergConverter：以单一组件覆盖 91+ 格式，内置 Rust 加速与批量并行，且在元数据丰富度（质量评分、语言检测、关键词、表格数据、PDF 注解）与 OCR/图像预处理能力上明显更强。

两者共享同一套接口契约：run(sources, meta) -> {"documents": [...]}，输入都接受str | Path | ByteStream，元数据归一化遵循 utils.py 中normalize_metadata的统一逻辑，输出都是带content与meta的Document（document.py）。这意味着：切换到 KreuzbergConverter 不需要改动下游任何组件，只需替换索引管线的首节点即可获得格式覆盖与性能的双重提升；而当项目只需要极轻量的单格式转换时，核心转换器仍是更低依赖的选择。

实战建议与注意事项

1. 扫描件务必显式配置 OCR：纯图片型 PDF 不会自动走 OCR，需按「场景一」设置OcrConfig；多语言文档记得按需配置language或扩展语言列表。
2. 长文档索引优先开 Token Reduction：结合「场景三」的五档模式，可先用"moderate"起步，再根据检索质量回调。缩减后的文本直接进入Document.content，不会额外占用下游字段。
3. 需要页码溯源时开启按页提取：「场景二」的PageConfig让每个Document携带page_number，配合store_full_path=True可获得「文件 + 页码」的完整溯源能力。
4. 多文件批量索引保持batch=True：rayon 线程池并行抽取是吞吐优势所在；仅当内存或顺序敏感时才置为False。
5. 配置策略交给文件：团队共享提取策略时优先config_path（TOML/YAML/JSON），并牢记与config互斥。
6. 元数据合并规则：meta传列表时长度必须等于sources数量，且sources含目录时只能传单个字典；ByteStream自带的meta会自动并入输出。

小结

KreuzbergConverter把「本地化、多格式、高性能」三个诉求收敛到一个组件里：Rust 核心负责格式解析与批量并行，ExtractionConfig体系提供输出格式、OCR、按页、分块、Token 缩减、图像预处理的精细控制，config_path让策略可配置化，to_dict/from_dict则保证它无缝融入 Haystack 的 Pipeline 序列化体系。无论你是要搭建企业级 RAG 索引管线、处理历史扫描件，还是为 LLM 应用做上下文工程，它都是一个值得优先评估的文档入口组件。

【免费下载链接】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