聊《一个GraphRAG项目上线后，最先暴露的并不是代码问题》之前，先说一句实在的：别急着背概念，先看它在真实项目里到底解决什么问题。

摘要

我带团队做过一个GraphRAG项目，用知识图谱增强RAG的检索能力，效果确实比纯向量检索好。但上线后最先暴露的问题不是检索质量，而是权限混乱、日志缺失、交接文档不全，团队接手成本极高。这篇文章复盘GraphRAG的构建流程，也讲讲工程化落地时那些"不性感但致命"的问题。

目录

• 传统RAG的瓶颈：为什么纯向量检索不够用
• 知识图谱建模：用Neo4j存实体和关系
• 实体关系抽取：从非结构化文本到结构化知识
• 图检索增强：GraphRAG的核心查询路径
• 上线之后：权限、日志和交接文档才是真门槛
• 评估与优化：怎么判断GraphRAG值不值得做
• 总结

---

传统RAG的瓶颈：为什么纯向量检索不够用

我们团队之前用纯向量RAG做过一个企业知识库，文档分块、Embedding、向量库检索，流程很标准。但有两个问题一直解决不了：

多跳推理能力弱。 用户问"张总负责的那个项目预算超支了多少"，这种需要跨实体、跨文档推理的问题，向量检索很难命中正确答案。

幻觉问题突出。 检索到的文档片段可能和查询有部分匹配，但语义上并不相关，模型照样会基于错误上下文生成答案。

一个具体场景：用户问"公司去年有哪些供应商涉及合规问题"。纯向量检索可能返回一堆包含"供应商"和"合规"的文档片段，但真正涉及合规问题的供应商信息分散在不同文档里，靠向量相似度根本拼不出来。

这就是我们决定引入知识图谱的原因——用结构化的实体关系来增强检索。

---

知识图谱建模：用Neo4j存实体和人物

GraphRAG的关键在于图谱的建模质量。我们选的是Neo4j，图数据库本身不是难点，难点在于schema设计。

一开始我们想把所有实体都建进去，结果图谱变得极其臃肿，查询性能也差。后来做了取舍，只保留对问答有直接价值的实体类型：

(:Person)-[:WORKS_FOR]->(:Company) (:Person)-[:MANAGES]->(:Project) (:Company)-[:HAS_SUPPLIER]->(:Company) (:Project)-[:HAS_BUDGET]->(:Budget) (:Supplier)-[:INVOLVED_IN_COMPLIANCE_ISSUE]->(:Incident)

实体属性方面，Person保留姓名、部门、职位；Company保留名称、行业；Project保留名称、状态、负责人。属性不宜过多，多了反而影响查询效率。

实战建议： 图谱schema设计前，先列清楚你的问答场景需要哪些实体和关系。不要先建图谱再想怎么用，那样大概率会建出一堆用不上的东西。

---

实体关系抽取：从非结构化文本到结构化知识

这一步是GraphRAG的"苦力活"。我们从PDF、Word、Excel里读文档，用大模型做实体识别和关系抽取，把结果写入Neo4j。

抽取prompt的设计直接影响图谱质量。我们的做法是分两步：先抽实体，再抽关系，避免一次prompt信息量过大。

from langchain_community.graphs import Neo4jGraph from langchain_openai import ChatOpenAI from langchain_core.prompts import ChatPromptTemplate from langchain_core.output_parsers import JsonOutputParser llm = ChatOpenAI(model="gpt-4o-mini", temperature=0) entity_prompt = ChatPromptTemplate.from_template(""" 从以下文本中抽取实体，以JSON格式输出： 文本：{text} 要求：只抽取Person、Company、Project三类实体， 返回格式：{{"entities": [{{"name": "名称", "type": "类型", "attributes": {{}}}}]}} """) parser = JsonOutputParser() chain = entity_prompt | llm | parser result = chain.invoke({"text": "张明是技术部的负责人，他管理着A项目，该项目供应商是XX公司"}) print(result) # {"entities": [ # {"name": "张明", "type": "Person", "attributes": {"department": "技术部", "role": "负责人"}}, # {"name": "A项目", "type": "Project", "attributes": {}}, # {"name": "XX公司", "type": "Company", "attributes": {}} # ]}

关系抽取的prompt类似，重点是让模型输出标准化的关系类型，不要让它自由发挥关系名称，否则图谱里会出现"属于"、"管理"、"负责"等各种变体，后续查询没法统一。

踩坑经验： 实体名称标准化是个大麻烦。文档里可能写"张明"，也可能写"张先生"，还有可能写"张明（技术部）"。我们在抽取后加了一层去重和合并的逻辑，用LLM判断是否为同一实体的不同表述，再统一写入图谱。这一步不能省，否则图谱质量会大打折扣。

