GraphRAG 配 Neo4j：为 AI Agent 构建图知识底座实战

1. 为什么要在 AI Agent 里用 GraphRAG 配 Neo4j

1.1 从向量检索的瓶颈说起

做过 RAG 的人大概都有过这种体验：用户问一个需要跨文档、跨段落推理的问题，比如“A 项目的负责人之前在哪个团队做过类似的技术选型”，普通的向量检索就开始露怯了。它能把语义相近的文本块捞回来，但它不理解“负责人”“团队”“技术选型”之间的关系。向量数据库存的是孤立文本块的嵌入，块与块之间的连接在检索时是丢失的。

GraphRAG 要解决的就是这个问题。它的核心思路是把知识表示成实体—关系—实体的图结构，检索时沿着图的边做多跳遍历，把散落在不同文档里的关联信息串起来。而 Neo4j 作为目前最成熟的原生图数据库，天然适合承载这层图结构。我在几个 AI Agent 项目里把向量检索和 Neo4j 图检索做了组合，实测下来，对于需要多跳推理的问答场景，答案的完整度和准确率提升非常明显。

这篇内容适合两类人：一是已经在做 RAG、想往 GraphRAG 方向升级的开发者；二是正在搭建 AI Agent、需要给 Agent 配一套靠谱知识底座的人。我会从整体设计讲到 Neo4j 的具体落地，包括安装配置、图模型设计、和 Agent 的对接方式，以及我踩过的那些坑。

1.2 GraphRAG 和普通 RAG 的本质区别

普通 RAG 的流程是：文档切块 → 向量化 → 存向量库 → 查询时做相似度检索 → 把 Top-K 块塞进 prompt。它的知识是扁平的，检索单元是文本块。

GraphRAG 多了一层：在切块之后，先做实体抽取和关系抽取，把知识组织成图，存进图数据库。查询时有两种模式——一种是局部检索，从命中的实体出发沿边扩展；另一种是全局检索，利用图的社区结构做摘要式回答。Neo4j 在这里承担的是图存储和图查询引擎的角色，它的 Cypher 查询语言让多跳遍历写起来非常直观。

打个比方，普通 RAG 像在图书馆里按关键词找书，找到几本内容相近的就给你；GraphRAG 像有个图书管理员，不仅知道每本书讲什么，还知道这本书引用了哪本书、作者之间是什么关系，你问一个问题，他能顺着关系链把相关的书都给你串起来。

1.3 为什么选 Neo4j 而不是别的图存储

市面上图存储的选择不少，我选 Neo4j 主要看三点。第一是Cypher 的表达力，写多跳查询、路径匹配非常顺手，比 Gremlin 那种偏底层的遍历语言好上手太多。第二是生态成熟度，Neo4j 有官方的 Python driver、有 Desktop 可视化工具、有 Bloom 做图探索，调试图数据的时候能直接看到节点和边，这个体验是很多新兴图库给不了的。第三是和 LLM 工具链的契合，LangChain、LlamaIndex 这些框架都有现成的 Neo4j 集成，不用自己从零写适配层。

当然它也有代价，社区版在集群、多数据库这些企业特性上有阉割，但对于个人项目和中型 Agent 应用，社区版完全够用。下面我会具体讲怎么装、怎么配。

2. Neo4j 安装与配置的完整路径

2.1 选 Desktop 还是 Server：先想清楚用途

Neo4j 的安装方式主要有两种，选错了后面会反复折腾。Neo4j Desktop是一个带图形界面的桌面应用，适合本地开发、学习、调试图模型，它内置了数据库实例管理、Browser 查询界面、插件管理。Neo4j Server（社区版）是纯服务端，适合部署到服务器上给 Agent 长期调用。

我的建议是：开发阶段用 Desktop，因为你能随时打开 Browser 看数据长什么样，调 Cypher 的时候有即时反馈；等图模型稳定了、要上线了，再迁到 Server。两者用的都是同一套 Cypher 和驱动，迁移成本很低。

注意：Desktop 和 Server 的配置文件位置不一样，Desktop 里每个实例的配置在实例目录下的 conf 文件夹，Server 的在安装目录的 conf 下。改端口、改内存这些操作别找错地方。

2.2 Neo4j Desktop 下载与安装步骤

Desktop 的下载去官网的部署页面找，选对应操作系统的安装包。Windows 是 exe，macOS 是 dmg，Linux 有 AppImage 和 tar.gz。安装过程没什么坑，一路下一步就行。

装完之后第一次打开，它会让你创建一个本地实例（Local DBMS）。这里有几个参数要留意：

• 密码：至少 8 位，记牢，后面 Agent 连接要用。忘了的话得删实例重建，很麻烦。
• 版本：选 5.x 的稳定版，别追最新的 beta。5.x 对 Cypher 的支持和驱动兼容性都更成熟。
• 插件：如果要做图算法（比如社区发现、最短路径），把 Graph Data Science 插件勾上。

