graphrag ollama怎么排查,先分清是图谱没建好还是模型没接上

接入与开发

按层排查本地 GraphRAG 配 Ollama 的卡点:实体抽取、索引构建、检索召回、生成回答四段分开测,给出判断标准和逐步动作。

本地用 Ollama 跑 GraphRAG,最容易出现的情况是命令跑完了不报错,问出来的答案却跟图谱没关系。多数人这时候去改 prompt,其实问题在更前面:实体抽没抽出来、索引落没落盘、检索有没有命中。这篇按这几段拆开讲,每段给你一个能自己动手验的动作,照着走基本能定位到卡在哪。

本地拿 Ollama 跑 GraphRAG,最气人的不是报错,是命令跑完了、日志也没红字,你问一句它答一句,但答案跟你的文档八竿子打不着。这时候很多人第一反应是去调 prompt,改半天没动静。其实问题大多在更靠前的位置:实体压根没抽出来、索引没落盘、检索根本没命中你的材料。方向搞反了,越调越乱。

这篇不铺概念,只讲怎么分段验。整条链路拆成建索引和查回答两块,每块再往下给一个能自己动手做的动作,照着走一般能定位到卡在哪一层。先别急着改代码,先让现象说话。

先把一条链路切成两段来看

GraphRAG 跟普通 RAG 的差别集中在索引那一侧,多了一道实体关系抽取,生成那侧还是老样子调模型。所以排错得分两头看:索引阶段出问题,现象是建库慢、中途报错、该生成的文件不出来;生成阶段出问题,现象是答得空、答得偏、答得跟你文档没关系。这两类现象混在一起看,基本没法下手。

最省事的判断动作是跑一次查询,把召回到的上下文单独打印出来——命中了哪些实体、哪些关系、哪些文本块,全摊开看。上下文里全是通用套话、跟你文档毫不相干,方向就在索引或检索;上下文明明对,回答却乱,那才轮到提示词和模型。有个前提:要是你的模型在 Ollama 里连普通对话都答得磕磕巴巴,先别碰 GraphRAG,回去把模型本身跑顺再说,不然所有现象都是噪音。

实体抽取这一步,先看输出文件而不是看日志

建索引会在输出目录落一批中间产物,实体表、关系表、社区报告各自成文件。日志刷得再热闹,这些文件是空的就等于白建。我见过最常见的翻车是:文件确实生成了,打开一看实体名全是「实体1」「未知类型」,或者干脆把整段原文塞进描述字段——这种不报错,但下游全废。

  1. 先看目录里有什么建完索引 ls 输出目录,确认实体、关系、社区报告这几类文件都非空,别只看命令行最后那行成功提示。
  2. 抽样打开实体表读前几条记录,实体名得是你文档里真实出现过的东西,类型分得也得像回事。全是占位词就说明抽取没生效。
  3. 对不上就查提示词语言拿中文文档配英文抽取提示词,模型容易把整段当描述吞掉,不报错但产出极差。换成中文提示,并明确要求按固定 schema 输出。

Ollama 接进来的三个配置点

把 Ollama 接进 GraphRAG,绕不开三处:base url、模型名、超时。任意一处不对,表现都差不多——跑一半卡住,或者干脆连不上,而且报错常被上层框架包一层,你在终端里看到的未必是真实原因。实际用下来,先单独验证连接比在完整流程里猜要快得多。

配置点典型症状先怎么验
base url连不上、超时、404用最简 OpenAI 兼容请求单独打一次 Ollama,确认地址和端口通
模型名报模型不存在或拉不到对着 Ollama 已拉取的列表核名字,别凭记忆填
超时与并发单条能通、批量建索引就挂先把并发和超时调小重跑,看是否还挂

判断标准很直接:单条请求通、一批量建索引就挂,多半是并发太高或者上下文超限,不是网络问题。把并发压下来、超时放开一点再试,现象会立刻变化。要是调完还是连不上,那就回到第一行,地址本身填错了。

检索回来了却没内容,问题在召回

图谱建得挺像样,查询却答得单薄,问题往往出在召回这一侧。常见两种情况:查询只走了向量那一路,图遍历根本没参与;或者召回条数设得太小,能拿到的实体和文本块就那么几条。先把检索命中的实体数、文本块数打出来,数字小得可怜,答案单薄就不奇怪了。

  • 一次只调一个参数:先加召回条数,重跑同一个问题,看答案有没有实质变化
  • 再切纯向量模式对比一次,判断图遍历到底有没有贡献
  • 本地模型上下文窗口小,召回加太多会把提示词撑爆,加召回必须配截断策略
  • 两条路都试过还是空,回头查索引文件,可能压根没建进去

一个能照着走的排查顺序

顺序比技巧重要。混着改参数最麻烦的地方是下次复现不了,你都不知道是哪一步起的作用。下面这个顺序是从底往上走,每步只改一处,改完重跑同一个问题。

  1. 确认模型可用先用单条对话确认 Ollama 里的模型能正常答,地址、模型名都对得上。
  2. 小文档建一次索引拿几页文档跑一遍,检查输出目录里实体、关系、社区报告文件非空,抽样看实体名是否真实。
  3. 打印查询上下文跑一次查询,把召回实体、关系、文本块打出来,看有没有命中你的材料。
  4. 最后才动提示词和参数前面三步都过了,再去调召回条数、提示词措辞、截断策略,一次只改一处。
排查 GraphRAG 配 Ollama,先证明每一层有产物,再谈回答好不好;没产物的层,调参数是白费。
下一步想先确认本地模型和中转线路的实际延迟,再决定要不要动 GraphRAG 参数,可以去测速页跑一次,心里有个底。

常见问题

GraphRAG 建索引跑到一半就断了,怎么定位?

先看断在哪个阶段。抽取阶段断,多半是单条请求超时或并发过高,把批大小和并发降到一,跑通再往上加;落盘阶段断,看磁盘空间和输出目录权限。把日志级别调高,让每条请求的耗时和返回状态打出来,比猜快。

Ollama 模型能正常聊天,但接进 GraphRAG 就报错,是兼容问题吗?

多数不是协议不兼容,是调用方式有差别。GraphRAG 会按固定结构要求模型返回,本地小模型经常不守格式,解析层就报错。先用极简的固定格式请求测一次,能返回就说明接口通,问题在提示词约束或模型能力,换个大点的模型对比一下。

答案看起来没错但很泛,是图谱没起作用吗?

很可能图谱没进到上下文里。把查询时实际塞给模型的上下文打印出来,如果只有零散文本块、没有实体和关系,说明走的是普通 RAG 通路。检查图检索开关和查询模式配置,再对比只开向量时的结果,两次差异明显才算图谱生效。

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