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

一、什么是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}]

9.4 索引构建缓慢

解决：

减少并发请求数：concurrent_requests: 1
降低模型大小：如从70B换成7B模型
增加硬件资源：特别是内存和GPU显存

十、总结与资源

GraphRAG通过知识图谱技术显著提升了RAG系统的全局理解能力，本教程介绍了在Linux系统上从环境准备到实际查询的完整部署过程。关键要点：

使用虚拟环境隔离依赖
配置Ollama实现本地模型部署
正确设置settings.yaml是成功关键
根据文档类型调整分块策略

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

一、什么是GraphRAG？

二、环境准备

2.1 系统要求

2.2 基础依赖安装

2.3 创建虚拟环境

三、安装GraphRAG

3.1 快速安装（推荐）

3.2 源码安装（开发版）

四、配置本地模型（Ollama）

4.1 安装Ollama

4.2 下载所需模型

五、初始化项目

5.1 创建工作目录

5.2 初始化配置文件

5.3 配置环境变量

5.4 配置settings.yaml

六、准备数据与构建索引

6.1 添加文档

6.2 构建索引

七、执行查询

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

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

7.3 混合查询

八、高级配置与优化

8.1 Docker部署（可选）

8.2 中文优化

8.3 性能调优

九、常见问题解决

9.1 编码错误

9.2 API连接失败

9.3 JSON解码错误

9.4 索引构建缓慢

十、总结与资源

推荐资源