企业官网建设流程全解析

Haystack 2.21 AzureOCRDocumentConverter 集成指南：基于 Azure Document Intelligence 的复杂文档转换

【免费下载链接】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 版本中AzureOCRDocumentConverter集成组件的 API 参考展开，系统讲解该组件如何调用 Azure Document Intelligence（原 Form Recognizer）服务，将 PDF、扫描件、Office 文档与 HTML 等 9 种格式的文件批量转换为 HaystackDocument对象；读完你将掌握其全部初始化参数（表格上下文、阅读顺序、路径存储策略）、run方法的输入输出契约、序列化行为，以及在索引流水线中接入该组件的完整方式。

组件定位与适用场景

AzureOCRDocumentConverter属于 Haystack 的转换器（Converter）类组件，位于数据索引流水线的最前端，最典型的位置是在 PreProcessors 之前，或干脆作为索引管线的第一个组件。它负责把原始文件（文件路径或ByteStream对象）交给 Azure 云端服务做 OCR 与版面分析，再转换回 Haystack 内存中的Document列表。

按 2.21 版组件文档 与 本 API 参考文档 的说明，该组件支持的文件格式包括：PDF（含可搜索与纯扫描版）、JPEG、PNG、BMP、TIFF、DOCX、XLSX、PPTX 以及 HTML。

使用它需要一个活跃的 Azure 账户，以及一个 Document Intelligence 或 Cognitive Services 资源；资源创建流程请参考 Azure 官方文档（API 参考 中的 "Azure documentation" 链接指向的快速入门页）。

与纯本地转换器相比，它的核心优势在于处理复杂版面：组件不会把表格压平成纯文本，而是为表格生成独立的Document对象并标记为table类型，从而保留表格的二维结构——这一点在处理含大量报表、账单的语料库时非常关键。

安装与环境准备

使用本组件涉及两层依赖：

1. 集成包。该组件的正式 API 参考路径为haystack_integrations.components.converters.azure_form_recognizer，即由外部集成包azure-form-recognizer-haystack提供，安装方式为：

   pip install azure-form-recognizer-haystack

   其底层依赖 Azure SDK 的表单识别客户端（azure-ai-formrecognizer，2.21 版组件文档要求>=3.2.0b2）。

2. Azure 资源凭据。组件默认从环境变量AZURE_AI_API_KEY读取 API Key（也可用Secret.from_env_var("CORE_AZURE_CS_API_KEY")等方式指向自定义变量）；资源端点 URL 必须显式传入endpoint参数。

需要注意的演进背景：该组件早期直接内置于 Haystack 核心包（haystack.components.converters），后来被标记为弃用并迁移至独立的集成包。仓库中的发布说明 deprecate-azure-ocr-converter-146df0c8cf40902e.yaml 明确记录了迁移路径：继续使用者应安装azure-form-recognizer-haystack并改用haystack_integrations.components.converters.azure_form_recognizer的导入路径。因此在 2.21 版本上，两套导入路径都可能见到，新代码建议统一采用集成包路径。

快速上手：独立调用示例

API 参考文档给出的标准用法如下：

import os from datetime import datetime from haystack_integrations.components.converters.azure_form_recognizer import AzureOCRDocumentConverter from haystack.utils import Secret converter = AzureOCRDocumentConverter( endpoint=os.environ["CORE_AZURE_CS_ENDPOINT"], api_key=Secret.from_env_var("CORE_AZURE_CS_API_KEY"), ) results = converter.run( sources=["test/test_files/pdf/react_paper.pdf"], meta={"date_added": datetime.now().isoformat()}, ) documents = results["documents"] print(documents[0].content) # 'This is a text from the PDF file.'

要点说明：

• api_key通过Secret封装传入，支持环境变量或明文 token（Secret.from_token("<your-api-key>")）两种构造方式，避免密钥硬编码；
• meta传入单个字典时，会附加到该次调用产出的所有Document上；
• run的返回值是字典，除documents外还包含raw_azure_response，即 Azure 的原始响应，便于做二次解析或问题排查。

