本地向量知识库

它解决什么问题

财务、审计人员手头往往躺着几十上百份制度文档——.doc/.docx 正文、规范类 PDF，还有扫描件。当被问到「某条款到底怎么规定的」时，手工翻找既慢又容易漏掉相邻条款。这类文档本身带有强结构（「第 X 章」「第 X 条」），这正是检索可以利用的信号。

核心工作方式

文档解析：.doc 走 macOS textutil，.docx 用 python-docx，.pdf 用 PyMuPDF；扫描件（每页文字不足 50 字符）会自动交给 MinerU 处理。

切片：默认使用 Chonkie RecursiveChunker 三级递归——先按「第 X 章」切章节，再按双换行切大段落，最后按单换行切条款。目标约 800 字符/chunk，最小 50 字符，15% overlap。通用 Markdown 可在配置里切换为按标题层级分割。

存储与检索：ChromaDB 持久化存储，每个项目对应一个 collection，文档完全隔离。默认用硅基流动的 BAAI/bge-m3（1024 维）做 embedding、BAAI/bge-reranker-v2-m3 做 rerank；也可经 Ollama 完全离线运行。

调用方式：提供 CLI 入口 bin/local-rag、Python API，以及 MCP Server 的 6 个 tool（create_project / delete_project / list_projects / ingest / search / rerank_search）。

LLM 协作约定：推荐 search_with_rerank 流程（top-20 检索 + rerank 到 top-10），模型必须读完候选 chunk 的完整内容，判断标准是「管理同一件事」而非「文字最相似」，并负责对「无对标」做二次判断。

适用边界与注意点

• API Key 必须通过环境变量提供，不要写进 config.yaml；
• 首次使用先 local-rag setup 或设置环境变量，再用 local-rag info 确认配置就绪；
• 项目名只能用英文、数字、点、横线（ChromaDB 限制），删除项目会连同文档和向量一并清除；
• 用 embedding 余弦相似度做 rerank 效果有限，追求精度需要 cross-encoder；
• Ollama 本地 reranker 曾出现乱码，v3 改用 embedding-based cosine similarity，属于有意识的精度取舍；
• 数据存放在用户目录下的 local-rag/ 文件夹，多用户、多机同步不在能力范围内。