在 LLM 应用开发中，传统的 RAG（检索增强生成）正面临“只见树木不见森林”的瓶颈。当你询问“这篇文章的主旨是什么？”或者“这些文档之间有什么关联？”时，基于向量相似度的传统 RAG 往往因为只能检索局部片段而失效。

为了解决这个问题，微软提出了 GraphRAG。但官方实现往往较重，且依赖复杂的图数据库。今天，我将通过 AgentForce 的核心源码，教你如何仅使用轻量级的开源库 networkx 实现一套完整的 GraphRAG 流程。

✨项目地址：https://github.com/TW-NLP/AgentForce

✨AgentForce使用说明：https://blog.csdn.net/qq_43765734/article/details/157396247?sharetype=blogdetail&sharerId=157396247&sharerefer=PC&sharesource=qq_43765734&spm=1011.2480.3001.8118

---

为什么选择轻量级 GraphRAG？

1. 无环境依赖：无需安装 Neo4j 或巨大的图数据库集群，仅需 pip install networkx。

2. 工程化友好：支持 PDF/Docx/CSV 全格式解析，自带自动持久化和增量更新。

3. 全局理解力：通过社区检测（Community Detection）和 Map-Reduce 架构，实现对大规模文档库的全局总结。

---

核心架构流程

1. 结构化索引生成

我们首先将非结构化文本转化为“实体-关系”三元组。代码中利用 LLM 提取 JSON 格式的实体描述和关系强度：

# AgentForce 中的提取逻辑片段
result = {
    "entities": [{"name": "实体名", "type": "类型", "description": "描述"}],
    "relationships": [{"source": "源实体", "target": "目标实体", "description": "关系"}]
}

2. 基于 NetworkX 的图构建

利用 networkx.Graph()，我们可以轻松地将数千个实体连接在一起。通过 weight 属性记录关系的强度，这为后续的算法分析奠定了基础。

3. 层次化社区检测（关键步骤）

这是 GraphRAG 的精髓。我们使用 community_louvain 算法对图进行聚类，将紧密相关的实体归为“社区”。

• 宏观层：大范围的主题分类。

• 微观层：具体的知识点细节。

# 使用 Louvain 算法进行聚类
partition = community_louvain.best_partition(self.graph, weight='weight')

4. 社区摘要与向量索引

为每个社区生成 LLM 摘要，并将其存入 FAISS 向量索引。当用户提问时，我们不再检索原始文本块，而是检索**“社区摘要”**。

---

核心代码实战：AgentForce 实现

在 AgentForce 中，我们封装了 GraphRAGPipeline 类，实现了从文件上传到全局查询的全自动闭环。

环境准备

pip install networkx faiss-cpu python-louvain openai pypdf tiktoken

初始化与文档添加

代码支持自动保存和加载，确保你的知识库不会因为程序退出而丢失。

pipeline = GraphRAGPipeline(
    llm_api_key="your_key",
    embedding_api_key="your_key",
    llm_url="https://api.openai.com/v1",
    embedding_url="https://api.openai.com/v1",
    embedding_name="text-embedding-3-small",
    embedding_dim=1536,
    llm_name="gpt-4-turbo"
)

# 自动解析并提取图元素
pipeline.add_document("my_paper.pdf")
pipeline.rebuild_index() # 构建图、检测社区、生成摘要

全局查询：Map-Reduce 模式

当用户提问时，系统会执行以下步骤：

1. Map：检索 Top K 个相关社区，并行询问每个社区的局部答案。

2. Reduce：汇总所有社区的回答，由 LLM 融合成最终的深度报告。

answer = pipeline.global_query("分析该项目的核心技术架构和应用场景")
print(answer)

---

项目亮点：不仅仅是 Demo

AgentForce 的这套实现考虑了诸多真实开发场景：

• 增量更新：通过文件哈希（MD5）检查，避免重复解析。

• 健壮的解析：集成了 pdfplumber 和 pypdf 双重保险，支持表格提取。

• 异步友好：虽然示例为同步，但结构易于扩展为异步任务流。

---

结语

GraphRAG 不应该是昂贵且复杂的。通过 networkx 这种经典的图论库，我们可以用极低的开发成本，赋予 AI 跨文档的深度思考能力。

如果你对这套实现感兴趣，或者想直接在你的项目中使用它，欢迎访问我的 GitHub 仓库： 👉 TW-NLP/AgentForce

如果你觉得有用，请点一个 Star ⭐️ 也是对我最大的支持！