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

文章目录

• • [一. 环境准备](#一. 环境准备)
  • • [1.安装 Python 环境](#1.安装 Python 环境)
    • 2.安装依赖
    • [3.配置 LLM API Key](#3.配置 LLM API Key)
  • [二. 初始化项目](#二. 初始化项目)
  • [三. 文档上传 & 索引构建](#三. 文档上传 & 索引构建)
  • [四. 问答（CLI 方式）](#四. 问答（CLI 方式）)
  • • 示例：
  • [五. 代码中调用 GraphRAG](#五. 代码中调用 GraphRAG)
  • • 工具概览
    • 核心工具详解
    • [1. simple_graphrag_integration.py - 智能问答核心](#1. simple_graphrag_integration.py - 智能问答核心)
    • [2. view_graph.py - 基础数据查看](#2. view_graph.py - 基础数据查看)
    • [3. visualize_graph.py - 图谱可视化](#3. visualize_graph.py - 图谱可视化)
    • [4. export_to_neo4j.py - Neo4j数据库导入](#4. export_to_neo4j.py - Neo4j数据库导入)
    • [5. export_to_csv_for_neo4j.py - CSV批量导出](#5. export_to_csv_for_neo4j.py - CSV批量导出)
    • [6. parquet_viewer.py - 文件查看转换](#6. parquet_viewer.py - 文件查看转换)
    • [7. view_communities.py - 社区分析](#7. view_communities.py - 社区分析)
  • [六. Tips](#六. Tips)

之前我写过一篇端到端构建知识图谱的文章，有人在后台问我关于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())

输出示例：

=== 实体信息 ===
总实体数: 68
                title    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")
    
    # 准备节点CSV
    nodes_df = entities_df[['title', 'type', 'description']].copy()
    nodes_df.columns = ['title:ID', 'type', 'description']
    nodes_df[':LABEL'] = 'Entity'
    
    # 准备关系CSV
    rels_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