如果你正准备往大模型方向转，《我把GraphRAG接进项目后，先推翻了几个想当然》这类问题别只看热度。更重要的是判断自己该补哪块能力，以及怎么证明你真的会。

摘要

最近团队在推 AI 编程工具，Codex、Claude Code 这类东西个人用着挺爽，但一放到协作场景就各种问题。我顺势把 GraphRAG 接进项目的企业知识库模块，原本以为只是把向量检索升级成图谱检索，结果上线前踩了一堆坑。今天把复盘写下来，给还在 Demo 阶段的开发者一个参考。

目录

• 传统 RAG 的瓶颈
• 知识图谱建模
• 实体关系抽取
• 图检索增强
• 评估与优化
• 失败原因
• 适用边界
• 总结

传统 RAG 的瓶颈

先说为什么我们要上 GraphRAG。原来的系统就是纯向量检索：把文档切片、Embedding、存 Milvus，查询时召回 Top-K 再喂给 LLM。

效果上，单跳问答还行，但遇到需要多跳推理的问题就露馅了。比如用户问"我们公司的差旅政策对远程办公员工有什么特殊规定"，这需要同时关联"差旅政策"和"远程办公"两个实体，纯向量检索召回的 chunk 往往是碎片化的，模型靠概率拼凑，经常答非所问。

另一个问题是不可解释性。业务方问"为什么返回这个答案"，我们只能说是向量相似度最高，但说不清逻辑链路。这在企业场景里是个硬伤。

知识图谱建模

我们选的知识图谱建模思路是自顶向下+自底向上结合。

自顶向下：先定义本体层，确定核心实体类型和关系类型。我们定义了三类实体：

Entity Types:
- Policy（政策）
- Employee（员工）
- Benefit（福利）
- Department（部门）
- Location（地点）

Relation Types:
- covers（覆盖范围）
- belongs_to（归属）
- provides（提供）
- located_in（位于）
- applies_to（适用于）

自底向上：用开源模型从现有文档里抽取实体和关系。这里踩的第一个坑是模型选型。一开始用了 spaCy 的默认模型，召回率只有 62%，后来换成 en_core_web_trf（Transformer 版本）提到 78%，最后发现对于中文内部文档，直接用 GPT-4o-mini 做 zero-shot 抽取效果反而更好——准确率 89%，F1 0.85，虽然贵一点但值得。

实体关系抽取

抽取流程我写了一个简单的 pipeline：

from graphrag.index import build_index
from neo4j import GraphDatabase

def extract_and_load(documents: list[dict], driver: GraphDatabase.Driver):
    """抽取实体关系并写入 Neo4j"""
    # 1. 文档预处理：按段落分割
    chunks = []
    for doc in documents:
        for para in doc["content"].split("\n\n"):
            if len(para.strip()) > 50:
                chunks.append({"text": para.strip(), "source": doc["id"]})

    # 2. 调用 LLM 抽取
    entities = []
    relations = []
    for chunk in chunks:
        result = call_llm_extract(chunk["text"])
        entities.extend(result["entities"])
        relations.extend(result["relations"])

    # 3. 去重和合并
    entities = deduplicate_entities(entities)
    relations = deduplicate_relations(relations, entities)

    # 4. 写入图数据库
    with driver.session() as session:
        # 创建实体节点（带 source 属性保留溯源）
        for e in entities:
            session.run(
                "MERGE (n:Entity {id: $id}) SET n.type = $type, n.source = $source",
                id=e["id"], type=e["type"], source=e["source"]
            )
        # 创建关系边
        for r in relations:
            session.run(
                "MATCH (a:Entity {id: $src}), (b:Entity {id: $dst}) "
                "MERGE (a)-[rel:RELATED {type: $rel_type}]->(b)",
                src=r["source"], dst=r["target"], rel_type=r["type"]
            )

代码解释：这段的核心逻辑是"抽取→去重→写入"三段式。call_llm_extract 是封装好的 LLM 调用，返回标准 JSON 格式。去重环节很关键——不同文档可能用不同表述指代同一实体（比如"差旅制度"和"差旅政策"），需要基于 Embedding 相似度合并。写入时用 MERGE 而不是 CREATE，保证幂等性，方便后续增量更新。

图检索增强

