1. 项目概述与核心价值最近在折腾一些个人项目需要处理大量非结构化文本数据比如从网页上爬下来的文章、PDF文档或者聊天记录。我的需求很简单把这些文本切分成有意义的片段方便后续做向量化处理然后扔进向量数据库里做语义搜索或者RAG应用。一开始我随手用了几个现成的文本分割器结果发现效果差强人意——要么是把一篇完整的文章切得支离破碎上下文全丢了要么是切出来的片段长度不一导致后续向量化的效果很不稳定。就在我为此头疼的时候一个叫axiarch的开源项目进入了我的视野。这个项目在GitHub上由开发者hiroyuki-miyauchi维护它不是一个功能庞杂的大框架而是精准地聚焦于解决“文本分块”这个看似简单、实则暗藏玄机的问题。axiarch这个名字听起来有点哲学意味但它的目标非常务实提供一个高效、灵活且高质量的文本分割工具。经过一番研究和实际使用我发现它确实解决了我遇到的几个核心痛点比如如何保持语义连贯性、如何处理不同语言和格式的文本、以及如何通过精细的参数控制来适配不同的下游任务。简单来说axiarch就是一个专门用于文本分块的Python库。它特别适合那些需要构建文档处理流水线、开发基于检索的生成式应用RAG或者任何需要对长文本进行智能切分的场景。如果你也在为文本预处理的质量和一致性发愁那么花点时间了解一下axiarch可能会让你的工作流顺畅不少。2. 文本分块的挑战与axiarch的设计哲学2.1 为什么简单的分割器不够用在深入axiarch之前我们先聊聊为什么不能随便用split(‘\n’)或者按固定字符数切割。文本分块的核心目标是在“信息完整性”和“计算效率”之间取得平衡。一个糟糕的分块策略会直接毁掉下游任务的效果。挑战一语义断裂。这是最常见的问题。比如一个复杂的句子刚好在规定的字符数限制处被拦腰截断。“由于天气原因明天的户外活动……”如果在这里被切断后半句“将被取消”就丢失了。对于依赖上下文理解的模型如嵌入模型或大语言模型来说这个前半段片段的意义是不完整甚至是被扭曲的。挑战二格式多样性。文本来源五花八门Markdown文档有标题和代码块PDF有分页符网页HTML包含各种标签中文和英文的断句逻辑也完全不同。一个通用的分割器需要能识别并妥善处理这些结构而不是把它们都当成普通文本来一刀切。挑战三下游任务适配。不同的应用对分块有不同的要求。做语义搜索时我们可能希望每个块包含一个完整的观点或事实块可以稍大一些。而在某些RAG场景中为了更精准地检索可能需要更小、更聚焦的块。分块的大小、重叠区域overlap的设置都需要可调。2.2axiarch的解决思路基于分隔符与规则的层级分割axiarch没有采用复杂的机器学习模型来进行分块而是选择了一条更轻量、更可控、也更容易理解的路径基于分隔符的递归分割。它的设计哲学可以概括为“分而治之层层细化”。优先级分隔符列表axiarch内部定义了一个分隔符优先级列表。例如它会优先尝试按“\n\n”双换行通常代表段落结束进行分割。如果分割后的块仍然太大它会降级到下一个优先级的分隔符比如“\n”单换行、“。”句号、“ ”空格等。递归应用这个过程是递归的。对于一个长文本先尝试用最高优先级的分隔符切分。检查每个切分后的子块如果某个子块的长度仍然超过设定的chunk_size就对这个子块再次应用下一优先级的分隔符进行分割如此往复。尊重原生结构通过将段落分隔符\n\n、标题符如Markdown的#、列表符-、*等置于高优先级axiarch在分割时会首先尊重文档原有的逻辑结构尽可能让一个块保持在一个段落或一个列表项内。灵活的参数控制核心参数就几个chunk_size目标块大小、chunk_overlap块间重叠字符数、separators自定义分隔符列表。通过调整它们你可以轻松适配从技术文档到文学小说的各种文本类型。这种方法的优势非常明显速度快、可解释性强、结果稳定。你完全能预测和理解它是如何把一篇文章切开的这对于调试和优化流水线至关重要。相比之下一个黑盒模型如果切分效果不好你很难知道该如何调整。3.axiarch核心功能与实操要点3.1 安装与极简入门安装过程毫无波澜直接使用pip即可。建议在虚拟环境中操作。pip install axiarch安装完成后一个最简单的使用示例如下from axiarch import TextSplitter # 初始化一个文本分割器目标块大小500字符重叠50字符 splitter TextSplitter(chunk_size500, chunk_overlap50) # 你的长文本 long_text “”” 这里是你的很长很长的文本内容。它可能包含多个段落。 这是第二个段落。我们需要把它智能地切分开。 “”” # 执行分割 chunks splitter.split_text(long_text) # 打印结果 for i, chunk in enumerate(chunks): print(f“Chunk {i1} (长度: {len(chunk)}):\n{chunk}\n{‘-’*40}“)执行上述代码axiarch会尝试将long_text切分成若干个长度接近500字符的文本块并且相邻块之间会有大约50字符的重叠以确保上下文信息不会在边界处完全丢失。3.2 关键参数深度解析TextSplitter的构造函数有几个关键参数理解它们是用好这个库的关键。chunk_size: int这是目标块大小的上限单位是字符数。axiarch会努力让每个块的大小不超过这个值但并不保证绝对精确。因为分割必须发生在分隔符处所以最终块的尺寸可能会略小于chunk_size。这是一个非常重要的预期管理它不是硬性截断而是基于语义的软约束。注意这里的“字符数”对于英文就是字母数对于中文就是汉字数。如果你在处理混合语言文本需要留意中英文字符在宽度上的差异不过对于大多数嵌入模型按字符数计算是一个合理的近似。chunk_overlap: int块与块之间重叠的字符数。设置重叠是为了解决“边界效应”。一个关键信息如果刚好落在两个块的连接处没有重叠的话就可能被割裂导致任何一块都无法完整表征该信息。重叠部分像一个“缓冲区”确保了信息的连续性。实操心得overlap的值通常设置为chunk_size的10%-20%。例如chunk_size500时overlap设为50-100是个不错的起点。设置太小可能效果不彰设置太大则会产生大量冗余增加存储和计算成本。需要根据具体文本的语义密度进行调整。separators: List[str]这是axiarch的灵魂参数。它定义了用于分割文本的分隔符列表顺序代表优先级。默认的分隔符列表是经过精心设计的通常类似于[“\n\n”, “\n”, “。”, “.”, “,”, “ “, “”]。你可以完全覆盖这个列表。例如如果你处理的是纯技术代码注释可能将“#”或“//”加入高优先级。空字符串“”通常放在最后作为一个“保底”分隔符意味着如果所有其他分隔符都无法在限制内完成分割则按单个字符切割。这确保了函数总能返回结果。keep_separator: bool决定分割后分隔符本身是保留在上一块的末尾还是下一块的开头或是直接丢弃。默认行为通常是保留这对于维持某些语法结构如句号的完整性是有益的。3.3 处理复杂文档结构axiarch的基础TextSplitter是面向纯文本的。但在实际中我们更常处理的是带有丰富格式的文档。为此社区和最佳实践通常会结合其他工具先进行“解构”然后再用axiarch进行“分块”。一个常见的流水线是文档加载使用langchain的DocumentLoader、pypdf、markdown等库将 PDF、Word、Markdown、HTML 文件转换成纯文本并尽可能保留元数据如来源、标题。文本清洗去除无关的页眉页脚、过多的换行符、乱码等。分块使用axiarch的TextSplitter对清洗后的文本进行智能分块。块封装为每个文本块附加元数据如原始文档ID、章节标题、页码等形成结构化的“文档块”对象供下游向量化使用。下面是一个处理Markdown文档的示例import markdown from bs4 import BeautifulSoup from axiarch import TextSplitter def split_markdown_file(md_file_path, chunk_size1000, chunk_overlap200): # 1. 读取Markdown文件 with open(md_file_path, ‘r’, encoding‘utf-8’) as f: md_text f.read() # 2. 将Markdown转换为HTML再提取纯文本这样可以去除标记保留段落结构 html markdown.markdown(md_text) soup BeautifulSoup(html, ‘html.parser’) plain_text soup.get_text(separator‘\n\n’) # 用双换行保留段落感 # 3. 使用 axiarch 进行分块 # 针对Markdown我们可以微调分隔符例如优先按标题分割但上一步已提取文本这里用默认即可 splitter TextSplitter(chunk_sizechunk_size, chunk_overlapchunk_overlap) chunks splitter.split_text(plain_text) # 4. 组装结果这里简单返回实际可附加更多元数据 return [{“text”: chunk, “source”: md_file_path} for chunk in chunks] # 使用函数 document_chunks split_markdown_file(“your_document.md”)对于PDF流程类似只是第一步需要使用像PyPDF2或pdfplumber这样的库来提取文本提取时要注意PDF本身可能分栏、图文混排带来的挑战。4. 在RAG流水线中的集成实践检索增强生成RAG是目前axiarch最典型的应用场景。分块质量直接决定了检索质量进而影响最终生成答案的准确性。4.1 与向量数据库的搭配一个标准的RAG前置流程如下from axiarch import TextSplitter from langchain.embeddings import OpenAIEmbeddings # 或其他嵌入模型 from langchain.vectorstores import Chroma # 或其他向量数据库 from langchain.document_loaders import TextLoader # 1. 加载文档 loader TextLoader(“data/sample.txt”) documents loader.load() # 2. 初始化文本分割器 text_splitter TextSplitter(chunk_size1000, chunk_overlap200) # 3. 分割文档 split_docs text_splitter.split_documents(documents) # 注意这里假设使用LangChain的Document对象 # 如果直接用axiarch的 split_text需要手动构建Document列表 # texts text_splitter.split_text(full_text) # split_docs [Document(page_contentt) for t in texts] # 4. 生成嵌入并存入向量数据库 embeddings OpenAIEmbeddings() vectorstore Chroma.from_documents(documentssplit_docs, embeddingembeddings, persist_directory“./chroma_db”) vectorstore.persist()在这个流程中axiarch的split_documents方法如果与LangChain深度集成或split_text方法承担了承上启下的关键角色。4.2 分块策略对RAG效果的影响实验为了找到最优的分块参数我设计了一个简单的实验这在实际项目中非常值得一做。实验设置数据源同一份技术文档。分块方案方案Achunk_size500, overlap50小块低重叠方案Bchunk_size1000, overlap100中块中重叠方案Cchunk_size2000, overlap300大块高重叠评估方式针对一组预设的问题使用相同的检索器如向量数据库的相似性搜索和相同的LLM生成答案。人工评估答案的准确性和引用块的相关性。实验结果与心得分块方案优点缺点适用场景A (小块)检索精度高答案容易定位到具体细节。上下文信息可能不足LLM可能因缺乏足够背景而胡编乱造检索出的块多需要LLM整合的信息也多。文档结构清晰、事实点分散的场景如FAQ、知识条目。B (中块)在精度和上下文丰富度之间取得较好平衡。最通用的选择。对于特别复杂或浓缩的文本可能仍显不足。大多数技术文档、维基百科文章、报告。C (大块)上下文最完整LLM生成答案的信息基础最扎实。检索精度下降可能引入无关信息向量化计算和存储成本更高。需要强逻辑连贯性的文本如论文、法律条文、叙事性内容。核心建议没有放之四海而皆准的“最佳参数”。务必用你的实际数据和查询进行测试。可以从方案B开始如果发现答案遗漏关键细节尝试减小chunk_size如果发现答案缺乏连贯性或经常“幻觉”尝试增大chunk_size或overlap。5. 高级技巧与常见问题排查5.1 自定义分隔符策略axiarch的灵活性很大程度上体现在separators参数上。以下是一些高级用法处理特定领域文本处理代码时可以加入“\ndef “, “\nclass “, “\n# “作为高优先级分隔符力求按函数或类进行分块。code_separators [“\n\n”, “\ndef “, “\nclass “, “\n# “, “\n”, “ “, “”] splitter TextSplitter(chunk_size800, separatorscode_separators)处理多语言文本中英文混合时确保分隔符列表包含两种语言的标点。multilingual_separators [“\n\n”, “\n”, “。”, “.”, “”, “;”, “”, “,”, “ “, “”]保留特定标记如果你不希望在某些标记处被分割比如一个特定的XML标签就不要把它放入分隔符列表。或者在分割前先进行预处理将这些标记替换为临时占位符分割后再恢复。5.2 性能优化与边界情况处理大文件处理对于非常大的单个文本文件如整本书一次性加载到内存可能压力较大。axiarch本身是处理字符串的所以上游的加载步骤需要考虑流式读取或分片读取。一个模式是先按超大粒度如“\n\n\n”预分割再对每个部分用axiarch精细分割。极短文本如果输入文本本身就小于chunk_sizeaxiarch会将其作为一个整体返回。这是符合预期的行为。分隔符无效如果提供的分隔符在文本中完全不存在且chunk_size小于文本长度分割器会一路降级到最后的分隔符如空字符串进行单字符分割这通常不是想要的结果。务必检查你的分隔符列表是否适合当前文本。5.3 常见问题速查表问题现象可能原因解决方案切分出的块远大于chunk_size文本中不存在分隔符列表中的任何字符导致无法分割。检查文本内容调整separators列表加入文本中实际存在的分隔符。切分后的块数量极少且块很大chunk_size设置过大。根据下游模型如嵌入模型的上下文窗口合理减小chunk_size。检索时找不到准确信息块太大信息不聚焦或者overlap太小边界信息丢失。减小chunk_size或适当增加chunk_overlap。相邻块内容几乎完全一样chunk_overlap设置得过大超过了块本身有意义的范围。减少chunk_overlap的比例通常10%-20%足矣。分块破坏了代码或公式结构默认分隔符不适合结构化内容。预处理时先将代码块、公式等用特殊标记包裹保护起来分割后再替换回来。或使用专门针对代码的分割器。处理速度慢文本极长且分隔符优先级策略导致多次递归尝试。考虑是否可以先按更高阶的结构如章节进行粗分再对每个部分精细分块。5.4 一个综合实战案例构建知识库助手假设我们要为一个产品手册构建一个问答助手。数据准备收集所有PDF和Markdown格式的产品手册。提取与清洗使用pdfplumber和markdown库提取文本并清洗掉页码、无意义的页眉页脚。智能分块from axiarch import TextSplitter # 产品手册通常段落清晰但包含图表说明。我们采用中等块大小并优先保证段落完整。 splitter TextSplitter( chunk_size1200, chunk_overlap150, separators[“\n\n”, “\n”, “。”, “.”, “”, “;”, “ “, “”] # 中英文标点兼顾 ) all_chunks [] for doc_text in cleaned_texts: chunks splitter.split_text(doc_text) all_chunks.extend(chunks)向量化与存储使用text-embedding-3-small等嵌入模型生成向量存入Chroma或Qdrant数据库。查询测试提出如“如何解决产品X的错误代码E05”的问题。检索器会找到相关的文本块由LLM合成答案。迭代优化根据初期测试答案的质量回头调整分块的size和overlap。例如如果发现答案总是引用不完整的步骤可能就需要减小块大小让每个块只包含1-2个操作步骤。在整个过程中axiarch扮演了一个可靠、透明的“文本裁缝”角色。它可能不是功能最多、名气最大的那个库但它在自己专注的领域——文本分块——做得足够好设计简洁易于集成和调试。对于需要稳定、可控文本预处理流程的开发者来说它是一个非常值得放入工具箱的选择。我的体会是在构建基于文本的AI应用时前期在数据预处理包括分块上多花一小时精心调试往往比后期在模型或检索算法上折腾几天带来的效果提升更显著。axiarch提供的正是这种精细控制的能力。