企业官网建设流程全解析

Haystack Extractors 组件深度指南：LLM 文档内容抽取、元数据生成、NER 命名实体识别与正则文本提取

【免费下载链接】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.22 参考文档 extractors_api.md 为骨架，系统讲解 Haystack 的 Extractors（提取器）组件族：LLMDocumentContentExtractor（视觉大模型抽取图片/扫描件文本）、LLMMetadataExtractor（LLM 生成文档元数据）、NamedEntityExtractor（基于 Hugging Face / spaCy 的命名实体识别）与RegexTextExtractor（正则表达式提取片段）。读完本文，你将掌握每个组件的初始化参数、运行契约、失败处理机制、序列化方式，以及如何把它们编排进索引/问答 Pipeline，并理解其底层源码实现与测试验证。

一、Extractors 组件族概览

Haystack 的 Extractors 是一组负责"从文本或文档中提取特定元素"的组件，典型用途包括：把图片型文档变成可检索文本、为文档补充可用于过滤与检索的元数据、识别命名实体、从 LLM 输出中解析结构化片段。它们在 Pipeline 中通常位于预处理（索引侧）之后，或在查询侧跟随 Retriever / Generator。

二、LLMDocumentContentExtractor：视觉大模型驱动的文档内容抽取

LLMDocumentContentExtractor面向"以图片为载体的文档"（扫描件、含文字的图片、PDF 页面），利用具备视觉能力的 Chat Generator 把图像内容转化为结构化文本。它的典型应用场景是把不可检索的图片型文档转成可搜索文本，再交给后续切分与写入组件。

2.1 工作原理

组件按如下三步工作（与参考文档描述一致）：

1. 通过DocumentToImageContent组件把每个输入文档转换为图像（源码导入）；
2. 使用一段预先定义好的提示词（prompt）指导 LLM 如何抽取内容；
3. 把"图像 + 提示词"一起作为一条 Chat Message 交给支持视觉输入的ChatGenerator，抽取结构化文本。

提示词中不允许包含任何变量：提示词只能包含抽取指令，不能有 Jinja 变量。源码在初始化时通过_validate_prompt_no_variables用沙箱化 Jinja 环境解析并检测未声明变量，一旦发现就抛出ValueError（见 llm_document_content_extractor.py#L245-L254）。这意味着提示词不能像PromptBuilder那样被动态填充——文档的图像数据本身即是"变量"。

2.2 初始化参数

def __init__(*, chat_generator: ChatGenerator, prompt: str = DEFAULT_PROMPT_TEMPLATE, file_path_meta_field: str = "file_path", root_path: str | None = None, detail: Literal["auto", "high", "low"] | None = None, size: tuple[int, int] | None = None, raise_on_failure: bool = False, max_workers: int = 3)

其中root_path带有安全语义：组件会读取file_path_meta_field指向的主机文件。若文档元数据可能受不可信输入影响，应设置root_path为专用数据目录，以拒绝路径穿越载荷（绝对路径或../）。组件内部正是把file_path_meta_field、root_path、detail、size透传构造了DocumentToImageContent（见 llm_document_content_extractor.py#L175-L177）。

2.3 使用示例

参考文档给出的最小用法如下：

from haystack import Document from haystack.components.generators.chat import OpenAIChatGenerator from haystack.components.extractors.image import LLMDocumentContentExtractor chat_generator = OpenAIChatGenerator() extractor = LLMDocumentContentExtractor(chat_generator=chat_generator) documents = [ Document(content="", meta={"file_path": "image.jpg"}), Document(content="", meta={"file_path": "document.pdf", "page_number": 1}), ] updated_documents = extractor.run(documents=documents)["documents"] print(updated_documents) # [Document(content='Extracted text from image.jpg', # meta={'file_path': 'image.jpg'}), # ...]

注意输入文档的content可以为空，但必须在元数据中携带有效文件路径（字段名由file_path_meta_field指定，默认为file_path）；对于 PDF 场景，可以像第二个文档那样通过page_number指定要渲染的页面。

2.4 响应处理与失败机制

run的签名与返回契约如下：

@component.output_types(documents=list[Document], failed_documents=list[Document]) def run(documents: list[Document]) -> dict[str, list[Document]]

• "documents"：抽取成功的文档，content已被更新；
• "failed_documents"：抽取失败的文档，元数据中带有失败说明。

参考文档（version-2.22）中失败文档的元数据键名为content_extraction_error。需要留意的是：当前主线源码中的_process_llm_results实际写入的键名是extraction_error（见 llm_document_content_extractor.py#L346-L371），且成功重跑时会自动清除旧的错误字段——以你实际安装版本为准。

