GraphRAG的使用和配置

这里以windows环境进行介绍。关于如何在windows下安装GraphRAG，请【点击这里】查看和学习。

1.创建GraphRAG项目

首先需要创建一个项目目录，例如，graphrag-project，该目项目录的完整路径为D:\Work\AI\graphrag-project。
使用下面这个命令初始化 graphrag-project 项目目录。

cd D:\Work\AI\
graphrag init --root graphrag-project --force

这里，在该目录下创建了.env、settings.yaml两个配置文件，以及prompts子目录。

2.配置GraphRAG项目

2.1. 准备好chat mode 和 embedding mode

模型类型	app_key	mode	url	app_base
chat mode	sk-abcdefghijklm	qwen_32b	http://192.168.1.100:20000/v1/chat/completions	http://192.168.1.100:20000/v1
embedding	<无>	BGE	http://192.168.1.200:20000/embed	http://192.168.1.200:20000

2.2. 模型测试

2.2.1. 测试chat 模型

curl http://192.168.1.100:20000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-abcdefghijklm" \
  -d '{
    "model": "qwen3_32b",
    "messages": [{"role": "user", "content": "你是谁？"}]
  }'

2.2.2. 测试embedding模型

curl http://192.168.1.200:20000/embed \
  -H "Content-Type: application/json" \
  -d '{
    "input": ["test text"],
    "model": "BGE"
  }'

2.3. 配置.env文件

把chat mode的app_key填写到.env文件

GRAPHRAG_API_KEY=sk-abcdefghijklm

2.4. 配置settings.yaml文件

2.4.1. 配置chat mode

修改models->default_chat_model的以下内容，其它内容保持不变

models:
  default_chat_model:
    api_key: ${GRAPHRAG_API_KEY} # 指向.env文件中配置的api_key
    model: qwen3_32b # chat模型名称
    api_base: http://192.168.1.100:20000/v1 # chat模型API地址
    concurrent_requests: 5 # 降低并发数，从25改为5
    max_retries: 5 # 降低重试次数，从10改为5

2.4.2. 配置embedding mode

models:
  default_embedding_model:
    api_key: placeholder # 没有app key时，填写固定值 placeholder
    model: BGE  # embedding模型名称
    api_base: http://192.168.1.200:20000  # embedding模型API地址
    concurrent_requests: 5 # 降低并发数，从25改为5
    max_retries: 5 # 降低重试次数，从10改为5

2.4.3. 关于向量数据库

这里使用默认的 lancedb 向量数据库，在settings.yaml文件中已经默认配置了 ,你也可以根据需要进行修改：

vector_store:
  default_vector_store:
    type: lancedb
    db_uri: output\lancedb
    container_name: default

1）向量数据库的作用
GraphRAG 需要向量数据库来存储：

• 文本块的嵌入向量（用于检索）
• 图节点的嵌入向量（如果启用 embed_graph）

2）LanceDB 的优势

• 本地文件存储：不需要额外服务，数据存储在 output/lancedb/ 目录
• 高性能：专门为向量搜索优化
• 轻量级：无需安装额外服务

3）LanceDB 向量数据库的自动管理
当你运行 graphrag run 时，它会：
（1）自动创建 LanceDB 数据库（如果不存在）
（2）存储所有文本块的嵌入向量
（3）在查询时自动进行向量相似度搜索
4）LanceDB 向量数据库的内容
（1）embeddings.lance # 向量数据
（2）metadata.json # 元数据
5）如果你想调整LanceDB 向量数据库配置

vector_store:
  default_vector_store:
    type: lancedb
    db_uri: output\lancedb
    container_name: default
    # 可选的额外参数：
    metric_type: cosine  # 相似度度量：cosine, l2, ip
    vector_column: vector  # 向量列名
    num_partitions: 256    # 分区数
    num_sub_vectors: 96    # PQ量化参数

支持的其他向量数据库
如果你需要更换向量数据库，可以配置：

# PostgreSQL + pgvector 示例
vector_store:
  default_vector_store:
    type: pgvector
    connection_string: postgresql://user:pass@localhost:5432/dbname
    table_name: embeddings

# 或 Weaviate
vector_store:
  default_vector_store:
    type: weaviate
    url: http://localhost:8080
    api_key: ${WEAVIATE_API_KEY}

# 或 Chroma
vector_store:
  default_vector_store:
    type: chroma
    persist_directory: ./chroma_db

3. 构建知识图谱

配置好 GraphRAG 后，以下是完整的使用流程：

3.1. 准备工作

3.1.1. 确保文件结构正确

