GraphRAG全流程部署及使用指南

🧠 GraphRAG 全流程部署及使用指南

版本环境

• GraphRAG: 2.7.0
• Python: 3.11
• Conda 环境: graphrag311
• 操作系统: Linux (Ubuntu)

---

📘 1. GraphRAG 简介

GraphRAG（Graph Retrieval-Augmented Generation）是一种结合“知识图谱结构 + 大模型生成能力”的检索增强方案。
它在传统 RAG 的基础上引入了图结构理解（Graph Embedding + Community Detection），可以对海量知识文档建立语义连接、实体关系与上下文社区。

核心特征：

• 自动实体与关系抽取；
• 社区聚类与知识主题生成；
• 支持局部（Local）与全局（Global）两种问答模式；
• 支持 LanceDB 向量数据库；
• 可视化输出知识图谱。

---

📦 2. 环境与依赖安装

conda create -n graphrag311 python=3.11
conda activate graphrag311

git clone https://github.com/microsoft/graphrag.git -b 2.7.0
cd graphrag

```
附：若直接下载压缩包解压，解压完后需创建一个仓库，不然后续会报错
创建仓库方法：
git init
git add .
git commit -m "Initial commit"
```
pip install -e .

（可选）安装扩展可视化包

pip install pyvis networkx pandas

---

📂 3. 目录结构说明

在根目录下创建测试工程：

# 创建文档存储目录：
mkdir -p ./graphrag_test/input
# 将数据集存放入input文件夹

# 执行初始化命令（注意：在graphrag_test文件夹外面运行），会生成prompts和settings.yaml文件
python -m graphrag init --root ./graphrag_test

文件夹树结构：

graphrag_test/
├── input/
│   ├── 【FAQ】SSLVPN用户导入错误.txt
│   ├── 【FAQ】XDR端口配置.txt
│   └── ...
├── settings.yaml
└── output/

---

🧩 4. 支持的输入格式

类型	扩展名	说明
纯文本	.txt	最推荐，稳定高效
Markdown	.md	可保留标题、结构
JSON	.json, .jsonl	需包含 "text" 字段
CSV	.csv, .tsv	需包含 "text" 列
PDF / Word	.pdf, .docx	需安装解析依赖

✅ 推荐使用 UTF-8 编码的 .txt 或 .md 文件。

---

⚙️ 5. settings.yaml 示例

部分内容示例，其中需要修改大模型和embedding模型的url和key，我的模型是本地部署的，并且是配置了nginx，从而实现代理访问。

### 此配置文件包含必须设置的核心默认值，以及一些常见的可选设置。
### 完整可用设置列表见：https://microsoft.github.io/graphrag/config/yaml/

### 大语言模型（LLM）设置 ###
## 有多项设置可用于调节 LLM 调用的并发与 token 限制——请查看文档。

models:
  default_chat_model:
    type: chat
    model_provider: openai
    auth_type: api_key # 或 azure_managed_identity
    api_key: "" # 在生成的 .env 文件中设置；若为托管身份可移除此项
    model: Qwen2.5-72B-Instruct
    api_base: http://172.20.13.3/sglang/v1
    # api_version: 2024-05-01-preview
    model_supports_json: true # 若模型支持，建议开启
    concurrent_requests: 10
    async_mode: threaded # 或 asyncio
    retry_strategy: exponential_backoff
    max_retries: 3
    tokens_per_minute: null
    requests_per_minute: null
  default_embedding_model:
    type: embedding
    model_provider: openai
    auth_type: api_key
    api_key: ""
    model: bge-m3
    api_base: http://172.20.13.3/dp_api/v1 
    # api_version: 2024-05-01-preview
    concurrent_requests: 10
    async_mode: threaded # 或 asyncio
    retry_strategy: exponential_backoff
    max_retries: 3
    tokens_per_minute: null
    requests_per_minute: null

---

🧠 6. 构建索引

python -m graphrag index --root ./graphrag_test --verbose

---

💬 7. 查询知识图谱

python -m graphrag query   --root ./graphrag_test   --method global   --query "SSLVPN 导入报错如何处理？"

部分运行情况（extract_graph时间较长）：
—

🕸️ 8. 可视化知识图谱

# 知识图谱可视化脚本
import pandas as pd
from pyvis.network import Network
import networkx as nx

nodes = pd.read_parquet("graphrag_test/output/entities.parquet")# 注意graphrag_test改为自己的路径
edges = pd.read_parquet("graphrag_test/output/relationships.parquet")

G = nx.DiGraph()
for _, r in nodes.iterrows():
    G.add_node(r["id"], label=str(r.get("title", r["id"])), group=r.get("community", None))

for _, r in edges.iterrows():
    s, t = r.get("source"), r.get("target")
    if pd.notna(s) and pd.notna(t):
        G.add_edge(s, t, label=str(r.get("description", "")))

net = Network(height="800px", width="100%", directed=True)
net.from_nx(G)
net.write_html("graphrag_test/output/graph_vis.html", notebook=False)

---

🔍 9. 数据结构对照表

文件名	内容	用途
entities.parquet	节点（实体）	Graph 构建、社区聚类
relationships.parquet	边（关系）	实体关联可视化
communities.parquet	社区划分	主题聚类
community_reports.parquet	聚合主题摘要	Global Query 溯源
text_units.parquet	原始分块文本	回溯原文内容
lancedb/	向量库	嵌入检索加速

---

🧩 10. 常见问题

问题	解决方案
extract_graph.txt 不存在	复制官方 prompt 到 prompts/
NoneType has no attribute 'render'	改用 write_html(..., notebook=False)
Config file not found	加上 --root ./graphrag_test
社区太多	降低 resolution 或提高 min_community_size
中文乱码	确保 UTF-8 编码

---

✅ 11. 成功运行标志

• 终端出现 Pipeline complete
• output/ 目录包含实体与报告文件
• 查询结果带有 [Data: Reports (...)]
• 可浏览 graph_vis.html 图谱

---

🧭 12、知识图谱查询方式总览

支持多种查询方式，按需选择：

---

🔍 查询方式一览

方法	用途	快速指引
🌐 全局查询	跨文档综合分析	使用 --method global
📄 局部查询	单文档精准检索	使用 --method local
🔄 DRIFT 查询	动态漂移分析	使用 --method drift
⚙️ 基础查询	传统 RAG 检索	使用 --method basic

---

🌐 全局查询（跨文档综合分析）

# 全局查询，替换引号中间的内容
python -m graphrag query --method global --query "知识图谱定义"

---

🏁 13. 结语

你已完成从文本到知识图谱的全流程构建，可将此系统嵌入 Dify、LangChain 等平台，实现结构化知识检索。

---

flowchart TD
    A[输入文档 input/] --> B[分块 create_base_text_units]
    B --> C[生成最终文档 create_final_documents]
    C --> D[抽取实体关系 extract_graph]
    D --> E[聚类成社区 create_communities]
    E --> F[生成社区报告 create_community_reports]
    F --> G[生成向量 generate_text_embeddings]
    G --> H[完成索引 Pipeline complete]