检索阶段我们用 Cypher 查询替代纯向量搜索。核心思路是混合检索：先用向量召回候选实体，再用图遍历扩展关系路径。

def hybrid_search(query: str, top_k: int = 5, hop: int = 2) -> list[dict]:
    """混合检索：向量召回 + 图遍历"""
    # 1. 向量召回候选实体
    query_emb = embed(query)
    similar_entities = vector_store.query(query_emb, top_k=top_k)

    # 2. 图遍历扩展
    all_paths = []
    for entity in similar_entities:
        paths = graph_db.query(
            """MATCH path = (start:Entity {id: $eid})-[*1..$hop]->(end)
               RETURN path""",
            eid=entity["id"], hop=hop
        )
        all_paths.extend(paths)

    # 3. 路径去重和排序
    ranked_paths = rank_paths(all_paths, query_emb)
    return ranked_paths[:top_k]

这里有个取舍：跳数（hop）设多少。我们实测发现 hop=2 效果最好——跳数太少信息不够，跳数太多噪声太多。具体数字取决于你们图谱的密度，建议先画个"召回率 vs 跳数"曲线再定。

评估与优化

上线前的评估我分了三层：

第一层：单元评估。用人工标注的 200 条问答对测召回率和准确率。GraphRAG 相比纯向量检索，多跳问题准确率从 54% 提升到 73%。

第二层：集成评估。端到端跑一遍，重点看延迟。图遍历这一步是瓶颈，单次查询从 200ms 涨到 800ms，需要加缓存。

第三层：线上灰度。先对 10% 流量开 GraphRAG，对比两组指标。发现一个问题：某些模糊查询会触发图遍历超时，导致用户感知到卡顿。

排查过程如下：

• 现象：超时请求集中在"帮我看看..."这类模糊 query
• 验证：日志显示这些 query 在向量召回阶段匹配到大量低置信度实体，导致图遍历分支爆炸
• 排除：不是 Neo4j 性能问题，是召回阈值太低
• 结论：加了一层置信度过滤，向量召回的实体 confidence < 0.7 直接丢弃，超时率从 12% 降到 0.3%

失败原因

结合这次上线前的踩坑，总结三类失败原因：

业务错误：知识图谱建模时漏掉了关键关系类型。比如我们一开始没建"Policy→excludes"关系，导致"哪些福利不覆盖远程办公"这类问题答不出来。区分方法：看用户反馈里有没有"为什么答不了这个"，这类问题往往是本体层设计缺陷。

配置错误：Neo4j 的 max_execution_time 设得太短，或者向量库的 ef_search 参数没调好。区分方法：看错误日志，通常是超时或返回结果为空，不涉及模型本身。

环境错误：生产环境的 GPU 显存不够，Embedding 模型推理排队严重。区分方法：监控指标里 GPU util 飙升但吞吐上不去，换机器或换小模型能解决。

适用边界

GraphRAG 不是万能药。我的判断标准：

• 适用：需要多跳推理的企业知识库、对可解释性有要求的场景、文档间存在强关联关系的知识领域
• 不适用：纯事实查询（"公司电话是多少"）、文档量极小（<1000 篇）、团队没有运维图数据库的能力

取舍方面：GraphRAG 的维护成本显著高于纯向量检索。图谱需要定期更新，关系需要人工校验，查询逻辑需要持续优化。如果团队只有 1-2 个 AI 工程师，建议先用纯向量检索跑通 MVP，等用户反馈明确指向多跳问题后再升级。

总结

把 GraphRAG 接进项目，最大的收获不是技术本身，而是对"Demo 到上线"这个跨越的理解。个人 Demo 追求的是功能跑通，团队协作要求的是可控、可观测、可兜底。这次上线前我们推翻了三个想当然：一是"图谱建好就能用"，实际发现本体设计比想象中复杂；二是"图检索一定比向量检索快"，实际延迟反而更高；三是"准确率提升就是胜利"，没考虑到模糊查询的兜底策略。

AI 编程工具从个人试用走向团队协作，GraphRAG 也是同理。技术选型不是看 Demo 多漂亮，而是看你们团队能不能扛住上线后的维护和异常。如果你正在做类似的项目，建议先花一周时间做本体设计和小规模验证，别急着全量上。

资料展示

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

需要这份AI大模型资料清单的话，在评论区回复「清单」即可；我会根据大家的问题继续补充对应的实战内容。