源码对 LLM 回复做了统一解析（_process_response，llm_document_content_extractor.py#L256-L274），存在三种结果形态：

1. 纯字符串回复（非 JSON）：整段回复直接写入文档content；
2. JSON 对象且仅含document_content键：该键的值写入content；
3. JSON 对象且含多个键：document_content的值写入content，其余键值合并进文档元数据。

因此，如果你想让 LLM 同时返回正文与结构化元数据（如作者、日期、文档类型），可以用generation_kwargs配置结构化输出：

chat_generator = OpenAIChatGenerator( generation_kwargs={ "response_format": { "type": "json_schema", "json_schema": { "name": "entity_extraction", "schema": { "type": "object", "properties": { "document_content": {"type": "string"}, "author": {"type": "string"}, "date": {"type": "string"}, "document_type": {"type": "string"}, "title": {"type": "string"}, }, "additionalProperties": False, }, }, } } )

2.5 并行与异步执行

组件用ThreadPoolExecutor(max_workers=self.max_workers)对每个文档的 LLM 调用做线程级并行（llm_document_content_extractor.py#L392-L393）；同时提供run_async，使用asyncio.Semaphore(max(1, self.max_workers))限制并发，兼容不支持异步的 Chat Generator（自动回退到线程执行，见 llm_document_content_extractor.py#L406-L451）。warm_up/warm_up_async会在有对应方法时预热底层 Chat Generator，close/close_async负责释放资源。此外组件还支持to_dict/from_dict序列化，from_dict会通过deserialize_chatgenerator_inplace就地反序列化嵌套的chat_generator（llm_document_content_extractor.py#L230-L243）。

对应的行为均有测试覆盖，例如混合成功/失败场景、纯字符串回复写入 content、非对象 JSON 报错、多键 JSON 元数据合并、重跑清除旧错误字段等，见 test/components/extractors/image/test_llm_document_content_extractor.py。

2.6 在 Pipeline 中使用

from haystack import Pipeline from haystack.components.extractors.image import LLMDocumentContentExtractor from haystack.components.generators.chat import OpenAIChatGenerator from haystack.components.preprocessors import DocumentSplitter from haystack.components.writers import DocumentWriter from haystack.document_stores.in_memory import InMemoryDocumentStore from haystack import Document document_store = InMemoryDocumentStore() p = Pipeline() p.add_component( instance=LLMDocumentContentExtractor( chat_generator=OpenAIChatGenerator(model="gpt-4o-mini"), file_path_meta_field="file_path", ), name="content_extractor", ) p.add_component(instance=DocumentSplitter(), name="splitter") p.add_component(instance=DocumentWriter(document_store=document_store), name="writer") p.connect("content_extractor.documents", "splitter.documents") p.connect("splitter.documents", "writer.documents") docs = [ Document(content="", meta={"file_path": "scanned_document.pdf"}), Document(content="", meta={"file_path": "image_with_text.jpg"}), ] result = p.run({"content_extractor": {"documents": docs}}) print(len(result["content_extractor"]["documents"])) print(len(result["content_extractor"]["failed_documents"]))

三、LLMMetadataExtractor：用 LLM 为文档生成元数据

LLMMetadataExtractor通过提示词让 LLM 从文档中抽取结构化元数据（如命名实体、主题标签、摘要字段），并把结果合并进文档的meta字段，供后续过滤、路由或检索使用。

3.1 工作原理与提示词约束

组件在初始化时接收一个prompt和一个ChatGenerator。提示词中必须且只能包含一个名为document的变量，它指向文档列表中的单个文档，因此访问正文用{{ document.content }}。源码在__init__中用沙箱化 Jinja 环境解析提示词并校验变量列表：若变量数不为 1 或名称不是document，直接抛出ValueError（见 llm_metadata_extractor.py#L186-L194）。校验通过后，组件内部组合了PromptBuilder（负责把每个文档渲染进提示词）与DocumentSplitter(split_by="page", split_length=1)（负责按页切分以支持page_range），见 llm_metadata_extractor.py#L195-L198。

3.2 完整使用示例（命名实体抽取）

参考文档给出了一个完整的 NER 元数据抽取示例，提示词采用"目标-步骤-示例-真实数据"的结构化模板：

