鸿蒙PC端本地知识库搭建：语义检索与向量索引实战

1. 为什么要做这个项目：从“文件堆成山”到“一问就能找”

先交代一下背景。我手头长期积累了几千份本地文档——PDF论文、技术手册、产品需求书、会议纪要、Markdown笔记、各种导出的HTML存档，甚至还有一部分OCR出来的扫描件。这些文件躺在硬盘里的时候是财富，真到用的时候就是灾难。想找一个半年前写过的方案细节，文件名记不清，目录结构又改过好几轮，只能一层层翻，运气好五分钟，运气不好半小时起步。

后来我试过不少“本地知识库”方案，但要么依赖云端API，文档内容必须传出去，数据隐私这块过不去；要么配置链路太长，又是向量库又是中间件，折腾完已经没力气整理文档了。更关键的是，大多数方案默认跑在Windows或者Linux服务器上，桌面端体验很割裂。

正好HarmonyOS 6.0的PC端能力已经开放了不少，API稳定程度也够用了，我就决定在鸿蒙PC环境里自建一个智能文档管理APP。核心目标有三个：第一，把文档统一收进来，做本地索引；第二，用语义检索替代纯粹的关键词匹配，解决“想不起来关键词但记得大概意思”的检索痛点；第三，所有数据不出本机，保证隐私可控。

这个项目做完之后，我实际用得最多的场景是：打开APP，输入“上回讨论的那个降本方案里关于缓存淘汰策略的结论”，系统直接返回对应的段落和来源文件。不用记文件名，不用记精确词，语义对上就能找到。这篇文章就把整个落地过程拆开讲清楚，包括技术选型、语义检索的实现细节、PC端适配的坑，以及我踩过的那些文档处理层面的雷。

2. 技术选型与整体架构：为什么用本地小模型，而不是云端大接口

2.1 选型之前先想清楚三件事

动工之前，我先列了几个硬性约束，后面所有选型都围绕着它们展开：

• 数据不出本机。文档内容、索引结果、检索日志全部保存在本地，不调用任何公网API。
• PC端资源和移动端不一样，内存、CPU、存储都更宽裕，但也不能随便吃满，毕竟电脑还要干别的活。
• 语义检索要快。打开APP之后，索引要能秒级加载，单次检索不能让人等出焦虑感。

在这些约束下，面向云端的大模型接口方案直接出局。剩下来要解决的核心问题是：嵌入模型用哪个、向量索引怎么存、检索召回之后怎么给用户呈现结果。

2.2 嵌入模型选择：量化小模型是实用主义的最优解

语义检索的第一步，是把文本变成向量。这一步的模型选型直接决定了检索效果的上限。

我的选择是本地运行一个小规模嵌入模型，采用量化版本部署。量化的意思是把模型权重从FP32压缩到INT8甚至INT4，体积缩小、推理速度变快，精度损失在可接受范围内。对于中文文档检索场景，量化后的模型仍然能把语义相近的句子映射到比较接近的向量空间，足够支撑日常检索。

为什么不选更大的模型？因为在这个场景里，检索召回质量并不完全取决于模型参数量。更大模型带来的收益在“理解复杂语义”上更明显，而本地知识库检索面对的问题大多是“用一句话描述一个概念或结论”，中等规模的嵌入模型已经能处理得很好。再往上加参数量，边际收益不高，但内存占用和推理延迟的增长却很直接。为了省那一点准确率，让每次检索多等两三秒，不值。

2.3 为什么选择向量数据库而非直接暴力遍历

文本向量化之后，如果文档量小（几百个段落），直接遍历计算余弦相似度也没问题。但这个项目要面对的是几千份文档、几万个文本块，每次检索都对全量计算代价太高。所以需要建立向量索引。

在这个项目里，我采用了一个比较轻量的方案：把向量索引持久化为本地文件，启动时加载进内存，检索时使用近似最近邻（ANN）算法进行匹配，配合暴力精确检索作为兜底。具体参数和实现细节在下一节展开。

