企业官网建设流程全解析

Haystack Azure 集成实战：使用 AzureOCRDocumentConverter 调用 Azure 文档智能服务进行 OCR 文档转换

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

AzureOCRDocumentConverter是 Haystack 生态中对接 Azure 文档智能（Document Intelligence）服务的文档转换组件，用于将 PDF、JPEG、PNG 等十余种格式的文件批量转换为 HaystackDocument对象。本文以该组件的 API 参考为骨架，完整讲解其安装迁移、构造参数、运行方式、表格处理细节与生命周期方法，并结合当前仓库的官方组件指南与发布说明（release notes）补充源码级演进依据，帮助你在一套 RAG / 语义检索索引流水线中正确、高效地接入 Azure OCR。

组件定位与适用场景

AzureOCRDocumentConverter位于haystack_integrations.components.converters.azure_form_recognizer模块，其核心职责是：输入文件路径或ByteStream，调用 Azure 云端服务完成 OCR 识别与版面分析，输出一批可直接进入后续预处理与索引环节的Document。

该组件适用于以下典型场景：

• 索引图像型 PDF（扫描件、拍照件）与纯图片文件，借助 Azure 云端 OCR 能力抽取文字；
• 处理结构化复杂版面（多栏、表格、页眉页脚、编号与章节标题），并在抽取结果中保留版面上下文信息；
• 在统一索引流水线中，将可搜索 PDF 与图像型 PDF 混合的文件批次交给同一组件处理。

组件支持的文件格式包括：PDF（含可搜索 PDF 与纯图像 PDF）、JPEG、PNG、BMP、TIFF、DOCX、XLSX、PPTX、HTML。要使用它，你需要一个有效的 Azure 账号，以及一个 Document Intelligence（文档智能）或 Cognitive Services（认知服务）资源，并按 Azure 官方快速入门文档完成资源创建与密钥获取。

从组件在流水线中的位置看，它通常被放置在整个索引流水线的最前端、各类 PreProcessor（如 DocumentCleaner、DocumentSplitter）之前，负责把原始文件统一转换成后续组件可消费的Document列表。

安装与导入路径

AzureOCRDocumentConverter在 Haystack 2.x 中曾被内置于核心包，随后被移出并独立成集成包。自该组件被标记为弃用（deprecated）起，使用方式变为先安装独立包，再从haystack_integrations命名空间导入：

pip install azure-form-recognizer-haystack

from haystack_integrations.components.converters.azure_form_recognizer import ( AzureOCRDocumentConverter, )

迁移依据可参考仓库根目录的 MIGRATION.md 中的导入路径映射表：旧的from haystack.components.converters import AzureOCRDocumentConverter已迁移至上述新路径；对应的发布说明 deprecate-azure-ocr-converter-146df0c8cf40902e.yaml 明确指出该组件将随 Haystack 3.0 从核心代码中移除，继续使用者需安装azure-form-recognizer-haystack包并更新导入语句。

提示：如果你从零开始新建 OCR 转换需求，建议优先评估官方推荐的继任组件AzureDocumentIntelligenceConverter（详见文末「迁移到 AzureDocumentIntelligenceConverter」一节），它基于更新的azure-ai-documentintelligenceSDK，输出更利于 LLM / RAG 消费的 GitHub Flavored Markdown。

构造函数参数详解

组件初始化签名（__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

各参数含义与配置建议如下表：

两个需要特别说明的参数：

• api_key与 Secret 机制：组件使用 Haystack 的Secret类型管理凭据，避免在代码、序列化产物中明文暴露密钥。发布说明 update-secret-handling-in-components-925d4f3c3c9530db.yaml 记录了对该组件 Secret 处理的统一调整：默认初始化参数改为优先从环境变量读取，并移除了 Azure 组件的azure_ad_token_provider参数。
• store_full_path的隐私取向：该参数于后续版本加入，用于控制文件完整路径是否写入 metadata。从 add-store-full-path-param-to-converters-5bd32a7561abfe78.yaml 可以看到其默认值经历了一次面向隐私的收紧（由默认存完整路径改为默认仅存文件名），与本 API 参考中False的默认值一致。若你的业务需要追溯文件来源，可显式开启。