创建完实例点 Start，等状态变成绿色 Running，就可以点 Open 打开 Neo4j Browser 了。Browser 是一个网页版的查询界面，地址通常是http://localhost:7474，第一次进去会让你用默认账号neo4j和刚才设的密码登录。

2.3 Neo4j Server 社区版在 Linux 上的部署

如果直接上服务器，用社区版的 tar.gz 包最灵活。下载解压之后，目录结构大概是这样的：

neo4j-community-5.x/ ├── bin/ # 启动脚本 ├── conf/ # 配置文件 ├── data/ # 数据存储 ├── logs/ # 日志 ├── plugins/ # 插件 └── import/ # 批量导入用的目录

启动前先改conf/neo4j.conf里几个关键配置。默认它只监听 localhost，如果 Agent 跑在另一台机器上，得放开监听地址：

# 允许远程连接，0.0.0.0 表示监听所有网卡 server.default_listen_address=0.0.0.0 # Bolt 协议端口，Python driver 默认连这个 server.bolt.listen_address=:7687 # HTTP 端口，Browser 用 server.http.listen_address=:7474

内存配置也很关键，Neo4j 默认的堆内存偏小，图数据一多就容易 OOM。在conf/neo4j.conf里调整：

# 堆内存初始值和最大值，根据机器内存来，一般给物理内存的 1/4 到 1/2 server.memory.heap.initial_size=2G server.memory.heap.max_size=4G # 页面缓存，用于缓存图数据，越大查询越快 server.memory.pagecache.size=2G

改完配置用bin/neo4j start启动，bin/neo4j status看状态，bin/neo4j stop停止。日志在logs/neo4j.log，启动失败先看这个。

提示：社区版默认只允许一个数据库，叫neo4j。如果你需要多个库隔离不同 Agent 的知识，社区版做不到，得用企业版或者干脆起多个实例。

2.4 连接验证与 Python 驱动安装

服务起来之后，先用 Browser 验证一下。浏览器打开http://服务器IP:7474，输入账号密码，能进去就说明服务正常。然后在查询框里跑一句：

RETURN "hello neo4j" AS greeting

能返回结果就说明 Cypher 引擎工作正常。

Python 这边装官方驱动：

pip install neo4j

连接测试代码：

from neo4j import GraphDatabase driver = GraphDatabase.driver( "bolt://localhost:7687", auth=("neo4j", "你的密码") ) with driver.session() as session: result = session.run("RETURN 1 AS num") print(result.single()["num"]) driver.close()

能打印出 1 就说明 Agent 侧的通路打通了。这里用 Bolt 协议而不是 HTTP，因为 Bolt 是二进制协议，传输效率高，适合 Agent 频繁查询的场景。

3. 为 GraphRAG 设计图模型与数据写入

3.1 实体关系图怎么设计才不返工

图模型设计是 GraphRAG 里最容易返工的一步。我见过太多人上来就建节点，结果数据灌了一半发现关系方向反了、属性放错地方了，只能推倒重来。这里分享一套我总结的设计顺序。

先确定实体类型。从你的文档里抽出高频名词，归类成节点标签。比如做技术文档问答，实体类型可能是Project、Person、Technology、Team。做企业知识库，可能是Employee、Department、Product、Customer。

再确定关系类型。关系是动词或介词短语，比如WORKS_ON、BELONGS_TO、USES、DEPENDS_ON。关系是有方向的，Person -[:WORKS_ON]-> Project和反过来意思完全不同，设计时要想清楚。

最后确定属性。节点和关系都可以带属性。节点属性比如Person.name、Project.status；关系属性比如WORKS_ON.since、DEPENDS_ON.version。属性不要设计得太细，够检索和过滤用就行，太细会让写入变慢。

一个技术文档场景的图模型示例：

// 创建节点 CREATE (p:Person {name: "张三", role: "架构师"}) CREATE (proj:Project {name: "订单系统重构", status: "进行中"}) CREATE (tech:Technology {name: "Neo4j", category: "图数据库"}) // 创建关系 CREATE (p)-[:WORKS_ON {since: "2024-01"}]->(proj) CREATE (proj)-[:USES {version: "5.x"}]->(tech)

注意：节点标签和关系类型一旦有数据了再改，成本很高。Neo4j 改标签要重写所有相关节点，改关系类型要重建关系。所以设计阶段多花点时间，把实体和关系列全了再动手。

3.2 从文档到图的抽取流程

GraphRAG 的图数据不是手写的，是从文档里自动抽出来的。流程分三步：切块、抽取、写入。

