微软GraphRAG 端到端使用及自用工具类

之前我写过一篇端到端构建知识图谱的文章，有人在后台问我关于GraphRAG的相关使用，今天我来讲一下微软的GraphRAG的使用。以及我自己写的一些工具类，我把它们封装成了每个都可以单独使用的文件，有需要的可以直接拿来用 仓库链接。

一. 环境准备

1.安装 Python 环境

要求 Python 3.10+（推荐 3.11）。

# 建议创建虚拟环境
python3 -m venv graphrag_env
source graphrag_env/bin/activate  # Linux/Mac
graphrag_env\Scripts\activate     # Windows

2.安装依赖

GraphRAG 使用 poetry 管理依赖。

pip install poetry# 克隆官方仓库
git clone https://github.com/microsoft/graphrag.git
cd graphrag# 安装依赖
poetry install

3.配置 LLM API Key

GraphRAG 默认支持 Azure OpenAI 和 OpenAI。

新建 .env 文件（或在环境变量里设置）：

OPENAI_API_KEY=your_openai_key
OPENAI_API_BASE=https://api.openai.com/v1
OPENAI_API_MODEL=gpt-4o-mini   # 或 gpt-4o, gpt-5 等
OPENAI_EMBEDDING_MODEL=text-embedding-3-small

如果用 Azure OpenAI，替换为：

AZURE_OPENAI_API_KEY=your_azure_key
AZURE_OPENAI_ENDPOINT=https://xxx.openai.azure.com/
AZURE_OPENAI_DEPLOYMENT=gpt-4o
AZURE_OPENAI_EMBEDDING_DEPLOYMENT=text-embedding-3-small

---

二. 初始化项目

在工作目录（例如 ~/my_graphrag）执行：

graphrag init --root ./my_graphrag

它会生成一个 settings.yaml 配置文件和数据目录结构：

my_graphrag/├── settings.yaml├── input/         # 放文档├── output/        # 索引和结果└── state/         # 中间状态

如果没有对应的目录结构手动创建 mkdir -p my_graphrag/input

---

三. 文档上传 & 索引构建

把你要问答的文档（txt/pdf/markdown 等）放到 input/ 目录。

例如：

input/└── demo.txt

然后执行索引构建：

  graphrag index --root ./my_graphrag

GraphRAG 会自动完成：

• 文档切分（text units）
• 实体 & 关系抽取
• 构建知识图谱
• 社区检测 & 摘要生成
• 向量存储

最终结果会放在 output/ 目录。

---

四. 问答（CLI 方式）

GraphRAG 支持 local / global / drift 三种查询模式。

示例：

# 本地检索（local）
graphrag query --root ./my_graphrag --method local -q "请总结一下报告中公司的主要业务？"# 全局检索（global）
graphrag query --root ./my_graphrag --method global -q "公司和竞争对手的差异是什么？"# 漂移搜索（drift）
graphrag query --root ./my_graphrag --method drift -q "哪些部门与AI相关？"

结果会直接输出在终端

---

五. 代码中调用 GraphRAG

环境搭建好以后，就可以在我们的项目中根据需要来使用GraphRAG的能力，下边我罗列了一些工具类。

工具概览

工具名称	主要功能	适用场景
simple_graphrag_integration.py	核心查询服务	在应用中集成 GraphRAG 问答功能
view_graph.py	基础数据查看	快速了解知识图谱的基本统计信息
visualize_graph.py	图谱可视化	生成知识图谱的网络图像
view_communities.py	社区分析	查看和分析图谱中的社区结构
parquet_viewer.py	文件查看器	查看和转换 GraphRAG 输出文件
export_to_neo4j.py	Neo4j 集成	将知识图谱导入到 Neo4j 数据库
export_to_csv_for_neo4j.py	CSV 导出	生成 Neo4j 兼容的批量导入文件

核心工具详解

1. simple_graphrag_integration.py - 智能问答核心

主要类：

# 基础服务
service = SimpleGraphRAGService("./graphrag/my_graphrag")
result = service.query("什么是RAG？", method="auto")# 聊天机器人
chatbot = SimpleGraphRAGChatBot("./graphrag/my_graphrag")
response = chatbot.chat("介绍一下这个知识库")

查询方法：

• local - 基于相关实体回答具体问题
• global - 基于社区报告回答概括性问题
• auto - 自动选择最适合的方法

核心功能：

• 自然语言问答
• 上下文智能构建
• 对话历史管理
• 多种查询策略

2. view_graph.py - 基础数据查看

def view_entities():df = pd.read_parquet("./graphragmy_graphrag/output/entities.parquet")print(f"总实体数: {len(df)}")print(df[['title', 'type', 'description']].head())def view_relationships():df = pd.read_parquet("./graphragmy_graphrag/output/relationships.parquet")print(f"总关系数: {len(df)}")print(df[['source', 'target', 'description']].head())