初始化参数详解（init）

组件构造签名为：

__init__( endpoint: str, api_key: Secret = Secret.from_env_var("AZURE_AI_API_KEY"), model_id: str = "prebuilt-read", preceding_context_len: int = 3, following_context_len: int = 3, merge_multiple_column_headers: bool = True, page_layout: Literal["natural", "single_column"] = "natural", threshold_y: float | None = 0.05, store_full_path: bool = False, ) -> None

各参数的作用与默认值如下表：

表格上下文参数：preceding / following_context_len

这两个参数解决了"表格脱离正文后语义不完整"的问题：当组件为表格生成独立Document时，会把表格前后各n行文本一并写入该表格文档的元数据，供下游检索与生成环节恢复上下文。这两个能力由发布说明 azure-ocr-converter-enhancements-c882456cad9a5efc.yaml 佐证，是后来为提升复杂版面转换准确性而增强加入的特性。

阅读顺序参数：page_layout 与 threshold_y

• page_layout="natural"：直接采用 Azure 识别出的自然阅读顺序，适合绝大多数文档；
• page_layout="single_column"：按单栏处理，把页面上"高度相近"的行归并为同一行。归并的判定阈值由threshold_y（英寸）控制。

threshold_y的实际意义在于处理横向空间上分离的元素：例如章节标题与编号、跨栏的标题与正文，它们在竖直方向高度接近但水平方向分开，若按自然顺序容易被拆断。调大threshold_y会让更多元素被合并到同一行，适合多栏报纸式版面；调小则更保守。从参数设计看，该值只对single_column模式生效。

元数据路径策略：store_full_path

store_full_path控制输出文档元数据中记录的路径粒度：True时记录完整路径，False时只记录文件名。仓库发布说明 add-store-full-path-param-to-converters-5bd32a7561abfe78.yaml 显示该参数最初默认值为True，之后出于隐私考虑在后续版本调整为False——2.21 版 API 参考中该默认值已是False。在多租户或跨环境部署时，建议保持False，避免把宿主机绝对路径泄漏到语料库元数据中。

生命周期管理：warm_up 与 close

组件提供显式的客户端生命周期方法：

def warm_up(self) -> None: """Create the Azure Document Analysis client.""" def close(self) -> None: """Close the Azure Document Analysis client."""

• warm_up()负责创建 Azure Document Analysis 客户端实例。在 Haystack 流水线中，组件的warm_up会在管线启动阶段被统一调用，因此通常无需手动触发；
• close()用于关闭该客户端并释放连接资源，适合长驻服务在退出前显式调用，避免悬挂连接。

这一"初始化时不建立连接、运行时惰性创建客户端"的设计，也与 Haystack 组件统一的资源生命周期约定一致。

run 方法：输入契约与输出结构

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

输入：sources 与 meta 的三种匹配规则

• sources：文件路径（str或Path）或ByteStream对象列表。传入ByteStream时适合与上游的文件抓取组件（如 LinkContentFetcher 类）串联，无需落盘；
• meta支持三种形态，规则如下：
  1. 单个字典：其内容会合并附加到本次调用产出的所有Document上。仓库发布说明 single-meta-in-azureconverter-ce1cc196a9b161f3.yaml 明确记录了这一增强：允许在源文件数量未知时为全部文件统一附加元数据（如{"date_added": ...}）；
  2. 字典列表：列表长度必须与sources一一对应，两者按位置 zip 配对，实现逐文件的差异化元数据；
  3. None：不附加额外元数据；
  4. 若sources中的项为ByteStream，其自带meta会自动并入输出Document的元数据。

输出：documents 与 raw_azure_response

返回字典包含两个键：

• documents：转换生成的Document列表。其中正文为文本型文档，表格为独立的table型文档，表格文档的元数据中携带前后上下文行；
• raw_azure_response：Azure 返回的原始响应列表。保留原始响应的价值在于：当需要对版面块（region）、置信度或表格单元格做自定义二次解析时，不必重新发起云端请求。