切块和普通 RAG 一样，按语义边界切，块大小控制在 500 到 1000 字。块太大抽取时容易漏实体，太小关系会断。

抽取是核心。用 LLM 做实体和关系抽取，prompt 要设计得足够明确。我常用的抽取 prompt 结构是这样的：

EXTRACT_PROMPT = """ 从下面的文本中抽取实体和关系。 实体类型限定为：Person, Project, Technology, Team 关系类型限定为：WORKS_ON, USES, BELONGS_TO, DEPENDS_ON 输出 JSON 格式： { "entities": [{"name": "", "type": "", "properties": {}}], "relations": [{"source": "", "target": "", "type": "", "properties": {}}] } 文本： {text} """

抽取完之后要做实体消歧。同一个实体在不同文档里可能有不同叫法，比如“Neo4j”和“neo4j 图数据库”指的是一个东西。简单做法是用字符串相似度合并，靠谱做法是用嵌入向量算相似度，超过阈值就合并。

写入用 Cypher 的MERGE而不是CREATE。MERGE是“存在就匹配，不存在就创建”，能避免重复节点。批量写入时用参数化查询，别拼字符串，既安全又快：

def write_entity(tx, name, label, props): tx.run( f"MERGE (n:{label} {{name: $name}}) SET n += $props", name=name, props=props ) with driver.session() as session: session.execute_write(write_entity, "张三", "Person", {"role": "架构师"})

3.3 向量索引和图索引的混合存储

GraphRAG 不是只用图，向量检索还是要保留的。Neo4j 5.x 原生支持向量索引，可以把文本块的嵌入直接存在节点上，建向量索引做相似度检索。这样图检索和向量检索在同一个库里完成，不用维护两套存储。

建向量索引的 Cypher：

CREATE VECTOR INDEX chunk_embedding IF NOT EXISTS FOR (c:Chunk) ON (c.embedding) OPTIONS { indexConfig: { `vector.dimensions`: 1536, `vector.similarity_function`: 'cosine' } }

维度要和你用的嵌入模型对齐，OpenAI 的 text-embedding-3-small 是 1536 维。相似度函数一般用 cosine。

查询时先用向量索引找相似块，再从块关联的实体出发做图遍历：

// 向量检索 CALL db.index.vector.queryNodes('chunk_embedding', 5, $query_vector) YIELD node AS chunk, score // 从块关联的实体出发做一跳扩展 MATCH (chunk)-[:MENTIONS]->(entity)-[r]-(related) RETURN chunk.text, entity.name, type(r), related.name, score

这种混合检索的好处是，向量负责“找得到”，图负责“连得起来”。实测下来，对于“谁负责的项目用了什么技术”这类问题，混合检索的召回率比纯向量高出一大截。

4. 把 Neo4j 接进 AI Agent 的实操

4.1 Agent 调用图检索的两种模式

Agent 用 Neo4j 有两种集成深度。浅层是工具调用，把图检索封装成一个 tool，Agent 需要的时候调一下。深层是检索前置，Agent 每次回答前都先走一遍图检索，把结果作为上下文。

浅层适合通用 Agent，图只是它众多工具之一。用 LangChain 封装成 tool 大概是这样：

from langchain.tools import tool from neo4j import GraphDatabase driver = GraphDatabase.driver("bolt://localhost:7687", auth=("neo4j", "密码")) @tool def graph_search(entity_name: str) -> str: """根据实体名查询图中的关联信息""" with driver.session() as session: result = session.run( """ MATCH (n {name: $name})-[r]-(m) RETURN n.name AS source, type(r) AS rel, m.name AS target LIMIT 20 """, name=entity_name ) return "\n".join( f"{row['source']} -{row['rel']}-> {row['target']}" for row in result )

深层适合知识密集型 Agent，比如企业问答、技术支持。做法是在 Agent 的检索节点里，把向量检索和图检索的结果合并后一起塞进 prompt。

4.2 多跳查询的 Cypher 写法与性能

GraphRAG 的价值在多跳，但多跳查询写不好性能会崩。我踩过的坑是：不加限制的变长路径查询，在图上节点一多就变成全图扫描。

看一个反面例子：

// 危险：不限制跳数和结果数 MATCH (a {name: "张三"})-[*]-(b) RETURN b

这个查询会从张三出发，沿着任意关系、任意跳数遍历，图一大直接卡死。正确写法是限制跳数和关系类型：

// 安全：限制 1 到 3 跳，限定关系类型，限制返回数量 MATCH path = (a:Person {name: "张三"})-[r:WORKS_ON|USES*1..3]-(b) RETURN b.name, length(path) AS hops ORDER BY hops LIMIT 50

跳数一般控制在 3 跳以内，超过 3 跳的结果相关性就很弱了，而且性能下降明显。关系类型一定要限定，别用[*]这种通配。