输出示例：

=== 实体信息 ===
总实体数: 68title    type                description
0                 RAG  CONCEPT  检索增强生成技术...
1                 LLM  CONCEPT  大语言模型...

3. visualize_graph.py - 图谱可视化

def create_network_graph():"""创建网络图可视化"""# 读取数据entities_df = pd.read_parquet("my_graphrag/output/entities.parquet")relationships_df = pd.read_parquet("my_graphrag/output/relationships.parquet")# 创建图G = nx.Graph()for _, entity in entities_df.iterrows():G.add_node(entity['title'])for _, rel in relationships_df.iterrows():G.add_edge(rel['source'], rel['target'])# 可视化plt.figure(figsize=(15, 10))pos = nx.spring_layout(G, k=3, iterations=50)nx.draw(G, pos, with_labels=True, node_color='lightblue')plt.savefig('knowledge_graph.png', dpi=300)

生成文件： knowledge_graph.png - 高分辨率知识图谱图像

4. export_to_neo4j.py - Neo4j数据库导入

class Neo4jExporter:def __init__(self, uri, user, password):self.driver = GraphDatabase.driver(uri, auth=(user, password))def create_entities(self, entities_df):"""创建实体节点"""with self.driver.session() as session:for _, entity in entities_df.iterrows():query = """CREATE (e:Entity {title: $title,type: $type,description: $description})"""session.run(query, **entity.to_dict())def create_relationships(self, relationships_df):"""创建关系"""with self.driver.session() as session:for _, rel in relationships_df.iterrows():query = """MATCH (a:Entity {title: $source})MATCH (b:Entity {title: $target})CREATE (a)-[r:RELATED_TO {description: $description}]->(b)"""session.run(query, **rel.to_dict())

常用Cypher查询：

-- 查找最重要的实体
MATCH (n:Entity)
RETURN n.title, COUNT { (n)--() } as connections
ORDER BY connections DESC LIMIT 10-- 查找两个实体间的最短路径
MATCH path = shortestPath((a:Entity {title: 'RAG'})-[*]-(b:Entity {title: 'LLM'}))
RETURN path

5. export_to_csv_for_neo4j.py - CSV批量导出

def export_for_neo4j_csv():"""导出Neo4j兼容的CSV文件"""# 读取数据entities_df = pd.read_parquet("my_graphrag/output/entities.parquet")relationships_df = pd.read_parquet("my_graphrag/output/relationships.parquet")# 准备节点CSVnodes_df = entities_df[['title', 'type', 'description']].copy()nodes_df.columns = ['title:ID', 'type', 'description']nodes_df[':LABEL'] = 'Entity'# 准备关系CSVrels_df = relationships_df[['source', 'target', 'description']].copy()rels_df.columns = [':START_ID', ':END_ID', 'description']rels_df[':TYPE'] = 'RELATED_TO'# 保存文件nodes_df.to_csv('neo4j_nodes.csv', index=False)rels_df.to_csv('neo4j_relationships.csv', index=False)

Neo4j导入命令：

neo4j-admin database import full \--nodes=neo4j_nodes.csv \--relationships=neo4j_relationships.csv \neo4j

6. parquet_viewer.py - 文件查看转换

def view_parquet_info(file_path):"""查看parquet文件信息"""df = pd.read_parquet(file_path)print(f"文件: {file_path}")print(f"行数: {len(df)}, 列数: {len(df.columns)}")print(f"列信息: {list(df.columns)}")print(df.head(3))def convert_to_csv(parquet_path):"""转换为CSV格式"""df = pd.read_parquet(parquet_path)csv_path = parquet_path.replace('.parquet', '.csv')df.to_csv(csv_path, index=False, encoding='utf-8')return csv_path

7. view_communities.py - 社区分析

def view_community_reports():"""查看社区报告"""df = pd.read_parquet("my_graphrag/output/community_reports.parquet")print(f"社区总数: {len(df)}")for i, row in df.iterrows():print(f"\n--- 社区 {i} ---")print(f"标题: {row.get('title', 'N/A')}")print(f"层级: {row.get('level', 'N/A')}")content = str(row.get('full_content', ''))[:200] + '...'print(f"内容摘要: {content}")

这套工具集提供了完整的GraphRAG数据处理和应用集成解决方案，从基础查看到高级分析，满足不同层次的使用需求。

六. Tips

1. 选择方法

   • local → 适合精准事实类问答（小范围）
   • global → 适合总结、综合类问题（大范围）
   • drift → 资源有限时的折中选择

2. Prompt 调整
   修改 settings.yaml 里的 prompts 部分，能优化答案风格。

3. 文档更新
   如果增加/修改文档，只需再次运行：

   graphrag index --root ./my_graphrag