from haystack import Document from haystack.components.extractors.llm_metadata_extractor import LLMMetadataExtractor from haystack.components.generators.chat import OpenAIChatGenerator NER_PROMPT = ''' -Goal- Given text and a list of entity types, identify all entities of those types from the text. -Steps- 1. Identify all entities. For each identified entity, extract the following information: - entity: Name of the entity - entity_type: One of the following types: [organization, product, service, industry] Format each entity as a JSON like: {"entity": <entity_name>, "entity_type": <entity_type>} 2. Return output in a single list with all the entities identified in steps 1. -Examples- ###################### Example 1: entity_types: [organization, person, partnership, financial metric, product, service, industry, investment strategy, market trend] text: Another area of strength is our co-brand issuance. Visa is the primary network partner for eight of the top 10 co-brand partnerships in the US today and we are pleased that Visa has finalized a multi-year extension of our successful credit co-branded partnership with Alaska Airlines, a portfolio that benefits from a loyal customer base and high cross-border usage. ... output: {"entities": [{"entity": "Visa", "entity_type": "company"}, {"entity": "Alaska Airlines", "entity_type": "company"}, ...]} ############################# -Real Data- ###################### entity_types: [company, organization, person, country, product, service] text: {{ document.content }} ###################### output: ''' docs = [ Document(content="deepset was founded in 2018 in Berlin, and is known for its Haystack framework"), Document(content="Hugging Face is a company that was founded in New York, USA and is known for its Transformers library") ] chat_generator = OpenAIChatGenerator( generation_kwargs={ "max_completion_tokens": 500, "temperature": 0.0, "seed": 0, "response_format": {"type": "json_object"}, }, max_retries=1, timeout=60.0, ) extractor = LLMMetadataExtractor( prompt=NER_PROMPT, chat_generator=chat_generator, expected_keys=["entities"], raise_on_failure=False, ) extractor.warm_up() extractor.run(documents=docs) # >> {'documents': [ # Document(id=.., content: 'deepset was founded in 2018 in Berlin, ...', # meta: {'entities': [{'entity': 'deepset', 'entity_type': 'company'}, # {'entity': 'Berlin', 'entity_type': 'city'}, # {'entity': 'Haystack', 'entity_type': 'product'}]}), # ... # ], 'failed_documents': []}

关键配置点：为了让组件正常工作，Chat Generator 必须配置为返回 JSON 对象。使用OpenAIChatGenerator时在generation_kwargs中传入{"response_format": {"type": "json_object"}}（也可以使用json_schema方式强制输出结构，如上文LLMDocumentContentExtractor一节所示）。当前实现支持OpenAIChatGenerator、AzureOpenAIChatGenerator、AmazonBedrockChatGenerator、VertexAIGeminiChatGenerator等 Haystack Chat Generator。

3.3 初始化参数

def __init__(prompt: str, chat_generator: ChatGenerator, expected_keys: list[str] | None = None, page_range: list[str | int] | None = None, raise_on_failure: bool = False, max_workers: int = 3)

3.4 page_range：按页抽取

page_range支持单页与可打印区间字符串两种形式：

• page_range=['1', '3']：抽取每个文档的第 1 页与第 3 页；
• page_range=['1-3', '5', '8', '10-12']：抽取第 1、2、3、5、8、10、11、12 页。

为None时对每个文档的全文抽取。run方法同样接受可选的page_range参数以覆盖初始化时的设置。实现上，区间字符串通过expand_page_range（来自haystack.utils）展开为具体页码列表，组件先用内置DocumentSplitter按页切分文档，再只把目标页内容拼接进提示词（见 llm_metadata_extractor.py#L271-L298）。

3.5 失败处理与重跑机制

@component.output_types(documents=list[Document], failed_documents=list[Document]) def run(documents: list[Document], page_range: list[str | int] | None = None)

• "documents"：成功抽取并合并元数据的文档；
• "failed_documents"：抽取失败的文档，其元数据中带有metadata_extraction_error与metadata_extraction_response两个键。

metadata_extraction_error描述失败原因（LLM 调用异常、回复不是合法 JSON、或缺少expected_keys中的键），metadata_extraction_response保存原始回复。这两者的组合让"失败重跑"成为可能：你可以把失败文档连同错误信息喂给另一个抽取器或同一抽取器的修正提示词再次尝试。成功重跑后，旧的metadata_extraction_error/metadata_extraction_response会被自动清除（见 llm_metadata_extractor.py#L344-L379）。另外两个值得注意的细节：空content的文档会被跳过并放入failed_documents（错误信息为 "Document has no content, skipping LLM call."）；即使expected_keys中恰好包含error这样的键，只要 LLM 返回了合法 JSON，该键也会被当作正常抽取结果而非失败——这两点都有对应测试覆盖（见 test/components/extractors/test_llm_metadata_extractor.py）。