另外，PC端的优势在这里体现得非常明显。移动端做同样的事情，内存吃紧、存储空间有限；PC端随便几十GB存储加16GB内存，本地跑向量索引完全没有压力。

2.4 整体架构长什么样

整个应用可以分成四个层次：

• 数据接入层：负责文件导入、格式解析、文本抽取、编码清洗。
• 索引构建层：把清洗后的文本切块、向量化、写入本地向量索引。
• 语义检索层：接收查询，计算查询向量，召回TopK文本块，做重排过滤。
• 展示交互层：HarmonyOS ArkUI搭建的PC端界面，呈现检索结果、文件来源、命中位置。

应用本体使用ArkTS开发，基于HarmonyOS 6.0的PC端适配能力。数据存储使用SQLite保存文档元信息和文本块内容，向量索引使用本地文件存储。整个应用构建完成后，离线可以独立运行，不需要任何外部服务。

3. 文档处理链路：从导入到可检索，中间隔着一堆格式坑

3.1 文档解析：不要指望一个库通吃所有格式

文档管理APP的第一个难点不是界面，也不是检索，而是把不同格式的文档干净地变成纯文本。我遇到的格式类型包括：TXT、Markdown、PDF（文本型和扫描型）、Word文档、HTML导出页，以及EPUB电子书。

这里必须强调一个经验：没有哪个解析库能完美处理所有格式，老老实实按格式分流处理是最省心的做法。

• TXT和Markdown：直接按编码读取，注意处理UTF-8、UTF-16、GBK多种编码，乱码问题要靠检测编码解决。
• PDF：文本型PDF用解析库抽取文本；扫描型PDF需要搭配OCR模块，识别质量和扫描分辨率强相关，建议至少300DPI。
• Word：需要按段落解析，注意表格内容不能丢，表格在文档里往往承载了关键信息。
• HTML：先清洗标签，再提取正文，不然样式代码和脚本会污染后续向量化的文本质量。
• EPUB：本质是打包的HTML集合，解析时按章节拆分，每一章作为独立文本块来源。

我在这个环节踩过最深的坑是PDF文件里的字体编码错乱，特别是某些国产软件导出的PDF，文本抽取出来是乱码。后来加了一层规则校验，抽出来的文本如果连续乱码比例过高，就自动降级走OCR流程。

3.2 编码清洗与规范化：这一步决定向量质量的天花板

很多人做知识库只关注后面的向量化和检索，忽略了文本清洗。实际上，脏文本直接进模型，检索效果会断崖式下跌。

清洗流程我总结成五步：

1. 统一换行符，把Windows的CRLF统一成LF。
2. 去掉不可见控制字符和零宽字符——这类字符是检索“幽灵命中”的元凶。
3. 把全角英文字符转成半角，全角数字同样处理，避免“Ａ”和“A”被当成两个概念。
4. 合并多余空行和空格，但注意不能过度压缩，代码块和表格里的空格有语义。
5. 清洗HTML解析残留，去掉内联样式残留片段。

这一套流程跑完之后，文本块质量会有一个非常直观的提升。实测下来，清洗前检索结果经常出现“明明感觉有相关内容但就是召不回”的情况，清洗之后命中率明显提升。

3.3 文本切块策略：段落级切分配合滑动窗口

文本清洗完之后，不能整篇丢给模型做向量化，必须切成块。切块策略直接影响检索精度。

我的切块逻辑是：优先按Markdown标题和段落边界切分，保留语义完整性；如果一个段落太长，再按句子边界二次切分，并设置最大长度上限（这里我设定为512个字符左右）。切出来的块会同时记录元信息，包括所属文件、章节路径、块在原文中的序号，方便结果展示时做来源回链。

这里有一个容易被忽略的技巧：切块时给每块文本额外保存一份“带上下文的扩展文本”。举例来说，如果某一章内容被切成了三块，那么每一块在向量化时，除了块本身的内容，还会拼接前一块和后一块的首句作为上下文补充。这样做的原因是，单块文本脱离上下文后语义会变得模糊，尤其是“结论依赖于前面的前提”这类文档；带上上下文首句之后，向量化效果会更好，检索召回也更准。代价是存储空间和向量维度会略微增加，但在PC端完全可接受。