---

图检索增强：GraphRAG的核心查询路径

图谱建好后，查询流程是这样的：

1. 用户提问
2. 用LLM识别问题中的实体和关系意图
3. 在图数据库中执行Cypher查询，获取相关子图
4. 将子图信息作为上下文，结合向量检索结果，一起送入LLM生成答案

// 示例：查询某供应商涉及的合规问题 MATCH (s:Company)-[:INVOLVED_IN_COMPLIANCE_ISSUE]->(i:Incident) WHERE s.name = 'XX公司' RETURN i.incident_type AS 问题类型, i.description AS 描述, i.date AS 日期 ORDER BY i.date DESC

图检索的结果是结构化的，模型生成答案时有据可依，幻觉率明显下降。我们做过对比测试，同样是回答供应商合规问题，纯向量RAG的准确率在60%左右，GraphRAG提升到了85%。

但图检索也有局限：图谱覆盖不到文档里的内容就查不到。 如果某份文档里没有提到供应商名称，而是用代号"供应商A"，那图谱里就没有对应的实体，这类问题还是会退化到向量检索。

判断标准： GraphRAG适合实体关系明确、多跳推理需求多的场景。如果知识库主要是文档问答、事实查询，纯向量RAG可能就够了，没必要上图谱。

---

上线之后：权限、日志和交接文档才是真门槛

这是这篇文章最想讲的部分。

我们的GraphRAG项目代码本身没什么问题，模型调用、图谱查询、答案生成都跑通了。但上线后，团队接手时遇到了几个致命问题：

权限管理混乱。 图谱数据库的账号密码硬编码在配置文件里，生产环境和测试环境共用一个库。API调用的密钥分散在多个文件，新人根本不知道有哪些key、分别用在什么地方。

日志几乎为零。 查询链路没有结构化日志，出了问题只能靠打印语句排查。模型调用的输入输出、图谱查询的耗时、向量检索的top-k结果，这些关键信息全都没有记录。

交接文档缺失。 图谱schema是边做边定的，没有设计文档。实体抽取的prompt改了十几版，只有一个人知道哪版是最新的。向量库的索引参数、分块策略、相似度阈值，全在代码注释里，新人根本找不到。

这些问题不是GraphRAG特有的，任何大模型项目都会遇到。但GraphRAG因为涉及多个组件（LLM、图数据库、向量库），链路更长，问题会被放大。

我们的补救措施：

1. 把所有密钥迁移到环境变量，用Vault管理，权限按角色分配
2. 用OpenTelemetry做链路追踪，记录每次查询的完整路径和耗时
3. 补写三样东西：图谱schema文档、prompt版本说明、部署手册

这部分工作占了项目后期40%的时间，但决定了项目能不能真正交付给团队维护。

---

评估与评估与优化：怎么判断GraphRAG值不值得做

我们用了三套指标来评估：

准确率。 手动标注了200个测试问题，分别用纯向量RAG和GraphRAG回答，人工评判答案是否正确。GraphRAG在需要多跳推理的问题上优势明显，但在简单事实查询上提升有限。

延迟。 图查询增加了额外的网络开销，平均响应时间比纯向量RAG慢了200-300ms。对于实时性要求高的场景，这个延迟需要评估。

维护成本。 图谱需要持续更新，文档变更后要重新抽取实体和关系。如果文档更新频繁，维护成本会显著上升。

结论： GraphRAG适合问答场景复杂、对准确率要求高、文档更新频率可控的项目。如果你的知识库主要是简单问答，或者文档每天都在变，先别急着上图谱。

---

总结

GraphRAG的本质是用知识图谱的结构化能力弥补向量检索的不足。技术上不难，难的是图谱建模的质量和工程化落地的细节。

我见过太多项目Demo跑得很漂亮，上线后却因为权限、日志、文档的问题翻车。GraphRAG涉及多个组件，链路更长，对这些工程化问题的容忍度更低。

如果你在考虑做GraphRAG，我的建议是：

1. 先明确你的场景是否需要多跳推理，不要为了用图谱而用图谱
2. 图谱schema设计要克制，只保留对问答有价值的实体和关系
3. 实体抽取的标准化和去重不能省，这是图谱质量的基础
4. 权限、日志、文档从第一天就开始做，别等上线再补

代码可以重写，但团队接手成本一旦堆积，后期很难清账。

资料展示

下面是我整理的AI大模型学习资料和工具包预览，适合收藏后按主题逐步学习。

如果你想看完整资料目录，可以在评论区留言「资料」；也欢迎告诉我你更关注AI大模型里的哪类内容。