运行转换：run 方法

run是组件的核心入口，签名如下：

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

输入参数

• sources：文件路径字符串、pathlib.Path或ByteStream对象的列表。ByteStream支持直接以内存字节流形式传入文件内容，便于与上游下载器、抓取器联动。
• meta：可选元数据，支持两种形态：
  • 单个字典：该字典内容会合并到本次所有输出Document的 metadata 中，适合给整批文件统一打标（如数据来源、导入批次、日期）；
  • 字典列表：列表长度必须与sources数量一致，两者按位置 zip 对应，为每个文件分别附加各自的 metadata。
  • 若sources中包含ByteStream对象，则这些对象自带的meta也会合并进对应输出Document的 metadata。

返回值

run返回一个字典，包含两个键：

• documents：本次转换生成的Document列表；
• raw_azure_response：用于生成这些Document的 Azure 原始响应列表，便于排查识别质量、做后续二次加工或调试。

表格的特殊处理方式

AzureOCRDocumentConverter对表格有一套专门的处理逻辑：表格不会以内联形式留在页面正文文本中，而是每个表格被抽取为独立的Document，其content为表格内容的CSV 渲染文本，metadata 中附加preceding_context（表格前文）、following_context（表格后文）以及page（页码）字段。

这一行为由多项发布说明印证：

• azure-ocr-converter-enhancements-c882456cad9a5efc.yaml 记录了本组件的表格与文本增强：提取表格上下文、合并多列表头、支持单栏页面布局；
• remove-df-doc-from-azure-ocr-4d65509235a5fd9d.yaml 说明输出Document不再携带已弃用的dataframe字段，表格统一以 CSV 文本写入content；若业务需要 DataFrame 形态，可用pandas.read_csv()将 CSV 文本还原。

因此，下游若想利用表格上下文做增强检索，可以直接读取表格Document的 metadata 中的preceding_context/following_context字段，无需自行实现版面上下文截取。

完整使用示例

单独使用

以下示例从环境变量读取端点与密钥，转换一份 PDF 并为结果附加导入时间元数据（示例中test/test_files/pdf/react_paper.pdf为集成包测试样例路径，实际使用时替换为你的文件即可）：

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.'

更简洁的写法是直接用Path对象，并让组件走默认的AZURE_AI_API_KEY环境变量：

from pathlib import Path from haystack_integrations.components.converters.azure_form_recognizer import AzureOCRDocumentConverter from haystack.utils import Secret converter = AzureOCRDocumentConverter( endpoint="azure_resource_url", api_key=Secret.from_token("<your-api-key>"), ) converter.run(sources=[Path("my_file.pdf")])

在流水线中使用

AzureOCRDocumentConverter输出的是结构完整的Document列表，可无缝接入 Haystack 索引流水线。官方组件指南 azureocrdocumentconverter.mdx 给出了一个「转换 → 清洗 → 切分 → 写入文档库」的完整示例：

from haystack import Pipeline from haystack.document_stores.in_memory import InMemoryDocumentStore from haystack_integrations.components.converters.azure_form_recognizer import ( AzureOCRDocumentConverter, ) from haystack.components.preprocessors import DocumentCleaner from haystack.components.preprocessors import 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}})

运行后，OCR 抽取出的正文与表格Document会依次经过清洗、切分并写入InMemoryDocumentStore，形成可被检索器消费的索引数据。若你的文档以表格为主，请留意切分与清洗策略，避免破坏表格 CSV 的结构完整性。

生命周期方法：warm_up 与 close

