Linux系统安装部署GraphRAG完全指南

原创于 2025-07-16 09:25:28 发布 · 550 阅读

CC 4.0 BY-SA版权

文章标签：

一、什么是GraphRAG？

GraphRAG（Graph-based Retrieval-Augmented Generation）是微软开源的新一代知识图谱增强型检索生成技术，它通过构建实体关系网络来提升传统RAG的全局理解能力。与传统基于文本块的RAG不同，GraphRAG能够：

提取文档中的实体和关系，构建结构化知识图谱
生成实体社区摘要，支持全局主题分析
显著提升复杂问题的回答准确性
支持本地大模型部署，保护数据隐私

官方仓库：microsoft/graphrag

二、环境准备

2.1 系统要求

操作系统：Ubuntu 20.04+/CentOS 8+ 或其他Linux发行版
Python版本：3.10-3.12（推荐3.11）
硬件建议：
- 内存：至少16GB（推荐32GB以上）
- 存储：至少50GB可用空间
- GPU（可选）：NVIDIA显卡（8GB显存以上，加速本地模型）

2.2 基础依赖安装

首先安装系统级依赖：

# Ubuntu/Debian
sudo apt update && sudo apt install -y python3 python3-pip python3-venv git build-essential libssl-dev

# CentOS/RHEL
sudo dnf install -y python3 python3-pip python3-devel git gcc openssl-devel

2.3 创建虚拟环境

# 创建虚拟环境
python3 -m venv graphrag-env

# 激活环境
source graphrag-env/bin/activate

# 升级pip
pip install --upgrade pip

三、安装GraphRAG

3.1 快速安装（推荐）

pip install graphrag

3.2 源码安装（开发版）

git clone https://github.com/microsoft/graphrag.git
cd graphrag
pip install -e .

验证安装：

graphrag --version

四、配置本地模型（Ollama）

GraphRAG默认使用OpenAI模型，我们配置本地模型以降低成本并保护隐私。

4.1 安装Ollama

# Linux安装命令 curl -fsSL https://ollama.com/install.sh | sh  
# 启动Ollama服务 ollama serve &

4.2 下载所需模型

# 下载LLM模型（选择一个）
ollama pull gemma2:9b    # 推荐，平衡性能和资源
ollama pull llama3:70b   # 高性能（需要更多资源）
ollama pull qwen2:7b     # 中文优化

# 下载Embedding模型
ollama pull quentinz/bge-large-zh-v1.5:latest  # 中文优化
ollama pull nomic-embed-text                   # 通用英文

查看已安装模型：

ollama list

五、初始化项目

5.1 创建工作目录

mkdir -p ./ragtest/input cd ragtest

5.2 初始化配置文件

graphrag init --root ./

执行后会生成以下文件：

.env：环境变量配置
settings.yaml：核心配置文件
prompts/：提示词模板目录
input/：文档存放目录

5.3 配置环境变量

编辑.env文件：

nano .env

修改内容：

GRAPHRAG_API_KEY=ollama # 固定值，无需修改

5.4 配置settings.yaml

这是最关键的步骤，编辑配置文件：

nano settings.yaml

核心配置如下（只列出需要修改的部分）：

encoding_model: cl100k_base

llm:
  api_key: ollama
  type: openai_chat
  model: gemma2:9b  # 替换为你下载的LLM模型名
  model_supports_json: true
  max_tokens: 2048
  api_base: http://localhost:11434/v1  # Ollama API地址
  concurrent_requests: 1  # 并发请求数，根据硬件调整

embeddings:
  async_mode: threaded
  llm:
    api_key: ollama
    type: openai_embedding
    model: quentinz/bge-large-zh-v1.5:latest  # 替换为你的Embedding模型
    api_base: http://localhost:11434/api  # 注意这里是/api
    concurrent_requests: 1

chunks:
  size: 300  # 文本分块大小
  overlap: 100  # 分块重叠度

input:
  type: file
  file_type: text
  base_dir: "input"
  file_encoding: utf-8  # 确保文件编码为UTF-8
  file_pattern: ".*\\.txt$"

六、准备数据与构建索引

6.1 添加文档

将你的文本文件（TXT/CSV格式）放入input目录：

# 示例：下载示例文档
curl https://www.gutenberg.org/cache/epub/24022/pg24022.txt -o ./input/book.txt

# 或添加自己的文件
cp /path/to/your/documents/*.txt ./input/

注意：确保所有文件都是UTF-8编码，中文文档建议预处理去除特殊字符。

6.2 构建索引

graphrag index --root ./

索引构建过程可能需要较长时间，取决于文档大小和硬件性能。成功完成后会显示：All workflows completed successfully

索引结果会保存在output目录，包括：

知识图谱数据
实体社区报告
处理日志

七、执行查询

7.1 全局查询（适合主题性问题）

graphrag query --root ./ --method global --query "文档的主要主题是什么？"

7.2 本地查询（适合具体细节问题）

graphrag query --root ./ --method local --query "主人公的主要关系有哪些？"

7.3 混合查询

graphrag query --root ./ --method hybrid --query "分析故事中的关键事件及其影响"

八、高级配置与优化

8.1 Docker部署（可选）

对于生产环境，推荐使用Docker部署：

# 拉取镜像
docker pull kylinmountain/graphrag-server:0.3.1

# 运行容器
docker run -d --platform linux/amd64 \
  -v ./env:/app/.env \
  -v ./output:/app/output \
  -v ./input:/app/input \
  -v ./settings.yaml:/app/settings.yaml \
  -p 20213:20213 \
  kylinmountain/graphrag-server:0.3.1

8.2 中文优化

修改分块策略（解决中文分词问题）：替换graphrag/index/verbs/text/chunk/strategies/tokens.py中的分块逻辑
优化提示词：将prompts/目录下的提示词文件翻译为中文，并调整实体提取规则

8.3 性能调优

增加concurrent_requests值（需硬件支持）
调整chunks.size适应文档类型（长文档增大至1000-1500）
启用缓存：确保cache.type: file配置

九、常见问题解决

9.1 编码错误

错误：UnicodeDecodeError: 'utf-8' codec can't decode byte...

解决：转换文件编码为UTF-8：

iconv -f GBK -t UTF-8 input.txt > input_utf8.txt

9.2 API连接失败

错误：APIConnectionError: Connection error

解决：

检查Ollama服务是否运行：ps aux | grep ollama
确认端口未被占用：netstat -tulpn | grep 11434
重启Ollama服务：ollama serve &

9.3 JSON解码错误

错误：json.decoder.JSONDecodeError

解决：

在settings.yaml中设置model_supports_json: false
更换更强大的模型（如从7B模型升级到13B+）

修改源码（仅高级用户）：

# 修改graphrag/query/structured_search/global_search/search.py
search_messages = [{"role": "user", "content": search_prompt + "\n\n### USER QUESTION ### \n\n" + query}]