GraphRag Visualization

GraphRag 图谱可视化

本文将详细介绍如何将微软 GraphRAG 框架生成的 entities.parquet 与 relationships.parquet 文件转换为 GraphML 图结构在 Gephi 中实现可视化。我们将逐步解释数据格式、图构建逻辑及 Python 代码实现的每个模块功能。

---

项目地址：https://github.com/EvannZhongg/Blog-Learning.git

---

效果展示

---

1. GraphRAG 简介与数据说明

Microsoft GraphRAG 是一种结合图结构与检索增强生成（Retrieval-Augmented Generation）的知识增强方案。它会自动从文本中提取实体及其关系，分别存储为 entities.parquet 和 relationships.parquet 文件。用户可基于此图谱进行可视化分析、结构化检索及上下文增强生成任务。

如果不知道怎么配置 GraphRag，可以参考官方文档

GraphRAG 输出文件说明如下：

1. entities.parquet

该文件用于存储图中的节点信息，每一行表示一个实体（节点）。字段如下：

字段名	说明
id	实体的唯一标识（主键）
human_readable_id	可读ID（序号或别名）
title	实体的标题或名称
type	实体类型（如概念/术语）
description	实体的文本描述信息
text_unit_ids	所属文本单元ID集合
frequency	出现频率
degree	在图中的连接度（可选）
x, y	可视化坐标（可选）

示例：

id: 053f7bde-5adf-4185-9964-0d51ccc5c313
title: Transformer Model
type: Concept
description: A deep learning model architecture...

---

2. relationships.parquet

该文件表示图中的边（关系），每一行表示两个实体之间的连线及其属性。

字段名	说明
id	关系的唯一ID
human_readable_id	可读ID
source	起点实体的ID（对应entities.id）
target	终点实体的ID
description	边的标签（如”引出”、”属于”）
weight	权重值（如关系强度）
combined_degree	综合度量（可选）
text_unit_ids	来源文本ID集合

---

2. 从 Parquet 到 GraphML 的字段映射关系

1. entities.parquet → GraphML 节点（node）

.parquet 字段	GraphML中映射内容	说明
id	node id	节点的唯一标识，GraphML 中 <node id="...">
title	label（属性）	节点显示标签
type	type（属性）	节点类型
description	description（属性）	节点的文本描述
text_unit_ids	text_unit_ids（属性）	来源文本段落 ID
frequency	frequency（属性）	出现频率（可选）
degree	degree（属性）	图中连接度（可选）
x, y	x, y（属性）	可视化坐标位置（可选）

2. relationships.parquet → GraphML 边（edge）

.parquet 字段	GraphML中映射内容	说明
source	edge source	边的起点
target	edge target	边的终点
description	label（属性）	边的标签
weight	weight（属性）	边的权重
text_unit_ids	text_unit_ids（属性）	来源文本 ID
combined_degree	combined_degree（属性）	综合度量（可选）

GraphML 输出结构示例

<node id="523ff398-4659-461e-810a-1b00e4af85df">
  <data key="label">Transformer Model</data>
  <data key="type">Concept</data>
  <data key="description">A deep learning model architecture...</data>
  <data key="frequency">3</data>
</node>

<edge source="523ff398-4659-461e-810a-1b00e4af85df" target="23a77be7-1b36-4fac-a505-f9424d3dbce2">
  <data key="label">based on</data>
  <data key="weight">1.0</data>
</edge>

---

3. 代码结构与功能解释

文件选择界面

root = tk.Tk()
root.withdraw()
entities_path = filedialog.askopenfilename(...)
relations_path = filedialog.askopenfilename(...)

• 利用 tkinter 弹出图形界面，分别选择实体文件和关系文件路径。
• 若用户未选择文件，则程序中断退出。

加载 parquet 文件

entities_df = pd.read_parquet(entities_path)
relations_df = pd.read_parquet(relations_path)

• 使用 pandas 将 .parquet 文件读取为 DataFrame。
• 后续操作以 DataFrame 行为单位进行图构建。

创建图结构

G = nx.DiGraph()

• 构建 NetworkX 有向图对象 DiGraph()。
• 若希望生成无向图，替换为 nx.Graph() 即可。

添加节点

for _, row in entities_df.iterrows():
    G.add_node(row["id"], label=row["title"], type=row["type"], description=row["description"])

• 遍历 entities_df 的每一行。
• 每行数据作为图中的一个节点：
  • ID 为 row["id"]
  • 附带属性包括 label, type, description

添加边

for _, row in relations_df.iterrows():
    G.add_edge(row["source"], row["target"], label=row["description"], weight=row.get("weight", 1.0))

• 遍历 relationships_df 的每一行。
• 使用 add_edge(source, target, **attrs) 方式添加有向边。
• 边的属性包括：
  • label: 描述关系含义
  • weight: 权重，默认为 1.0

导出为 GraphML 文件

output_path = os.path.join(output_dir, "output.graphml")
nx.write_graphml(G, output_path, encoding="utf-8")

• 设置输出路径到本地 output_graphml/ 文件夹中。
• 利用 networkx.write_graphml() 将图写为 .graphml 文件。
• GraphML 是 XML 格式，便于被 Gephi、Cytoscape 等图分析工具读取。

---

4. 将 GraphML 导入 Gephi 实现可视化

1. 下载 Gephi

下载地址：https://gephi.org/users/download/

2. 在 Gephi 中打开转换后的.graphml 文件

点击左上方的 数据资料，查看节点与边的信息是否均被正确导入。

3. 节点与边的渲染

• 打开 窗口, 选择 外观。
• 在 外观 中的 节点 窗口，点击 分割 ，选择 description 或是 type 进行渲染，点击 应用。
• 如果需要节点与边的具体信息被渲染在窗口，根据图中的配置自行处理。

---

该项目代码参考 GraphRag。