4. 语义检索核心实现：本地模型向量化、ANN索引与TopK召回

4.1 检索的整体流程

整个检索流程分为离线和在线两个阶段。

离线阶段发生在文档导入时：文档解析、清洗、切块、向量化、写入索引，全部后台异步执行。在线阶段发生在用户输入查询词时：查询文本向量化、在索引中搜索、重排、输出结果。

在线检索的步骤可以拆成五步：

1. 用户输入查询语句，系统对查询文本做同样的清洗和规范化处理。
2. 查询文本被送入嵌入模型，生成查询向量。
3. 在向量索引中执行相似度搜索，召回Top 50候选块。
4. 对Top 50候选做精确重排，用更严格的相似度计算方式重新排序。
5. 取前10个结果返回给界面，展示文本块内容和来源文件信息。

这里引入一个优化细节：先用ANN做粗召回，再用精确距离做重排。原因是ANN在召回阶段追求速度，允许一定程度的近似误差；如果直接把ANN结果当作最终结果，可能漏掉最优匹配。重排阶段只对50个候选做计算，成本很低，但能显著提升最终精度。

4.2 本地向量索引的构建与存储细节

向量索引使用HNSW（分层小世界图）算法的实现思路。HNSW是当前本地端做语义检索最常用的索引结构之一，检索速度快、召回率高，比较适合构建一次性写入、多次查询的场景。

索引构建时的参数我调过好几轮，最终采用以下配置：

• 向量维度根据嵌入模型输出决定，这里使用的模型输出维度是768维。
• HNSW的M参数（每个节点的最大连接数）设为16，这个值决定了图的稠密程度。M越大，召回越准，但内存占用和构建时间也越长。16在PC端是一个性价比不错的选择。
• efConstruction参数设为200，控制构建阶段的候选队列大小，影响索引质量。这个值调大，构建慢一些，但图的质量更高。
• 检索阶段的efSearch参数设为64，代表搜索时遍历的候选节点数。这个值可以在召回率和延迟之间做权衡，64是实测比较舒服的档位。

索引文件落地时，除了向量数据本身，我额外保存了一个映射表，把向量的顺序ID映射回文本块的主键ID。检索出向量之后，通过映射表找到对应的文本块元信息，再回SQLite查出完整内容。

4.3 检索的兜底方案：关键词匹配不能丢

语义检索虽然强，但也不是万能的。有些场景下用户输入的是文件名、版本号、作者名这类“专有名词”，语义模型对这类词汇的感知并不敏感。比如用户输入“V3.2版架构说明”，语义上召回结果可能不如直接关键词匹配来得精准。

所以我在系统里做了一个简单的混合策略：语义检索作为主通道，关键词匹配作为辅助通道。查询时两条通道同时触发，结果按相关度做加权融合。权重方面，语义结果占主要比重，但关键词精确命中的结果会获得额外加分，这样既保证语义理解的深度，又不丢失精确匹配的刚性需求。

实测效果：混合策略的准确率和召回率都比单通道更好。最典型的是搜“缓存淘汰策略”这个词，语义通道能召回各种表述（LRU、最近最少使用、cache eviction等），关键词通道则能精确命中标题或正文中出现特定术语的段落，两者互补很明显。

4.4 查询理解：先判断用户意图，再决定检索策略

除了基础的向量检索，我在查询端加了一个轻量的意图判断逻辑，分三种情况处理：

• 问句型查询（“什么是xxx”“xxx怎么做”）：语义检索为主，强调召回相关段落。
• 短语型查询（“缓存淘汰方案”“降本策略汇总”）：语义和关键词并重。
• 一个明显的文件名或编号（“V3.2架构.docx”“PRD-2024-001”）：直接走文件元数据匹配，不经过向量化，效率最高。

