导语：把企业资料、项目文档或个人笔记交给云端模型处理，往往会带来隐私、网络依赖和调用成本等问题。Ollama 可以在本机运行大语言模型与嵌入模型，LlamaIndex 则负责文档加载、节点切分、向量索引、检索和回答编排。两者结合后，可以快速搭建一套数据尽量留在本地、配置灵活且便于调优的文档问答系统。本文从可运行的基础流程出发，重点分享节点检索的优化思路。🦙
一、理解本地文档问答的处理链路
这套系统本质上是一个本地 RAG 流程：先读取 PDF、Markdown、Word 或纯文本文件，将内容切分成多个 Node；再通过 Ollama 中的嵌入模型把节点转换为向量，并写入向量索引；用户提问时，系统对问题进行同样的向量化处理，检索最相关的节点，最后把问题与上下文交给本地生成模型组织答案。
LlamaIndex 的 VectorStoreIndex 接收节点并建立向量索引，使用 from_documents 时还会将 Document 解析为带有文本、元数据和关系信息的 Node。需要进一步控制切分与嵌入过程时，可以改用 IngestionPipeline。相关机制可参考 LlamaIndex 向量索引文档。
需要注意：本地运行并不自动等于绝对安全。若程序还调用了远程解析器、在线嵌入服务或外部向量数据库，数据仍可能离开设备。部署前应逐项检查依赖与网络请求。
二、准备 Ollama 与 Python 环境
首先安装 Ollama，启动服务后分别拉取一个生成模型和一个嵌入模型。模型选择不要盲目追求参数规模，应综合考虑内存、显存、响应速度和中文能力。嵌入模型负责判断语义相似度，生成模型负责阅读检索结果并回答，两者职责不同，不能只配置其中一个。
Python 环境可安装 llama-index-core、llama-index-llms-ollama、llama-index-embeddings-ollama 与文件读取组件。如果希望索引长期保存，还可以接入 Chroma 等本地向量库。官方提供了 Ollama、SentenceSplitter、OllamaEmbedding 和 Chroma 的完整本地流程示例，可参考 全本地 RAG 示例。🔧
- 生成模型：根据机器资源选择已在 Ollama 中可用的指令模型。
- 嵌入模型：优先选择适合检索任务、支持目标语言的模型。
- 文档目录：统一存放待索引文件，并排除临时文件和重复副本。
- 持久化目录：单独保存向量索引，避免每次启动都重新计算。
三、完成最小可用的索引与问答
实现时可先用 SimpleDirectoryReader 加载目录，再创建 OllamaEmbedding 和 Ollama 实例，并将它们配置给 LlamaIndex。随后使用 SentenceSplitter 设置 chunk_size 与 chunk_overlap，把文档生成节点，最后通过 VectorStoreIndex 建立索引。查询阶段创建 query engine，并设置 similarity_top_k，便可向本地模型提问。
建议为节点保留 source、file_name、page、section 等元数据。回答完成后，将命中的文件名、页码或章节一并展示。这样不仅便于用户核对依据，也能快速判断问题究竟出在召回环节，还是生成模型没有正确利用上下文。✅
四、节点切分是检索质量的起点
节点过大时，多个主题容易混在同一个向量中，检索结果虽然包含答案，却会夹杂大量无关内容；节点过小时，语义可能被截断，标题、条件和结论分散在不同节点里。调优时不要只尝试一个固定值，而应针对真实文档建立多组切分方案。
- 按结构切分：优先识别标题、段落、列表和章节，再进行长度限制。
- 保留适度重叠：让跨边界的定义、条件和结论同时出现在相邻节点中。
- 补充上下文：将文档标题、章节名称写入节点元数据，减少孤立片段。
- 清理噪声：删除重复页眉、页脚、目录残片和无意义空白，避免污染向量。
实践中可以先选择一批具有代表性的问题，包括明确事实、跨段落关系、专业缩写和否定条件，然后比较不同 chunk_size、chunk_overlap 组合下的命中情况。不要把“回答看起来通顺”当作唯一标准，真正需要观察的是正确依据是否进入前几个节点。
五、从 Top-K 到重排的检索调优
similarity_top_k 决定初始召回节点数量。数值太小可能漏掉关键片段，太大又会让无关内容挤占模型上下文。较稳妥的方式是先适当扩大候选集合，再通过相似度阈值、元数据过滤或重排器缩小最终上下文。例如，用户限定某个项目或年份时，应先按 metadata 过滤，再执行向量检索，而不是让所有文档参与竞争。
对于术语、编号、接口名和精确错误信息，纯向量检索未必稳定，可以引入关键词与向量混合检索；对于语义接近但答案不同的节点，可以加入 rerank 阶段，让重排模型重新判断问题与候选片段的相关性。若问题需要多个章节共同作答，还可启用节点扩展：命中某个节点后，追加其前后相邻节点或父级章节，但要控制总长度。🔍
建立可重复的评测集
调优不能只靠临时提问。建议维护一个小型测试集，为每个问题标注预期文件、章节或答案依据，并记录 Hit Rate、MRR 等检索指标，同时人工检查答案是否忠于上下文。官方本地 RAG 示例也展示了使用命中率与 MRR 评估检索质量的思路，可作为落地参考。
排查失败案例时，可按三类处理：正确节点未被召回，优先检查切分、嵌入模型和查询表达；正确节点已召回但排序靠后，调整 Top-K、过滤和重排；正确上下文已进入提示词但回答仍错误，则优化提示词，明确要求仅依据材料作答，并在证据不足时直接说明无法确定。
六、工程化时容易忽略的细节
- 增量更新：根据文件哈希或修改时间识别变化，只重建新增和修改内容。
- 模型一致性：索引建立后不要随意更换嵌入模型，否则应重新生成全部向量。
- 异常处理：对扫描版 PDF、乱码、空文档和超大文件设置单独处理流程。
- 可观测性：记录检索得分、节点来源、耗时和最终上下文，方便定位瓶颈。
- 回答约束：要求模型引用来源，不允许在材料不足时自行补全事实。
总结
Ollama 与 LlamaIndex 能够组成一条清晰的本地文档问答链路，但系统效果并不只取决于生成模型。文档清洗、节点切分、元数据、嵌入模型、Top-K、混合检索与重排都会直接影响答案质量。最有效的实践路径是先完成最小闭环，再建立真实问题评测集，通过检查命中节点逐项调优。只有让检索过程可观察、可评估、可追溯，本地问答系统才能从“可以对话”的演示版本，逐步变成真正可靠的知识工具。🚀
