ARTICLE DETAIL

资讯详情

深耕编程入门与网站建设的一线实战洞察。

Haystack HanLP 集成:ChineseDocumentSplitter 中文文档切分组件 API 详解与实战

Haystack HanLP 集成:ChineseDocumentSplitter 中文文档切分组件 API 详解与实战 Haystack HanLP 集成ChineseDocumentSplitter 中文文档切分组件 API 详解与实战【免费下载链接】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 的 HanLP 集成组件ChineseDocumentSplitter展开完整讲解其全部构造参数、split_by七种切分模式、run/warm_up/chinese_sentence_split/to_dict/from_dict等 API并结合主仓库中的DocumentSplitter源码剖析其底层切分机制。读完后你将掌握如何在 Haystack 索引流水线中完成对中文文本的语言学感知切分word segmentation sentence tokenization如何控制split_length/split_overlap/split_threshold与句子边界以及如何将切分结果写入 Document Store。为什么中文切分不能照搬英文逻辑Haystack 官方 API 参考文档hanlp.md对该组件的定位是A DocumentSplitter for Chinese text.它首先解释了与英文切分的本质差异英文单词通常以空格分隔而中文文本是连续书写的词与词之间没有空格一个中文“词”可以由多个汉字构成。文档给出的例子是英文单词 America 译为中文“美国”由两个字符组成但作为一个词处理Portugal 译为“葡萄牙”三个字符仍是一个词。因此split_byword的含义是按这些多字符词元token切分而不是按单个字符或空格切分——这正是必须引入 HanLPHan Language Processing分词模型的原因。组件支持两种分词粒度granularity这是 HanLP 集成区别于核心库DocumentSplitter的关键能力coarse粗粒度分词适用于大多数通用场景默认值fine细粒度分词适用于需要更细切分粒度的专用场景。如果传入的值既不是coarse也不是fine构造时抛出ValueError。说明HanLP 集成是 Haystack 的独立集成包安装路径为haystack_integrations.components.preprocessors.hanlp包名为hanlp-haystack参见 中文组件文档。该组件源码位于独立的 haystack-core-integrations 仓库本仓库不直接包含其实现下文涉及其内部模型细节的内容均来自仓库内官方文档。快速上手独立使用组件API 参考文档给出的最小用法示例原文档 Usage example 完整继承from haystack import Document from haystack_integrations.components.preprocessors.hanlp import ChineseDocumentSplitter doc Document(content 这是第一句话这是第二句话这是第三句话。 这是第四句话这是第五句话这是第六句话 这是第七句话这是第八句话这是第九句话 ) splitter ChineseDocumentSplitter( split_byword, split_length10, split_overlap3, respect_sentence_boundaryTrue ) result splitter.run(documents[doc]) print(result[documents])要点输入是list[Document]通过run(documents[doc])调用输出是dict键为documents值是切分后的Document列表中文分词模型属于重资源文档为此专门提供了warm_up()方法见下文 API 说明在生产环境中建议显式调用以把模型加载成本前置到启动阶段。组件文档chinesedocumentsplitter.mdx还给出了三种典型变体配置按句子边界切分respect_sentence_boundaryTrue使每个 chunk 都在完整句子处结束细粒度分词granularityfine配合较小的split_length自定义切分函数split_byfunction并传入splitting_function例如按中文逗号切分def custom_split(text: str) - list[str]: 按中文逗号切分 return text.split() doc Document(content第一段第二段第三段第四段) splitter ChineseDocumentSplitter(split_byfunction, splitting_functioncustom_split) result splitter.run(documents[doc]) print(result[documents])__init__完整参数参考以下是 API 参考文档中ChineseDocumentSplitter.__init__的完整签名与参数说明__init__( split_by: Literal[word, sentence, passage, page, line, period, function] word, split_length: int 1000, split_overlap: int 200, split_threshold: int 0, respect_sentence_boundary: bool False, splitting_function: Callable | None None, granularity: Literal[coarse, fine] coarse, ) - None参数类型默认值说明split_byLiteral[word, sentence, passage, page, line, period, function]word切分单元见下表split_lengthint1000每个 split 中允许的最大单元数split_overlapint200相邻 split 之间的重叠单元数split_thresholdint0每个 split 的最小单元数不足阈值的 split 会被合并到前一个 splitrespect_sentence_boundaryboolFalse按word切分时是否尊重句子边界为True时使用 HanLP 检测句子边界保证切分只发生在句子之间splitting_functionCallable \| NoneNone当split_byfunction时必填接收单个str并返回list[str]代表切分后的 chunkgranularityLiteral[coarse, fine]coarse中文分词粒度coarse或fine非法值抛ValueErrorsplit_by各取值对应的切分逻辑取值切分方式word按中文词切分粗/细粒度分词模型产出的多字符词元sentence使用 HanLP 句子分词器按句切分passage按双换行\n\n切分page按换页符\f切分line按单换行\n切分period按句点.切分function使用自定义splitting_function从配套组件文档chinesedocumentsplitter.mdx可以进一步了解到各模式背后的 HanLP 模型分工粗粒度分词使用COARSE_ELECTRA_SMALL_ZH模型细粒度分词使用FINE_ELECTRA_SMALL_ZH模型而respect_sentence_boundaryTrue时使用 HanLP 的句末标点分词器UD_CTB_EOS_MUL检测句子边界确保切分只发生在完整句子之间保留文本的语义完整性。方法 API 详解runrun(documents: list[Document]) - dict[str, list[Document]]将文档列表切分为更小的 chunk。入参documents—— 待切分的Document列表返回dict[str, list[Document]]即{documents: [...]}异常若中文分词模型尚未加载抛出RuntimeError。每个切分产物会继承原始文档的 metadata并附加以下追踪字段与 Haystack 核心切分器的行为一致source_id原始文档的 IDpage_numberchunk 所属页码split_idchunk 在该文档内的顺序编号split_idx_startchunk 在原文中的起始索引。这套元数据机制在本仓库的核心实现中可以完整对照document_splitter.py 中_create_docs_from_splits约 L427-L456负责生成page_number、split_id、split_idx_start字段_split_by_*系列方法在 metadata 中写入source_id。warm_upwarm_up() - None预热组件加载必要的 HanLP 模型。由于中文分词模型体积较大在流水线冷启动时显式调用warm_up()可以把加载延迟从首次run挪到初始化阶段避免第一次请求超时。chinese_sentence_splitchinese_sentence_split(text: str) - list[dict[str, Any]]将中文文本切分为句子入参为字符串text返回句子字典列表。它是内部respect_sentence_boundary逻辑所依赖的句级切分能力单独暴露出来也便于在切分前做句子级预处理或调试。to_dict / from_dictto_dict() - dict[str, Any] from_dict(data: dict[str, Any]) - ChineseDocumentSplitter序列化为字典 / 从字典反序列化遵循 Haystack 组件的标准序列化协议。这意味着ChineseDocumentSplitter可以像其他组件一样被嵌入Pipeline后通过pipeline.dumps()/Pipeline.loads()整体保存与恢复。核心库中对应的实现可参考 document_splitter.py 的to_dict/from_dict其中splitting_function会经由serialize_callable/deserialize_callable做可调用对象序列化。底层切分机制对照核心库 DocumentSplitter 源码ChineseDocumentSplitter的参数体系与 Haystack 核心库的 DocumentSplitter 高度同构借助后者源码可以理解各参数的真实行为。参数校验。核心DocumentSplitter._init_checksdocument_splitter.py展示了同类切分器的通用校验规则split_by必须在合法枚举内split_byfunction时必须提供splitting_functionsplit_length 0split_overlap 0且split_overlap split_length。ChineseDocumentSplitter在此基础上额外校验granularity必须为coarse/fine否则抛ValueError。单元合并与重叠窗口。_concatenate_unitsdocument_splitter.py揭示了split_length/split_overlap/split_threshold的协作方式使用滑动窗口步长 split_length - split_overlap把切分单元依次聚合成 chunk当某个窗口内的单元数小于split_threshold且已有前序 chunk 时不新建 chunk而是把该窗口中超出重叠部分的单元追加到上一个 chunk——这就是split_threshold的“防止碎片 chunk”语义同时按\f统计页码增量维护page_number元数据。句子边界模式。当respect_sentence_boundaryTrue且按词切分时核心实现走_concatenate_sentences_based_on_word_amountdocument_splitter.py先把句子逐句累加当“当前 chunk 词数 下一句词数”将超过split_length时才截断开新 chunk保证每个 chunk 以完整句子结尾随后_number_of_sentences_to_keep反向挑选需要带进下一 chunk 的“重叠句子”数量使重叠以整句为单位发生。ChineseDocumentSplitter中的句子来源换成 HanLP 分词器UD_CTB_EOS_MUL但“整句截断 整句重叠”的策略一致——这正是中文场景下split_overlap33 个词这类小重叠值仍然可用的原因重叠会向上取整到完整句子。切分单元与分隔符映射。核心库用一张映射表定义非词类切分document_splitter.py_CHARACTER_SPLIT_BY_MAPPING {page: \f, passage: \n\n, period: ., word: , line: \n}在核心库中word对应空格这是英文假设而ChineseDocumentSplitter将word单元替换为 HanLP 分词模型产出的多字符词元sentence单元替换为 HanLP 句法切分——参数名相同、语义被本地化这正是该集成组件存在的意义。重叠元数据。当split_overlap 0时核心库还通过_add_split_overlap_informationdocument_splitter.py在相邻 chunk 的meta[_split_overlap]中互相登记doc_id与重叠range供 AutoMergingRetriever 等下游组件做重叠合并检索。HanLP 集成文档虽未详述该字段但从参数设计的一致性可以推断其行为与核心切分器对齐。在索引流水线中使用组件文档推荐的典型位置是索引流水线中位于 Converter 和 DocumentCleaner 之后、分类/嵌入之前。完整流水线示例继承自 chinesedocumentsplitter.mdxfrom haystack import Pipeline, Document from haystack.document_stores.in_memory import InMemoryDocumentStore from haystack.components.converters.txt import TextFileToDocument from haystack_integrations.components.preprocessors.hanlp import ChineseDocumentSplitter from haystack.components.preprocessors import DocumentCleaner from haystack.components.writers import DocumentWriter document_store InMemoryDocumentStore() p Pipeline() p.add_component(instanceTextFileToDocument(), nametext_file_converter) p.add_component(instanceDocumentCleaner(), namecleaner) p.add_component( instanceChineseDocumentSplitter( split_byword, split_length100, split_overlap20, respect_sentence_boundaryTrue, granularitycoarse, ), namechinese_splitter, ) p.add_component(instanceDocumentWriter(document_storedocument_store), namewriter) p.connect(text_file_converter.documents, cleaner.documents) p.connect(cleaner.documents, chinese_splitter.documents) p.connect(chinese_splitter.documents, writer.documents) p.run({text_file_converter: {sources: [path/to/your/chinese/files.txt]}})该流水线的处理路径为文本文件 → Document → 清洗 → 中文语言学感知切分 → 写入 Document Store供后续 Embedding 与检索使用。选型与使用建议综合 API 参考与组件文档可以给出如下实践指引均以仓库文档与源码为依据语言匹配中文语料优先使用ChineseDocumentSplitter纯英文语料使用核心库 DocumentSplitter 更轻无额外模型依赖。若语料中英混排需要评估哪种分词器对整体召回更友好可结合split_bysentence降低语言差异影响。默认值偏大split_length1000、split_overlap200是面向长文档的默认值对于以句为单位的小样本如 API 文档中的九句话示例示例采用split_length10, split_overlap3以便观察切分效果。碎片抑制文档尾部常出现远小于split_length的残留 chunk可将split_threshold设为一个较小正整数如 5~10 词让残留片段并入上一个 chunk。语义完整性面向 RAG 检索的中文语料建议开启respect_sentence_boundaryTrue让每个 chunk 以完整句子收尾减少句子被拦腰截断带来的语义损失。资源管理粗/细粒度模型COARSE_ELECTRA_SMALL_ZH/FINE_ELECTRA_SMALL_ZH需在warm_up()时下载/加载若分词模型未加载即调用run会抛RuntimeError部署时应确保运行环境可访问模型源并预留加载时间。参考文档的版本说明HanLP 集成 API 参考在 version-2.18 至 version-3.1 各版本间内容一致逐版文件比对结果相同说明该组件 API 在 Haystack 2.x 至 3.x 期间保持稳定本文以 version-2.21 参考文档 为准。【免费下载链接】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),仅供参考
返回列表