这个逻辑不需要复杂模型，用简单的规则就能实现。它的价值在于减少了无意义计算，并且在用户输入不完整、信息稀疏的时候，能更准确地命中目标。

5. HarmonyOS PC端应用开发：ArkUI布局、多窗口适配与文件交互

5.1 PC端和移动端在UI开发上的差异

在做这个应用之前，我先做了一套移动端原型，后来才发现PC端的开发思路完全不一样。移动端是竖屏、单列、触摸交互；PC端是宽屏、多列、键鼠交互，窗口还能缩放。直接在移动端的界面上拉伸窗口，效果会很难看。

PC端适配的核心是响应式布局。ArkUI的栅格系统在这里派上了用场，我把界面划分为左侧导航栏、中间文档列表、右侧预览面板三段布局。窗口宽度缩小时，右侧预览面板自动收窄；窗口宽度低于阈值时，预览面板隐藏，改成点击文档后弹窗展示。

布局细节上要注意的是，PC端的悬停态、右键菜单、键盘快捷键这些交互在移动端根本不存在，开发时需要单独处理。比如文档列表支持右键直接打开所在目录，这个功能在移动端就用不上。

5.2 文件导入：文件夹递归扫描与增量更新的实现

PC端应用最大的优势是能直接读取本地文件系统，文档导入不再需要通过文件选择器一个个点选。

我实现了一个“添加文件夹”的功能：选择某个目录后，应用递归扫描其下的所有支持格式文件，建立文件清单。首次导入时会全量解析，后续再次扫描时只处理新增或修改过的文件，通过文件路径加修改时间戳判断，避免重复解析。

这里有一个需要特别注意的点：中文文件名和特殊字符文件名的处理。鸿蒙的PC文件系统接口对Unicode的支持总体不错，但还是有几个边角场景要小心，比如文件名包含emoji、包含连续空格、以及某些特殊Unicode字符的情况。如果不做处理，部分文件会解析失败且不报错，表现为“文件列表中少了一个文件”。我的做法是在扫描阶段记录原始文件名并同时生成一个安全文件名用于内部处理，展示时优先用原始文件名。

5.3 后台任务与进度反馈：索引构建时App不能卡死

文档解析和向量化是计算密集型任务，如果同步在主线程执行，界面会直接卡死，用户体验极差。尤其是一次性导入几千份文档时，整个索引构建可能需要几分钟。

我用的方案是后台任务机制，把解析、清洗、切块、向量化、写入索引整条链路放进后台执行队列，主线程只负责更新进度条。

进度反馈上做了两级显示：第一级是“文件级进度”，显示当前正在处理哪个文件以及整体完成百分比；第二级是“文件内阶段”，显示当前文件处于解析、切块还是向量化阶段。这样一个文件在某个阶段卡住时，能快速定位是哪一个文档、哪一步出了问题。

任务执行期间，用户仍然可以正常浏览已索引的内容、进行检索。新文件索引完成后，通过事件通知刷新列表，不打断当前操作。

5.4 系统权限与文件访问范围的界定

HarmonyOS PC端的权限模型和移动端一样严格，不是拿到了存储权限就能访问所有目录。

在“添加文件夹”这个功能上，我采用了用户主动授权目录访问的方式。应用内选择目标文件夹后，系统弹出授权确认，用户同意后应用才能读取该目录。这个设计其实很合理，不搞“全盘扫描”那套，隐私边界清晰，也符合平台规范。

实现过程中踩过一个小坑：授权目录后，子目录的访问权限在不同版本上有细微差别。有的版本树状继承，有的版本只授权到当前层级。我的处理是在扫描时逐层检查访问权限，遇到无权限的子目录就跳过并在日志里标注。后续在界面上增加一个“未索引目录”的提示入口，用户看到后可以单独为这些子目录补授权。

5.5 索引持久化与秒级启动

应用启动时如果每次都要重建索引，体验会非常糟糕。所以索引必须持久化，启动时加载而不是重建。

我的做法是：文档元信息存SQLite，向量索引存文件，两者通过映射表关联。应用启动时先读SQLite中的元信息和映射表，再加载向量索引文件到内存。实测启动时间在一秒以内，前提是索引文件不是特别巨大。