还有一个性能技巧是给高频查询的属性建索引：

CREATE INDEX person_name IF NOT EXISTS FOR (p:Person) ON (p.name)

实体名是最常用的查询入口，建了索引之后按名字查节点从全表扫描变成索引查找，快很多。

4.3 让 Agent 自己决定查图还是查向量

高级一点的玩法是让 Agent 根据问题类型自己选检索策略。事实型问题（“X 是什么”）走向量，关系型问题（“X 和 Y 什么关系”）走图，混合型问题两个都走。

实现方式是在 Agent 的规划节点里加一个路由判断，用 LLM 做意图分类：

ROUTE_PROMPT = """ 判断下面的问题属于哪种类型： - fact: 询问某个实体的定义、属性 - relation: 询问实体之间的关系、关联 - hybrid: 既需要事实也需要关系 只输出类型词。 问题：{question} """

路由判断的准确率实测能到 85% 以上，剩下 15% 走 hybrid 兜底也不会错。这个设计让 Agent 在简单问题上不浪费图查询开销，在复杂问题上又能用上图的优势。

5. 常见问题与排查技巧实录

5.1 连接类问题速查

Agent 连不上 Neo4j 是最常见的问题，我整理了一张排查表：

提示：改了neo4j.conf之后一定要重启服务才生效，neo4j restart。我见过有人改完配置直接测，测半天没反应，最后发现没重启。

5.2 写入性能与数据一致性

批量写入图数据时，如果一条一条MERGE，几千个节点能跑几分钟。优化手段有两个：一是用UNWIND把批量数据展开成一次查询，二是开事务批量提交。

// 批量写入：一次传一批实体 UNWIND $entities AS e MERGE (n:Entity {name: e.name}) SET n += e.props

Python 侧把实体攒成列表，一次传进去：

def batch_write(tx, entities): tx.run( "UNWIND $entities AS e MERGE (n:Entity {name: e.name}) SET n += e.props", entities=entities ) with driver.session() as session: session.execute_write(batch_write, entity_list)

实测下来，批量写入比逐条写入快 10 倍以上。批次大小控制在 1000 到 5000 之间，太大反而会因为事务日志膨胀变慢。

数据一致性方面，实体消歧没做好会导致图里出现重复节点，同一个实体有好几个节点，关系就断了。定期跑一个查重查询：

MATCH (a:Person), (b:Person) WHERE a.name = b.name AND id(a) < id(b) RETURN a.name, id(a), id(b)

发现重复就用apoc.refactor.mergeNodes合并（需要装 APOC 插件）。

5.3 图模型设计的三个反模式

第一个反模式是万能节点。有人图省事，所有实体都用同一个标签Entity，类型放在属性里。这样查询时没法按标签过滤，性能差，而且 Cypher 的可读性也没了。正确做法是每种实体类型一个标签。

第二个反模式是关系当属性。比如把“张三在 A 项目”写成Person.project = "A"，而不是建WORKS_ON关系。这样就没法做多跳遍历了，图退化成表。凡是需要遍历的关联，都要建成关系。

第三个反模式是过度建模。有人把每个属性都建成节点，比如把“进行中”这个状态建成Status节点。这会让图变得极其臃肿，查询要绕好几跳。状态、日期、数值这类简单值，放属性里就行，别建节点。

5.4 检索结果不相关的调优思路

GraphRAG 检索出来的东西不相关，通常出在三个环节。抽取环节实体抽错了或关系方向反了，这个要回去看抽取 prompt 和样本。消歧环节把不该合并的实体合并了，导致关系串味，这个要调相似度阈值。检索环节跳数太多引入了噪声，这个要收紧跳数限制和结果数量。

我的调优顺序是：先看抽取质量，随机抽 20 个块人工核对实体和关系；再看消歧，查有没有错误合并；最后调检索参数，跳数从 1 开始往上加，加到结果开始变噪就停。

6. 我在实际项目中的几点体会

GraphRAG 配 Neo4j 这套组合，我最大的体会是图模型的质量决定了整个系统的上限。向量检索差点还能靠多召回几个块补救，图模型设计错了，后面怎么调 prompt 都救不回来。所以前期在实体关系设计上多花的时间，后面都会以调试时间的减少还回来。

另一个体会是别一上来就追求全自动抽取。我第一个项目想完全靠 LLM 自动抽实体关系，结果噪声很大。后来改成半自动：LLM 抽，人工审核一批样本，把抽取规则固化下来再全量跑，质量稳定多了。对于知识密集型的 Agent，这一步人工投入是值得的。

最后分享一个小技巧：Neo4j Browser 里可以用CALL db.schema.visualization()把整个图模型可视化出来，节点标签和关系类型一目了然。每次改完图模型跑一下这个，能快速发现设计上的问题，比翻代码直观多了。