本地部署 GraphRAG

本地部署 GraphRAG 主要有两种主流方案：使用微软官方 GraphRAG 命令行工具，或使用集成 UI 的生态项目。下面按步骤说明最实用的本地部署方案。

🎯 方案对比

方案	特点	适合人群
方案一：微软官方 GraphRAG	功能完整，支持全局/局部搜索，但仅限命令行	开发者、技术调研
方案二：GraphRAG-Local-UI	带可视化界面，支持本地模型（Ollama）	不想用 OpenAI、喜欢 GUI 的用户
方案三：GraphRAG-SDK	支持图数据库（FalkorDB/Neo4j）和多智能体	企业级应用、复杂场景

📦 方案一：微软官方 GraphRAG（命令行版）

1. 环境准备

bash 复制代码

# 创建虚拟环境（Python 3.10-3.12）
conda create -n graphrag python=3.11
conda activate graphrag

# 安装 GraphRAG
pip install graphrag

2. 准备数据与初始化

bash 复制代码

# 创建项目目录
mkdir -p ./ragtest/input

# 放入测试文档（支持 txt/pdf/docx）
# 例如下载示例文本
curl https://www.gutenberg.org/cache/epub/24022/pg24022.txt -o ./ragtest/input/book.txt

# 初始化配置
python -m graphrag.index --init --root ./ragtest

初始化后，目录结构如下：

复制代码

ragtest/
├── .env              # API密钥配置
├── settings.yaml     # 模型、切片等参数
└── prompts/          # 实体抽取等提示词模板

3. 配置 API 密钥

编辑 ./ragtest/.env：

env 复制代码

GRAPHRAG_API_KEY=your_openai_api_key

编辑 ./ragtest/settings.yaml（使用 OpenAI 兼容 API，如 DeepSeek 或硅基流动）：

yaml 复制代码

llm:
  api_key: ${GRAPHRAG_API_KEY}
  type: openai_chat
  model: gpt-4o-mini        # 或 deepseek-chat
  api_base: https://api.openai.com/v1   # 替换为自定义 endpoint
  model_supports_json: true

embeddings:
  llm:
    api_key: ${GRAPHRAG_API_KEY}
    type: openai_embedding
    model: text-embedding-3-small

4. 构建知识图谱索引

bash 复制代码

python -m graphrag.index --root ./ragtest

这一步会调用 LLM 提取实体、关系，并进行社区检测，耗时取决于文档大小和 API 速率。

索引完成后，./ragtest/output/ 目录会生成：

entities.parquet - 实体表
relationships.parquet - 关系表
communities.parquet - 社区结构

5. 执行查询

bash 复制代码

# 全局查询（适合主题性问题）
python -m graphrag.query --root ./ragtest --method global "故事的核心主题是什么？"

# 局部查询（适合实体细节）
python -m graphrag.query --root ./ragtest --method local "主角有哪些主要关系？"

🖥️ 方案二：GraphRAG-Local-UI（带界面，支持本地模型）

如果你不想依赖 OpenAI API，可以使用这个带完整 UI 的开源项目。

1. 安装 Ollama 并下载模型

bash 复制代码

# 安装 Ollama（参考 ollama.com）
ollama pull llama3.1:8b      # LLM 模型
ollama pull nomic-embed-text # 嵌入模型

2. 克隆并安装项目

bash 复制代码

git clone https://github.com/your-repo/GraphRAG-Local-UI.git
cd GraphRAG-Local-UI

# 创建虚拟环境
conda create -n graphrag-local python=3.11
conda activate graphrag-local

# 安装依赖
pip install -e ./graphrag
pip install -r requirements.txt

3. 启动服务

bash 复制代码

# 终端1：启动 API 服务器
python api.py --host 0.0.0.0 --port 8012 --reload

# 终端2（如使用 Ollama 嵌入）：启动嵌入代理
python embedding_proxy.py --port 11435 --host http://localhost:11434

# 终端3：启动索引和提示调优 UI
gradio index_app.py

# 终端4：启动主交互 UI
gradio app.py

访问：

索引 UI：http://localhost:7861
主应用 UI：http://localhost:7860

4. 通过 UI 完成索引与查询

在 index_app.py 界面中配置 settings.yaml（指向本地 Ollama）
上传文档到 ./indexing/input/
运行索引任务
在主应用中执行查询并可视化知识图谱

🗄️ 方案三：GraphRAG-SDK（图数据库 + 多智能体）

适合需要持久化存储、大规模图谱或智能体协作的企业场景。

1. 启动图数据库（FalkorDB）

bash 复制代码

docker run -p 6379:6379 -p 3000:3000 -it --rm -v ./data:/data falkordb/falkordb:latest

2. 安装 SDK

bash 复制代码

pip install graphrag_sdk

3. 配置环境变量

bash 复制代码

export FALKORDB_HOST="localhost"
export FALKORDB_PORT=6379
export OPENAI_API_KEY="your-key"  # 或使用 Ollama

4. 创建知识图谱并查询

python 复制代码

from graphrag_sdk import KnowledgeGraph, Ontology
from graphrag_sdk.source import URL
from graphrag_sdk.models.litellm import LiteModel

# 定义数据源
sources = [URL("https://example.com/doc1"), URL("https://example.com/doc2")]

# 自动检测本体
model = LiteModel(model_name="openai/gpt-4.1")
ontology = Ontology.from_sources(sources=sources, model=model)

# 创建知识图谱
kg = KnowledgeGraph(
    name="my_knowledge_graph",
    model_config=KnowledgeGraphModelConfig.with_model(model),
    ontology=ontology,
    host="localhost",
    port=6379
)

# 处理文档（实体提取 + 关系构建）
kg.process_sources(sources)

# 查询
chat = kg.chat_session()
response = chat.send_message("这些文档的主要内容是什么？")
print(response)

⚠️ 常见问题与优化建议

问题	解决方案
API 费用过高	使用 Ollama 本地模型，或选择 DeepSeek/硅基流动等便宜 API
索引速度慢	调整 `settings.yaml` 中 `concurrent_requests: 5` 增加并发
内存不足	减少 `chunk_size`（如 600→300），降低社区检测分辨率
中文支持差	使用中文嵌入模型如 `BAAI/bge-large-zh-v1.5`，并确保 prompt 模板包含中文示例
实体抽取不准	修改 `prompts/entity_extraction.txt`，自定义 `entity_types`（如 `["人物","地点","事件"]`）

📌 总结

你的需求	推荐方案
快速体验、技术调研	方案一：微软官方 GraphRAG + OpenAI API
不想花钱、喜欢图形界面	方案二：GraphRAG-Local-UI + Ollama
企业级、大规模知识库	方案三：GraphRAG-SDK + FalkorDB/Neo4j

建议先从方案一入手，理解 GraphRAG 的核心流程（实体提取 → 社区检测 → 全局/局部查询），再根据实际需求切换到其他方案。