如果文档总量增长到几十万块，索引加载时间会明显上升。到时候可以通过内存映射文件的方式按需加载，避免一次性全量载入。这个优化我目前还没做，但方案已经预留了。

另外我还做了一个“增量索引”的小机制：每次导入新文档后不重建全量索引，而是只向现有索引中添加新向量，避免构建时间和磁盘写入的浪费。启动时的加载仍然是全量加载，但构建过程是增量的，这种“构建增量、加载全量”的组合方式，在文档量达到数万块时依然能保持流畅。

6. 检索体验优化：高亮、来源定位与结果重排的交互细节

6.1 高亮显示：不能只标关键词，还要标语义相关的部分

检索结果里，关键词命中的部分做高亮是基本操作，但语义检索命中的块往往不包含用户输入的任何关键词。这时候如果只有整块文本，用户会困惑“这结果到底哪里相关”。

我的处理是在结果展示时，把查询向量和结果块中每个句子的向量也做一次相似度计算，挑出最相关的一两句作为“命中摘要”，摘要中再对语义匹配的关键短语做模糊高亮。这样用户可以直观看到为什么这个结果被召回，体验比整块展示好很多。

6.2 结果卡片设计：信息密度与可读性的平衡

检索结果列表我设计成卡片形式，每张卡片展示以下信息：

• 文本块摘要（截取命中区域前后各几十字）
• 来源文件名和完整章节路径
• 命中类型标签（语义命中、关键词命中、混合命中）
• 与查询的相关度评分（展示为百分比进度条）

这个设计的核心是让用户在海量结果中快速判断点开哪一个。评分数字的意义有限，但进度条能让人一眼扫出相对高低。命中类型标签能解释“为什么结果里没有关键词还能搜到”。

6.3 点击结果后的定位方式

用户点击某个结果卡片后，系统应该定位到原文的准确位置，而不是只打开整个文件。

这里我根据文件类型做了不同处理：

• 文本类和Markdown：直接定位到对应章节名，并滚动到目标段落。
• PDF：根据切块时记录的页数偏移量，用PDF阅读组件的页面跳转功能定位到具体页面。
• Word：通过章节标记跳转，定位速度会比PDF稍慢，但准确度可以接受。

这个功能实现起来工作量不小，因为它需要和各个格式的渲染组件深度配合。但它是“知识库”和“文件搜索工具”之间的重要分水岭。如果搜索完还得自己翻文件找位置，体验就大打折扣了。

7. 性能优化与资源占用控制：模型推理、内存与磁盘的平衡术

7.1 模型推理的并发控制

嵌入模型在CPU上运行。索引构建时，如果多个文件同时进入向量化阶段，会触发并发推理。这里必须做并发控制，否则CPU占用直接拉满，整个电脑风扇狂转，其他操作全部卡顿。

我的策略是设置推理并发数为1，即同一时间只处理一个文本块的向量化。虽然牺牲了一点吞吐，但换来了稳定的系统响应。单独处理一个文本块的时间在毫秒级，即使有几千个文本块，总耗时可接受。相比并发压满CPU带来的体验崩坏，串行推理是更好的选择。

索引构建结束后，模型占用的内存会释放一部分。平时只有用户发起查询时才临时加载模型，查询完成后再释放，避免常驻内存吃资源。

7.2 存储空间测算与清理机制

向量存储的空间占用需要提前算清楚。以768维向量为例，每维度一个FP32浮点数占用4字节，一个向量就是768×4=3072字节，约3KB。如果积累一万个文本块，向量索引文件本身就约30MB，加上HNSW图的额外结构，实际占用会翻倍到60MB左右。

再算上SQLite里的元信息和文本块原文，一万块的规模大约占用100MB到150MB的总空间。对于PC端来说，这个量级可以接受。但文档量如果持续增长到十万块量级，就需要考虑压缩向量精度和清理策略了。