graphrag-project/
├── .env                # API密钥配置
├── settings.yaml       # 主配置文件
├── prompts/            # 提示词目录
├── input/              # 输入文件目录
├── output/             # 输出目录
└── cache/              # 缓存目录

3.1.2. 准备知识库文件

在 input/ 目录下放置你的知识库文件（文本文件）：

• 支持 .txt, .csv, .json 格式
• 对于文本文件，每行一个文档或整个文件作为一个文档
• 示例：input/documents.txt

3.2. 构建知识图谱

3.2.1. 知识图谱构建

# 进入项目目录
cd graphrag-project

# 运行命令进行构建
graphrag index --config settings.yaml

这将会执行以下步骤：

1. 读取并分块输入文档
2. 提取实体和关系（构建知识图谱）
3. 生成图嵌入
4. 社区检测和摘要生成

3.2.2. 查看构建结果

运行完成后，查看生成的文件：

• output/ - 包含构建的知识图谱文件
• logs/ - 运行日志和报告
• cache/ - 缓存文件（加速后续运行）

4. 查询知识图谱

4.1. 启动查询服务

# 启动本地搜索API
graphrag query --search-method local_search

# 启动全局搜索
graphrag query --search-method global_search

# 启动基础搜索
graphrag query --search-method basic_search

4.2. 查询方式1：通过API查询

启动查询服务后（默认端口 8000）：

# 使用curl查询
curl -X POST http://localhost:8000/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "查询内容",
    "top_k": 5
  }'

# 或者使用graphrag CLI查询
graphrag search --query "你的问题" --top-k 5

4.3. 查询方式2：通过Python SDK查询

from graphrag.query.local_search import LocalSearchClient

# 初始化客户端
client = LocalSearchClient(
    config_path="settings.yaml",
    search_method="local_search"
)

# 执行查询
response = client.search(
    query="你想查询的问题",
    top_k=5
)

print(response.answer)  # 生成的答案
print(response.sources) # 参考来源

5. 高级功能

5.1. 自定义提示词

在 prompts/ 目录下修改提示词文件：

• extract_graph.txt - 图提取提示词
• summarize_descriptions.txt - 摘要提示词
• local_search_system_prompt.txt - 本地搜索提示词

5.2. 调整配置参数

编辑 settings.yaml：

# 调整分块大小
chunks:
  size: 800  # 根据你的模型调整
  overlap: 100

# 调整实体类型
extract_graph:
  entity_types: [organization, person, location, concept, event]
  max_gleanings: 2  # 增加提取的丰富度

5.3. 监控和调试

# 查看详细日志
graphrag run --verbose

# 生成详细报告
graphrag run --reporting-level detailed

# 查看帮助
graphrag --help
graphrag run --help
graphrag query --help

6. 实际示例

6.1. 示例1：处理技术文档

# 1. 准备文档
echo "GraphRAG是微软开发的基于知识图谱的检索增强生成系统。" > input/tech.txt
echo "它结合了图数据库和LLM来提供更准确的回答。" >> input/tech.txt

# 2. 运行管道
graphrag run

# 3. 查询
graphrag query --search-method local_search
# 在新终端中查询
graphrag search --query "GraphRAG是什么？"

6.2. 示例2：处理多文档

# 1. 创建多个文档
cp document1.txt input/
cp document2.txt input/

# 2. 运行处理
graphrag run

# 3. 使用全局搜索
graphrag query --search-method global_search
graphrag search --query "总结所有文档的关键信息"

7. 常见故障排除

1. API连接失败：

   # 测试API连通性
   curl http://10.0.76.31:30000/v1/models
   

2. 内存不足：

   # 在settings.yaml中减小配置
   concurrent_requests: 2
   chunks:
     size: 500
   

3. 查看详细错误：

   # 启用调试模式
   GRAPHRAG_LOG_LEVEL=DEBUG graphrag run
   
   # 查看日志文件
   cat logs/graphrag.log
   

4. 重置缓存：

   # 删除缓存重新运行
   rm -rf cache/
   graphrag run
   

8. 最佳实践建议

1. 从小规模开始：

   • 先用少量文档测试
   • 确认配置正确后再处理大量数据

2. 监控资源使用：

   • 本地模型注意内存和显存使用
   • 调整 concurrent_requests 避免过载

3. 逐步优化：

   • 根据结果调整分块大小
   • 优化提示词以获得更好的提取效果

4. 版本控制：

   # 保存配置版本
   cp settings.yaml settings_backup.yaml
   cp -r prompts/ prompts_backup/
   

从少量文档开始，逐步调整参数以获得最佳效果。