Haystack 2.x Classifiers 组件详解DocumentLanguageClassifier 与 TransformersZeroShotDocumentClassifier【免费下载链接】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 仓库中 version-2.21 的 Classifiers API 参考文档docs-website/reference_versioned_docs/version-2.21/haystack-api/classifiers_api.md系统讲解 2.21 时期haystack.components.classifiers包下的两个文档分类组件基于langdetect的DocumentLanguageClassifier与基于 Hugging Face 零样本分类管线zero-shot-classification的TransformersZeroShotDocumentClassifier。读完后你将能够在自己的 Pipeline 中为文档自动标注语言元数据并配合MetadataRouter分流以及使用 NLI 模型对文档内容做免训练的标签分类把预测结果写入文档 metadata 供下游路由或筛选。Classifiers 在 Haystack 2.x 组件体系中的定位Haystack 2.x 对分类与路由做了明确区分Classifier 负责改变文档的 metadata 值如语言、标签但不改变数据的流向把数据分流到多个下游组件是 Router 的职责。这一点有明确的演进记录仓库中的 separate-classifiers-from-routers 发布说明 记载了从 DocumentLanguageClassifier 中移除路由功能、将 TextLanguageClassifier 更名为 TextLanguageRouter的变更并指出在 Haystack 2.x 中Classifiers 会改变 metadata 值但不将输入路由到多个输出后者保留给 routers还建议在索引管线中把DocumentLanguageClassifier与MetadataRouter组合使用来完成分类 路由。而 move-classifiers 发布说明 则记录了文本/文档语言分类组件从 routers 包迁移进 classifiers 包的历史。这一设计决定了本文两个组件的共同使用模式分类器只贴标签写 metadata路由由独立的 Router 组件完成。DocumentLanguageClassifier为文档标注语言元数据DocumentLanguageClassifier会对每个文档进行语言识别并把识别结果写进文档 metadata。初始化时传入候选语言列表如果文档文本与所有指定语言都不匹配metadata 值会被设为unmatched。要对文档按语言分流需要在分类器之后接MetadataRouter而要对纯文本非 Document 对象路由则应改用TextLanguageRouter组件。完整用法示例下面这个示例构建了一条语言分类 → 按元数据路由 → 写入文档存储的索引管线只有英文文档会被写入InMemoryDocumentStorefrom haystack import Document, Pipeline from haystack.document_stores.in_memory import InMemoryDocumentStore from haystack.components.classifiers import DocumentLanguageClassifier from haystack.components.routers import MetadataRouter from haystack.components.writers import DocumentWriter docs [Document(id1, contentThis is an English document), Document(id2, contentEste es un documento en español)] document_store InMemoryDocumentStore() p Pipeline() p.add_component(instanceDocumentLanguageClassifier(languages[en]), namelanguage_classifier) p.add_component(instanceMetadataRouter(rules{en: {language: {$eq: en}}}), namerouter) p.add_component(instanceDocumentWriter(document_storedocument_store), namewriter) p.connect(language_classifier.documents, router.documents) p.connect(router.en, writer.documents) p.run({language_classifier: {documents: docs}}) written_docs document_store.filter_documents() assert len(written_docs) 1 assert written_docs[0] Document(id1, contentThis is an English document, meta{language: en})几个关键点值得注意DocumentLanguageClassifier(languages[en])只识别英文示例中的西班牙语文档不会被丢弃而是被标记为meta{language: unmatched}走不到en路由分支MetadataRouter的规则语法为{路由名: {metadata字段: 过滤表达式}}上例中en: {language: {$eq: en}}表示当文档meta里的language字段等于en时从router.en输出 socket 放行分类器的输出 socket 固定为documentslist[Document]与路由器的documents输入直接相连。构造函数参数def __init__(languages: Optional[list[str]] None)参数类型默认值说明languageslist[str]None等价于[en]ISO 语言代码列表支持的具体语言以langdetect库的说明为准文档内容与列表均不匹配时标记为unmatched底层实现依赖langdetect库做统计式语言识别无需下载模型或调用外部 API适合对多语言混合语料做粗粒度语言分拣。run 方法component.output_types(documentslist[Document]) def run(documents: list[Document])输入documents—— 待做语言分类的文档列表输出documents—— 每个文档的 metadata 中新增language字段的文档列表异常输入不是Document列表时抛出TypeError。分类结果只写 metadata、不改写content因此该组件可以安全地放在索引管线的前置阶段供后续的过滤器、路由器和写入器使用。TransformersZeroShotDocumentClassifier基于 Hugging Face 的零样本文档分类TransformersZeroShotDocumentClassifier使用 Hugging Face 的 zero-shot-classification 管线底层是 NLI自然语言推理模型对文档做零样本分类无需针对标签做训练只需在初始化时给出model和labels预测出的标签会写入文档 metadata 的classification字段。分类默认作用于文档的content字段也可以通过classification_field参数改到某个 metadata 字段上执行。文档中列出的、可用于该任务的候选模型包括valhalla/distilbart-mnli-12-3cross-encoder/nli-distilroberta-basecross-encoder/nli-deberta-v3-xsmall完整可选模型列表可参考 Hugging Face 模型库中 pipeline_tag 为 zero-shot-classification 的 NLI 类模型。完整用法示例下面这条管线演示了BM25 检索 → 零样本情感分类的组合两条文档一条表达积极的一天、一条表达消极的一天cross-encoder/nli-deberta-v3-xsmall模型配合[positive, negative]标签对检索结果自动打标签from haystack import Document from haystack.components.retrievers.in_memory import InMemoryBM25Retriever from haystack.document_stores.in_memory import InMemoryDocumentStore from haystack.core.pipeline import Pipeline from haystack.components.classifiers import TransformersZeroShotDocumentClassifier documents [Document(id0, contentToday was a nice day!), Document(id1, contentYesterday was a bad day!)] document_store InMemoryDocumentStore() retriever InMemoryBM25Retriever(document_storedocument_store) document_classifier TransformersZeroShotDocumentClassifier( modelcross-encoder/nli-deberta-v3-xsmall, labels[positive, negative], ) document_store.write_documents(documents) pipeline Pipeline() pipeline.add_component(instanceretriever, nameretriever) pipeline.add_component(instancedocument_classifier, namedocument_classifier) pipeline.connect(retriever, document_classifier) queries [How was your day today?, How was your day yesterday?] expected_predictions [positive, negative] for idx, query in enumerate(queries): result pipeline.run({retriever: {query: query, top_k: 1}}) assert result[document_classifier][documents][0].to_dict()[id] str(idx) assert (result[document_classifier][documents][0].to_dict()[classification][label] expected_predictions[idx])这个例子的要点分类器直接消费检索器的输出文档pipeline.connect(retriever, document_classifier)自动完成 socket 匹配分类结果存放在document.to_dict()[classification]中其中label键就是预测出的标签该模型需要本地下载并加载属于较重的组件batch_size默认值为 1处理大批量文档时建议显式调大。构造函数参数def __init__(model: str, labels: list[str], multi_label: bool False, classification_field: Optional[str] None, device: Optional[ComponentDevice] None, token: Optional[Secret] Secret.from_env_var( [HF_API_TOKEN, HF_TOKEN], strictFalse), huggingface_pipeline_kwargs: Optional[dict[str, Any]] None)参数类型默认值说明modelstr必填Hugging Face 上零样本文档分类模型NLI 模型的名称或本地路径labelslist[str]必填候选标签集合例如[positive, negative]标签语义依赖所选模型的能力multi_labelboolFalse是否允许多个标签同时为真。False时对分数做归一化使每个序列的标签似然之和为 1True时各标签相互独立对每个候选做蕴含分 vs 矛盾分的 softmax 归一化classification_fieldstrNone用于分类的文档 metadata 字段名不设置时默认使用Document.contentdeviceComponentDeviceNone模型加载设备为None时自动选择默认设备。若huggingface_pipeline_kwargs中指定了 device/device map则以后者为准tokenSecret从环境变量HF_API_TOKEN或HF_TOKEN读取非强制访问 Hugging Face 的 HTTP Bearer 认证令牌可在 HF 账户设置中查看huggingface_pipeline_kwargsdict[str, Any]None透传给 Hugging Face 文本分类管线构造函数的关键字参数可用于控制模型加载行为其余方法与 run 行为warm_up()在管线运行时初始化组件加载模型to_dict()/from_dict(data)组件的序列化与反序列化支持把组件配置持久化进 Pipeline 的 YAML/JSON 表示runcomponent.output_types(documentslist[Document]) def run(documents: list[Document], batch_size: int 1)输入documents待分类文档列表batch_size处理每个文档内容时使用的批大小输出documents—— 每个文档的 metadata 中新增classification字典metadata 结构classification.label存放预测标签当multi_labelTrue时classification.details键下可读取每个候选标签各自的得分便于自定义阈值或做细粒度过滤。由于分类结果写在 metadata 里TransformersZeroShotDocumentClassifier之后可以直接接MetadataRouter或文档过滤器按classification.label将文档分流到不同处理分支实现检索 → 分类 → 分流的完整链路。版本语境与当前仓库状态本文所依据的 API 文档属于version-2.21版本的存档docs-website/reference_versioned_docs/version-2.21/haystack-api/classifiers_api.md描述的是 Haystack 2.21 时期haystack.components.classifiers包内可用的组件。需要说明的是当前仓库主干已经演进到 3.x从 deprecate-langdetect-components 发布说明 和 remove-langdetect-components 发布说明 可以看到基于langdetect的DocumentLanguageClassifier与TextLanguageRouter在 3.0 中被移出 Haystack 核心迁移至独立的langdetect-haystack集成包pip install langdetect-haystack导入路径相应从haystack.components.classifiers变为haystack_integrations.components.classifiers.langdetect在当前仓库的haystack/components/源码目录中也不再包含 classifiers 子包。因此如果你在 2.21 版本上维护既有管线本文的组件名、导入路径与参数签名均可直接沿用若升级到 3.x语言分类部分需切换到集成包而零样本分类组件的参数设计model/labels/multi_label/classification_field/token/huggingface_pipeline_kwargs在参考文档中的语义仍然是理解这类组件的标准范式。小结与延伸阅读两个组件的共同点是只改 metadata、不改变流向语言路由交给MetadataRouter纯文本语言路由交给TextLanguageRouter这符合 Haystack 2.x classifiers 与 routers 的职责划分见 separate-classifiers-from-routers 发布说明DocumentLanguageClassifier轻量、离线、零依赖模型适合多语言语料索引前的语言分拣未命中语言统一落到unmatchedTransformersZeroShotDocumentClassifier以 NLI 零样本分类换取标签灵活性预测标签与逐标签得分分别落在classification.label与classification.details可无缝衔接后续的元数据路由与过滤相关发布历史可参考 add-zero-shot-document-classifier 发布说明 与 document-language-classifier 发布说明原始 API 文档位于 classifiers_api.md。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