我在设置里加了一个存储统计面板，展示文本块数量、索引文件大小、原文存储大小。用户可以手动清理“已经被替换的旧版本文件的索引记录”，释放空间。同时，我把原始导入的临时解析缓存定期清理，避免临时文件堆积。

7.3 冷启动与热启动的优化

应用启动分两种场景：一种是系统重启后第一次打开，需要从磁盘加载索引；另一种是已经打开过、切到后台再回前台，索引还在内存中。

冷启动优化方面，我先把索引加载逻辑放到后台线程，界面先渲染出来显示“正在加载索引...”的提示，加载完成后自动刷新界面。实测冷启动时间大约0.8秒，体验尚可。

热启动优化方面，回到前台时只检查索引文件是否有变化，没有变化就直接使用内存中的索引，不重复加载。这套逻辑下来，日常使用基本感知不到等待。

8. 实测效果与使用体会：真实检索场景下的表现

8.1 三类典型检索场景的效果对比

项目上线后，我用三个典型场景做了多轮测试：

第一类，精确术语检索。输入“LRU缓存淘汰”，系统能召回所有提到LRU、最近最少使用、cache eviction的段落，召回顺序合理，最相关的方案文档排在最前面。

第二类，语义模糊检索。输入“上个月讨论的那个节省成本的存储方案”，不包含任何精确术语，系统能正确召回关于存储分层降本的文档，命中摘要显示了“冷热数据分离”“低频数据归档”等内容，用户一眼就能确认相关性。

第三类，文件名/编号检索。输入“PRD-2024-001”，系统直接命中对应文件卡片，没有走语义推理，响应速度极快。

这三类场景覆盖了我在实际使用中绝大部分的搜索需求，整体满意度很高。核心痛点“搜不到”“搜不准”“搜得慢”都被解决得比较干净。

8.2 一些值得说的不满意之处

实事求是的讲，还有几个场景效果一般。一是扫描版PDF经过OCR之后，文本质量不稳定，部分识别错误会影响向量化效果；二是图表内容目前不参与检索，只能通过图表标题和上下文文本间接召回，遇到“想找某个数据图表但记不清标题”的情况，表现一般；三是在处理英文、中文混排文档时，切块偶尔会把双语对照的段落拆散，导致检索结果不完整。

这些问题的根因都不在检索算法本身，而是在上游的解析和切块环节。后续我会在前置处理上继续优化，比如OCR结果校对、图表标题提取、双语段落识别等。

9. 常见问题与排查技巧实录

9.1 文档导入后索引构建卡住不动

发生概率不低。常见原因是某个PDF文件有加密保护或内嵌字体异常导致解析线程阻塞。排查方式是看日志中当前处理到哪个文件，找到问题文件后单独测试解析。

我的处理是在解析链路里加了解析超时机制，单文件解析超过30秒自动跳过并记录异常原因。这样不会因为一个坏文件卡住整个索引队列。

9.2 检索结果里出现乱码内容

这个问题的根源通常在编码检测失误。部分文件声明是UTF-8编码，实际内容是GBK，检测工具直接判断错误。

处理办法是解析时做双重校验：先按检测出的编码解码，再检查解码后的文本中有没有异常字符分布。异常率超过阈值就换一种编码重新解码。这套机制上线后，乱码入库的情况基本消失。

9.3 高亮不明显或命中摘要不相关

出现这个问题的原因是文本块切分粒度偏大，导致块内其他主题的句子干扰了摘要生成。解决方式是缩小切块上限，并提升摘要选择时的句子向量相似度阈值。

调整后，命中摘要的准确率明显提升。经验值是：切块上限设在512字符左右，摘要相似度阈值设在0.68左右，这两个参数配合起来效果不错。

9.4 应用启动时索引加载失败

偶发场景，通常是因为上次非正常退出导致索引文件损坏。我的处理是索引写入时先写临时文件，成功后通过原子替换覆盖旧文件。这样即使写入中途崩溃，旧索引仍然可用。

启动加载失败时，应用会提示用户重新构建索引，同时保留损坏文件的备份用于排查原因。