与内容抽取器一致，该组件同样具备warm_up/warm_up_async（预热生成器与切分器）、close/close_async、to_dict/from_dict序列化（from_dict同样就地反序列化嵌套的chat_generator），以及线程池并行（run）与信号量限流的异步执行（run_async）。

四、NamedEntityExtractor：基于 Hugging Face / spaCy 的命名实体识别

NamedEntityExtractor从一段文本中识别预定义实体（人名、组织、地点等），并把识别结果写入文档的meta字段。它适用于索引流水线中预处理之后，或在查询流水线中跟随 Retriever，为下游提供实体级别的结构信息。

4.1 后端与注解数据结构

组件支持两种 NLP 后端：

• NamedEntityExtractorBackend.HUGGING_FACE：使用 Hugging Face 模型与 pipeline；
• NamedEntityExtractorBackend.SPACY：使用 spaCy 模型与 pipeline。

两者都可与各自生态中支持 token 分类 / NER 的模型配合使用（如dslim/bert-base-NER、en_core_web_sm）。后端枚举还提供from_str静态方法，把字符串转换为枚举值。

每个识别结果是一个NamedEntityAnnotation，包含四个字段：

例如：NamedEntityAnnotation(entity='PER', start=11, end=16, score=0.9)。

4.2 初始化与运行

def __init__( *, backend: str | NamedEntityExtractorBackend, model: str, pipeline_kwargs: dict[str, Any] | None = None, device: ComponentDevice | None = None, token: Secret | None = Secret.from_env_var(["HF_API_TOKEN", "HF_TOKEN"], strict=False) ) -> None

使用示例：

from haystack import Document from haystack.components.extractors.named_entity_extractor import NamedEntityExtractor documents = [ Document(content="I'm Merlin, the happy pig!"), Document(content="My name is Clara and I live in Berkeley, California."), ] extractor = NamedEntityExtractor(backend="hugging_face", model="dslim/bert-base-NER") extractor.warm_up() results = extractor.run(documents=documents)["documents"] annotations = [NamedEntityExtractor.get_stored_annotations(doc) for doc in results] print(annotations)

• warm_up()负责初始化组件（加载模型），后端初始化失败时抛出ComponentError；
• run(documents, batch_size=1)对每个文档标注实体，batch_size控制处理批大小，注解存入文档meta的named_entities键下；
• initialized属性返回抽取器是否已就绪；
• get_stored_annotations(document)类方法透明地读取文档中存储的注解列表；若文档没有注解则返回None。

参考文档还展示了更完整的输入输出形态：输入三个文档，输出meta中带有named_entities列表，例如Document(..., meta: {'named_entities': [NamedEntityAnnotation(entity='PER', start=11, end=16, score=0.99641764), NamedEntityAnnotation(entity='LOC', start=31, end=39, score=0.996198), ...]})。2.22 用户指南的完整说明见 docs-website/versioned_docs/version-2.22/pipeline-components/extractors/namedentityextractor.mdx。

4.3 版本迁移提示：组件已迁出主仓库

需要特别说明的是：当前主仓库的haystack/components/extractors/目录下已不再包含named_entity_extractor.py。根据发布说明 releasenotes/notes/remove-named-entity-extractor-a8d65992a201a775.yaml，NamedEntityExtractor（连同NamedEntityAnnotation、NamedEntityExtractorBackend）已从 Haystack 主仓库移除，拆分进按后端划分的独立集成包：

• Hugging Face 后端：安装transformers-haystack，改用from haystack_integrations.components.extractors.transformers import TransformersNamedEntityExtractor，并以TransformersNamedEntityExtractor(model="dslim/bert-base-NER")初始化；
• spaCy 后端：安装spacy-haystack，改用from haystack_integrations.components.extractors.spacy import SpacyNamedEntityExtractor，并以SpacyNamedEntityExtractor(model="en_core_web_trf")初始化。

因此，本文所述 API 以 2.22 参考文档为准；若你使用更高版本，请安装对应集成包并调整导入路径。

五、RegexTextExtractor：用正则从文本与 ChatMessage 中提取片段

RegexTextExtractor是一个零依赖、确定性的轻量提取器：用正则表达式解析输入文本或ChatMessage列表，返回第一个捕获组命中的文本。它非常适合放在 Chat Generator 之后，用于从 LLM 输出中解析带标签（如 XML 风格标签、JSON 代码块）的结构化片段。

5.1 初始化与运行契约

def __init__(regex_pattern: str)

regex_pattern应包含捕获组（圆括号）以指定提取目标。例如'<issue url="(.+)">'从'<issue url="github.com/hahahaha">'中捕获'github.com/hahahaha'。若模式不含任何捕获组，源码在初始化时会打印警告，运行时不返回捕获组而是返回整个匹配串（见 regex_text_extractor.py#L52-L59 与 regex_text_extractor.py#L129-L146）。