• warm_up() -> None：创建 Azure 文档分析客户端（Document Analysis client）。Haystack 会在流水线正式运行前自动调用各组件（含此组件）的warm_up，将网络客户端初始化集中到预热阶段，避免首次运行时的冷启动延迟。
• close() -> None：关闭 Azure 文档分析客户端，释放底层连接资源。在长生命周期服务中，可通过显式调用close及时回收资源。

序列化：to_dict 与 from_dict

作为标准的 Haystack 组件，AzureOCRDocumentConverter实现了序列化协议：

• to_dict() -> dict[str, Any]：将组件配置序列化为字典，便于 YAML 化保存、版本化管理与跨环境复现。
• from_dict(data: dict[str, Any]) -> AzureOCRDocumentConverter：从字典反序列化重建组件实例，返回新的AzureOCRDocumentConverter。

需要注意的是，由于api_key使用Secret类型管理，序列化产物不会包含明文密钥，凭据仍须在运行环境中以环境变量或Secret提供，这符合组件库对凭据安全处理的统一约定。

源码级演进与设计要点

虽然AzureOCRDocumentConverter的实现在独立的azure-form-recognizer-haystack集成仓库中，但当前仓库的发布说明完整记录了它的设计演进，可据此把握其行为细节：

1. 表格增强（azure-ocr-converter-enhancements-c882456cad9a5efc.yaml）：引入表格前后文提取、多列表头合并、单栏版面阅读顺序，支撑复杂版面的准确抽取；
2. CSV 化表格（remove-df-doc-from-azure-ocr-4d65509235a5fd9d.yaml）：移除过时的dataframe字段，表格统一以 CSV 文本承载；
3. 单字典 meta 支持（single-meta-in-azureconverter-ce1cc196a9b161f3.yaml）：当输入源数量未知时，仍可通过单个 metadata 字典为整批文档统一打标；
4. 路径隐私（add-store-full-path-param-to-converters-5bd32a7561abfe78.yaml）：store_full_path默认值向False收紧，减少敏感路径信息外泄；
5. 凭据安全（update-secret-handling-in-components-925d4f3c3c9530db.yaml）：统一改用Secret与环境变量，移除azure_ad_token_provider参数。

这些演进共同决定了你在 API 参考中看到的参数默认值与行为约定，理解它们有助于在升级 Haystack 版本时评估兼容性影响。

迁移到 AzureDocumentIntelligenceConverter

AzureOCRDocumentConverter基于较旧的azure-ai-formrecognizerSDK，官方已将其标记为弃用并推荐使用新的 AzureDocumentIntelligenceConverter。两者对比如下：

迁移时的注意点：

• 将依赖从azure-form-recognizer-haystack切换为azure-doc-intelligence-haystack，并把导入语句改为from haystack_integrations.components.converters.azure_doc_intelligence import AzureDocumentIntelligenceConverter；
• 输出由纯文本变为 Markdown 后，不要用默认配置的DocumentCleaner直接清洗，因为其默认开启的remove_extra_whitespaces=True、remove_empty_lines=True会折叠换行、压平标题/表格/列表，建议直接连接下一组件，或按需关闭这些选项后再清洗（详见 azuredocumentintelligenceconverter.mdx）；
• 原依赖表格Document的preceding_context/following_context元数据的处理逻辑，需要按新的 Markdown 内联表格输出重新设计。

小结

AzureOCRDocumentConverter是 Haystack 对接 Azure 文档智能服务的高性价比 OCR 入口：构造参数覆盖了识别模型、版面阅读顺序、表格上下文与路径隐私等关键诉求；run的meta双形态设计与表格独立成Document的行为，使其能自然嵌入标准索引流水线；warm_up/close/to_dict/from_dict则保证了它与 Haystack 组件生命周期与序列化协议的无缝协同。在新项目中，建议优先评估其继任组件AzureDocumentIntelligenceConverter的 Markdown 输出能力；而在维护存量流水线时，可按本文的迁移对照完成平滑升级。

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