为 Hermes/OpenClaw等智能体 构建本地 PDF/DOCX 解析技能将上下文信息从 270 万个词元减少到 2200 个词元SQLite FTS5本地基准测试 PDF AMD 技术文档页数 3,799 页 | 105 万字 | 746 万字符解析时间 ~14 分钟在 AMD FireRange CPU 上测试 我向 LLM 提出了一个非常具体、略带口语化的问题关于特定寄存器的位功能模拟工程师在现实世界中实际提问的方式。不包含该技能全文转储 ~2,794,829 tokens 。上下文信息爆炸模型完全失去焦点开始胡思乱想。运用技能目标片段检索 ~2,244 tokens 。智能体检索到了确切的片段并提供了正确、精确的答案。机器学习与人工智能我的配置操作系统 Windows 11LLM runner Ollama型号 Qwen3.6:27b文档结构化工具把PDF当数据库查你有没有试过让AI读一份几千页的PDF结果AI直接摆烂要么胡说八道要么直接告诉你“内容太多我记不住”。这玩意儿就是来解决这个问题的。它把PDF和Word文档切碎、标号、存进数据库让AI不再“硬读”整篇文章而是像查字典一样精准抓取需要的段落。这玩意儿到底在干啥把一份几百页甚至几千页的技术文档扔进去。它先扫描文档结构把每一章、每一节、每一个小标题都认出来。然后按照标题层级把文档切成一块一块的Markdown格式碎片。每一块都有编号第几章、第几节、标题是什么、从第几页开始、存成了哪个文件。接着它把这些碎片信息全部塞进一个SQLite数据库里。数据库里建了两张核心表一张记文档基本信息一张记每个碎片的具体内容。同时它还启用了SQLite的FTS5全文搜索引擎给所有碎片内容建了索引。计算机科学最后你只要输入关键词它就能在零点几秒内告诉你这个词出现在哪个章节、上下文是什么、文件在哪儿。整个过程就像在Google里搜东西一样简单。它解决了什么要命问题一般的AI读文档你只能把整篇PDF一股脑塞进它的上下文窗口。这就好比让你把整本新华字典背下来再去查一个字脑子不炸才怪。对于一份2400页的PDF直接喂给AI大概要消耗450万个token。这是什么概念用主流付费模型处理一次可能就得花掉几十块钱关键是AI还不一定能答对。因为信息太多了AI根本不知道重点在哪儿。你问一个具体问题它可能把文档里所有沾边的段落都拼凑起来给你里面还夹杂着一堆无关的废话。更离谱的是AI经常会编造答案。本来文档里根本没有的内容它为了凑字数自己脑补出来一段。这种情况在技术文档领域尤其致命——你问的可能是芯片寄存器的位定义它给你一个完全不存在的寄存器名字你要真信了去写代码硬件可能直接烧了。但用这个工具就不一样了。你问一个问题它先去FTS5索引里搜关键词找到最相关的3到5个碎片只把这几个碎片喂给AI。AI需要处理的token数量从几百万骤降到两三千。它只需要阅读那几段关键内容就能给出精准回答不会再胡说八道。AI基础设施怎么把文档吃进去这个工具的操作分成四步走每一步都有专门的处理逻辑。第一步是解析。针对PDF文件它用的是PyMuPDF库配合pymupdf4llm这个转换器。这个组合能把PDF里的文字、标题、页码、段落结构全部识别出来转成结构清晰的Markdown格式。针对Word文档它用python-docx库来读取。不管你扔什么格式进去最终都会变成统一的Markdown片段。第二步是切块。切块的依据是标题层级。文档里的H1大标题、H2中标题、H3小标题全部被识别。工具按照这些标题把文档切成独立单元。每个单元包含完整的标题、正文内容、起始页码和层级关系。第三步是入库。所有切好的碎片被写入SQLite数据库的chunks表。每个碎片分配一个唯一编号同时记录它属于哪个文档、章节号是多少、对应哪个物理文件。documents表则记录文档的整体信息包括文件名、上传时间、碎片总数。第四步是建索引。这一步用到的是SQLite的FTS5扩展模块。它会对每个碎片的标题和正文内容建立全文索引支持布尔检索、前缀匹配、短语查询等高级搜索语法。索引建好后搜索速度比直接遍历数据库快了上百倍。怎么把信息查出来工具提供了好几套查询方式适应不同的使用场景。最核心的是关键词搜索。你输入一个查询词比如ACPI或者某个寄存器名字工具会返回所有匹配的碎片列表。每个匹配结果都包含碎片编号、章节标题、匹配内容片段、所在文件路径。搜索范围可以单独限定在标题里也可以扩大到正文全文。如果你已经知道了某个碎片编号可以直接根据编号获取完整内容。这个操作会返回整个碎片的原始Markdown文本包含完整的章节标题和正文不需要加载整篇文档。还有一个专门查看目录结构的功能。你能看到整篇文档的章节树形结构每节对应哪个文件、层级关系是怎样的、总共有多少章节。这在做文档概览或知识导航的时候特别有用。所有查询返回的内容都是结构化的可以直接被LLM Agent读取和处理。如果搜索结果不够精准还可以用LIKE模糊匹配作为兜底方案。整个系统的底层逻辑这套工具的本质是一个轻量级的文档ETL系统。ETL是数据工程里的术语代表抽取、转换、加载三个步骤。在这里抽取指的是从PDF和Word文件里提取文字内容和结构信息。转换指的是按照标题层级切分、转成Markdown格式。加载指的是写入SQLite数据库并建立FTS5索引。流程可以画成这样原始PDF或DOCX文件进去经过结构解析和标题分块处理变成一堆Markdown片段。这些片段入库的同时生成全文索引。最终对外暴露的是查询API和命令行工具。这种架构的好处是处理过程完全离线不需要依赖任何云服务。所有数据都保存在本地隐私安全有保障。性能方面SQLite本身是经过高度优化的嵌入式数据库对于单机场景完全够用。这套设计还带来了一个额外优势删改特别方便。如果你更新了文档只要重新上传同名的文件工具会自动删除旧数据并重建索引不会产生脏数据。用在什么地方最合适技术手册是头号适用场景。硬件厂商经常发布几千页的编程指南工程师需要频繁查阅特定寄存器的定义。把这堆文档扔进去以后查一个寄存器定义只需要几秒钟。论文库也适用。学术论文往往有清晰的章节结构每篇论文可以被切分成摘要、引言、方法、实验、结论等独立单元。研究者可以根据关键词快速定位到相关论文的特定章节。API文档同样不在话下。大型API文档动辄几百个接口定义每个接口都有独立的描述和参数说明。把API文档结构化存储以后开发者搜索某个函数用法的时候可以直接定位到对应的接口说明。企业内部的知识库也能用上。很多公司有大量的内部技术文档和合规资料平时很难被充分利用。有了这套工具员工可以用自然语言提问的方式快速获取答案不用在海量文档里逐篇翻阅。跟其他类似工具有啥不一样市面上有个叫Unstract的产品它主打的是企业级文档数据抽取。它的工作方式是自动识别文档里的关键字段比如发票号、日期、金额这些然后以JSON格式输出结构化数据。它更适合做业务流程自动化比如自动处理财务单据。但这个工具完全不同。它的核心目标是让LLM Agent能够高效检索和理解文档内容。它不关心文档里有哪些关键字段只关心文档的章节结构。它输出的不是JSON而是可被AI读取的Markdown片段和搜索结果。更直白地说Unstract解决的是文档数据抽取的问题而这个工具解决的是文档知识检索的问题。前者适合做自动化流程后者适合做AI知识库。实际跑起来效果咋样开发者用一份AMD技术文档做了测试。文档有3799页约105万个单词总字符数超过746万。在AMD FireRange CPU上跑完整个解析流程花了大概14分钟。测试的问题是关于某个特定寄存器的位功能。这个问题特意用了一种偏口语化的问法模仿工程师在实际工作中会用的表达方式不是那种标准的术语查询。在不使用这个工具的情况下直接把整份文档塞进LLM的上下文窗口消耗了279万多个token。模型的回答逻辑混乱而且编造了不少不存在的寄存器信息根本没法用。但用了这个工具以后Agent先通过FTS5搜索找到匹配的碎片只把那几个相关的碎片喂给模型。最终的上下文窗口只用了2244个token还不到原来的千分之一。模型的回答精准地描述了寄存器各个位的功能定义全部有据可查。从279万降到两千多这个压缩比例相当惊人。意味着同样的一份硬件文档原来处理一次可能就耗尽预算现在可以反复查询几百上千次。背后的关键技术点PyMuPDF4llm这个库是整套解析流程的核心。它不是普通的PDF转文本工具而是专门针对LLM场景优化的转换器。它输出的Markdown保留了原始文档的层级结构标题、列表、表格、代码块都能被正确识别和转换。SQLite的FTS5模块提供了企业级的全文搜索能力但不需要额外部署任何服务。它支持BM25相关性评分算法可以对搜索结果按相关度排序。对于技术文档里经常出现的专业术语和缩写词FTS5的精确匹配能力特别重要。基于碎片的架构设计是整个系统的灵魂。工具始终不处理整篇文档只处理被切分后的独立单元。每个碎片在内容上是完整的在上下文上是独立的。这种设计让系统具备了极强的可伸缩性文档数量增加的时候只要扩展数据库记录就行。建好以后怎么扩展这套工具可以和RAG系统无缝对接。RAG的全称是检索增强生成是目前主流的知识问答系统架构。这个工具本质上已经提供了RAG系统里最关键的检索组件。只需要把它的查询结果喂给任意LLM就构成了一个完整的RAG流水线。如果想让LLM Agent直接调用这套工具可以把它封装成MCP工具。MCP全称是模型上下文协议是一种标准化的Agent工具调用规范。封装以后Agent可以像调用内部函数一样调用文档查询功能整个过程对用户完全透明。实际的部署方式也很灵活。可以直接用命令行工具执行查询也可以写成API服务供其他程序调用。对于本地部署场景最简单的就是把查询命令集成到Agent的工作流里。如果你想进一步深挖还有几个方向可以探索。比如碎片的粒度控制切得太细可能丢失上下文切得太粗又影响检索精度。还有搜索结果的排序优化如何根据问题的语义找到最匹配的碎片而不是仅仅依赖关键词命中。这些都会直接影响最终的回答质量。总结一下对于技术手册、论文库、API文档这类内容用传统方式让AI处理就是给自己找麻烦。这工具把PDF和Word变成可查询的结构化知识库让LLM不再硬读整篇文档而是像查数据库一样精准定位内容。一份3799页的硬件文档处理时间14分钟查询消耗从279万token降到2244token。本质上就是把文档阅读问题变成了数据库查询问题。github网址点击原文标题 https://www.jdon.com/92965-document-structuring-pdf-chunk-retrieval-sqlite-ft.html
