Agentic GraphRAG Kit：把图谱检索变成 Java Agent 可调用的工具

项目地址：https://github.com/MarcelLeon/agentic-graphrag-kit

起因：RAG Demo 很多，但 Agent 真能接的 GraphRAG 不多

最近看 GraphRAG 和 Agentic RAG，最大的感受不是“图谱很神”，而是很多 demo 离真实 Java 业务还有一段距离：

要么是一份 Notebook，演示漂亮，但很难塞进已有 Spring 项目；
要么默认依赖一整套图数据库和云服务，本地复现成本高；
要么只展示 graph-RAG 的好答案，却没有把 plain-RAG 放在旁边同题对比。

我想要的是一个更朴素的东西：

一个 Java Agent 能直接调用的 GraphRAG 工具层。它应该有稳定 SPI、本地可跑、能和 plain-RAG 同题对比，并且不要绑定某个厂商、图数据库或内部 SDK。

于是把这个项目重新命名和整理成 Agentic GraphRAG Kit。

它是什么

Agentic GraphRAG Kit 是一个 public preview 阶段的 Java GraphRAG 工具箱，核心目标是让 Agent 在遇到多跳、血缘、影响分析问题时，可以调用图谱检索工具，而不是只靠向量相似度从散文片段里猜。

今天仓库里已经有：

GraphDatabaseClient：图数据库后端抽象，当前有 Neo4j 和零依赖 InMemory 后端；
GraphRagToolSpi：面向 Agent 的稳定工具接口，可接 Spring AI @Tool、LangChain4j 或自研 agent harness；
Spring Boot starter：提供自动装配和 Ops API；
Spring AI + Ollama 示例应用；
plain | graph | both 三种模式的 dogfooding CLI；
LLM-as-judge 评测装置，覆盖 L1/L2/L3 问题。

怎么验证

本地有 Java 17、Maven、Ollama 后，可以先装上模型：

ollama pull qwen3:8b
ollama pull nomic-embed-text

然后在仓库根目录跑：

export JAVA17_HOME=/Library/Java/JavaVirtualMachines/microsoft-17.jdk/Contents/Home

JAVA_HOME=$JAVA17_HOME mvn -pl graph-rag-core,graph-rag-spring-boot-starter -am -DskipTests install -q

JAVA_HOME=$JAVA17_HOME mvn -pl graph-rag-examples spring-boot:run \
  -Dspring-boot.run.arguments="--mode=cli --variant=both --server.port=8086"

启动后可以问：

If fact_user_activity_daily fails to load tomorrow, which top-level metrics will be impacted? Trace the lineage.

plain-RAG 往往会给出一段比较流畅的解释；graph-RAG 会把 DERIVED_FROM、BELONGS_TO、FORMULA_USES 这类显式关系链暴露出来。对血缘、依赖、影响面问题来说，这个差别比“回答是否更像人话”更重要。

目前结果

最新一次真实 Ollama 参考评测里，graph-RAG 在 L3 多跳题上相对 plain-RAG 是 +0.50，overall 是 +0.20。

这个数字我没有包装成“碾压”。项目的 NORTH_STAR 目标是 L3 ≥ +1.0，所以现在更准确的说法是：

demo 已经能展示图谱上下文的价值，但 benchmark 卖点还在继续打磨。

这种诚实状态反而是我想保留的。开源项目如果一开始就把话说满，后面只会越来越难维护。

适合谁

想把 GraphRAG 接进已有 Java / Spring AI 应用的人；
正在评估 Agentic RAG，想看工具调用和图谱检索怎么落到代码里的人；
需要向团队解释“图谱检索和普通向量检索差异”的人；
想要一个可以本地复现、带评测报告和 demo GIF 的 GraphRAG 起点的人。

不适合的场景也说清楚：

它还不是一键生产平台；
默认样例是 BI 指标血缘域，不是通用知识库的完整产品；
当前还没有宣称稳定达到 L3 +1.0 的 milestone。

为什么叫 Agentic GraphRAG Kit

这个名字的重点不是“蹭 Agentic RAG 热度”四个字，而是把项目定位说清楚：

Agentic：不是只做离线检索，而是给 Agent 一个可调用、稳定、可降级的工具面；
GraphRAG：核心差异是显式图关系，而不是单纯 embedding 相似度；
Kit：它是可以嵌入 Java 应用的工具箱，不是假装自己已经是完整平台。

如果你也在做 RAG、Agent 或知识图谱工程，欢迎试一下，也欢迎直接提 Issue 告诉我哪一步跑不顺。