myLocalKb 如何通过 Ollama 和向量搜索实现离线文档问答？

myLocalKb 是一个面向单用户的离线文档问答原型。它用 FastAPI 提供本机后端，用原生 HTML、CSS 和 JavaScript 构建界面，通过 Ollama 在本机生成嵌入与答案，再把向量和文档元数据写入本地 ChromaDB。完成依赖和模型下载后，日常上传、检索和问答不需要云端 LLM API 或密钥。

先确认适用范围

项目当前定位是 early alpha 和本地原型，适合个人资料检索、RAG 学习与小规模实验，不是生产级文档管理系统。它没有多用户权限、团队空间、OCR、成熟审计或高可用部署能力。

支持上传 PDF、DOCX、PPTX、TXT 和 Markdown。扫描版 PDF 没有可提取文本时无法正常入库，复杂 Office 排版也可能在纯文本提取阶段丢失。

离线链路由哪些组件组成

环节	默认组件	本地位置
网页界面	原生 HTML、CSS、JavaScript	FastAPI 静态页面
聊天模型	Ollama 的 qwen3:4b	本机 Ollama 服务
嵌入模型	nomic-embed-text	本机 Ollama 服务
向量检索	ChromaDB 余弦相似度	data/chroma_db
原始上传	本地文件副本	data/documents

仓库没有引入 OpenAI、Anthropic、Gemini、Cohere 或托管向量数据库 SDK。ChromaDB 配置还显式关闭了匿名遥测。不过，初次安装 Python 依赖和下载 Ollama 模型仍需要联网。

准备 Python 与 Ollama

项目推荐 Python 3.11。默认模型约需要 4 GB 可用磁盘空间，8 GB 内存是更现实的起点。Windows 上使用较新的 Python 时，固定版本的 ChromaDB 依赖可能尝试本地编译并要求 C++ 构建工具。

克隆仓库后，可使用提供的初始化脚本：

git clone 项目仓库地址
cd myLocalKb
bash setup.sh

Windows PowerShell 使用：

cd myLocalKb
.setup.bat

脚本会安装 Python 依赖，创建 data 目录，并拉取 qwen3:4b 与 nomic-embed-text。执行前应审阅脚本内容和模型许可。

启动本地服务

日常运行需要 Ollama 与 FastAPI 两个进程。先启动 Ollama：

ollama serve

再在仓库目录启动应用：

python -m uvicorn backend.main:app --host 127.0.0.1 --port 8000

浏览器访问本机 8000 端口即可使用。服务默认只绑定 127.0.0.1，不要为了手机或局域网访问而随意改为全网卡，因为应用没有为公网暴露设计认证和访问控制。

配置模型与检索参数

运行设置集中在 config.yaml。默认聊天温度为 0.1，最大生成长度为 2048，文档按 512 个字符切块，相邻块重叠 64 个字符，每次检索 5 个片段。

llm:
  model: qwen3:4b
  temperature: 0.1
  max_tokens: 2048

embeddings:
  model: nomic-embed-text

retrieval:
  chunk_size: 512
  chunk_overlap: 64
  top_k: 5

低内存设备可改用 phi3:mini；拥有约 16 GB 内存的设备可以尝试 qwen3:8b。修改聊天模型后需先用 Ollama 拉取相应模型。更换嵌入模型会改变向量维度和语义空间，通常应重新建立已有文档索引。

上传文档时发生了什么

1. 浏览器把文件提交到文档上传接口。
2. 后端以唯一标识加原文件名保存到本地 documents 目录。
3. 解析器从 PDF、DOCX、PPTX 或文本文件提取文字。
4. 分块器按字符窗口切分，并保留重叠上下文。
5. Ollama 为每个分块生成本地嵌入。
6. ChromaDB 保存向量、文件名、页号和分块序号。

界面显示文件名不代表索引一定完整。上传后应等待处理完成，再用文件中特有的词语进行检索测试。

不同格式的解析边界

• PDF 使用 pypdf 逐页提取文本，图片型扫描页不会自动 OCR。
• DOCX 读取普通段落文本，不会完整保留表格、文本框和版式关系。
• PPTX 遍历幻灯片文本框并附加讲者备注，图表和图片内容不会自动理解。
• TXT 与 Markdown 按空行拆分，无法保证所有编码和复杂语法都被保留。

如果问题依赖图表、表格或版面，应先把关键内容人工转成清晰文本，或使用支持视觉解析的上游流程。

问题如何经过向量搜索

提问后，系统先用 nomic-embed-text 为问题生成向量，再在 ChromaDB 中按余弦距离取回前若干片段。片段连同文件名和页号被拼入严格提示词，最后交给 qwen3:4b 生成答案。

默认 top_k 为 5。值太小可能遗漏跨段信息，值太大会把无关内容塞进上下文。调整时应使用固定测试题集，记录正确片段是否进入前几名，而不是只根据回答读起来是否流畅。

防幻觉机制能做到什么

后端有三层保守措施：没有任何检索片段时直接返回未找到信息；系统提示要求模型只依据片段回答；模型没有输出来源区时，后端会追加检索结果中的文件名。

这些措施不能彻底消除幻觉。只要向量检索返回了相关性较弱的片段，模型仍可能过度推断；后端追加的文件名也只能证明该文件被检索到，不能证明答案中的每个句子都由它支持。

设计一组可靠验收题

1. 精确题：询问某页独有的日期、编号或人名。
2. 改写题：用同义表达询问原文事实，验证语义召回。
3. 跨页题：要求组合相邻两页的信息。
4. 冲突题：导入两份说法不同的文件，观察答案是否指出差异。
5. 无答案题：询问知识库中不存在的信息，检查拒答。

验收时同时记录检索片段、来源文件和最终回答。若片段错误，应调整解析、分块或检索；若片段正确而回答错误，再考虑聊天模型和提示词。

数据删除与备份

删除接口会按文档标识清理 ChromaDB 中的分块，但使用者仍应验证本地上传副本是否同步移除。备份时要同时保存配置、documents 和 chroma_db，单独复制原文件无法恢复索引。

敏感资料还应依赖操作系统账户权限和磁盘加密。即使应用不联网，本机上的其他进程、备份软件和恶意扩展仍可能读取数据目录。

常见故障排查

现象	优先检查
无法连接模型	Ollama 是否运行、模型名是否已拉取
首次回答很慢	模型冷启动、内存和磁盘速度
PDF 没有内容	是否为扫描版、页面能否复制文字
答案总是未找到	索引状态、嵌入模型和 top_k
引用看似不准确	打开对应文件与页号核对原文

myLocalKb 用较少组件展示了一条清晰的离线 RAG 路径：本地解析、本地嵌入、本地向量检索和本地生成。把它用好需要承认 alpha 阶段的解析与引用限制，并通过检索级测试验证证据，而不是只凭最终答案判断系统是否可靠。