9.5 检索延迟高，用户体感明显

索引构建完后，正常检索耗时在毫秒级。如果出现明显延迟，优先级检查清单如下：

• 是否触发了全量精确搜索而不是ANN搜索？在文档量大的情况下，全量搜索会有明显延迟。
• 是否有其他后台任务在抢CPU资源？批量文档导入时做实时检索会受到干扰。
• 模型是否被重复加载了？查询期间频繁加载和释放模型，也会带来额外延迟。

前两个问题通过日志定位，第三个问题则是通过设置模型常驻内存（仅当系统内存充足时）解决。默认配置不常驻，如果用户内存大于16GB，可以在设置里手动开启常驻模式。

10. 工程化经验与应用扩展方向

10.1 日志体系是整个项目Debug的核心

这个项目涉及到的环节太多，从文件解析到模型推理，任何一个环节出问题都可能导致最终结果异常。如果没有完整的日志体系，排查问题简直是大海捞针。

我的日志方案分三层：应用运行日志记录执行链路和关键参数；解析日志单独记录每个文件的处理状态和异常原因；检索日志记录查询语句和结果统计用于效果调优。

日志文件按大小轮转，单文件不超过5MB，最多保留10个历史文件，避免日志无限膨胀。界面上保留一个“最近异常”查看入口，普通用户遇到问题可以直接看原因，不用打开日志目录。

10.2 扩展方向一：本地会话问答

当前的检索方式是“多召回、用户自己判断”。扩展一步就是引入生成式问答：基于召回的文本块生成一段自然语言回答。本地小参数生成模型配合检索增强生成（RAG）可以做到全离线运行。

工程量主要在生成模型的优化和提示词工程上。PC端的内存足够跑7B级别的量化模型，但生成速度是一个需要权衡的点。可以做成两级模式：快速模式只给出召回段落拼接的回答，深度模式调用生成模型输出综合回答。

10.3 扩展方向二：文档关系的知识图谱化

语义检索的短板在于无法体现文档之间的复杂关系。比如“A方案里提到了B方案的设计取舍”，用户通过关键词可能永远搜不到这种隐性关联。如果把抽取出的实体和关系做成知识图谱，可以在检索之外增加“关联发现”的能力。

这个方向工程量更大，但对知识管理来说是真正的质变。目前我把它作为下一阶段的规划，第一步先做实体抽取，把文档中的人物、项目名、技术方案名称归拢，然后做共现关系网络。

10.4 扩展方向三：多端数据同步与协作

目前应用是纯本地单机版。如果未来需要多设备同步，比如办公室PC和家里笔记本共享同一个知识库，需要设计加密同步方案。早期版本可以基于局域网共享文件夹做索引同步，文档主体留在各自设备，只同步索引和元数据。这样既能保证数据隐私，又能在多端之间共享检索能力。

11. 个人经验沉淀：踩坑之后的最终建议

整套项目做下来，给我最深的体会是：语义检索本身不是瓶颈，文档处理的干净程度才是决定成败的关键。很多人在搭知识库的时候，把精力全部放在模型选择和向量库调参上，结果喂给模型的是充满乱码、格式混乱的脏文本，后面再怎么调优也是徒劳。

先把导入链路做扎实，把编码、清洗、切块这些基础处理做到位，再考虑模型和索引的事，这个顺序不能乱。

另外，本地知识库产品化过程中，“编辑体验”和“检索体验”同等重要。一个能找回文档的应用，和一套让人愿意持续维护文档的体系，之间的距离往往就藏在“命中摘要是否清晰、来源定位是否准确、导入新文档是否丝滑”这些细节里。

这个项目目前已经稳定运行了一段时间，日常检索需求基本都能覆盖。每次把散落在硬盘各处的文档导入并索引成功、然后一条语义查询秒出结果的时候，我都会觉得当初投入在这套自研方案上的时间特别值。如果你也在对抗“文件堆成山却找不到东西”的困境，希望这篇实战记录能帮你少走几步弯路。