本地 RAG 配 Ollama 的开源项目教程:第一次上手卡住的多半不是模型

接入与开发

讲清挑开源 RAG 项目配 Ollama 时该看哪几件事、装完先验证什么,给一套能照着走的判断顺序和排查清单。

搜「本地 RAG 配 Ollama 的开源项目教程」的人,多半已经在 GitHub 上存了三五个仓库,真装起来却卡在第一步:项目起来了,问答是空的。这篇不列项目名单,也不替你做选择,只讲清挑项目看哪几处、装完按什么顺序验证、出问题先怀疑哪一段。看完你应该能自己判断某个仓库值不值得动手。

搜这个词的人,通常已经在 GitHub 上存了三五个仓库,星标也点了,README 也翻了,真跑起来却卡在第一步:服务起来了,页面能打开,问一句什么也没有。这时候最容易犯的错是回去换项目,其实问题多半不在模型,在你没搞清楚这个项目是怎么跟 Ollama 说话的。

这篇不列项目名单,也不替你挑。只讲三件事:动手前对哪几处、装完按什么顺序验、出问题先怀疑哪一段。看完你应该能自己判断某个仓库值不值得花一个下午。

选项目之前,先把这三件事对一遍

第一件是它怎么调 Ollama。有的项目走原生接口,配置里要填地址和模型名;有的走 OpenAI 兼容层,你还得额外填一个看似无关的路径。这两种填法完全不同,把兼容层的地址塞进原生接口的格子,日志里只会告诉你连不上,不会告诉你是填错了地方。翻一眼项目里的请求代码或者配置文件模板,比看 README 快。

第二件是嵌入模型和生成模型有没有分开配。这两者混在一个输入框里的项目,看着省事,换模型的时候最坑:你把生成模型换了,向量维度可能跟着变,之前建好的索引直接对不上,库就废了。分开配的项目多一个输入框,但换模型时只动一个,风险小很多。

第三件是文档里有没有写清楚模型怎么拉、Ollama 版本有什么要求。只写「支持 Ollama」四个字、不给拉取命令的,通常要你自己试错。这不是不能装,是你得预留出折腾的时间。

  • 看请求代码或配置模板,确认走原生接口还是兼容接口,这决定地址和字段怎么填
  • 看嵌入模型和生成模型是不是两个独立配置项,混在一起的要小心换模型
  • 看有没有给模型拉取命令,没给的默认按要自己试错来估时间
  • 看分块参数能不能调,写死且不暴露的项目,文档类型一变就很难救

装完别急着传文档,先按这个顺序验

很多人装完第一件事就是拖一整个文件夹进去建索引,然后等半天,最后问答是空的,根本不知道断在哪。正确的做法是把链路拆成三段,一段一段确认。前一段不通,后一段一定不通,顺序不能跳。

  1. 只验连通配置里填好 Ollama 地址,用它自带的连接测试,或者保存后直接看服务日志。确认两边的服务能握手,这一步跟模型能力无关,纯粹是网络和地址。
  2. 单独验嵌入丢一小段文本进去建索引,看有没有真的生成向量、维度是多少。这一步失败,后面问答一定是空的,别往下走。
  3. 再验生成先不挂知识库问一句常识问题,确认生成模型本身能回话;再挂上知识库,问一句只有你那份文档里才有答案的问题。

这三步做完,你就有了一个基准状态。后面任何改动出问题,都能回到这个基准上对比,而不是从头猜。

问答答非所问,先分是检索空还是生成飘

现象先怀疑哪一段怎么确认
召回为空,模型说不知道嵌入模型或分块把检索结果单独打出来看有没有内容
召回有内容,答案还是不对生成模型或提示词看召回的片段里到底有没有答案那句话
答案沾边但不完整分块切得太碎把分块调大一点,重跑同一批问题
答案串了别的文档内容分块太大或相似度阈值太松缩分块、收紧阈值,抽十条人工看

最常见的误判是直接换更大的生成模型。实际用下来,嵌入模型没配对、分块切得不对,都会让召回质量塌下来,这时候换生成模型一点用没有,只是把排查方向带偏了。

分块大小没有通用最优值,得按文档类型定。条款类要整条保留,切断了意思就变了;问答类按一问一答切最自然;技术文档按小节切。切完别急着全量灌,抽十条人工看一眼,比什么参数都靠谱。

本地跑得动跑不动,先算显存和时间账

有个容易低估的地方:生成模型和嵌入模型是同时常驻的,两个都要占显存。只看生成模型那一栏来估,往往会发现跑起来就爆。选模型之前先把两边的占用加一起,再看机器扛不扛得住。

另一个是时间。首次建索引是批量嵌入,整条链路里最慢的就是这一段。文档量大的时候先拿一小批试,确认从建索引到问答全通了,再全量灌。不然等半小时发现配置错了,重来一遍很烦。

机器实在扛不住,有个折中做法:嵌入放本地,生成走 API。链路不用重搭,只改配置里的地址和密钥那一格。哪些模型适合这么配、各家价格怎么算,到 /price-watch 核对当时的数字,别凭印象。

跑起来之后,这几件事决定它能不能长期用

跑通只是开始。文档会更新,模型会换,配置会被人改。没有这几样东西,知识库会慢慢变脏,最后没人敢信它的答案。

  • 文档更新要能触发重新索引。只增不删、只删不重建,旧内容会一直留在库里
  • 留一份手写的问题清单,每次换模型或改分块都跑一遍,比凭感觉判断可靠
  • 记下当前用的模型名和分块参数,出问题先看是不是有人动过配置
  • 定期抽查召回结果,别只看最终答案,答案对了也可能是碰巧

这套东西不复杂,但得有人真的做。一个人维护的小项目,写在 README 里就够了;团队用的话,最好放进入库流程,不然过两个月没人记得当初为什么这么配。

下一步想先确认某个中转或本地方案的实际表现,可以到 /tools/speed-test 跑一遍连通性和延迟;要看各家模型的当前价格和可用情况,去 /price-watch 对一下,再决定本地跑还是走 API。

常见问题

开源 RAG 项目和 Ollama 一定要装在同一台机器上吗?

不一定。项目通过 HTTP 调 Ollama,只要网络能通、地址填对,分开放也行。同机省网络配置,分开则可以让一台机器专门跑模型。真出问题时先确认地址是宿主机地址还是容器内地址,容器里写 localhost 是最常见的错。

装完项目、模型也拉下来了,为什么问答还是说没有相关资料?

大概率是知识库根本没建索引,或者嵌入模型没配对导致向量是空的。按顺序查:文档有没有真的入库、嵌入接口有没有返回向量、检索时召回条数是不是零。三步里哪一步断了,都能表现成同一句「没找到」。

要不要一开始就上多模态或者复杂检索的项目?

先别。第一版目标是把「文档进去、答案出来」这条链路跑通,用最简单的向量检索就够。等你能稳定判断是检索的问题还是生成的问题,再考虑加重排、混合检索这些。一上来堆功能,出问题时根本分不清是哪一层坏的。

本文依据各平台公开文档与官方公告整理,只做中文归纳;具体做法、参数与限制以官方文档为准。