@component.output_types(captured_text=str) def run(text_or_messages: str | list[ChatMessage]) -> dict[str, str]

• 输入为字符串时直接在其中搜索；
• 输入为ChatMessage列表时，只处理最后一条消息（如果最后一条不是ChatMessage实例则抛出TypeError）；列表为空或最后一条消息无文本时返回{"captured_text": ""}并记录警告（见 regex_text_extractor.py#L114-L127）；
• 返回值为{"captured_text": "matched text"}（命中）或{"captured_text": ""}（未命中）。

5.2 使用示例

参考文档给出的两种输入形态：

from haystack.components.extractors import RegexTextExtractor from haystack.dataclasses import ChatMessage # Using with a string parser = RegexTextExtractor(regex_pattern='<issue url="(.+)">') result = parser.run(text_or_messages='<issue url="github.com/hahahaha">hahahah</issue>') # result: {"captured_text": "github.com/hahahaha"} # Using with ChatMessages messages = [ChatMessage.from_user('<issue url="github.com/hahahaha">hahahah</issue>')] result = parser.run(text_or_messages=messages) # result: {"captured_text": "github.com/hahahaha"}

与 LLM 输出配合时，可以提取```json代码块中的 JSON：

extractor = RegexTextExtractor(regex_pattern=r"```json\s*(.*?)\s*```") messages = [ ChatMessage.from_user("Extract the data"), ChatMessage.from_assistant('Here is the data:\n```json\n{"name": "Alice", "age": 30}\n```'), ] result = extractor.run(text_or_messages=messages) # result: {'captured_text': '{"name": "Alice", "age": 30}'}

5.3 在 Pipeline 中解析 LLM 结构化输出

一个典型场景是：让 LLM 输出同时包含<analysis>与<summary>标签的回复，再用RegexTextExtractor只摘出<summary>部分：

from haystack import Pipeline from haystack.components.builders import ChatPromptBuilder from haystack.components.generators.chat import OpenAIChatGenerator from haystack.components.extractors import RegexTextExtractor from haystack.dataclasses import ChatMessage pipe = Pipeline() pipe.add_component("prompt_builder", ChatPromptBuilder()) pipe.add_component("llm", OpenAIChatGenerator()) pipe.add_component( "extractor", RegexTextExtractor(regex_pattern=r"<summary>(.*?)</summary>"), ) pipe.connect("prompt_builder.prompt", "llm.messages") pipe.connect("llm.replies", "extractor.text_or_messages") messages = [ ChatMessage.from_system( "Respond using this exact format:\n" "<analysis>Your detailed analysis here</analysis>\n" "<summary>A one-sentence summary</summary>", ), ChatMessage.from_user("What are the main benefits and drawbacks of remote work?"), ] result = pipe.run({"prompt_builder": {"template": messages}}) print(result["extractor"]["captured_text"])

注意pipe.connect("llm.replies", "extractor.text_or_messages")把 LLM 的回复列表直接接到提取器输入，提取器会自动只取最后一条消息。

5.4 版本差异与序列化兼容

2.22 用户指南曾描述过一个已废弃的return_empty_on_no_match参数（旧行为：无匹配时返回空字典{}）。在参考 API 文档与当前源码中，该参数已被移除：无匹配时统一返回{"captured_text": ""}。为保证旧 Pipeline 反序列化不中断，from_dict会识别并忽略残留的return_empty_on_no_match参数并打印警告（见 regex_text_extractor.py#L70-L85）。序列化方面，to_dict/from_dict只保存regex_pattern一个初始化参数。该组件的字符串、消息列表、空列表、无捕获组等分支均有测试覆盖，见 test/components/extractors/test_regex_text_extractor.py。

六、小结与选型建议

四个组件都遵循 Haystack 的组件规范：以@component装饰、声明output_types、实现to_dict/from_dict可序列化、warm_up预热、run运行，并（LLM 系组件）提供run_async异步入口。LLM 系组件普遍采用"成功文档 + 失败文档"双输出设计，配合raise_on_failure与失败元数据键（extraction_error/metadata_extraction_error、metadata_extraction_response），可以在生产索引链路中做到"失败不阻断、事后可重跑"。更多组合用法可参考 2.22 用户指南的 extractors.mdx 及各组件独立页面（llmdocumentcontentextractor.mdx、llmmetadataextractor.mdx、namedentityextractor.mdx、regextextextractor.mdx）。

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