人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆【免费下载链接】voltagentAI Agent Engineering Platform built on an Open Source TypeScript AI Agent Framework项目地址https://gitcode.com/gh_mirrors/vo/voltagent点击查看免费下载本指南围绕 VoltAgent 的voltagent/rag包中面向 LaTeX 源码的格式感知分块器LatexChunker展开先介绍其核心设计目标与快速上手用法再深入源码剖析章节分割算法与元数据构建原理最后讲解maxTokens、tokenizer、label等关键配置并结合StructuredDocument与 auto 策略说明如何在真实 RAG 流水线中使用。读完本文你将掌握如何把\section/\subsection结构的 TeX 文档稳定切分为携带章节上下文的检索块。一、为什么需要专门的 LaTeX 分块器论文、技术手册、教材等文档常以 LaTeX 源码形式存在。这类文本的特点是结构信息章节层级编码在\section{...}、\subsection{...}、\subsubsection{...}等命令中而正文内容散落在各级标题之间。如果直接用通用文本分块器如RecursiveChunker、TokenChunker处理这类内容通常会遇到两个问题章节标题与正文被割裂按段落或 token 切分时标题行可能单独成块检索时无法把某段正文与它所属的章节标题关联起来召回结果的上下文信息丢失元数据缺失分块结果不带heading、sectionType等字段下游做粗粒度过滤例如只检索第 3 章无从下手。LatexChunker正是为弥补这一空白而设计。官方文档对其定位的概括是Splits content on section/subsection commands and chunks section bodies withRecursiveChunker——即先按章节命令切出章节骨架再借用RecursiveChunker对每个章节正文做 token 预算内的递归细分。源码 latex-chunker.ts 中的实现完全印证了这一描述。二、快速上手最小可用示例在官方文档 latex-chunker.md 的基础上直接使用即可import { LatexChunker } from voltagent/rag; const tex \section{Intro} Intro text with context. \subsection{Details} More text inside the subsection. ; const chunks new LatexChunker().chunk(tex, { maxTokens: 120 }); // Output: // [ // { content: Intro text with context., metadata: { sourceType: latex, heading: Intro, sectionType: section } }, // { content: More text inside the subsection., metadata: { sourceType: latex, heading: Details, sectionType: subsection } }, // ]从这个示例可以看到三个关键行为章节命令不出现在正文块中\section{Intro}这行本身被当作分隔符消费掉content只保留标题下的正文层级信息进入元数据每个 chunk 的metadata.heading记录了所属标题文本metadata.sectionType记录了章节层级maxTokens控制每个章节块的大小示例中为120意味着单个章节正文若超过预算会被进一步细分。LatexChunker与RecursiveChunker、MarkdownChunker、HtmlChunker等一起由 index.ts 从voltagent/rag包统一导出无需额外安装任何依赖该包唯一的生产依赖是js-tiktoken用于默认 tokenizer见 package.json。三、章节分割算法源码级剖析LatexChunker的核心逻辑由 latex-chunker.ts 中的splitLatex函数第 1841 行承担它是一个纯文本扫描器不依赖任何 LaTeX 编译环境const regex /\\(section|subsection|subsubsection)\*?\{([^}]*)\}/g;3.1 支持的命令形态正则匹配三类章节命令并支持带星号版本\section*{...}这类命令在 LaTeX 中通常表示不编号的章节\section{标题}\subsection{标题}\subsubsection{标题}以及对应的\section*{标题}等标题文本通过捕获组([^}]*})提取并trim()后存入heading命令类型section/subsection/subsubsection存入kind。3.2 前置内容与尾部内容的归属splitLatex用一个游标记录上次匹配结束位置lastIndex逐段切分文本第一个章节命令之前的内容归入kind: none的隐式节currentHeading为null。这意味着文档开头的前言、摘要等无标题正文不会被丢弃而是作为sectionType: none的块保留最后一个章节命令之后的内容归入最后一个已知标题之下tail分支。因此\section{Intro}之后、\subsection{Details}之前的过渡段落会归属Intro符合阅读直觉空白内容被过滤content为空且无标题的空段不会产生 chunkfilter((s) s.content.length 0 || s.heading)。从源码结构看这种游标切片方案保证了heading、kind、content三者的对应关系始终一致是后续元数据构建正确性的基础。3.3 chunk 主流程chunk方法第 5291 行对每个 section 执行三步用options?.tokenizer ?? this.tokenizer确定 tokenizer用Math.max(1, options?.maxTokens ?? 300)确定 token 预算保证最小值 1防止非法配置将每个 section 的content交给RecursiveChunker按maxTokens细分子块 label 为${label}-section重写每个子块的id为${label}-${idx}-${cidx}idx为章节序号cidx为章节内子块序号并用buildMetadata统一装配元数据。也就是说LatexChunker本身只负责结构感知的粗切正文是否超预算、如何继续细分完全由RecursiveChunker决定。四、Options 配置详解官方文档列出了三个核心选项结合 latex-chunker.ts 中的LatexChunkerOptions类型实际还支持一组文档级元数据选项选项类型默认值说明maxTokensnumber300每个章节块的 token 预算。传入非正值时会被Math.max(1, ...)钳制为1tokenizerTokenizertiktokencl100k_base提供{ tokenize(text), countTokens(text) }接口的计数器用于度量正文 token 数labelstringlatexchunk 的 label 前缀参与生成id与子 chunk labeldocIdstring无文档标识会写入每个 chunk 的metadata.docIdsourceIdstring无来源标识会写入metadata.sourceIdbaseMetadataRecordstring, unknown无自定义元数据合并进每个 chunk 的 metadata4.1 关于 maxTokens 的取值建议maxTokens决定的是章节正文块的 token 上限而非硬性长度。若一个章节正文超出预算RecursiveChunker会继续细分若每个章节正文都远小于预算则一个章节通常产出一个 chunk。实践中建议面向 LLM 检索场景256512是常用区间按所用模型的上下文窗口与检索粒度权衡需要一章节一块的粗粒度场景可将maxTokens调到足够大如2000但不建议超过模型单次检索可容纳的上下文长度。4.2 自定义 tokenizerTokenizer接口定义在 types.tsexport type Tokenizer { tokenize: (text: string) Token[]; countTokens: (text: string) number; };默认 tokenizer 由 tokenizer.ts 的createTikTokenizer()生成底层使用js-tiktoken的cl100k_base编码。RecursiveChunker内部使用tokenizer.countTokens度量段落与句子的 token 数因此自定义 tokenizer 的countTokens行为会直接影响分块粒度。如果希望按具体模型如gpt-4o-mini的编码切分可以这样构造并传入import { LatexChunker, createTikTokenizer } from voltagent/rag; const tokenizer createTikTokenizer({ model: gpt-4o-mini }); const chunker new LatexChunker(tokenizer); // 构造器传入作为全局默认 const chunks chunker.chunk(tex, { maxTokens: 256, tokenizer }); // 每次调用也可覆盖4.3 label 与 chunk id 的生成规则从源码第 6266 行与第 73 行可以确认内部子块 label 为${label}-section例如默认latex-section最终 chunkid为${label}-${idx}-${cidx}例如latex-0-0、latex-0-1、latex-1-0。label也同时写入每个 chunk 的label字段可用于区分哪些 chunk 来自 LaTeX 文档与metadata.sourceType: latex互为冗余保险。五、输出结构与元数据语义Chunk类型同样定义在 types.ts包含id、content、start、end、metadata、tokens、label、score等字段。LatexChunker产出的 chunk 元数据由 metadata.ts 的buildMetadata统一装配最终包含metadata.format固定为latex逻辑格式标识metadata.sourceType固定为latexchunk 来源标识官方文档亦明确此字段metadata.heading所属章节标题文本若文档开头无标题则为nullmetadata.sectionTypesection、subsection、subsubsection或none前置无标题内容metadata.path当heading存在时为[heading]数组形式用于表示层级路径可推断其在多章节嵌套场景下可作为章节路径检索锚点docId/sourceId仅当调用时传入才出现baseMetadata中的自定义字段合并且不与核心字段冲突。关于正文块是否带标题前缀需要特别说明与MarkdownChunker等不同LatexChunker的content不含标题文本标题只进元数据。检索时如需将标题与正文拼接可在下游自行用metadata.heading拼装。六、与 RecursiveChunker 的协作原理每个章节正文的细分由 recursive-chunker.ts 完成其内部是一个段落 → 句子 → token的三级递归流程段落级先用splitIntoParagraphs按空行切段见 text.ts段落 token 数不超过maxTokens则直接成块句子级超预算的段落交给SentenceChunkersentence-chunker.ts按句子边界聚合并带上overlapSentences: 1的重叠策略Token 级兜底仍超预算的句子组交给TokenChunkertoken-chunker.ts按 token 窗口硬切。这一设计意味着LatexChunker切出的章节正文永远不超maxTokens且天然以语义边界段落、句子为优先切割点。测试 latex-chunker.spec.ts 验证了按章节命令切分且保留 heading 元数据这一核心行为const tex \\section{Intro} Some intro text. \\subsection{Details} Detailed text here.; const chunker new LatexChunker(); const chunks chunker.chunk(tex, { maxTokens: 8 }); expect(chunks.some((c) c.metadata?.heading Intro)).toBe(true);七、在 StructuredDocument 与 auto 策略中的集成LatexChunker不仅可以独立使用还可以作为StructuredDocument的分块策略接入完整流水线。官方文档 structured-document.md 中的工作流为创建文档节点 → 运行提取器标题/摘要/关键词/问题→ 按策略分块 → 读取文档与 chunk 的链接图。import { StructuredDocument } from voltagent/rag; const doc StructuredDocument.fromText(texSource); doc.extract({ title: true, summary: true, keywords: true, questions: true }); const { chunks } doc.chunk({ strategy: latex, maxTokens: 200 }); const links doc.getLinkGraph(); // { doc-id: [chunk-id, ...] }策略分发实现在 transformers.ts 的chunkByStrategy中当strategy: latex时直接实例化LatexChunker当strategy: auto时则先由 format-detector.ts 的detectFormat做格式探测——其中 LaTeX 的判定信号是正则\\(section|subsection|subsubsection|begin\{document\})命中命中后自动路由到latex策略。因此在不确定文档格式的批处理场景中把strategy设为auto即可让 LaTeX 文档自动走LatexChunker无需人工指定。每次chunk()调用产出的 chunk 都会自动带上metadata.docId方便下游把 chunk 关联回源文档节点。八、注意事项与边界不处理 LaTeX 编译产物LatexChunker处理的是.tex源码文本而非 PDF 或渲染后的富文本公式环境equation、align等中的\section字样理论上也可能被正则命中但从命令形态看此类冲突极少若源文档含特殊宏重定义需自行验证不负责嵌入与向量索引分块产出的是结构化文本块后续的 embedding、向量入库需接入你自己的流水线参见 chunkers overview 的说明content不含标题文本需要标题正文联合检索时请自行拼接metadata.headingmaxTokens下限保护传入0或负数会被钳制为1不会报错但会产生极小碎片注意合理取值版本与环境以上行为基于voltagent/rag1.0.2 版本源码js-tiktoken是唯一生产依赖使用时请确保其正确安装。九、小结LatexChunker是 VoltAgent RAG 工具集中结构优先思想的典型代表以正则驱动的章节扫描保住语义骨架把 token 预算内的细分交给RecursiveChunker最终产出的每个 chunk 都带heading、sectionType、sourceType元数据。对于论文、技术文档等 LaTeX 语料这一方案比纯通用分块器更贴合按章节检索的召回需求。结合 StructuredDocument 与auto格式探测可低成本接入批量文档的 RAG 索引流水线。赞分享人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆【免费下载链接】voltagentAI Agent Engineering Platform built on an Open Source TypeScript AI Agent Framework项目地址https://gitcode.com/gh_mirrors/vo/voltagent点击查看免费下载相关推荐VoltAgent 集成 Pinecone 向量数据库构建双模式 RAG 知识检索 Agent 实战指南VoltAgent 集成 Pinecone 向量数据库构建双模式 RAG 知识检索 Agent 实战指南 导读 本文基于 VoltAgent 官方示例 exa人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音VoltAgent RAG系统完全指南从文档检索到知识增强生成VoltAgent RAG系统完全指南从文档检索到知识增强生成 VoltAgent是一个开源TypeScript AI Agent框架其强大的RAG检索增人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音LlamaIndex StripeDocsReader 实战指南从 Stripe 官方文档构建可查询的 RAG 索引LlamaIndex StripeDocsReader 实战指南从 Stripe 官方文档构建可查询的 RAG 索引 导读 StripeDocsReader人工智能RAG大模型上一篇Mood Application下一篇GBFR Logs终极指南简单快速的碧蓝幻想Relink伤害统计工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考