序列化：to_dict / from_dict

def to_dict(self) -> dict[str, Any]: """Serializes the component to a dictionary.""" def from_dict(self, data: dict[str, Any]) -> AzureOCRDocumentConverter: """Deserializes the component from a dictionary."""

这两个方法使组件能够随 Haystack 流水线一起被序列化、存储与重建（例如通过Pipeline.dumps()保存 YAML 再加载）。有一个值得注意的安全设计：从源码发布说明 remove-api-key-from-serialization-2474a1539b86e233.yaml 可以看到，api_key被刻意排除在序列化输出之外——反序列化后组件会重新从环境变量（AZURE_AI_API_KEY）读取密钥。这意味着把管线 YAML 提交到版本库或共享给他人时，不会意外泄露 Azure 凭据，但也意味着部署环境必须配置好同名环境变量。

在索引流水线中的完整用法

2.21 版组件文档给出了典型的"转换 → 清洗 → 切分 → 写入"索引管线：

from haystack import Pipeline from haystack.document_stores.in_memory import InMemoryDocumentStore from haystack.components.converters import AzureOCRDocumentConverter from haystack.components.preprocessors import DocumentCleaner, DocumentSplitter from haystack.components.writers import DocumentWriter from haystack.utils import Secret document_store = InMemoryDocumentStore() pipeline = Pipeline() pipeline.add_component( "converter", AzureOCRDocumentConverter( endpoint="azure_resource_url", api_key=Secret.from_token("<your-api-key>"), ), ) pipeline.add_component("cleaner", DocumentCleaner()) pipeline.add_component("splitter", DocumentSplitter(split_by="sentence", split_length=5)) pipeline.add_component("writer", DocumentWriter(document_store=document_store)) pipeline.connect("converter", "cleaner") pipeline.connect("cleaner", "splitter") pipeline.connect("splitter", "writer") file_names = ["my_file.pdf"] pipeline.run({"converter": {"sources": file_names}})

使用时的实操要点：

• 该示例使用haystack.components.converters导入（2.21 时期核心包仍内置该组件且已弃用），迁移到 3.x 后请改用haystack_integrations.components.converters.azure_form_recognizer；
• DocumentCleaner承接转换器输出时，需要注意表格类文档的特殊性——DocumentCleaner 文档 中提到其对表格文本的支持范围，串联前建议先用小样本验证表格文档经过清洗与切分后的形态是否符合预期；
• 由于转换发生在云端，管线对 Azure 资源有网络依赖与配额消耗，生产环境应关注请求批量与限流行为，并利用raw_azure_response排查单文件转换异常。

版本演进小结

从仓库发布说明可以还原该组件的能力演进脉络，便于判断你所在版本支持哪些参数：

• 组件引入：add-azure_ocr_doc_converter-935130b3b243d236.yaml（最初以预览特性加入）；
• 表格与文本高级处理增强（前后上下文、表头合并、单栏版面）：azure-ocr-converter-enhancements-c882456cad9a5efc.yaml；
• 单一 meta 字典支持：single-meta-in-azureconverter-ce1cc196a9b161f3.yaml；
• store_full_path参数引入及默认值隐私化调整：add-store-full-path-param-to-converters-5bd32a7561abfe78.yaml；
• api_key移出序列化：remove-api-key-from-serialization-2474a1539b86e233.yaml；
• 弃用并迁移至独立集成包：deprecate-azure-ocr-converter-146df0c8cf40902e.yaml。

在 2.21 版本上，AzureOCRDocumentConverter提供了以云端 OCR 换取高质量复杂版面解析的完整方案：表格保留二维结构、支持阅读顺序定制与表格上下文元数据、序列化安全且可嵌入任意索引管线。若你处理的是扫描件 PDF、多栏报表或 Office 导出文档，它值得作为转换器层的备选；若文档均为结构规整的文本型 PDF，则本地转换器在延迟与成本上通常更具优势。

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